数据迁移Skill：数据库迁移自动化

一、数据迁移Skill的设计

数据迁移Skill是一个专为开发团队设计的自动化工具，旨在简化和标准化数据库Schema变更的全流程管理。随着业务需求的不断演进，数据库结构不可避免地需要频繁调整——新增字段、修改表结构、添加索引等。传统的手动迁移方式容易出错、难以追溯，且跨团队协作时极易产生冲突。数据迁移Skill通过将迁移流程自动化，解决了这些痛点。

该Skill的核心设计理念围绕三个关键目标：自动化数据库迁移流程、确保迁移安全和可回滚、统一团队迁移规范。通过封装主流迁移框架（Alembic、Django Migrations、Prisma Migrate）的最佳实践，它让开发者能够以声明式的方式描述数据库变更，而将繁琐的迁移脚本生成、版本管理和执行调度交由Skill自动处理。

在设计层面，数据迁移Skill遵循以下架构原则：

声明式配置：开发者只需描述最终想要的数据库状态，迁移路径由Skill自动规划
幂等性：同一迁移脚本在任何环境下多次执行都能得到相同结果
可逆性：每次迁移都必须提供回滚方案，确保可以安全回退到上一个版本
审计追踪：所有迁移操作记录详细日志，包括执行人、时间戳、SQL语句和执行结果

核心设计思想：数据迁移不是一次性操作，而是一个需要版本控制、自动化执行和安全管理的过程。一个好的迁移Skill应当让"安全地修改数据库"像提交代码一样自然。

二、迁移文件自动生成

迁移文件自动生成是数据迁移Skill的核心功能。它通过分析模型定义的变化，自动生成对应的迁移脚本，大幅减少手动编写重复代码的工作量。Skill支持多种主流ORM和迁移框架，能够根据项目配置自动选择合适的迁移引擎。

Alembic迁移生成

对于使用SQLAlchemy的Python项目，Skill集成了Alembic的自动生成能力。当检测到模型定义发生变化时，Skill自动执行以下流程：

# 检测模型变化并自动生成迁移脚本
def generate_migration(message, autogenerate=True):
    """自动分析模型变化并生成迁移脚本"""
    with alembic_config() as config:
        if autogenerate:
            # 自动检测模型与当前数据库的差异
            script = AlembicScript(config)
            script.run_revision(message=message, autogenerate=True)
        else:
            # 创建空迁移，供手动编写
            script = AlembicScript(config)
            script.run_revision(message=message, autogenerate=False)
        return script.revision

支持主流迁移框架

数据迁移Skill支持以下迁移框架，并根据项目类型自动选择：

框架	适用场景	命令示例
Alembic	Python / SQLAlchemy 项目	alembic revision --autogenerate -m "描述"
Django Migrations	Python / Django 项目	python manage.py makemigrations
Prisma Migrate	Node.js / TypeScript 项目	prisma migrate dev --name "描述"
Entity Framework Migrations	.NET 项目	dotnet ef migrations add 描述
Flyway	Java / JVM 项目	flyway migrate

迁移文件代码模板

自动生成的迁移文件包含完整的模板结构，开发者只需关注业务逻辑即可：

"""数据迁移Skill自动生成的迁移文件
Revision ID: a1b2c3d4e5f6
Revises: 9z8y7x6w5v4u
Create Date: 2026-05-08 09:30:23.123456
"""

from alembic import op
import sqlalchemy as sa

# revision identifiers
revision = 'a1b2c3d4e5f6'
down_revision = '9z8y7x6w5v4u'

def upgrade():
    '''执行迁移：添加用户角色和状态字段'''
    op.add_column('users', sa.Column('role', sa.String(50)))
    op.add_column('users', sa.Column('status', sa.String(20),
                   server_default='active'))
    op.create_index('ix_users_role', 'users', ['role'])

def downgrade():
    '''回滚迁移：移除添加的字段和索引'''
    op.drop_index('ix_users_role')
    op.drop_column('users', 'status')
    op.drop_column('users', 'role')

最佳实践：迁移文件名应采用语义化命名，包含变更的简要描述。例如：20260508_add_user_role_field。避免使用模糊不清的名称如"fix"或"update"，否则在回顾迁移历史时将难以定位。

三、迁移预览和安全检查

在实际执行迁移之前，数据迁移Skill提供了全面的预览和安全检查机制。这是确保生产环境数据库安全的关键防线。Skill会从多个维度对即将执行的迁移进行风险评估。

生成迁移对应的SQL语句预览

Skill能够将ORM层面的迁移描述转换为纯SQL语句，让开发者清晰地看到数据库实际要执行的操作：

# 预览迁移将要执行的SQL语句
$ skill db:migrate --preview --revision a1b2c3d4e5f6

# 输出预览结果
═══════════════════════════════════════════
Migration Preview: a1b2c3d4e5f6
File: 20260508_add_user_role_field.py
═══════════════════════════════════════════

-- upgrade SQL (2 operations):
 1. ALTER TABLE users ADD COLUMN role VARCHAR(50) NULL;
 2. ALTER TABLE users ADD COLUMN status VARCHAR(20) DEFAULT 'active' NOT NULL;
 3. CREATE INDEX ix_users_role ON users (role);

-- downgrade SQL (3 operations):
 1. DROP INDEX ix_users_role;
 2. ALTER TABLE users DROP COLUMN status;
 3. ALTER TABLE users DROP COLUMN role;

-- 风险评估结果：无高风险操作
✔ 无 DROP COLUMN 操作
✔ 无 ALTER TABLE ... DROP 数据丢失风险
✔ 外键约束无变化
✔ 索引变更：新增 1 个索引
⚠ 建议：对大表添加索引时，考虑使用 CONCURRENTLY

风险检测规则

数据迁移Skill内置了丰富的风险检测规则，在预览阶段自动执行安全检查：

高风险操作检测：以下操作会被标记为高风险，需要额外审批才能执行：

DROP COLUMN — 删除列可能导致数据永久丢失
DROP TABLE — 删除表是最高风险操作之一
ALTER COLUMN ... TYPE — 修改列类型可能导致数据截断
RENAME COLUMN / TABLE — 重命名会破坏现有查询

外键约束和索引变化检查

Skill会自动分析迁移中的外键约束和索引变化，评估对现有数据完整性和查询性能的影响：

外键变更：检测新增/删除的外键约束，评估级联删除的影响范围
索引变化：分析新增索引是否需要长时间锁定表（如PostgreSQL中需确认是否使用CONCURRENTLY）
唯一约束：检查新增唯一约束是否与现有数据冲突
默认值变更：评估新增默认值对现有行的影响

数据完整性影响分析

针对可能影响数据的迁移操作，Skill会执行数据完整性检查：

-- 数据完整性检查报告
═══════════════════════════════════════════
Data Integrity Check Report
═══════════════════════════════════════════
Table: users
  ✔ 新增列 role(VARCHAR(50)) - 允许NULL，不影响现有数据
  ✔ 新增列 status(VARCHAR(20)) - 有默认值 'active'
    将为 15,234 条现有记录设置默认值
  ✔ 新增索引 ix_users_role - 不影响数据，仅提升查询性能

受影响的行数：15,234
预计锁表时间：< 1秒（MySQL InnoDB）
迁移策略：在线DDL，无需停机                    

安全检查黄金法则：任何修改现有数据的迁移都必须经过预览和审批流程。预览阶段应回答三个问题：影响多少行数据？是否需要锁表？是否可以回滚？只有当三个问题都有明确答案时，才适合在生产环境执行迁移。

四、迁移执行和回滚

迁移执行是数据迁移Skill的核心工作流环节。Skill提供了一站式的迁移执行命令，并内置了安全保护机制，确保即使在迁移失败时也能快速恢复。

执行待定迁移

通过简单的命令即可执行所有待定的迁移脚本：

# 执行所有待定的迁移
$ skill db:migrate --env production --target upgrade

# 执行到指定版本
$ skill db:migrate --revision a1b2c3d4e5f6 --target upgrade

# 执行结果输出
═══════════════════════════════════════════
Migration Execution Report
Environment: production
═══════════════════════════════════════════
✔ 已备份 users 表（15,234 行）
✔ 已执行迁移 a1b2c3d4e5f6 (add_user_role_field)
  - ALTER TABLE users ADD COLUMN role → 完成 (0.32s)
  - ALTER TABLE users ADD COLUMN status → 完成 (0.28s)
  - CREATE INDEX ix_users_role → 完成 (0.45s)
✔ 迁移版本已记录到 alembic_version
✔ 当前数据库版本: a1b2c3d4e5f6

总计执行时间：1.05s
迁移状态：成功

自动备份受影响的数据表

在执行可能修改数据的迁移之前，Skill会自动创建受影响表的备份：

自动检测：分析迁移脚本，识别哪些表会被修改
创建备份：在执行迁移前，使用 CREATE TABLE ... AS SELECT 或导出为CSV/JSON
备份标记：备份表以 _bak_YYYYMMDDHHMMSS 后缀命名，方便后续清理
备份验证：验证备份的行数和校验和，确保备份完整性

备份策略说明：对于超大规模表（行数超过100万），Skill会使用分批备份策略，避免长时间锁定表。备份完成后会在迁移日志中记录备份文件的位置和校验值，以便需要时快速恢复。

迁移失败自动回滚

当迁移执行过程中发生错误时，Skill会自动执行回滚操作：

# 迁移失败时的自动回滚日志
═══════════════════════════════════════════
Migration Failure & Auto-Rollback Report
═══════════════════════════════════════════
✖ 迁移 a1b2c3d4e5f6 执行失败
  错误信息: Duplicate column name 'role'
  失败步骤: ALTER TABLE users ADD COLUMN role VARCHAR(50)

⟳ 自动回滚中...
  ✔ 正在执行回滚操作 (downgrade)
  ✔ 已撤销: CREATE INDEX ix_users_role
  ✔ 已撤销: ALTER TABLE users DROP COLUMN status (无数据丢失)
  ✔ 已撤销: ALTER TABLE users DROP COLUMN role (无数据丢失)
  ✔ 数据库版本已回退到: 9z8y7x6w5v4u

恢复状态：成功
数据完整性：已确认无损

支持upgrade/downgrade指定版本

Skill支持灵活地在不同迁移版本之间切换：

命令	说明
`skill db:migrate --target upgrade`	升级到最新版本
`skill db:migrate --revision a1b2c3 --target upgrade`	升级到指定版本
`skill db:migrate --target downgrade`	回滚到上一个版本
`skill db:migrate --revision 9z8y7x6 --target downgrade`	回滚到指定历史版本
`skill db:migrate --rollback-all`	回滚所有迁移（谨慎使用）

警告：回滚操作会对数据库进行结构性修改。在回滚到指定版本时，所有在该版本之后执行的迁移都会被依次回退。如果只想撤销某个特定的迁移（而非所有之后的迁移），需要先确认迁移之间是否存在依赖关系。对于生产环境，建议先在预发布环境测试回滚流程。

五、多环境迁移管理

在实际项目中，数据库通常需要部署在开发（Development）、测试（Staging/Testing）和生产（Production）等多个环境中。数据迁移Skill提供了完善的多环境迁移管理功能，确保各环境的数据库Schema保持同步和一致。

开发/测试/生产环境迁移同步

Skill能够识别当前环境并执行相应的迁移策略：

# 在不同环境中执行迁移
# 开发环境 — 自动生成并执行
$ skill db:migrate --env development --autogenerate
✔ 检测到模型变更: 2 项
✔ 自动生成迁移脚本: 20260508_add_user_role_field.py
✔ 已执行迁移

# 测试环境 — 预览后确认执行
$ skill db:migrate --env staging --preview
⚠ 即将在 staging 环境执行 1 个迁移
请输入 y 确认执行: y
✔ 迁移执行成功

# 生产环境 — 需要审批流程
$ skill db:migrate --env production
⚠ 生产环境迁移需要审批
📧 已发送审批请求至: dba@company.com
⏳ 等待审批中...

迁移版本一致性检查

Skill会自动比对各环境的迁移版本，检测不一致的情况：

版本快照：定期采集各环境的迁移版本号，生成一致性报告
差异告警：当某个环境的迁移版本落后于其他环境时，自动发出告警通知
漂移检测：检测数据库中是否存在未通过迁移工具管理的"脏"变更（即Schema漂移）

# 环境迁移版本一致性检查报告
═══════════════════════════════════════════
Migration Version Consistency Report
═══════════════════════════════════════════
  环境       当前版本         最新版本      状态
  ─────────────────────────────────────────
  development  a1b2c3d4e5f6    a1b2c3d4e5f6  ✔ 一致
  staging      a1b2c3d4e5f6    a1b2c3d4e5f6  ✔ 一致
  production   9z8y7x6w5v4u    a1b2c3d4e5f6  ✖ 落后 1 个版本

⚠ production 环境落后于其他环境
  建议: 安排窗口执行 skill db:migrate --env production

迁移冲突检测和解决

当多个开发者同时修改数据库模型时，可能产生迁移冲突。Skill的冲突检测机制能够提前发现并协助解决这些问题：

分支检测：检测迁移历史是否存在分叉（多个迁移共享同一个父版本）
依赖分析：分析冲突迁移的依赖关系，确定合并策略
自动合并：对于无冲突的并行迁移，自动生成合并迁移脚本
手动解决：对于存在真正冲突的迁移（如同时修改同一列），引导开发者手动解决

# 冲突检测日志
═══════════════════════════════════════════
Migration Conflict Detection
═══════════════════════════════════════════
检测到迁移历史分叉:

  9z8y7x6w5v4u (base)
  ├── a1b2c3d4e5f6 (alice: add_user_role_field)
  └── b2c3d4e5f6a7 (bob: add_user_preferences)

⚠ 两个迁移共享同一个父版本 9z8y7x6w5v4u
  冲突分析: 无重叠操作 - 可自动合并

✔ 生成合并迁移: m3n4o5p6q7r8 (merge_conflict_resolution)
  - 合并 alice/add_user_role_field
  - 合并 bob/add_user_preferences
  - 执行顺序: a1b2c3 → b2c3d4

生产环境迁移的安全审批流程

生产环境的迁移需要经过严格的安全审批流程，Skill内置了完整的审批机制：

安全审批流程：

提交申请：开发者发起生产环境迁移请求，包含迁移脚本预览和风险评估报告
自动审查：Skill自动执行安全检查，标记高风险操作并生成审查报告
人工审批：DBA或技术负责人审查迁移内容，批准或驳回请求
窗口调度：审批通过后，在预定的维护窗口内执行迁移
执行确认：迁移完成后通知所有相关方，更新审计日志

要点总结：数据库迁移是应用程序变更中最具风险的操作之一。通过数据迁移Skill的自动化管理，团队可以将迁移纳入标准化的开发流程，享有版本控制、自动化检查、安全审批和快速回滚等能力。最终目标是让数据库Schema的变更像代码变更一样安全、可追溯、易于协作。