EntityFramework Core 9 迁移机制变更：当数据库存在表但无迁移历史时的处理方式

背景介绍

在 EntityFramework Core 9 中，微软对数据库迁移机制做出了一项重要变更，这一变更影响了那些在数据库中存在表结构但尚未应用任何迁移的应用场景。本文将深入分析这一变更的技术细节、影响范围以及应对策略。

问题现象

在 EntityFramework Core 8 及更早版本中，当开发者调用 Database.Migrate() 方法时，即使数据库已经包含表结构但缺少迁移历史表(__EFMigrationsHistory)，EF Core 仍会创建迁移历史表并继续执行迁移操作。

然而在 EF Core 9 中，这一行为发生了改变。当系统检测到数据库中存在表结构但没有对应的迁移历史时，会抛出 InvalidOperationException 异常，提示"模型有待处理的更改，请在更新数据库前添加新的迁移"。

技术细节分析

旧版本行为

在 EF Core 8 中，迁移机制的工作流程如下：

1. 检查是否存在迁移历史表
2. 如果不存在，则创建该表
3. 检查已应用的迁移与可用迁移的差异
4. 应用缺失的迁移

这种机制允许开发者先通过其他方式(如手动创建或使用 CreateTables())初始化数据库结构，然后再通过迁移机制来管理后续变更。

新版本行为

EF Core 9 引入了更严格的检查机制：

1. 检查模型与数据库的同步状态
2. 如果发现数据库中存在表结构但没有对应的迁移历史，则认为存在"待处理的模型更改"
3. 抛出异常，强制开发者显式创建迁移

这一变更背后的设计理念是确保迁移历史的完整性和可追溯性，避免出现数据库结构与代码模型不同步的情况。

影响范围

这一变更主要影响以下场景：

1. 使用 CreateTables() 方法初始化数据库的应用
2. 手动创建数据库表结构的应用
3. 多数据库提供程序支持的应用(如同时支持 SQL Server 和 SQLite)
4. 使用自定义迁移历史表的应用

解决方案

针对这一变更，开发者有以下几种应对策略：

1. 创建初始迁移

最规范的解决方式是创建初始迁移：

dotnet ef migrations add InitialCreate

这将确保数据库结构与代码模型完全同步，并建立完整的迁移历史记录。

2. 配置警告行为

如果暂时无法创建迁移，可以配置警告行为来避免异常：

optionsBuilder.ConfigureWarnings(warnings => 
    warnings.Log(RelationalEventId.PendingModelChangesWarning));

这种方式适合过渡期使用，但不推荐长期使用。

3. 自定义数据库初始化逻辑

对于需要支持多数据库提供程序的应用，可以考虑重构初始化逻辑：

if (!dbCreate.HasTables())
{
    // 优先尝试使用迁移
    try 
    {
        Database.Migrate();
    }
    catch
    {
        // 回退到创建表
        dbCreate.CreateTables();
        
        // 确保创建迁移历史表
        var migrator = Database.GetService<IMigrator>();
        migrator.GetAppliedMigrations(); // 这会创建历史表
    }
}

最佳实践建议

1. 始终使用迁移机制：避免混合使用 CreateTables() 和迁移机制
2. 为每个环境创建迁移：特别是当支持多个数据库提供程序时
3. 保持迁移历史完整：确保所有环境都有完整的迁移历史记录
4. 测试迁移流程：在 CI/CD 流程中加入迁移测试环节

总结

EntityFramework Core 9 的这一变更体现了微软对数据库迁移机制严谨性的提升。虽然短期内可能需要开发者调整现有代码，但从长期来看，这一变更有助于提高数据库变更的可控性和可维护性。开发者应当尽快适应这一变更，采用更规范的迁移管理实践。