Umbraco-CMS 中SQL迁移语句换行符丢失问题解析

问题背景

在Umbraco-CMS 13.5.3版本中，开发人员在使用自定义多行SQL迁移时遇到了一个关键问题。当通过MigrationBase类的Execute.Sql()方法执行包含多行SQL语句的迁移时，系统会意外移除SQL语句中的换行符，导致SQL语法错误，最终使迁移失败。

问题根源分析

问题的核心在于MigrationExpressionBase类对多行SQL语句的处理方式。该类原本的设计目的是为了兼容SQL CE数据库，需要将多行SQL语句分割处理。其实现参考了SQL Server Compact Toolbox中的解决方案，但遗漏了一个关键细节。

正确的实现应该像Stack Overflow上的示例那样，在读取每行SQL后重新添加换行符。然而，Umbraco的实现中只保留了行内容本身，没有保留换行符，导致所有SQL语句被压缩成一行。

技术细节

具体来看，问题出在以下代码段：

var stmtBuilder = new StringBuilder();
using (var reader = new StringReader(sql))
{
    string? line;
    while ((line = reader.ReadLine()) != null)
    {
        if (line.Trim().Equals("GO", StringComparison.OrdinalIgnoreCase))
        {
            ExecuteStatement(stmtBuilder);
        }
        else
        {
            stmtBuilder.Append(line); // 这里缺少了换行符的添加
        }
    }
    // 其他代码...
}

问题表现

当开发人员尝试执行如下多行SQL迁移时：

Execute.Sql(
    """
    ALTER TABLE [_DictionaryItemStatus]
    ADD [LastReceivedFromTranslation] DATETIMEOFFSET NOT NULL
    CONSTRAINT [D_DictionaryItemStatus_LastReceivedTranslation] DEFAULT GETDATE()
    """).Do();

系统会将SQL语句转换为：

ALTER TABLE [_DictionaryItemStatus]ADD [LastReceivedFromTranslation] DATETIMEOFFSET NOT NULLCONSTRAINT [D_DictionaryItemStatus_LastReceivedTranslation] DEFAULT GETDATE()

这导致"NOT NULL"和"CONSTRAINT"关键词被连在一起，形成语法错误。

解决方案

Umbraco团队已经确认并修复了这个问题。修复方法是确保在读取每行SQL后添加换行符，保持原始SQL语句的格式完整性。这个修复将包含在13.8.0版本中。

临时解决方案

对于需要使用13.5.3版本的开发者，可以采取以下临时解决方案：

1. 将所有SQL语句写在一行中，避免换行
2. 创建自定义迁移执行器，重写SQL语句处理逻辑
3. 考虑使用其他迁移方式，如Entity Framework风格的迁移

最佳实践建议

1. 在执行重要数据库迁移前，先在测试环境中验证SQL语句
2. 考虑将复杂SQL迁移拆分为多个简单迁移
3. 对于生产环境，建议等待包含修复的13.8.0版本发布后再实施相关迁移

总结

这个问题提醒我们在处理文本内容时，特别是像SQL这样的结构化语言，保持原始格式的重要性。即使是看似无害的换行符处理，也可能导致严重的功能问题。Umbraco团队对此问题的快速响应也展示了开源社区解决问题的效率。