业务表要加一个字段,开发环境里通常只需要几秒。到了线上,难点会变成另一件事:旧实例还在写,新实例已经开始读,历史数据只迁了一半,值班同事还需要保留回滚按钮。
假设一个订单服务准备把金额字段从 integer 扩展为 bigint。直接修改类型看起来最省事,但数据库操作、应用滚动发布和历史数据修复并不共享同一个提交点。某个部署任务显示成功,无法证明三者已经一起完成。
本文用这个场景拆解 expand-contract 迁移:先扩展可兼容的数据结构,再迁移数据和读写职责,最后收缩旧结构。文章按 PostgreSQL 17 的官方文档讨论具体数据库行为;容量数字是明确列出的设计假设,并非生产测量结果。文中的 Python 顺序模型已经执行,SQL、数据库锁竞争和压力测试尚未实机执行。
一、先把真正要改变的契约写下来
示例中的 orders 表有八千万行,id 是不可修改的 bigint 主键,amount_cents 是非空 integer。金额表示各订单币种的最小货币单位。本次只扩展整数范围,不转换汇率,不改变货币单位,也不重新解释历史金额。新列叫 amount_minor,类型为 bigint。
服务有二十个应用实例,每秒约八千次读、千五百次写。白天不能停写,每天有六小时较宽松的维护窗口。除了 HTTP 服务,还有退款任务、批量导入和后台修复脚本。所有这些入口都是迁移范围的一部分,不能只看 Deployment 是否滚动完成。
先明确三个约束。第一,读旧列期间,旧列始终是业务事实来源。第二,过渡版本在同一个数据库事务内更新两列。第三,在旧版本的回退窗口结束前,新功能仍然遵守旧 integer 的取值范围。提前接受超过上限或低于下限的金额,会让旧代码无法表达已经存在的数据。
这里的兼容包括数据库结构、存量数据、写入能力和接口表示。即使数据库支持 bigint,JSON 客户端、报表工具或 JavaScript 计算也未必能安全承接完整的大整数范围。因此,对外协议是否采用十进制字符串,需要单独验收,不能跟着换列顺便上线。
二、先比较方案,再决定是否需要在线迁移
第一种方案是安排维护窗口,暂停写入,修改字段并验证,再部署匹配的新版本。它的优点是状态少、路径短,故障定位也直接。如果表只有几万行,业务允许明确的短暂停机,排练证明锁等待和数据处理能在窗口内完成,这通常比维护一周的双列协议更划算。
本例的数据量和可用性约束不适合把风险压进一次操作,所以选择第二种方案:新增影子列,通过应用过渡版本维护两列,分批回填,切换读取,最后删除旧列。它增加了发布次数和清理责任,却把大部分工作变成可以暂停、检查、继续的步骤。Prisma 的官方指南也介绍了先扩展、迁移、再收缩的基本模式;下面的多版本门禁和分批调度,是针对大表持续写入场景补充的设计。参考:Expand-and-contract migrations
还有一种实际可选的变体:由数据库触发器把旧列同步到新列。数据库内的 BEFORE 行级触发器可以修改即将写入的行,适合写入来源很多、难以同时升级的系统。参考:PostgreSQL CREATE TRIGGER
触发器把兼容逻辑集中到一个位置,也把转换成本和失败风险放进每一次写事务。使用它需要确认批量导入、复制设置和运维操作是否会绕过触发器,并规定哪个方向有权覆盖另一个方向。本例能完整管理所有写入口,因此采用应用过渡版本,避免把临时业务逻辑长期留在数据库中。若无法盘清写入口,这个选择就不再成立。
三、把一次发布拆成四种明确的版本能力
建议直接用读写能力命名发布阶段,而不是只有一个“迁移已开启”开关。
- V0:读旧列,只写旧列。
- V1:读旧列,在同一条语句或同一事务中写两列。
- V2:读新列,仍在同一事务中写两列。
- V3:读新列,只写新列。
数据库先增加允许空值的新列,再发布 V1。V0 与 V1 共存时,整个系统继续读旧列。这期间允许新列暂时缺失或陈旧,因为它还没有成为读取依据。
随后设置一个明确的门槛:所有写入口都已经升级为 V1,V0 不再接收任务,旧进程持有的事务已经结束,调度器不会再次启动旧镜像。低频月度任务、失败队列中的旧任务载荷、人工修复程序,都要有负责人确认。只检查线上请求的版本号不够。
组件之间的数据流可以写成下面这样:
HTTP / 后台任务 / 导入程序
│
▼
V1 兼容写入层
│ 同一事务更新两列
▼
PostgreSQL orders
▲ │
│ ▼
分批迁移器 分段一致性校验
│ │
▼ ▼
范围进度表 发布门禁与告警
迁移器没有决定业务金额的权力,只负责把当前旧列映射到新列。校验器负责发现差异,不自动切换流量。发布控制负责确认版本、数据和容量条件同时满足。三个职责分开后,迁移器暂停不会迫使应用回滚,应用回滚也不需要立刻删除已经完成的回填。
四、最容易漏掉的竞态:非空的新列也可能是旧值
考虑一行金额最初为 100。V1 把金额改成 120,同时写入两列。随后仍存活的 V0 把旧列改成 150。此时旧列是 150,新列是 120,而且新列并不为空。
如果回填条件只是 amount_minor IS NULL,这行会被永久跳过。读取时使用 COALESCE(amount_minor, amount_cents) 也会返回错误的 120。空值比例降到零,不能证明迁移成功。
所以,本例在所有旧写入者退出后,修复条件覆盖“缺失”和“不一致”两类数据。回填必须使用数据库当前行中的旧值,不能先把旧值读到进程内存,过一会儿再覆盖新列。后一种做法可能把刚刚由在线事务写入的新金额覆盖成旧快照。
V1 的更新形式可以很简单:
-- $1 为订单 ID,$2 为同一份经过校验的金额输入。
UPDATE orders
SET amount_cents = $2::integer,
amount_minor = $2::bigint
WHERE id = $1;
两个赋值来自同一个输入。旧列上的 integer 转换也让越界值在兼容期被拒绝。插入、冲突更新和批量导入必须遵循相同规则,不能只改普通 UPDATE。这个协议保证两列一致,并不替代业务本来需要的乐观锁或余额并发控制。
对于回填,直接执行 SET amount_minor = amount_cents::bigint,让计算与更新发生在数据库里。在 PostgreSQL 的 Read Committed 下,遇到并发修改时,更新会等待并检查更新后的目标行条件。这里依赖的是同一行上的事务协调,不是进程之间自行约定的先后顺序。参考:Transaction Isolation
五、扩列和回填必须使用不同的运行方式
扩列是短 DDL,回填是长期数据任务,不应该塞进一个持续数小时的事务。扩列可以先按下面的方式准备,具体超时数值需要在目标库排练:
BEGIN;
SET LOCAL lock_timeout = '800ms';
SET LOCAL statement_timeout = '5s';
ALTER TABLE orders ADD COLUMN amount_minor bigint;
COMMIT;
不设置默认值,让“尚未填充”保持可识别。本例也不需要让默认值代替真实金额。PostgreSQL 对常量默认值有快速扩列机制,但易变默认表达式可能带来逐行工作,不能把所有 ADD COLUMN 都视为同一种成本。参考:Modifying Tables
短操作仍然需要锁。应先检查长事务与锁等待,让 DDL 在拿不到锁时尽快失败,而不是一直排队。lock_timeout 限制每次锁获取等待,statement_timeout 限制语句时间,两者用途不同。示例只对当前事务生效,避免把迁移的容忍度应用到所有业务连接。参考:Client Connection Defaults
回填采用持久化范围清单。先记录扫描上界,再把主键空间划分为互不重叠的半开区间。本例用单个迁移进程串行处理,范围内预计约五百行。稀疏主键下应按实际分布调整区间,不能把五百个 ID 当成必然存在的五百行。
每个范围用一个事务,同时提交数据修复与进度。下面的 $1、$2 分别为区间下界和上界,由数据库驱动绑定;两条语句必须使用同一连接。进度表预先保存迁移名称、范围边界和状态,并对迁移名称与下界建立唯一约束。
BEGIN;
SET LOCAL lock_timeout = '500ms';
SET LOCAL statement_timeout = '3s';
UPDATE orders
SET amount_minor = amount_cents::bigint
WHERE id >= $1 AND id < $2
AND amount_minor IS DISTINCT FROM amount_cents::bigint;
UPDATE migration_ranges
SET state = 'done'
WHERE migration_name = 'orders_amount_minor_v1'
AND range_start = $1
AND range_end = $2;
COMMIT;
IS DISTINCT FROM 同时覆盖空值和普通的不等值。进度更新必须命中恰好一条范围记录,否则客户端应回滚并检查清单。若数据更新后进程崩溃,事务未提交时两部分都不生效;若提交成功但响应丢失,重启后读取进度表即可判断,重复执行同一范围也不会改变已经一致的数据。
这里有意不使用 SKIP LOCKED。它会跳过当前拿不到的行锁,如果随后把整个范围标记为完成,忙碌行可能再也不会被修复。需要并行扫描时可以设计补扫清单,但必须证明遗漏会被再次覆盖。官方文档同样提醒,跳过锁定行提供的并不是完整一致的数据视图。参考:SELECT 的锁定选项
扫描上界也不是“提交时间边界”。有些事务可能提前分配 ID、较晚才提交。之所以允许固定上界,是因为门禁之后所有新插入都经过 V1,同时写好两列。这个证明依赖旧事务已排空,不能拿自增主键代替排空检查。
六、迁移速度要从数据库余量推导
先做一个可复算的预算。假设每批确实更新五百行,数据库处理与提交共需一百五十毫秒,再休息三百五十毫秒,平均每秒处理一千行。八千万行的理想时间约为二十二点二二小时。
如果考虑业务高峰、锁冲突和人工暂停,维护窗口内只有百分之七十的时间能够按上述速率运行,总窗口时间约三十一点七五小时。每天六小时,需要进入第六个维护窗口才能完成。这种进度并不异常,也没有必要为了让发布当天“全绿”而提高数据库负载。
继续假设每个回填行平均产生一千二百字节 WAL,则本次总增量约九十六 GB,执行期间约每秒一点二 MB。如果副本落后六小时,仅回填部分就可能增加约二十五点九二 GB 的未消费 WAL。这里使用十进制 GB 和 MB。实际值必须从小规模试跑测量,还要叠加业务写入、检查点、索引维护和复制保留策略。
在线业务本来每秒写千五百行,再增加一千行回填,相当于行更新次数增加约三分之二。即便 CPU 看起来空闲,存储延迟、复制回放和旧行版本回收也可能先成为瓶颈。PostgreSQL 的更新不会立即移除旧行版本,回填期间应一起观察 vacuum 与空间增长。参考:Routine Vacuuming
建议让调速规则至少考虑业务写入的尾延迟、复制延迟、空闲磁盘和每批耗时。本例可以把“业务 P99 连续五分钟比基线高百分之二十”或“复制延迟超过十秒”设为初始暂停条件,但这些只是示范阈值,必须服从服务实际 SLO。恢复时从较低速度开始,避免在积压尚未消化时立刻回到原速率。
迁移仪表盘不能只显示完成百分比。还要展示最近成功区间、未完成区间数量、修复行数、失败原因、当前速率及暂停原因。完成行数增加但差异数量不降,往往意味着仍有漏网的旧写入者。
七、验证完成后才能移交读取职责
范围清单全部完成只是第一层证据。第二层是分段检查空值与不一致,确保没有区间遗漏。第三层是以真实读取路径做影子比较,覆盖普通查询、详情页、导出、退款和报表。抽样可以用于早期发现问题,最终门禁不能只靠抽样。
回填结束后,再增加约束作为数据库侧的保护。例如,对新列先增加 CHECK (amount_minor IS NOT NULL) NOT VALID,随后单独执行 VALIDATE;确认有效后再设置 NOT NULL。需要让两列一致的阶段,也可增加并验证对应的相等约束。不要在历史空值仍然很多时贸然加非空检查,因为 NOT VALID 仍会约束之后的插入和更新。
这些操作需要独立安排:ALTER TABLE 通常获取较强的锁,而 VALIDATE CONSTRAINT 使用不同的锁级别;已有有效检查约束在满足证明条件时,还可避免 SET NOT NULL 的重复扫描。这里应逐条检查目标版本的执行计划与锁影响。参考:PostgreSQL ALTER TABLE
随后灰度发布 V2:先让少量实例读新列,继续双列写入。确认查询结果、序列化、性能和错误率符合预期,再扩大范围。若新查询需要索引,应把建索引列成单独步骤。CREATE INDEX CONCURRENTLY 不能放进普通事务块;失败后还可能留下无效索引,必须检查状态,而不是只看迁移记录里有没有索引名称。参考:CREATE INDEX
本例原有主要查询按主键取订单,不因换金额列自动增加新索引。迁移期每多一个索引,都要解释它服务什么查询,以及它给八千万次更新增加了多少代价。
八、回滚按钮有明确的有效期
V1 阶段,读取仍走旧列,迁移器出错可以暂停,保留已经填好的新列。若必须退回 V0,则“所有写入者已兼容”的门禁立即失效;之后再进入 V2 前,需要重新排空旧写入者、修复差异并校验,不能复用此前的完成状态。
V2 阶段,只要仍然双写、金额没有超出旧类型范围,通常可以退回 V1,让读取重新回到旧列。这是保留旧列的主要价值。但若问题来自金额业务计算本身,两列可能同时写错,切换读取无法修复数据,需要按业务审计记录处理。
决定进入 V3 时,应先完成回退窗口验收,并明确不再把读旧列的 V0、V1 作为回退目标。因为旧列最初是 NOT NULL,在部署只写新列的版本之前,必须解除旧列的非空要求,以及任何要求两列持续相等的过渡约束,否则新插入会失败。
V3 滚动期间与 V2 共存仍有一个条件:新金额范围暂不放开。只写新列开始后,旧列会逐渐陈旧,但 V2 读取新列,因此不能简单断言所有旧版本都不可回退。只有确认 V2 不依赖两列持续相等、旧列仍然存在、所有金额仍可转换为 integer,才可把它保留为回退目标,并提前排练。
等最后一个 V2 实例、后台任务和在途事务都退出,团队也决定结束 V2 的回退窗口后,才能放开金额范围。接受旧 integer 无法表示的值,才是本例另一个明确的不可直接回退边界。此后重新部署 V2,会让相关双写发生转换错误。
删除旧列是最后一个独立变更。先确认没有视图、导出脚本、ORM 映射、数据同步和告警查询引用它,再安排删除。恢复备份可以用于灾难恢复,但不是这种变更的廉价撤销键:回到旧时间点还意味着处理之后已经发生的业务写入。旧列已经删除或超范围数据已经落库时,通常需要修复前进,或者专门设计反向数据迁移。
九、实际验证了什么,还有什么没有验证
为了检查上述推理,执行了一个不依赖第三方库的 Python 模型。它先复现“新列非空但陈旧”与“客户端旧快照覆盖新值”两种反例,再枚举四种初始行状态,以及两次兼容写入、两次回填的全部排列,共九十六种顺序。
下面是已经执行过的核心模型。每个操作代表一次完成提交的单行事务,B1 和 B2 都表示从当前旧列回填。模型刻意把 V0 排除在门禁之后的序列之外。
from itertools import permutations
initial_rows = ((100, None), (100, 80), (100, 100), (100, 120))
operations = ('W120', 'W150', 'B1', 'B2')
checks = 0
for initial in initial_rows:
for schedule in permutations(operations):
row = initial
for op in schedule:
if op.startswith('W'):
value = int(op[1:])
row = (value, value)
else:
row = (row[0], row[0])
assert row[0] == row[1]
checks += 1
assert checks == 96
print(f'{checks} schedules passed')
运行结果为 96 schedules passed。同时执行的容量算式得到理想二十二点二二小时、百分之七十可运行比例下三十一点七五小时、假设 WAL 总量九十六 GB,与前面的预算一致。
这证明了模型中已声明的顺序性质,没有证明 PostgreSQL 实际执行器、驱动事务边界或生产容量。本次环境没有 PostgreSQL 客户端、服务端与 Docker,因此没有执行文章中的 SQL,也没有测量 DDL 锁等待、真实 WAL、主从切换和 vacuum 行为。
上线排练还需要至少覆盖:旧事务跨越版本切换、批量导入遗漏新列、长事务阻塞扩列、回填中断与提交结果未知、复制延迟触发暂停、V2 回退读取、V3 插入,以及开放超范围金额后旧客户端的表现。尤其要测试迁移器暂停一天之后系统是否仍然正确,长期任务不能依赖“今晚肯定跑完”。
这套方案适合映射明确、写入口可管理、能够保留一段兼容窗口的同库字段迁移。拆表、跨库搬迁、单位变化或不可逆的业务语义重构,需要额外解决关系、顺序和反向映射,不能照搬本例的相等条件。
一次可靠的在线迁移,应当随时回答四个问题:当前谁有权写,当前读哪份数据,什么证据允许进入下一阶段,失败后还能退到哪里。先把这四个答案写清楚,再执行第一条 ALTER TABLE,通常比事后寻找一个万能回滚命令更有效。
评论
暂无评论。