SuperAPI AI 工具集

zero-downtime-migration

部署与运维

查看项目

更新于 10-16 04:26

技能介绍

Zero-Downtime Migration 是一套面向数据库模式变更的迁移模式与技能集合,核心目标是在对生产系统执行 schema 变更时保证服务持续可用、不出现停机。它适用于有在线可用性要求的系统,涵盖重命名或删除列、为已有数据添加 NOT NULL 约束、在大表上非阻塞建索引、在线流量下在列或表之间迁移数据等场景。

主要能力与模式

该技能以 expand-contract(扩展—收缩)模式为主线,分为三个阶段:Phase 1 EXPAND 新增列(可空);Phase 2 MIGRATE 回填数据并让应用同时兼容新旧结构;Phase 3 CONTRACT 在应用完成迁移后删除旧列。每个阶段都说明了对应的回滚方式。

自动化方面,推荐使用 pgroll 实现 expand-contract:可通过 brew install xataio/pgroll/pgroll 或 go install github.com/xataio/pgroll@latest 安装;使用 pgroll init 初始化;以 JSON 迁移文件描述操作(示例为 add_column,向 users 表添加 email_verified 布尔列,默认 false、非空);通过 pgroll start 启动并生成版本化 schema(如 public_001_add_email_verified),应用 v1 和 v2 可分别使用不同 schema 版本;验证后使用 pgroll complete 完成,出现问题时使用 pgroll rollback 回滚。

手工 expand 阶段包括:ALTER TABLE 添加可空新列;若应用无法双写,则创建触发器进行双写同步(示例为根据 first_name 与 last_name 拼接生成 display_name);以及分批回填已有数据(示例每批 1000 行)。

手工 contract 阶段包括:先用 pg_stat_statements 检查是否仍有查询读取旧列;删除触发器与函数;在应用完全迁移后才删除旧列;如需要再对新列设置 NOT NULL。

非阻塞变更技术

索引方面,使用 CREATE INDEX CONCURRENTLY 创建索引,使用 DROP INDEX CONCURRENTLY 删除索引,并提示 CONCURRENTLY 不能在事务块内运行,需在 Alembic 事务之外或使用原生连接执行。

约束方面,采用 NOT VALID 模式:先以 NOT VALID 方式添加约束(如 CHECK 或 FOREIGN KEY,示例为 orders 表的 chk_amount_positive 与 fk_orders_user),此步骤瞬时完成;再单独执行 VALIDATE CONSTRAINT,该过程会扫描表但允许写入。

迁移期间监控

提供多条监控查询:用 pg_stat_activity 检查执行超过 5 分钟的非空闲查询与锁情况;用 pg_stat_replication 检查复制延迟(sent_lsn 与 replay_lsn 差值);用聚合查询统计回填进度(已迁移数、剩余数、完成百分比)。

关键决策

资料给出的建议包括:工具选择上推荐 pgroll 自动化,因其可自动处理双写;列重命名采用新增加复制再删除旧列,因为直接 RENAME 会阻塞读取;约束时机为先 NOT VALID 再单独 VALIDATE;回滚窗口建议保留旧 schema 24 至 72 小时;回填批量大小建议每批 1000 至 10000 行以避免锁升级;索引策略始终使用 CONCURRENTLY;通过 pg_stat_statements 验证旧列不再被查询。

反模式(禁止)

资料明确列出若干禁止写法:单步 ALTER 重命名列(会因元数据锁阻塞所有查询);直接为已有列添加 NOT NULL 且无默认值;在大表上使用普通 CREATE INDEX;未经验证期就删除列;在同一事务中同时创建并验证约束;未分批执行回填。

相关技能

资料提及的相关技能包括 alembic-migrations(支持 expand-contract 的 Python 迁移框架)、database-schema-designer(模式设计与规范化原则)、database-versioning(schema 的版本控制与变更管理)。

限制

资料未提供具体的服务条款、收费信息、支持的数据库种类范围、性能数据或平台限制;除 PostgreSQL 与 pgroll 相关示例外,其他数据库的适配情况暂未提供。