数据库迁移脚本使用

本文档引用的文件

• /lmes-template/src/CMS.Plugin.MyPluginName.MySQL/Scripts/UpdateDB.bat
• /lmes-template/src/CMS.Plugin.MyPluginName.MySQL/Scripts/UpdateMigrations.bat
• /lmes-template/src/CMS.Plugin.MyPluginName/CMSPluginRuntimeMigrator.cs
• /lmes-template/src/CMS.Plugin.MyPluginName.Domain/Data/CMSPluginDbMigrationService.cs
• /lmes-template/src/CMS.Plugin.MyPluginName.EntityFrameworkCore/CMSPluginDbSchemaMigrator.cs
• /lmes-template/src/CMS.Plugin.MyPluginName.EntityFrameworkCore/ICMSPluginDbContext.cs
• /lmes-template/src/CMS.Plugin.MyPluginName.EntityFrameworkCore/CMSPluginEntityFrameworkCoreModule.cs
• /lmes-template/src/CMS.Plugin.MyPluginName.EntityFrameworkCore/appsettings.json
• /lmes-template/src/CMS.Plugin.MyPluginName.MySQL/CMSPluginDbContextFactory.cs

目录

1. 简介
2. 项目结构
3. 核心组件
4. 架构概述
5. 详细组件分析
6. 依赖分析
7. 性能考虑
8. 故障排除指南
9. 结论

简介

UpdateDB.bat 和 UpdateMigrations.bat 使用 EF Core 管理 MySQL、PostgreSQL、SQL Server 的数据库迁移。本文说明设计时脚本的用法，以及它们与运行时迁移器 CMSPluginRuntimeMigrator 的协作方式。

项目结构

本项目采用模块化设计，各数据库平台（MySQL、PostgreSQL、SQL Server）分别拥有独立的项目结构，包含各自的 DbContext、DbContextFactory 以及迁移脚本。所有迁移脚本均位于各自平台项目的 Scripts 目录下。

Diagram sources

• /lmes-template/src/CMS.Plugin.MyPluginName.MySQL/Scripts/UpdateDB.bat
• /lmes-template/src/CMS.Plugin.MyPluginName.PostgreSql/Scripts/UpdateDB.bat
• /lmes-template/src/CMS.Plugin.MyPluginName.SqlServer/Scripts/UpdateDB.bat

Section sources

• /lmes-template/src/CMS.Plugin.MyPluginName.MySQL/Scripts/UpdateDB.bat
• /lmes-template/src/CMS.Plugin.MyPluginName.MySQL/Scripts/UpdateMigrations.bat

核心组件

系统的核心迁移机制由多个组件协同工作：设计时的批处理脚本（UpdateDB.bat 和 UpdateMigrations.bat）用于生成和应用迁移，而运行时的 CMSPluginRuntimeMigrator 则在应用程序启动或项目加载时自动执行数据库迁移，确保环境一致性。

Section sources

• /lmes-template/src/CMS.Plugin.MyPluginName/CMSPluginRuntimeMigrator.cs
• /lmes-template/src/CMS.Plugin.MyPluginName.EntityFrameworkCore/CMSPluginDbSchemaMigrator.cs

架构概述

系统采用分层架构，将数据库迁移逻辑分为设计时和运行时两个阶段。设计时通过 EF Core CLI 命令生成和更新迁移文件；运行时通过依赖注入的服务自动执行迁移。

Diagram sources

• /lmes-template/src/CMS.Plugin.MyPluginName/CMSPluginRuntimeMigrator.cs
• /lmes-template/src/CMS.Plugin.MyPluginName.EntityFrameworkCore/CMSPluginDbSchemaMigrator.cs
• /lmes-template/src/CMS.Plugin.MyPluginName.EntityFrameworkCore/ICMSPluginDbContext.cs

详细组件分析

设计时迁移脚本分析

UpdateMigrations.bat 脚本

该脚本用于生成新的迁移文件。其主要功能是进入项目根目录并执行 dotnet ef migrations add 命令，创建初始迁移或后续更新迁移。脚本中注释部分提供了添加后续迁移的示例命令。

Diagram sources

• /lmes-template/src/CMS.Plugin.MyPluginName.MySQL/Scripts/UpdateMigrations.bat

UpdateDB.bat 脚本

该脚本用于将已生成的迁移应用到目标数据库。它通过 dotnet ef database update 命令执行所有待应用的迁移，使数据库 Schema 与代码模型同步。

Diagram sources

• /lmes-template/src/CMS.Plugin.MyPluginName.MySQL/Scripts/UpdateDB.bat

运行时迁移机制分析

CMSPluginRuntimeMigrator

这是运行时迁移的核心组件，实现了 IProjectRuntimeMigrator 接口。当项目加载器 (IProjectRunner) 加载工程时，该组件会被调用，负责执行数据库迁移流程。

Diagram sources

• /lmes-template/src/CMS.Plugin.MyPluginName/CMSPluginRuntimeMigrator.cs
• /lmes-template/src/CMS.Plugin.MyPluginName.Domain/Data/CMSPluginDbMigrationService.cs
• /lmes-template/src/CMS.Plugin.MyPluginName.EntityFrameworkCore/CMSPluginDbSchemaMigrator.cs

Section sources

• /lmes-template/src/CMS.Plugin.MyPluginName/CMSPluginRuntimeMigrator.cs

依赖分析

系统各组件之间存在明确的依赖关系，遵循依赖倒置原则，通过接口和依赖注入实现松耦合。

Diagram sources

• /lmes-template/src/CMS.Plugin.MyPluginName/CMSPluginRuntimeMigrator.cs
• /lmes-template/src/CMS.Plugin.MyPluginName.Domain/Data/CMSPluginDbMigrationService.cs
• /lmes-template/src/CMS.Plugin.MyPluginName.EntityFrameworkCore/CMSPluginDbSchemaMigrator.cs
• /lmes-template/src/CMS.Plugin.MyPluginName.EntityFrameworkCore/ICMSPluginDbContext.cs

Section sources

• /lmes-template/src/CMS.Plugin.MyPluginName.Domain/Data/CMSPluginDbMigrationService.cs

性能考虑

• 迁移执行时机：设计时迁移应在开发阶段完成，避免在生产环境执行耗时的模式变更。
• 批量迁移：UpdateDB.bat 会一次性应用所有待处理的迁移，建议在非高峰时段执行。
• 连接管理：运行时迁移通过 DI 容器获取数据库连接，确保连接的正确生命周期管理。
• 日志记录：所有迁移操作均有详细日志输出，便于监控和故障排查。

故障排除指南

常见问题及解决方案：

1. EF Core 工具未安装：确保已全局安装 dotnet-ef 工具。
2. 数据库连接失败：检查 appsettings.json 中的连接字符串配置。
3. 迁移冲突：多人开发时，应协调迁移文件的添加，避免冲突。
4. 运行时迁移不执行：确认 CMSPluginRuntimeMigrator 已正确注册到 DI 容器。
5. 平台特定问题：不同数据库平台可能有语法差异，需在目标平台上测试迁移脚本。

Section sources

• /lmes-template/src/CMS.Plugin.MyPluginName.EntityFrameworkCore/appsettings.json
• /lmes-template/src/CMS.Plugin.MyPluginName/CMSPluginRuntimeMigrator.cs

结论

UpdateMigrations.bat 和 UpdateDB.bat 管理设计时迁移，CMSPluginRuntimeMigrator 执行运行时迁移。更新数据库前需核对迁移记录与代码模型。