SqlSugar如何用种子数据初始化MySQL表？

Question

在使用 SqlSugar 进行 MySQL 数据库开发时，如何在项目启动阶段通过代码自动初始化表结构并插入种子数据（Seed Data）是一个常见需求。许多开发者遇到问题：即便正确配置了实体映射和连接字符串，调用 `Db.CodeFirst.InitTables()` 创建表后，种子数据未能成功插入，或插入时抛出唯一键冲突、字段为空等异常。尤其是在使用 `InsertRange` 批量插入时，未判断数据是否已存在，导致重复插入。此外，MySQL 的自增主键与 SqlSugar 的 `IsIdentity=true` 配置不匹配也会引发问题。该如何结合 SqlSugar 的 `Seed` 方法或 `EnsureTableAsync` 实现幂等性表创建与安全的种子数据初始化？

Answer 1

一、问题背景与核心挑战

在现代IT系统开发中，数据库的自动化初始化已成为微服务架构和DevOps流程中的标准实践。使用SqlSugar作为ORM框架时，开发者期望通过Db.CodeFirst.InitTables()实现表结构自动创建，并结合种子数据（Seed Data）完成初始数据填充。然而，在MySQL环境下，常出现以下典型问题：

• 调用InitTables()后表成功创建，但种子数据未插入；
• 重复执行导致唯一键冲突（如主键或唯一索引重复）；
• IsIdentity=true配置未正确映射到MySQL自增字段，引发插入异常；
• 批量插入使用InsertRange时缺乏存在性判断，破坏幂等性；
• 多环境部署下初始化逻辑失控，影响CI/CD稳定性。

这些问题的根本原因在于对SqlSugar Code-First机制与MySQL DDL语义理解不足，以及缺乏对“幂等性”和“数据一致性”的工程化设计。

二、SqlSugar初始化机制解析

SqlSugar提供了两种主要方式用于代码优先建表：

方法	说明	是否支持异步	幂等性保障
InitTables()	同步创建表（若不存在）	否	部分（仅建表）
EnsureTableAsync()	异步确保表存在，可指定种子函数	是	强（支持条件判断）
Seed()	定义种子数据插入策略	否	需手动控制

其中，EnsureTableAsync 是推荐方案，因其支持异步执行并允许传入初始化回调函数，便于整合种子逻辑。

三、常见错误场景分析

1. 未启用自增标识：实体类中未设置[SugarColumn(IsIdentity = true)]，而MySQL字段为AUTO_INCREMENT，导致插入时报“Field can't be null”；
2. 重复插入无校验：直接调用InsertRange(seedData)而未先查询是否存在记录；
3. 事务边界不清：建表与插数不在同一作用域，中途失败导致状态不一致；
4. 字符集与排序规则不匹配：MySQL默认utf8mb4_general_ci可能导致唯一索引误判（大小写敏感问题）；
5. 并发初始化竞争：多个实例同时启动时可能触发多次建表或插数操作。

四、解决方案：构建幂等性初始化流程

我们提出一个分层、可复用的初始化模式，结合EnsureTableAsync与Seed思想，实现安全可靠的数据库准备过程。

public async Task InitializeDatabaseAsync(ISqlSugarClient db)
{
    var entities = new Type[] { typeof(User), typeof(Role), typeof(Permission) };

    foreach (var entity in entities)
    {
        await db.CodeFirst
            .EnsureTableAsync(entity, async table => 
            {
                // 检查是否已有数据
                var exists = await db.Queryable(entity).AnyAsync();
                if (!exists)
                {
                    var seedData = GetSeedDataForEntity(entity);
                    await db.Insertable(seedData).ExecuteCommandAsync();
                }
            });
    }
}

private object[] GetSeedDataForEntity(Type entityType)
{
    return entityType.Name switch
    {
        "User" => new User[]
        {
            new() { Id = 1, Name = "admin", Email = "[e-mail]" },
            new() { Id = 2, Name = "guest", Email = "[e-mail]" }
        },
        "Role" => new Role[]
        {
            new() { Id = 1, RoleName = "Administrator" },
            new() { Id = 2, RoleName = "Guest" }
        },
        _ => Array.Empty<object>()
    };
}
    

    
五、关键配置与最佳实践
    
为确保MySQL兼容性和性能稳定，需注意以下配置细节：
    
实体主键必须标注：[SugarColumn(IsPrimaryKey = true, IsIdentity = true)]
连接字符串应包含Allow User Variables=true以支持某些SqlSugar内部变量解析；
使用DbType.MySql明确指定数据库类型；
建议开启MoreSettings.IgnoreCase避免C# PascalCase与数据库snake_case映射问题；
对于复合唯一键，应在实体上使用[SugarIndex]显式声明索引。

    
六、流程图：完整的数据库初始化流程
    
graph TD
            A[应用启动] --> B{表是否存在?}
            B -- 否 --> C[创建表结构]
            B -- 是 --> D{数据是否存在?}
            C --> D
            D -- 否 --> E[加载种子数据]
            E --> F[提交事务]
            D -- 是 --> G[跳过初始化]
            G --> H[继续启动流程]
            F --> H
            style A fill:#4CAF50,stroke:#388E3C
            style H fill:#2196F3,stroke:#1976D2
</object>