数据库迁移模式

模式演进策略

默认采用仅增加策略。 仅在必须修改或删除现有结构时，才升级为扩展-收缩策略。

零停机模式

所有生产环境迁移都必须避免锁表，且不能破坏正在运行的应用程序代码。

迁移工具

根据所使用的 ORM 和部署流水线选择匹配的工具。简单 Schema 推荐使用声明式工具；需要精细控制数据操作时，优先选用命令式工具。

回滚策略

数据保留

1. 软删除列 — 使用 _deprecated 后缀重命名列，而非直接删除
2. 快照表 — CREATE TABLE _backup__ AS SELECT * FROM
   时间点恢复（PITR） — 确保 WAL 归档覆盖整个迁移窗口期
   逻辑备份 — 迁移前对受影响表执行 pg_dump

   蓝绿数据库

   1. 主库 → 从库（绿色）复制数据
   2. 在绿色库上应用迁移
   3. 对绿色库运行完整验证套件
   4. 将流量切换至绿色库
   5. 将蓝色库保留为回滚目标（N 小时）
   6. 在确认稳定后下线蓝色库
   

   数据迁移模式

   填充策略

   策略	适用场景
   内联填充（Inline backfill）	小表（< 100K 行）
   分批填充（Batched backfill）	中等规模表（100K–10M 行）
   后台任务（Background job）	大表（10M+ 行）
   懒填充（Lazy backfill）	无需立即强一致性的场景

   批处理示例

   DO $$
   DECLARE
     batch_size INT := 1000;
     rows_updated INT;
   BEGIN
     LOOP
       UPDATE my_table
       SET new_col = compute_value(old_col)
       WHERE id IN (
         SELECT id FROM my_table
         WHERE new_col IS NULL
         LIMIT batch_size
         FOR UPDATE SKIP LOCKED
       );
       GET DIAGNOSTICS rows_updated = ROW_COUNT;
       EXIT WHEN rows_updated = 0;
       PERFORM pg_sleep(0.1);  -- 限流以降低锁压力
       COMMIT;
     END LOOP;
   END $$;
   

   双写期

   适用于扩展-收缩与并行变更：

   1. 双写 — 应用同时向旧列/旧表和新列/新表写入
   2. 填充 — 使用历史数据补全新结构
   3. 校验 — 核查一致性（行数、校验和等）
   4. 切换 — 将读请求切至新结构，并停止向旧结构写入
   5. 清理 — 冷却期后删除旧结构

   迁移测试

   使用类生产数据进行测试

   • 切勿仅在空数据或合成数据上测试
   • 使用脱敏后的生产快照数据
   • 匹配真实数据量 — 在 1K 行上成功的迁移，在 10M 行上可能引发严重锁竞争
   • 复现边界情况：NULL 值、空字符串、最大长度字段、Unicode 字符等

   迁移 CI 流水线

   - name: Test migrations
     steps:
       - run: docker compose up -d db
       - run: npm run migrate:up        # 全量应用迁移
       - run: npm run migrate:down      # 全量回滚
       - run: npm run migrate:up        # 重新应用（验证幂等性）
       - run: npm run test:integration  # 验证应用功能
       - run: npm run migrate:status    # 确认无待执行迁移
   

   每个迁移 PR 必须通过以下流程：up → down → up → 测试。

   迁移检查清单

   迁移前

   • 已在类生产数据量级上完成测试
   • 已编写并验证回滚方案
   • 已创建受影响表的备份
   • 应用代码已兼容新旧两种 Schema
   • 已在预发环境完成执行耗时基准测试
   • 已分析锁影响范围
   • 已配置复制延迟监控

   迁移中

   • 监控锁等待与活跃查询
   • 监控复制延迟
   • 观察错误率是否突增
   • 随时准备执行回滚命令

   迁移后

   • Schema 状态与预期完全一致
   • 集成测试在迁移后的数据库上全部通过
   • 数据完整性已验证（行数、校验和等）
   • ORM 的 Schema / 类型定义已同步更新
   • 已在冷却期后清理弃用结构
   • 迁移过程已记录至团队运行手册

   绝对禁止事项

   1. 绝对禁止 在生产环境直接运行未经测试的迁移
   2. 绝对禁止 在未先移除所有应用层引用并完成部署前，直接删除列
   3. 绝对禁止 在大表上单条语句中添加无默认值的 NOT NULL 列
   4. 绝对禁止 在同一迁移文件中混用 Schema DDL 与数据变更操作
   5. 绝对禁止 在线上系统中重命名列时跳过双写阶段
   6. 绝对禁止 认为迁移是瞬时操作 — 必须始终在生产规模数据上进行基准测试
   7. 绝对禁止 为“加速”迁移而在生产环境中禁用外键检查
   8. 绝对禁止 在迁移尚未完成前，部署依赖该 Schema 变更的应用代码