本文是 MySQL overview 的 implementation-layer deep article。Overview 已說明 MySQL 在 OLTP 譜系的定位、本文聚焦 online schema change — gh-ost 跟 pt-online-schema-change 兩條工具路徑的機制對比。

兩工具最終結果一樣（ghost table 取代原表）、但 過程中對 production 的影響非常不同。選哪個取決於：trigger overhead 可不可接受、是否有 foreign key、是否需要 resume/throttle 能力、團隊熟悉哪條工具鏈。

為什麼 ALTER TABLE 需要 online path

MySQL 8.0 之前的 ALTER TABLE 多數情況下 rebuild 整張表 — 過程中 primary key 之外的 read/write 都 block。100 GB 表 ALTER 跑 hours、production write 全部失敗。

MySQL 8.0 加 Instant DDL（部分 ALTER 不 rebuild、只改 metadata、毫秒級完成）、但 能用 instant 的 ALTER 是 subset：

• 支援：ADD COLUMN（末尾）、DROP COLUMN（部分情境）、RENAME COLUMN
• 不支援：ADD INDEX、CHANGE COLUMN type、ADD/DROP PRIMARY KEY、ADD FOREIGN KEY

不支援 instant 的場景仍要走 ghost table。Percona 跟 GitHub 各自從 production 痛點出發、產出 pt-osc（2011）跟 gh-ost（2016）。

pt-online-schema-change：用 trigger 同步寫入

pt-osc 流程：

1. CREATE ghost table（跟原表同 schema + 你要的 ALTER）
2. 在原表上 建 3 個 trigger：INSERT / UPDATE / DELETE
3. 任何寫入原表的 transaction 同時觸發 trigger 寫對應 ghost
4. 背景 chunk-by-chunk copy 既有 row 到 ghost
5. 全部 copy 完後 RENAME TABLE：原表 → archive、ghost → 原表名（atomic、metadata lock 毫秒級）
6. Drop trigger、drop archive

Trade-off：

• 寫入 overhead：每個 primary 寫入 transaction 都多一次 trigger 執行、寫吞吐降 10-30%
• Replica lag：trigger 跟原寫入同 transaction、replica 上每個 row 也跑 trigger、replica lag 可能暴增（缺少主動 throttle）
• Roll back 困難：tool 跑到一半失敗、trigger 已建、要手動清掉才能 retry
• FK 處理：原表有 FK 指向時、ghost table 要先 drop FK 再 recreate、操作複雜

適用：

• 寫吞吐 < 50% capacity（有 buffer 撐 trigger overhead）
• 無 FK 或 FK 簡單
• 沒有 replica lag 敏感的 read（trigger 在 replica 也跑）

不適用：

• 高寫吞吐（> 80% capacity）— trigger overhead 直接 saturate
• 大量 FK 結構
• 需要 throttle / pause / resume

gh-ost：用 binlog stream 同步寫入

gh-ost 流程：

1. CREATE ghost table
2. 從 replica 讀 binlog（不在 primary 加 trigger）
3. 同步 primary 上的寫入 透過 binlog event 寫到 ghost
4. 背景 chunk-by-chunk copy 既有 row 到 ghost
5. 全部 copy 完後 swap：RENAME TABLE
6. Drop archive

Trade-off：

• 寫入 overhead：0（binlog 已經寫了、gh-ost 只是 consumer）
• Replica lag 影響：gh-ost 可監測 replica lag、超過 threshold 自動 throttle copy（不影響 primary 寫入）
• Roll back 容易：取消時直接 drop ghost table、原表完全沒被改動
• FK 不支援：gh-ost 設計上不處理 FK、有 FK 必須先 drop / restructure

適用：

• 高寫吞吐 production（trigger overhead 不可接受）
• 需要 throttle / pause / resume（gh-ost interactive command 可動態調 chunk size、cut-over 時點）
• 已用 GitHub-flavored MySQL operations workflow

不適用：

• 有複雜 FK 結構、不想動 schema
• Replica 跑不了 binlog（極少數場景）

配置 step-by-step（gh-ost）

實務 production 多用 gh-ost（GitHub / Slack / Booking.com 等）。pt-osc 用於有 FK 或舊系統。

gh-ost 一個 ALTER 命令

 1gh-ost \
 2  --host=replica.example.com \           # 從 replica 讀 binlog
 3  --user=ghost \
 4  --password=... \
 5  --database=production \
 6  --table=orders \
 7  --alter='ADD COLUMN status VARCHAR(20) DEFAULT NULL, ADD INDEX idx_status (status)' \
 8  --allow-on-master=false \              # 不直接連 primary 讀 binlog
 9  --chunk-size=1000 \                    # 每批 copy 1000 row
10  --max-load='Threads_running=50' \      # primary load 限制
11  --critical-load='Threads_running=200' \ # 超過直接 abort
12  --max-lag-millis=1500 \                # replica lag 限制
13  --throttle-additional-flag-file=/tmp/throttle \  # touch 此檔 throttle
14  --postpone-cut-over-flag-file=/tmp/postpone \    # touch 此檔延後 cut-over
15  --execute                              # 真的執行（沒這個只 dry-run）

Interactive command（gh-ost 跑起來後）

1# 連 gh-ost socket（同 directory）
2echo "status" | nc -U /tmp/gh-ost.production.orders.sock
3# 動態調 chunk size
4echo "chunk-size=500" | nc -U /tmp/gh-ost.production.orders.sock
5# 立即觸發 cut-over（不再等）
6echo "unpostpone" | nc -U /tmp/gh-ost.production.orders.sock
7# Abort 並 drop ghost
8echo "panic" | nc -U /tmp/gh-ost.production.orders.sock

配置 step-by-step（pt-osc）

對比 gh-ost 的 binlog reader、pt-osc 命令更短但配置義務同樣多：

 1pt-online-schema-change \
 2  --host=primary.example.com \
 3  --user=ghost \
 4  --password=... \
 5  --alter='ADD COLUMN status VARCHAR(20) DEFAULT NULL, ADD INDEX idx_status (status)' \
 6  D=production,t=orders \
 7  --chunk-size=1000 \
 8  --max-load='Threads_running=50' \
 9  --critical-load='Threads_running=200' \
10  --max-lag=1.5 \
11  --check-replication-filters \           # 防 binlog filter 漏 trigger
12  --alter-foreign-keys-method=auto \      # auto / rebuild_constraints / drop_swap / none
13  --execute

--alter-foreign-keys-method 是 pt-osc 對 FK 處理的策略選項、四種選擇對 production 影響非常不同（rebuild 重建 FK / drop_swap 用更快但少了 atomic、none 是不處理）。

5 個 Production 踩雷

1. pt-osc trigger overhead 不可預期

--max-load='Threads_running=50' 看起來保護了 server、但 trigger 在 transaction 內、production 的 每個寫入 都加 trigger 開銷。Threads_running 是 當下 數字、看不到 trigger 累積 latency。常見場景：高峰時段下 pt-osc、預期 30% overhead、實際 60%、p99 飆 5x。

修法：

• 高峰時段不跑 pt-osc、排 off-peak window
• 用 staging environment 跑 production-like load 預估 trigger overhead
• 對寫吞吐 > 50% capacity 的 server 改用 gh-ost

2. gh-ost binlog lag 跟 primary 寫入率追不上

gh-ost 從 replica 讀 binlog、binlog event 進來速度有上限。如果 primary 寫入率超過 gh-ost binlog consume 速度（每秒幾千 transaction 對某些 server 已是 ceiling）、gh-ost 永遠追不上、cut-over 會長時間卡住。

修法：

• gh-ost 預設用 replica binlog、改用 --allow-on-master 直接從 primary 讀（如果 primary 容量夠）
• 提高 --chunk-size 加快 copy（同時用 --max-load 防過載）
• 真的追不上、考慮 暫停部分寫入流量（throttle traffic，而非 throttle tool）

3. Foreign key constraint — 兩工具都尷尬

原表有 FK 指向（其他 table FK references 這張表）、ghost table 切換時 新 ghost 沒有那些 FK 指向。Cut-over 一瞬間、FK 從指向「原表」變成指向「archive 表」、外部 constraint 失效。

修法（pt-osc）：

• 用 --alter-foreign-keys-method=rebuild_constraints：先 ALTER 外部 table FK 指向 ghost、再 cut-over
• 或 drop_swap：cut-over 前 drop FK、cut-over 後 recreate（更快但 cut-over 期間 FK 失效）

修法（gh-ost）：

• gh-ost 不支援 — 手動 drop FK / 重 setup FK
• 或維護 schema 改 FK 結構（FK 改在 application 層 enforce）

4. pt-osc trigger 跟 application 既有 trigger 衝突

原表上已經有 application 自建 trigger、pt-osc 在原表 再加 3 個 trigger、新舊 trigger 執行順序 MySQL 不保證（多 trigger 同事件按 未定義順序）。Application 行為可能 subtly broken。

修法：

• 跑 pt-osc 前 audit 原表 trigger（SHOW TRIGGERS FROM production LIKE 'orders'）
• 如果有 application trigger、考慮 暫時 disable 再 ALTER 或改 gh-ost
• gh-ost 不在原表加 trigger、不會碰到這個問題

5. Cut-over 瞬間 deadlock — 兩工具都有但表現不同

Cut-over 用 RENAME TABLE original TO archive, ghost TO original（atomic operation）。但 cut-over 瞬間需要 metadata lock、跟 進行中的 long-running transaction 衝突會 wait。Long-running transaction 持續、cut-over 永遠 wait、最後 timeout 失敗。

修法（gh-ost）：

• --cut-over-lock-timeout-seconds=3、超時 abort、稍後 retry
• --postpone-cut-over-flag-file：先把 copy 跑完、等流量空檔再觸發 cut-over

修法（pt-osc）：

• --set-vars="lock_wait_timeout=60"、cut-over 等更久（風險：long transaction 撐住更久 server 更多 lock wait）
• 或排在 long transaction 已知不會跑的時段（nightly backup 後）

容量 / 時間估算

對 100 GB 表、ALTER 加 column + 加 index 為例：

兩工具總時間接近、影響 production 的差異大。

跟其他模組整合

跟 GTID / Replication topology

兩工具都 依賴 replication — pt-osc 透過 trigger 確保 replica 同步、gh-ost 直接從 replica 讀 binlog。Pre-requisite：

• Binlog ROW format（兩工具都要）
• GTID 啟用（gh-ost 更需要、binlog re-pointing 容易）
• 詳見 Replication Topology

跟 Vitess

Vitess 有自己的 VReplication-based online DDL、不用 gh-ost 或 pt-osc。Vitess online DDL 在 shard 內部用類似 gh-ost 的 binlog stream 機制、但有 Vitess-aware schema management。詳見 Vitess sharding 設計 篇（待寫）。

跟 Aurora MySQL

Aurora MySQL 仍支援 gh-ost / pt-osc、但 Aurora 自己的 fast DDL（部分 ALTER） 比 8.0 Instant DDL 更廣。先檢查 Aurora 文件、能用 native fast DDL 就不用 ghost table tool。詳見 Aurora vendor page。

跟 PlanetScale

PlanetScale（managed Vitess）走 branch-based schema migration — 建 schema branch、跑 schema change、deploy 時 atomic merge。schema change 由 PlanetScale 內建流程承擔。詳見 PlanetScale migration playbook。

Production case：gh-ost operation workflow

Online schema change 的 production 責任是把大表 DDL 拆成可暫停、可節流、可切換的資料搬移流程。gh-ost 作為 GitHub 開源工具，把 schema change 轉成 ghost table copy、binlog tailing 與 controlled cutover；這讓 operator 可以在 replica lag、application load 或部署窗口變化時調整速度。

這個案例要回收到三個操作判準。第一，throttle 指標要接 production SLO，例如 replica lag、thread running、application latency 或錯誤率，而非只看 copy rows/sec。第二，pause / resume 是變更治理能力，代表 schema change 可以配合 incident response、deploy freeze 與商業尖峰窗口。第三，cutover 要設 rollback window 與 owner，因為 rename table 的瞬間仍是高風險控制點。

gh-ost workflow 的 sibling 路由是 PostgreSQL Online Schema Change。PostgreSQL 常靠 fast ALTER、MVCC 與 extension 工具解決同類需求；MySQL 的 ghost table tool 更常成為標準路徑，主因是大表 DDL、metadata lock 與 replication event 的組合壓力不同。

何時用哪一個

相關連結

• MySQL vendor overview
• MySQL Replication Topology（binlog ROW format + GTID 是 pre-requisite）
• PostgreSQL Online Schema Change（PG sibling、為什麼 PG 比 MySQL 少用 ghost table — fast ALTER 覆蓋多數變更）
• Aurora vendor page（managed MySQL fast DDL）
• PlanetScale（branch-based 不用 ghost table）
• 1.6 Database Migration Playbook（schema migration 治理）
• Expand / Contract 卡片（schema migration 設計原則）
• 官方：gh-ost / pt-online-schema-change

本文是 PostgreSQL overview 的 implementation-layer deep article。Overview 已說明 PG 在 OLTP 譜系的定位、本文聚焦 online schema change — 先看 PG ALTER 哪些已 fast catalog-only、再看 pg_repack / pg-osc 何時必要。

跟 MySQL 不同：PG 大量 schema change 內建 fast catalog-only 行為、不必走 ghost table tool。MySQL 對應的 gh-ost / pt-online-schema-change 之於 PG 是 少數場景才需要的 escape hatch、不是 standard practice。

寫作 OSC 時必須 先看 PG 自身 ALTER 行為、確認真的需要再上 pg_repack / pg-osc — 否則徒增複雜度。

PG ALTER TABLE 的 fast / slow 分類

1-- ALTER TABLE 的操作大致三類

類 A：Fast catalog-only（< 1 秒、metadata 改）

PG 9.4+ / 11+ 多數 ALTER 已 catalog-only：

• ADD COLUMN col TYPE NULL DEFAULT NULL — 直接 metadata、不 rewrite
• ADD COLUMN col TYPE NOT NULL DEFAULT <constant>（PG 11+）— optimizer 把 default 存在 metadata、舊 row read 時動態返回 default、不 rewrite
• DROP COLUMN — metadata 標 dropped、實際 row 不 rewrite（VACUUM 之後逐步清理）
• ALTER COLUMN ... SET DEFAULT <constant> — metadata
• RENAME COLUMN / RENAME TABLE — metadata
• ADD CONSTRAINT ... NOT VALID — 標記 constraint 不 validate、之後 VALIDATE CONSTRAINT 才 scan
• ALTER COLUMN ... TYPE 同 binary-compat 類型（VARCHAR(10) → VARCHAR(20)、TEXT → VARCHAR 等）— catalog-only

這類 ALTER 直接跑、不必任何工具。

類 B：Lock heavy（rewrites table、production 慎用）

需要 rewrite 整張 table、ACCESS EXCLUSIVE lock 整個 ALTER 期間：

• ALTER COLUMN ... TYPE binary 不相容類型（INT → BIGINT 永遠 rewrite、TEXT → INT 也是）— 雖然語意「擴大」、底層 4-byte 跟 8-byte storage 不同、全表 rewrite + ACCESS EXCLUSIVE 不可省
• ALTER COLUMN ... SET NOT NULL 對既有 nullable column（要 scan 整 table）
• ALTER COLUMN ... DROP IDENTITY
• ALTER TABLE ... SET TABLESPACE

這類 ALTER 對大表 production 不能直接跑、要 ghost table tool。

類 C：Concurrent index / online operation（無 table lock）

• CREATE INDEX CONCURRENTLY — 不 lock 寫入、background build、慢但安全
• REINDEX INDEX CONCURRENTLY（PG 12+） — 同上
• DROP INDEX CONCURRENTLY — 短 ACCESS EXCLUSIVE lock 只在最後 swap

何時需要 ghost table tool

只在以下場景才需要 pg_repack / pg-osc：

1. Rewrite-required type change（類 B ALTER COLUMN TYPE）對大表
2. VACUUM FULL 替代：pg_repack 比 VACUUM FULL 安全（不 lock 整表）
3. Bloat 重組：大表 dead tuple 累積、想完整 rewrite

對「add column」「drop column」「create index」等場景 PG 內建 fast 已夠、不必 ghost table tool。

Tool 1：pg_repack — Trigger-based + 雙 table swap

pg_repack 是 PG community 標準 online table rewrite 工具：

1pg_repack -h primary.example.com -p 5432 -d production -U postgres \
2  --table=orders --no-superuser-check

Mechanism：

1. CREATE repack.table_<oid> 跟原表同 schema
2. 在原表加 3 個 trigger：INSERT / UPDATE / DELETE → 寫入 log table repack.log_<oid>
3. 從原表 INSERT INTO repack.table_<oid> SELECT * FROM original 複製 row
4. 邊複製邊 apply log table 紀錄的變更
5. 切換：rename 原表 → original_old、rename repack.table_ → original（atomic）
6. Drop 舊原表跟 trigger / log

Trade-off：

• Trigger overhead：每個 primary 寫入加 trigger 執行（10-30% 寫吞吐降）
• FK 處理：需要 drop & re-create FK referencing original table（pg_repack 自動處理但有 lock window）
• 適用 PG-version 綁定 — pg_repack 13 不能對 PG 14 cluster 跑

配置：

1-- Primary 安裝
2CREATE EXTENSION pg_repack;

1# Repack orders
2pg_repack -d production --table=orders
3# 監控 lock：另一 session 跑 SELECT * FROM pg_stat_activity

Tool 2：pg-osc / pg-online-schema-change — WAL-shipping style

pg-osc（Shayon Mukherjee、2023）是較新的工具、模仿 gh-ost mechanism：

Mechanism：

1. 用 logical replication slot 從 primary WAL stream 變更
2. CREATE shadow table + 套 ALTER 變更
3. Stream WAL event 同步 shadow table（不靠 trigger）
4. 完成後 swap

Trade-off：

• Primary 寫入 overhead：0（WAL 已存在）
• 比 pg_repack 較新（社群驗證度低）
• 適合 trigger overhead 不可接受 的高吞吐 production

配置：

1# 用 gem install
2gem install pg_online_schema_change
3
4# Run
5pg-online-schema-change perform \
6  --alter-statement="ALTER TABLE orders ADD COLUMN status VARCHAR(20)" \
7  --schema=public \
8  --dbname=production \
9  --host=primary.example.com

配置 step-by-step（pg_repack 為主）

實務多數 PG OSC 用 pg_repack。pg-osc 是 high-write-throughput escape hatch。

Step 1：安裝 + 確認版本

1-- 安裝 pg_repack（versioned）
2CREATE EXTENSION pg_repack;
3SELECT * FROM pg_available_extensions WHERE name = 'pg_repack';
4-- 確認 installed_version 跟 PG major version 對齊

Step 2：跑 pg_repack

1pg_repack -h primary -d production -U postgres \
2  --table=orders \
3  --jobs=4 \                       # 並行 worker
4  --wait-timeout=60 \              # 等 lock 超時（秒）
5  --no-kill-backend                # 不主動 kill 卡 lock 的 query

Step 3：監控

1-- 看 pg_repack 進度
2SELECT pid, query, state, wait_event_type, wait_event
3FROM pg_stat_activity
4WHERE query LIKE '%repack%';
5
6-- 看 lock 狀態
7SELECT * FROM pg_locks WHERE relation IN (
8  SELECT oid FROM pg_class WHERE relname IN ('orders', 'repack.table_xxx')
9);

Step 4：驗證

1-- 跑完後對比 row count + 抽樣 query
2SELECT count(*) FROM orders;
3-- 跟 pg_repack 之前 count 對比

5 個 Production 踩雷

1. ALTER 直接跑沒看是不是 fast 變 lock heavy

ALTER TABLE orders ADD COLUMN status VARCHAR(20) NOT NULL DEFAULT 'pending' — 預期 catalog-only（PG 11+）、但若 PG 10 跑這個就會 rewrite 整表、ACCESS EXCLUSIVE lock 幾小時。

修法：

• 寫 schema migration 前 確認 PG version
• 看 PG ALTER doc、each subcommand 標 Note 段是否 fast
• Production 跑前 staging 測 + 監控 pg_stat_activity lock wait

2. VACUUM FULL 誤用 — Production downtime

VACUUM FULL 等於「rewrite 整表 + ACCESS EXCLUSIVE lock」。Production 跑 = 表變 unavailable 幾分鐘到幾小時。

修法：

• 永遠用 pg_repack 取代 VACUUM FULL（除非 maintenance window）
• 對 bloat 議題、定期跑 pg_repack
• autovacuum tuning 第一優先（autovacuum-tuning 詳細）

3. pg_repack version mismatch

PG cluster 升 14、但 pg_repack extension 還是 13 版本。試 ALTER 跑 pg_repack 命令、ERROR: program "pg_repack 14.x" does not match installed extension "pg_repack 13.x"。

修法：

• 升 PG cluster 後 立即 ALTER EXTENSION pg_repack UPDATE
• 若 pg_repack 還沒釋出對應 PG 版本（早期升級）、暫時用 pg-osc 替代或等待
• 升級 runbook 紀錄 pg_repack 是 必同步升級的 extension

4. CREATE INDEX CONCURRENTLY 失敗清理

CREATE INDEX CONCURRENTLY 跑到一半被 cancel（用戶 Ctrl-C / connection drop）、產生 invalid index：

1SELECT indexrelid::regclass FROM pg_index WHERE NOT indisvalid;
2-- 顯示一個 idx_orders_status_invalid

Invalid index 仍佔 disk、但 optimizer 不會用。

修法：

• 跑 DROP INDEX CONCURRENTLY idx_orders_status_invalid
• 之後重新 CREATE INDEX CONCURRENTLY
• 避免在 connection 不穩的 session 跑長時間 CREATE INDEX CONCURRENTLY、改用 cron 或 deploy pipeline

5. Generated stored column 不能 online ADD

ADD COLUMN total NUMERIC GENERATED ALWAYS AS (price * qty) STORED — stored generated column 必須 rewrite 整表計算 column value、不是 catalog-only。

修法：

• 用 GENERATED ALWAYS AS (...) VIRTUAL（PG 18+）— 不存實際 value、catalog-only

• 或 先加 nullable column + backfill + 加 NOT NULL constraint：

  1ALTER TABLE orders ADD COLUMN total NUMERIC;
  2UPDATE orders SET total = price * qty WHERE id BETWEEN ...;  -- chunked
  3ALTER TABLE orders ALTER COLUMN total SET NOT NULL;
  4-- 之後加 trigger 或 application 層維護 total

• 或用 pg_repack 跑 rewrite ADD GENERATED STORED

容量 / 時間估算

對 100 GB 表、ADD COLUMN 加 index 為例：

跟 MySQL gh-ost / pt-osc 對照

PG OSC tool 使用頻率比 MySQL 低 — 因為 PG 內建 fast ALTER 已 cover 90% schema change、ghost table tool 只對 少數 rewrite-required 場景。

詳見 MySQL Online Schema Change Tools — sibling、不同 use case mix。

跟其他模組整合

跟 Replication topology

ALTER TABLE / pg_repack / pg-osc 都產生 WAL、會 replicate 到 standby。Standby 上的 long-running query 可能跟 ALTER 衝突、被 hot_standby_feedback 影響 primary autovacuum。詳見 Replication Topology。

跟 Autovacuum Tuning

Schema change 後常產生 dead tuple、autovacuum 需要重新 cover。詳見 Autovacuum Tuning。

跟 Logical Replication

logical replication 透過 publication / subscription 同步 — DDL 不會 logical replicate（PG 16 之前）、必須 在 publisher / subscriber 各自跑 DDL。詳見 Logical Replication + Debezium。

跟 Patroni HA

Patroni promote 新 primary 後、pg_repack extension state（slot / catalog）跟著走、新 primary 仍可繼續 pg_repack。詳見 Patroni HA。

何時用哪個

相關連結

• PostgreSQL vendor overview
• PG Replication Topology（ALTER 跟 streaming replication 互動）
• PG Autovacuum Tuning（schema change 後 vacuum 議題）
• PG Logical Replication + Debezium（DDL 不 replicate 議題）
• PG Patroni HA（HA 跟 pg_repack 整合）
• MySQL Online Schema Change Tools（sibling、tool ecosystem 不同）
• Expand / Contract 卡片（schema migration 設計原則）
• 官方：ALTER TABLE / pg_repack GitHub / pg-osc GitHub

本文是 Cloud Spanner overview 的 implementation-layer deep article。Overview 已說明 Spanner 在全球 OLTP 譜系的定位、本文聚焦 schema migration without downtime + interleaved tables — Spanner 兩個跟傳統 SQL 差異最大的 schema 機制。

問題情境：DDL 不停機跟 parent-child 物理 layout 的兩個疑問

傳統 PostgreSQL / MySQL DDL 拿 ACCESS EXCLUSIVE / metadata lock、線上跑 ALTER TABLE 動輒鎖表幾分鐘、大型 schema change 要 pt-osc / gh-ost / pg_repack 等外掛工具。Spanner 宣稱「schema change 不停機」、但團隊不知道實際機制跟邊界。讀者徵兆通常從這幾個地方浮現：「Spanner ALTER 真的不卡寫入嗎」「INDEX backfill 跑了 12 小時是正常嗎」「parent-child 的 INTERLEAVE IN PARENT 是什麼黑魔法」「ON DELETE CASCADE 在 interleaved table 為什麼是 storage-level 而不是 application-level」。

真實壓力：multi-tenant SaaS 要對 100 億 row 的 orders 表加 column + 加 index、不能停機、不能讓 p99 write latency 超過 SLA。團隊以為「Spanner schema change 不停機」等同於「DDL 瞬間完成」、實際 ALTER 是 long-running operation、index backfill 在大表上跑數小時到數天、capacity 規劃要把 backfill 期間的 CPU 升幅算進去。

Case anchor：缺案例。9.C10 是 Google internal dogfood case、未展開 schema migration 細節、且 9.C10 不是 customer-facing capacity reference。本文用通用 pattern + 官方文件 + 反向回 PostgreSQL Online Schema Change 對照、待後續 customer case audit 補強。

核心機制：DDL 是 long-running、TrueTime 對齊 schema version

Schema change 的 lifecycle

Spanner DDL 不是同步 ALTER、是 long-running operation。TrueTime 給每次 schema change 分配一個 version timestamp、所有 read / write 用各自 transaction timestamp 對應「當下看到哪個 schema version」。讀者要理解的核心是：DDL 不是「鎖表→改→解鎖」、是「廣播新 schema version、讓現有 transaction 用舊 schema、新 transaction 用新 schema、背景 backfill 物理資料」。

 1時間軸：
 2
 3T0 (DDL 開始)
 4     |
 5     | ──── 舊 schema 仍可用、新 schema metadata 廣播 ────
 6     |
 7T1 (metadata 完成)
 8     |
 9     | ──── 新 transaction 用新 schema、舊 transaction 完成自己 ────
10     | ──── backfill 開始（背景）────
11     |
12T2 (backfill 完成)
13     |
14     | ──── 新 schema fully serve ────

DDL 本身瞬間完成的部分是 metadata 廣播（毫秒到秒級）、慢的部分是 backfill（依資料量、可能數小時到數天）。讀者常見誤解是把 metadata 完成當「DDL 完成」、實際 query 還沒走新 index 因為 backfill 沒跑完。

不停機的關鍵：不同 DDL 的兩階段行為

讀者要記的是：index backfill 完成前、query 該 index 會 fallback 到 table scan、用 EXPLAIN 確認 query plan 走新 index 才算真正完成。沒做這層驗證、團隊會以為 CREATE INDEX 已經成功、實際 p99 query latency 還在表掃描的數量級。

Interleaved table 的設計

Interleaved Table 把 parent table（如 Customer）跟 child table（如 Order）的 row 在 storage 層 物理上交錯儲存 — child row 跟對應 parent row 在同一個 split。不是純 foreign key、是 storage layout：

 1傳統 PostgreSQL FK 設計（兩張獨立表）：
 2Customer table:  [c1, c2, c3, ...]  → 一張表、一段 storage range
 3Order table:     [o1, o2, o3, ...]  → 另一張表、另一段 storage range
 4FK 由 planner 在 JOIN 時拼接、可能跨 page / 跨 segment
 5
 6Spanner Interleaved 設計（物理交錯）：
 7Storage layout: [c1, c1.o1, c1.o2, c2, c2.o1, c2.o2, c2.o3, c3, ...]
 8                 |____________________|  |________________|
 9                  c1 + 其 child           c2 + 其 child
10                  在同一個 split          在同一個 split

Interleaved 的效果：parent + child JOIN 在同一個 Range Sharding split 完成、不跨 split = 不跨 Paxos group = 低延遲 transaction。這條設計把「FK 是 logical constraint」翻成「parent-child access pattern 是 physical co-location」、對 access pattern 固定的 workload（customer → orders、user → posts、tenant → records）是巨大 latency benefit。

Interleaved 的硬限

最後一條是讀者最容易踩的雷 — 一開始沒設 interleaved、後悔時要 export-import 100 億 row、是大工程、不是 ALTER。Schema 設計階段要先 audit access pattern、決定哪些 parent-child 該 interleave。

跟通用 FK 概念的差異

PostgreSQL FK 是 logical constraint、JOIN 由 planner 處理；Spanner interleaved 是 physical layout、JOIN cost 跟 single-table access 接近。對應 transaction-boundary 卡 — interleaved 讓 transaction boundary 跟 storage boundary 對齊、跨 split transaction 變少、commit wait + Paxos round-trip 也省。

操作流程：DDL 跟 interleaved table 的具體步驟

加 column

1ALTER TABLE Orders ADD COLUMN tax_amount FLOAT64;

執行後拿 long-running operation id、用 gcloud spanner operations list 觀察狀態：

1gcloud spanner operations list --instance=prod --database=app
2gcloud spanner operations describe projects/.../operations/<op-id>

驗證點：operation 顯示 done: true 後、跑 SELECT tax_amount FROM Orders LIMIT 1 確認 column 可查。

加 index

1CREATE INDEX OrdersByCustomer ON Orders(customer_id);

拿 operation id → 用 Monitoring metric spanner.googleapis.com/instance/indexes/backfill_progress（或對應的最新 metric、查官方文件）追蹤進度。Backfill 完成前 query 不會走新 index、要用 EXPLAIN 確認：

1EXPLAIN SELECT * FROM Orders WHERE customer_id = 'c123';
2-- 應看到 plan 用 OrdersByCustomer index、不是 table scan

創建 interleaved table

1CREATE TABLE `Order` (
2    customer_id INT64 NOT NULL,
3    order_id INT64 NOT NULL,
4    amount FLOAT64,
5    created_at TIMESTAMP,
6) PRIMARY KEY (customer_id, order_id),
7  INTERLEAVE IN PARENT Customer ON DELETE CASCADE;

關鍵約束：

• child PK (customer_id, order_id) 第一段是 parent PK
• ON DELETE CASCADE 是 storage-level — 刪 parent row 自動刪 child row、Spanner 內部處理、不是 trigger

從 non-interleaved 改成 interleaved

無法直接 ALTER、要走 export-recreate-import：

1. 用 Dataflow / gcloud spanner databases export 把舊表 export 到 GCS
2. 建新表（interleaved schema）
3. 用 Dataflow / gcloud spanner databases import 把資料倒回
4. 應用層 cutover（feature flag / dual write）

這個流程是 mini-migration、要走完整 migration playbook 的 phase plan。Schema 設計階段就決定好 interleave、避免後悔成本。

Rollback boundary

DDL 完成前可 gcloud spanner operations cancel 取消；完成後加 index 要 DROP、加 column 要 DROP COLUMN（同樣是 long-running）。讀者要先確認自己在 DDL 哪個階段、cancel 跟 reverse DDL 是兩條不同路徑。

失敗模式：5 個 production 踩雷

Backfill 時間沒估、event window 撞牆

100 億 row 加 index、預期 1 小時、實際 12 小時 — 沒先用 cost 估 + 沒監控進度 metric。事故場景：團隊在 black friday 前一週開 CREATE INDEX、以為週末跑完、實際週末仍在 backfill、event 期間 CPU 升、query latency 退化。

修法：

• DDL 前用小表 benchmark backfill 速度（rows/sec）、推估大表時間
• DDL 期間監控 instance/cpu/smoothed_utilization、若 > 80% 暫停或降流量
• 大 DDL 排在 capacity headroom 充足的時段、避開 event window

Interleaved table 一開始沒設、後悔時要 recreate

100 億 row export-import + cutover 是大工程、不是 ALTER。事故場景：團隊一開始把 Customer / Order 設成獨立表、上線一年後發現 customer → orders access pattern 是 99% 的 query、JOIN 跨 split 付 commit wait + Paxos cost、想改 interleaved、發現要 mini-migration。

修法：

• Schema 設計階段就 audit access pattern、決定哪些 parent-child 該 interleave
• 寫 ADR 把 interleave 決策跟業務 access pattern 綁定、避免後悔成本

把 interleaved 跟 FK 混為一談

interleaved 的 ON DELETE CASCADE 是 storage-level、刪 parent 自動刪 child；非 interleaved FK 要 application 或 trigger 處理。事故場景：團隊以為「我加了 FK 就會 CASCADE」、實際非 interleaved table 只是 constraint check、刪 parent 時 child orphan、對帳爆炸。

修法：

• Schema 設計時明確分類：interleaved（storage-level CASCADE）vs FK constraint（只檢查、不 CASCADE）
• 非 interleaved 的 parent-child 刪除邏輯放應用層、寫入對帳測試

加 NOT NULL 一步到位

直接 ALTER ADD COLUMN x INT64 NOT NULL 會失敗、必須兩階段。事故場景：開發環境 schema 是新建空表、ADD COLUMN NOT NULL OK；production 表有資料、ADD 失敗、團隊以為 Spanner 不支援、回退。

修法：

1-- Phase 1: ADD with default
2ALTER TABLE Orders ADD COLUMN tax_amount FLOAT64 DEFAULT 0;
3-- 等 backfill 完成
4
5-- Phase 2: ADD CONSTRAINT
6ALTER TABLE Orders ALTER COLUMN tax_amount SET NOT NULL;

Schema change 期間舊 client 還在用舊 schema

TrueTime 保證 read 看到自己 timestamp 對應的 schema version、但 client SDK cache schema 過期會 retry — 沒處理會看到 transient error。事故場景：DDL 完成後、舊 client session 看到 transient FAILED_PRECONDITION、團隊以為 DDL 失敗、回退。

修法：

• 應用層處理 transient retry（指數退避）
• DDL 完成後重新 deploy app instance、避免長期 stale schema cache

容量與觀測：Backfill 是 CPU + I/O 的額外負載

必看 metric：

1spanner.googleapis.com/instance/cpu/smoothed_utilization
2   → backfill 期間 CPU 升幅、判讀是否撞 headroom
3api/api_request_count for ExecuteSql
4   → application traffic 是否受 backfill 影響
5long-running operation API progress
6   → DDL 自身進度（不是 query 進度）

Backfill 期間的 capacity impact：DDL 跑在 background priority、但仍佔 CPU、需要在 instance 有足夠 headroom（建議 < 65% CPU baseline 才開大 backfill）。capacity 規劃要把 schema migration 列入 buffer、回 9.6 容量規劃模型。

Observability evidence：backfill 開始 timestamp、operation id、predicted duration、實際 duration、CPU peak — 全進 incident decision log、回 4.20 Observability Evidence Package。

監控盲點：DDL operation 失敗 silent fail 在 gcloud operations describe 才能看到、Cloud Monitoring 沒有直接 alert。團隊要寫自己的 polling script、operation 失敗時主動 alert、不靠 Cloud Monitoring default。

邊界與整合：何時不用 interleaved、怎麼跟 PG 對照

何時不用 interleaved

• 小 table（< 1M row、單機可放）：不需要 interleave、用 standard FK 就好
• 過度 interleave 7 層：把 split 變窄、反而 hot、得不償失
• access pattern 不是 parent-child JOIN：interleave 沒 benefit、純粹給 schema 加複雜度

跟 PostgreSQL 的對照

PostgreSQL Online Schema Change 用 pg_repack / pt-osc workflow 模擬「不停機」 — 實際是用 trigger + 影子表 + cutover 把 lock 時間壓到秒級、不是真正瞬間。Spanner 是原生支援 DDL long-running operation、不需要外掛工具、但 backfill 時間在大表上仍長、跟 pg_repack 在大表上的執行時間量級接近。

差異點：

讀者選 Spanner 不是為了「DDL 更快」、是為了「不依賴外掛 + 多版本並存」。實際在大表上的耗時兩邊差不多。

Sibling deep articles

• truetime-api-depth：schema version 也是 TrueTime timestamp、跟 transaction timestamp 同層機制
• migrate-from-cloud-sql-pg：target schema 設計含 interleaved、Phase 1 必讀本文
• consistency-models-comparison：schema change 期間多版本並存的一致性保證

跟 1.x 章節

Schema Design — interleaved 是 schema 設計的物理層決策、不是純 logical design。對照 schema-migration-rollout-evidence 看 schema rollout 的 evidence 收集模式。

Anti-recommendation

讀者讀完本文應該能判斷：interleaved 不是「強制使用」的 feature、是「access pattern 固定時的 latency benefit」。小規模 OLTP、access pattern 不確定的 workload、用 standard PostgreSQL FK 就好、為 interleaved 付 schema 後悔成本的判準很高。

本文的驗收標準是：你能跑一個低風險 ALTER、觀察 metadata lock、記錄 validation query，並理解 gh-ost / pt-osc 的 cutover evidence。

Direct ALTER Baseline

Direct ALTER baseline 的核心責任是先看 MySQL 原生 DDL 的行為。

1mysql -h 127.0.0.1 -P 33069 -u app_user -papp_pw appdb <<'SQL'
2ALTER TABLE accounts ADD COLUMN email VARCHAR(255) NULL;
3SHOW CREATE TABLE accounts\G
4SQL

記錄 ALTER duration、algorithm、lock impact 與 table size。不同 MySQL 版本與 DDL 類型會有不同行為，production 要在 staging dry run。

Metadata Lock Observation

Metadata lock observation 的核心責任是看到 blocker。

開 Session A：

1START TRANSACTION;
2SELECT * FROM accounts WHERE id = 1;

保持 transaction 開啟。Session B 執行：

1ALTER TABLE accounts ADD COLUMN note VARCHAR(255) NULL;

Session C 查：

1SELECT OBJECT_SCHEMA, OBJECT_NAME, LOCK_TYPE, LOCK_STATUS, OWNER_THREAD_ID
2FROM performance_schema.metadata_locks
3WHERE OBJECT_SCHEMA = 'appdb';

完成觀察後，Session A COMMIT。這段 lab 展示 long transaction 如何讓 DDL 等待。

OSC Frame

OSC frame 的核心責任是理解 gh-ost / pt-online-schema-change 的證據，而非要求每個 lab 都安裝工具。

OSC runbook 要記錄：

1. Source table、ghost table、migration statement。
2. Copy progress、chunk size、throttle condition。
3. Replication lag / load threshold。
4. Cutover pre-check：long transaction、metadata lock、traffic。
5. Cutover duration 與 validation query。
6. Rollback / drop ghost table policy。

Cutover 前最重要的是 metadata lock pre-check。工具能降低大部分 copy 風險，但最後 rename / swap 仍需要短暫鎖。

Validation

Validation 的核心責任是證明 schema change 後資料與 query 仍正確。

1mysql -h 127.0.0.1 -P 33069 -u app_user -papp_pw appdb <<'SQL'
2SELECT COUNT(*) FROM accounts;
3SELECT COUNT(*) FROM ledger_entries;
4EXPLAIN SELECT * FROM accounts WHERE tenant_id = 'tenant-a';
5SQL

正式 migration 要補 row checksum、null rate、index usage、replication lag 與 application smoke test。

Release Gate

Release gate 的核心責任是形成交付 artifact。

1Migration:
2DDL / OSC command:
3Table size:
4MDL pre-check:
5Duration:
6Validation:
7Rollback:
8Owner:

完成本篇後，MDL 事故讀 Metadata Lock Deep Dive；工具選型讀 Online Schema Change Tools。