---
name: database-migration
type: procedure
when: '数据库变更, 表结构修改, migration, DDL, 加字段, 建表, 索引, 数据迁移, 表结构变更'
scope:
  - backend
products:
  - '*'
id: ka-procedure-数据库迁移流程
asset_kind: procedure
lifecycle_status: active
authority: supporting
owner_mechanism_id: mc-knowledge-asset-governance
routes:
  - code_change
primary_triggers:
  - 数据库迁移流程
secondary_triggers: []
negative_triggers: []
priority: P1
specificity: 5
consumes:
  - mc-knowledge-asset-governance
emits:
  - migration_script
  - rollback_script
  - migration_compatibility_check
required_evidence:
  - execution_evidence
version: 1.1.0
last_reviewed: '2026-06-01'
stages: ["编码与单元测试", "联调验证"]
---

## 适用场景
数据库表结构变更（新增表、加字段、改字段、加索引、数据迁移等）。所有 DDL 变更必须通过 migration 脚本管理，禁止手动执行。

## 步骤
1. 评估变更类型：加列、改列、删列、加索引、数据迁移、新建表
2. 确认向前兼容性：新列必须有默认值或允许 NULL，不删除正在使用的列
3. 编写 migration 脚本（Flyway/MyBatis Migrations），DDL 脚本放 resources/db，文件名 V{version}__{description}.sql（正向）和 U{version}__{description}.sql（回滚）
4. 确保 migration 脚本幂等（重复执行不出错）
5. 编写回滚脚本（每个 migration 必须有对应的 rollback）
6. 禁止在 migration 脚本中写业务逻辑（业务变更走应用代码）
7. 大表加列必须指定默认值或使用分批更新
8. 在开发环境执行 migration，验证表结构变更正确
9. 检查数据迁移逻辑：大数据量迁移需分批执行（每批 1000 条）
10. 在测试环境验证：运行应用 + 执行全量测试
11. 评估执行时间：大表加索引按锁表风险处理，需在低峰期执行并准备回滚窗口
12. 生产执行前备份数据库（全量或变更表）

## 检查点
- [ ] migration 脚本有对应回滚脚本
- [ ] migration 脚本幂等（可重复执行）
- [ ] 新增列有默认值或允许 NULL（向前兼容）
- [ ] migration 脚本无业务逻辑
- [ ] 大数据量迁移使用分批策略
- [ ] 生产执行前已完成数据库备份

## 注意事项
- 禁止使用 DROP COLUMN（应标记为 deprecated 后续清理）
- 加索引在 >100 万行表上使用 ONLINE DDL 或 pt-online-schema-change
- migration 脚本一旦执行到生产不可修改（只能新增补偿脚本）
- 字段兼容策略必须同时覆盖四层：数据库、接口契约、前端展示、导出逻辑
