migration-zero-downtime

Zero-Downtime Migration Skill — 零停机 schema 变更

何时使用

• 给生产数据库加列 / 删列 / 改类型 / 加索引
• 大表（千万 / 亿级）改 schema 想避免锁表
• 拆库 / 合库 / 改主键
• 评审 PR 中的 migration 是否安全
• 部署多副本应用时新旧版本短暂共存的兼容设计

一、核心原则：Expand-Contract（扩展-收缩）

任何 schema 变更都拆成最小前向兼容步骤，应用与 schema 多版本共存：

应用 v1 (旧)        应用 v2 (新)
   │                   │
   └──── 同时运行 ─────┘
   │                   │
   └──需要 schema 同时支持两个版本──┘

标准 6 步

[1] expand schema:    加新结构（向后兼容，旧 app 不受影响）
[2] backfill data:    历史数据迁移
[3] dual write:       app v2 同时写新旧（v2 部署）
[4] read switch:      app v3 改读新结构（v3 部署）
[5] stop dual write:  app v4 只写新（v4 部署）
[6] contract:         移除旧结构

每步独立部署 + 验证 + 必要时可回滚。

二、典型场景剧本

场景 1：加非空列

直接 ALTER TABLE x ADD COLUMN c TEXT NOT NULL DEFAULT 'x' —— PostgreSQL 11+ 元数据级（瞬间），但 MySQL 5.7 / 老版本会重写整表。

保险做法（任何 DB 都安全）：

-- 步骤 1: 加列允许 NULL
ALTER TABLE users ADD COLUMN locale TEXT;

-- 步骤 2: backfill（分批避免长事务）
UPDATE users SET locale = 'en' WHERE locale IS NULL AND id BETWEEN 1 AND 10000;
-- ... 循环

-- 步骤 3: 应用 v2 部署：新写入填值
INSERT INTO users (..., locale) VALUES (..., 'en');

-- 步骤 4: 加 NOT NULL（验证无 NULL 后）
ALTER TABLE users ALTER COLUMN locale SET NOT NULL;

-- 步骤 5（可选）: 加默认值
ALTER TABLE users ALTER COLUMN locale SET DEFAULT 'en';

场景 2：重命名列

绝对不要直接 ALTER TABLE ... RENAME COLUMN。中间窗口旧 app 找不到列直接崩。

[1] 加新列 new_name（兼容）
[2] 应用 v2: dual write — 同时写 old_name 和 new_name
[3] backfill: UPDATE ... SET new_name = old_name WHERE new_name IS NULL
[4] 应用 v3: 读 new_name（旧 fallback 读 old_name）
[5] 应用 v4: 只读写 new_name
[6] 删除 old_name

场景 3：删列

[1] 应用 v2: 不再写该列（保留读，避免 SELECT * 崩）
[2] 应用 v3: 不再读该列（彻底切断引用）
[3] 等所有版本下线（关键！）
[4] ALTER TABLE x DROP COLUMN old

SELECT * 是隐藏炸弹：删列前先把所有 SELECT * 改成显式列列表。

场景 4：改列类型

-- ❌ 直接 ALTER COLUMN TYPE 大表锁
ALTER TABLE orders ALTER COLUMN amount TYPE BIGINT;

-- ✅ 加新列
ALTER TABLE orders ADD COLUMN amount_v2 BIGINT;
-- dual write
-- backfill: UPDATE orders SET amount_v2 = amount::BIGINT;
-- 切读
-- 删旧列