PostgreSQL / 系统课时
形成迁移运行手册
形成迁移运行手册
迁移 Runbook 要把“知道怎么做”变成任何值班成员都能按顺序执行的操作文档。本课把前置检查、命令、监控、验收、回退和责任分工压缩成一套可复用模板,并给出可以直接改造的执行脚本骨架。
学习目标
- 把跨版本迁移拆成可执行、可验证、可回退的 Runbook 步骤。
- 为每个关键动作定义负责人、观察指标、成功标准和停止条件。
- 用命令模板固化检查与验收,降低临场遗漏和口头协作风险。
Runbook 应该包含什么
一份可执行的迁移手册至少要回答六个问题:迁移前检查什么、谁来执行、执行什么命令、观察哪些指标、什么条件算成功、什么条件必须回退。只写“确认复制正常”“必要时回退”不够,因为现场无法据此做一致决策。
推荐把 Runbook 按阶段组织为:前置检查、追平确认、写入冻结、最终校验、应用切换、放量观察、验收或回退。每个阶段都要有明确的进入条件和退出条件。
固化前置检查与验收命令
下面的脚本骨架把最容易遗漏的订阅状态检查和业务表校验放在一起。执行前替换数据库连接信息、订阅名和业务表 SQL;示例使用环境变量,避免把密码写进手册正文。
set -euo pipefail
: "${TARGET_DSN:?set TARGET_DSN first}"
: "${SUBSCRIPTION_NAME:=migration_sub}"
echo "[check] subscription"
psql "$TARGET_DSN" -v ON_ERROR_STOP=1 -Atc "SELECT subname || '|' || subenabled
FROM pg_subscription
WHERE subname = '${SUBSCRIPTION_NAME}';"
echo "[check] replication worker"
psql "$TARGET_DSN" -v ON_ERROR_STOP=1 -Atc "SELECT subname || '|' || COALESCE(pid::text, 'NULL')
FROM pg_stat_subscription
WHERE subname = '${SUBSCRIPTION_NAME}';"
echo "[check] business row count"
psql "$TARGET_DSN" -v ON_ERROR_STOP=1 -Atc "SELECT count(*) FROM orders;"预期输出
[check] subscription
migration_sub|t
[check] replication worker
migration_sub|<PID>
[check] business row count
<VALUE><PID> 和 <VALUE> 为动态值。真正的 Runbook 应把“看到什么才算通过”写在命令旁,例如订阅必须启用、复制进程必须存在、业务数据量必须达到预先记录的基线。
把监控和停止条件写成表
运行手册最重要的不是命令数量,而是阈值清晰。把观测指标、成功标准和动作放在同一张表,执行人不需要临场解释。
| 检查项 | 通过条件 | 不通过时动作 |
|---|---|---|
| 订阅状态 | 订阅启用且复制进程存在 | 暂停切换,恢复订阅并查日志 |
| 复制积压 | 在约定时间内持续下降并归零或低于阈值 | 延长追平窗口;超过上限则停止切换 |
| 应用健康 | 错误率、延迟和关键接口均在基线范围 | 停止放量,必要时回退 |
| 数据一致性 | 关键表计数、抽样主键和业务汇总一致 | 冻结写入,执行对账与补偿 |
| 回退可行性 | 回退路径已验证,责任人在线 | 不满足时禁止进入正式切换 |
阈值不要写成“正常”“可接受”。应使用团队已有的可量化标准,例如错误率不高于 <VALUE>、复制积压在 <VALUE> 分钟内降到阈值以下。
明确责任分工和口令
迁移窗口中建议至少区分执行人、数据库观察人、应用观察人和最终决策人。一个人可以兼任多个角色,但手册里必须明确谁有权发出“继续”“暂停”“回退”口令。
| 角色 | 主要职责 |
|---|---|
| 迁移执行人 | 执行订阅、切流、验证和回退命令 |
| 数据库观察人 | 观察复制状态、锁、错误日志和数据一致性 |
| 应用观察人 | 观察接口错误率、延迟、连接池和业务指标 |
| 决策人 | 根据停止条件批准继续、暂停或回退 |
所有关键动作都记录时间 <TIME>、执行人、命令或变更内容和结果。这样即使迁移失败,也能还原时间线,而不是依赖聊天记录猜测现场发生了什么。
把回退写成前置条件
Runbook 的回退章节应在迁移开始前完成,而不是出故障后临时补写。尤其是逻辑复制迁移,必须注明目标库开始接收新写入之后,回退是否依赖反向复制、双写或数据补偿。
最终手册应能让未参与设计的人仅凭文档完成演练:知道从哪里开始、每一步执行什么、看到什么算通过、何时必须停手,以及由谁做最后决策。只有做到这一点,Runbook 才是迁移控制面,而不是会议纪要。