---
name: database-migration
description: 数据库渐进迁移（database migration expand contract rollback PostgreSQL）。把数据库结构变更拆成兼容扩展、可重跑回填、切换和清理，保留可恢复路径。用于给已有大表加字段并迁移旧数据。;字段改名怎样不影响旧版本？;检查数据库迁移和回滚方案。
---

# 数据库渐进迁移

把数据库结构变更拆成兼容扩展、可重跑回填、切换和清理，保留可恢复路径。

## 输入与开始方式

- `change`：当前/目标schema、数据库版本和业务不变量。先找受影响入口与写入者。
- `traffic`：表规模、读写模式、消费者版本和部署顺序。缺规模先做小样本演练，估计项写明。
- `recovery`：备份、恢复时间目标、回滚和校验方式。先确认能恢复何种数据，再决定删旧字段时机。

缺少非关键资料时，先给明确假设下的草案或局部结果；资料补齐后只重验受影响部分。授权已覆盖的可逆工作继续，不重复确认。

## 执行

1. 定位所有读写者与schema约束，确认数据库版本和变更影响。
2. 设计expand阶段让旧新客户端共存，保持旧行为可用。
3. 按稳定主键分批回填并保存进度，更新条件避免覆盖新写入。
4. 检查锁、时延、数据完整及新旧读路径，再切换消费者。
5. 确认旧写入者消失且恢复路径可用后收缩；记录不可逆点和恢复步骤。

按需要读 [专业方法](references/professional-method.md) 和 [完整案例](references/delivery-template.md)。

## 交付

- `sequence`：扩展到收缩顺序。
- `backfill`：可重跑回填。
- `verification`：锁和数据验证。
- `recoveryPlan`：回退和清理。

## 检查结果

- 旧新版本共存时先扩展并双读/双写或兼容映射，校验后才删旧。
- 固定分批边界、检查点与幂等规则，核行数及业务值。
- 按实际版本检查锁/耗时/约束，数据检查含空值、冲突和消费者读取。
- 区分代码回滚、数据恢复及不可逆点，满足条件后清理旧路径。

检查方法和证据要求在 [method.json](method.json)；参考 [作者正反例](evals/professional-cases.json) 识别实际错误。

## 需要额外处理的动作

生产DDL和不可逆数据删除按已有授权及恢复条件执行；迁移脚本、兼容代码和隔离演练可继续。
