数据库迁移

要解决的实际问题

手动执行 SQL 变更、多人同时改表、线上环境的 DDL 语句不可回滚，常常导致锁表、脏数据或服务不可用。database-migration 面向这些具体的工程痛点：

• 变更缺少版本记录，无法按顺序回放或回滚
• 大表上直接加列或加约束，容易阻塞写入
• 自动化工具把字段重命名当成 drop + add，导致数据丢失
• 多实例部署时，多个进程同时跑迁移，破坏元数据一致性

核心工作流

技能围绕六步展开，每一步都有可检查的输出：

1. 评估变更类型：判断是向后兼容的增量变更还是破坏性变更，破坏性变更需要多阶段迁移。
2. 选择迁移框架：根据技术栈匹配 Alembic（Python/SQLAlchemy）、Prisma Migrate（TypeScript/Prisma）、Flyway（Java/SQL）或 Knex（Node.js），也覆盖 Django Migrations 和 Sequelize。
3. 生成迁移脚本：优先通过工具的 autogenerate 能力从 schema 差异生成脚本，再人工审阅和补全 downgrade 逻辑；数据回填写进同一迁移文件，保证 schema 和数据变更原子化。
4. 在 staging 验证：对镜像生产结构的数据库执行迁移，确认应用、查询和回滚路径都正常。
5. 零宕机部署：使用 expand-and-contract 模式，先加新结构，双写，回填数据，切换读流量，最后收缩旧结构。
6. 部署后监控：检查迁移框架的 status 命令和版本表，观察应用日志与数据库性能。

适用边界与注意点

• 始终手写回滚逻辑：不要假设部署失败后可以临时手写修复，回滚必须预先版本化。
• 审阅所有 autogenerate 结果：重命名字段可能被识别为 drop + add，需要改用 op.alter_column() 或原生 ALTER TABLE ... RENAME COLUMN。
• 大表加 NOT NULL 列：旧版 PostgreSQL 会锁表，应先加可空列，分批回填，再设置约束。
• 并发迁移：多实例部署时只允许一个实例执行迁移，可使用 advisory lock 或把迁移作为独立部署前置步骤。
• 枚举类型变更：PostgreSQL 的枚举加值不是事务性的，需要新建枚举、迁移列、再删除旧枚举；更灵活的方案是改用带 CHECK 约束的 VARCHAR。
• 纯数据迁移：不修改 schema 的字段加密或数据清洗，也必须放进版本化迁移文件，保证各环境一致可重放。