FluentMigrator 在 SQL Server 迁移中的常见问题解析

问题现象分析

许多开发者在将 FluentMigrator 从 SQLite 迁移到 SQL Server 时，会遇到一个典型现象：迁移脚本看似执行成功，控制台也输出了完整的 SQL 语句，但实际上数据库没有任何变化。这种情况通常表现为：

1. 控制台完整显示了所有迁移 SQL 语句
2. 数据库中没有创建预期的表和结构
3. 多次运行迁移会产生相同的输出
4. 版本控制表（VersionInfo）未被创建

根本原因探究

经过深入分析，这种现象通常由以下几个关键因素导致：

1. 连接字符串配置问题

最常见的原因是连接字符串未正确传递到迁移运行器。当 FluentMigrator 检测到无效或空连接字符串时，会自动切换到"ConnectionlessProcessor"模式。这是一种安全机制，在这种模式下：

• 所有 SQL 语句会被记录但不会真正执行
• 不会对数据库进行任何修改
• 设计初衷是用于开发和调试场景

2. 预览模式意外启用

虽然开发者没有显式配置预览模式，但某些配置组合可能导致 FluentMigrator 意外进入预览模式。在预览模式下：

• 会显示将要执行的 SQL 语句
• 不会实际提交事务
• 类似于数据库操作的"试运行"

3. 依赖注入配置不当

在 .NET Core/5/6/7/8 中使用 FluentMigrator 时，依赖注入的配置方式对行为有重要影响。特别是：

• AddFluentMigratorCore() 的调用顺序
• 日志配置与处理器配置的交互
• 运行器选项的配置方式

解决方案与实践建议

1. 确保连接字符串有效传递

// 正确示例 - 确保连接字符串非空且有效
var connectionString = Configuration.GetConnectionString("DefaultConnection");
services.AddFluentMigratorCore()
    .ConfigureRunner(rb => rb
        .AddSqlServer()
        .WithGlobalConnectionString(connectionString)
        .WithMigrationsIn(typeof(Program).Assembly));

2. 显式禁用预览模式

// 明确设置预览模式为false
services.Configure<ProcessorOptions>(opt => {
    opt.PreviewOnly = false;
});

3. 完整的依赖注入配置

// 推荐的标准配置方式
services.AddLogging(lb => lb.AddFluentMigratorConsole())
    .AddFluentMigratorCore()
    .ConfigureRunner(rb => rb
        .AddSqlServer2016()  // 根据实际SQL Server版本选择
        .WithGlobalConnectionString(connectionString)
        .WithMigrationsIn(Assembly.GetExecutingAssembly()))
    .Configure<ProcessorOptions>(opt => {
        opt.PreviewOnly = false;
    })
    .Configure<RunnerOptions>(opt => {
        opt.Tags = new[] { "Production" };  // 根据需要设置标签
    });

调试技巧

当遇到迁移不生效的情况时，可以采取以下调试步骤：

1. 验证连接字符串：在迁移代码之外单独测试连接字符串是否有效
2. 检查日志级别：确保日志级别设置为Information或更低，避免遗漏警告信息
3. 隔离测试：创建一个最小化的测试项目，只包含最基本的迁移
4. 版本检查：手动查询数据库中的VersionInfo表，确认迁移记录是否存在

最佳实践

1. 环境隔离：为开发、测试和生产环境使用不同的连接字符串配置
2. 版本控制：将数据库迁移作为应用程序部署的一部分，纳入版本控制系统
3. 回滚策略：始终为迁移实现Down方法，以便必要时回滚
4. 日志记录：配置适当的日志级别，便于问题排查
5. 集成测试：为关键迁移编写自动化测试，验证迁移效果

通过遵循这些实践和解决方案，开发者可以避免常见的迁移问题，确保 FluentMigrator 在 SQL Server 环境中可靠运行。