本文是 PostgreSQL overview 的 implementation-layer deep article。Overview 已說明 PostgreSQL 在 OLTP 譜系的定位、本文聚焦 Patroni-based HA 的 lifecycle 設計 — 從正常運作到 failover 完成的 5 段、每段配置 + failure mode + recovery。

Failover lifecycle：5 段不是一條曲線

PostgreSQL 原生沒有 auto-failover；primary 掛了、application 卡死、SRE 手動 promote standby — 整個過程通常 5-30 分鐘。Patroni 把這條鏈拆成 自動化的 5 段 lifecycle、每段有自己的 trigger、配置、失敗模式：

每段都有獨立配置、不是「設一個 timeout 就好」。後面分段展開。

Stage 1：Detection — DCS heartbeat 跟 TTL

 1# patroni.yml 核心配置
 2scope: myapp-pg-cluster
 3namespace: /db/
 4name: pg-node-1                                # 跟 hostname 一致
 5
 6etcd:
 7  hosts: etcd1:2379,etcd2:2379,etcd3:2379       # DCS quorum
 8  protocol: https
 9
10bootstrap:
11  dcs:
12    ttl: 30                                     # leader lock TTL
13    loop_wait: 10                               # patroni 主循環間隔
14    retry_timeout: 10                           # DCS retry 上限
15    maximum_lag_on_failover: 1048576            # standby 落後 1MB 內才能 promote
16    synchronous_mode: false                     # async / sync 取捨

關鍵直覺：

• TTL (30s) = leader 失聯多久才被視為 dead。設太短（< 15s）會把 transient network jitter 當 dead；設太長（> 60s）unavailability 拖長
• loop_wait + retry_timeout < TTL：Patroni 必須在 TTL 內成功跟 DCS 互動 N 次、loop_wait=10 + retry_timeout=10 給每個循環 20s buffer
• maximum_lag_on_failover：standby WAL 落後超過這個閾值就 不參與 election；防止「promote 一個落後 5 分鐘的 standby」資料丟失

Stage 2：Election — DCS quorum + watchdog 防 split-brain

1watchdog:
2  mode: required                                # required / automatic / off
3  device: /dev/watchdog
4  safety_margin: 5

Election 期間最大風險是 split-brain — network partition 下、舊 leader 還活著但跟 DCS 斷線；新 leader 從 standby 升上來、application 同時連兩個 PostgreSQL 寫。資料 divergence 後 無法自動 reconcile。

防護機制兩層：

1. DCS quorum：etcd / Consul 至少 3 node、過半 quorum 才能寫 leader key — 少數派 partition 無法 elect 新 leader
2. Watchdog (Linux kernel)：required mode 強制 — Patroni 必須定期 poke /dev/watchdog、若 Patroni 自己掛或被 OS 凍結、kernel 自動 reboot 整台機器、避免舊 leader 在 DCS 失聯後繼續接寫

Watchdog required 是 production-grade 的硬要求 — automatic / off 在 split-brain 場景下無法防護。

Stage 3：Promotion — pg_ctl + replication slot 切換

新 leader 寫 DCS key 成功後、Patroni 自動執行：

1# Patroni 內部、不要手動跑
2pg_ctl promote -D /var/lib/postgresql/data
3# postgresql.auto.conf 移除 primary_conninfo
4# postgresql.auto.conf 重新計算 timeline ID
5# 啟動接寫

Promotion 期間關鍵議題：

• timeline divergence：新 leader 開新 timeline ID（從 leader 失聯時的 LSN 開始）；其他 standby 需要 pg_rewind 把自己的 WAL fork 點對齊新 timeline
• replication slot 處理：舊 leader 上的 replication slot 在 DCS 中已 stale、新 leader 重建 slot；如果 logical replication consumer 沒 idempotent、會 replay 部分訊息
• promotion latency：通常 3-10 秒（pg_ctl 本身 < 5s、加 DCS 寫確認）

Stage 4：Reconfiguration — client routing 切換

PostgreSQL 自己升 leader 還不夠、application 不知道；要靠前端 routing 層轉發。三種典型 pattern：

1[client] → [HAProxy / pgBouncer] → [pg-node-1 (leader)]
2                                 → [pg-node-2 (standby, read)]
3                                 → [pg-node-3 (standby, read)]

Patroni REST API 暴露 /leader / /replica / /health endpoint、HAProxy 用 health check 跑這些 endpoint：

1# haproxy.cfg
2backend pg-write
3  option httpchk OPTIONS /leader
4  http-check expect status 200
5  server pg-node-1 pg-node-1:5432 check port 8008
6  server pg-node-2 pg-node-2:5432 check port 8008 backup
7  server pg-node-3 pg-node-3:5432 check port 8008 backup

Reconfiguration 期間關鍵延遲：

• HAProxy health check 間隔（預設 2s）+ failure threshold（預設 3 次）= ~6s 切換感應
• PgBouncer 不主動 health check、要靠 application 端 retry 跟 connection drop 觸發重連
• 整個 reconfiguration 端到端通常 10-20s（含 PostgreSQL promotion 時間）

Stage 5：Recovery — pg_rewind 跟 base backup 取捨

舊 leader 恢復後變 standby，但 WAL 已 divergence — 必須選一條 recovery path：

• pg_rewind：rewind 舊 leader WAL 到分歧點、重新接 streaming replication；條件 = 分歧 WAL 量小（< 幾 GB）且 timeline 可對齊
• 重 base backup：用 pg_basebackup 從新 leader 拉完整 base + WAL；條件 = 任何時候都可、但時間長（TB 級 1-4 小時）

Patroni 預設嘗試 pg_rewind、失敗才退 base backup。production 配置：

1postgresql:
2  use_pg_rewind: true
3  remove_data_directory_on_rewind_failure: true   # rewind 失敗自動清 data dir、再 base backup
4  remove_data_directory_on_diverged_timelines: true

Production 故障演練

Case 1：Split-brain due to DCS partition

徵兆：兩個 PostgreSQL node 都在接寫、application 大量寫入 conflict / unique constraint violation。

根因：DCS（etcd）partition — 兩個 etcd node 在 partition 兩側、都自認 quorum；其實是 split-vote、兩邊都不應該。Patroni 在兩邊各 elect 一個 leader。

修法：

1. DCS 必須奇數 node（3 / 5 / 7）、過半 quorum 嚴格 enforce
2. DCS 部署跨 AZ / region 時、quorum size 要考慮 partition 機率（3 AZ 各 1 node 是 production 最低標）
3. Watchdog required mode 是最後一道閘門 — DCS partition 加 quorum 失靈時、watchdog 強制 reboot 失聯 node

Case 2：Standby 落後太多、無法 failover

徵兆：primary 失聯後、Patroni log 顯示 Following members have lag greater than maximum_lag_on_failover、所有 standby 都被拒 promote、cluster unavailable。

根因：maximum_lag_on_failover 設 1MB、但 standby replication lag 累積到 50MB（write-heavy workload + slow disk on standby）。安全機制觸發、但代價是 無 standby 可升、需要人工降低門檻或等 standby catch up。

修法：

1. 預防：standby 容量 / IO 對齊 primary、避免 lag 累積；prometheus alert pg_replication_lag_bytes > 10MB 觸發前 catch
2. 臨時：手動 patronictl edit-config 把 maximum_lag_on_failover 暫時拉到 50MB、接受可能丟 50MB worth of writes、換 availability
3. 長期：sync replication（一個 standby 強制同步）、保證至少一個 standby zero-lag

Case 3：Promotion 後 application connection storm

徵兆：failover 完成後 30-120 秒內、application log 大量 connection refused / password authentication failed、application 自己 retry storm。

根因：新 leader 剛 promote、PostgreSQL max_connections 容量還在 warm up（shared memory / cache 未 prime）、application 同時湧入大量 connection request；應用 retry 不夠 jitter、queue 堆積。

修法：

1. Application 用 exponential backoff with jitter、不要 immediate retry
2. PgBouncer / connection pool 限制每 application instance 對 PG 的 connection 上限、不直連 PG
3. 預先在 standby 跑 pg_prewarm 把熱表 cache 預熱、promotion 後 cache miss 不爆

Case 4：pg_rewind 失敗、退到 base backup 沒做

徵兆：舊 leader 恢復後、Patroni log 顯示 pg_rewind failed、舊 leader 一直 STARTING、無法重接 cluster；SRE 手動跑 pg_basebackup 才恢復。

根因：remove_data_directory_on_rewind_failure: false（預設）— rewind 失敗時 Patroni 不主動清 data dir、需要 SRE 手動處理；運維沒 runbook、卡在這步幾小時。

修法：

1. Production 設 remove_data_directory_on_rewind_failure: true + remove_data_directory_on_diverged_timelines: true、讓 Patroni 自動 fallback
2. data dir 跑在獨立 PV / disk、清掉風險可控（不要跑 root disk）
3. 容量規劃：base backup 時間預估納入 RTO（TB 級 base backup 1-4 小時、不是 RTO 30 分鐘所能承受）

Case 5：Watchdog 觸發整機 reboot、誤殺

徵兆：production server 在無故障時 unexpected reboot、dmesg 顯示 watchdog: BUG: soft lockup。

根因：Patroni 主循環因 etcd 短暫慢回應卡住 60+ 秒、kernel watchdog 觸發 reboot；但實際 PostgreSQL 沒 hang、是 Patroni-watchdog 鏈過敏。

修法：

1. safety_margin 設大一點（10-15）、給 Patroni loop_wait 抖動空間
2. etcd 跟 Patroni 部署在低延遲 network 內（同 AZ < 5ms）、跨 region etcd 不建議
3. watchdog device 用 softdog（軟體模擬）vs 硬體 watchdog、debug 時 softdog 容易觀察

容量規劃

整合 / 下一步

跟 PgBouncer 整合

PgBouncer 不主動感知 Patroni failover、要靠：

1. HAProxy 在 PgBouncer 上層：HAProxy 跑 Patroni health check、PgBouncer connection 重新路由
2. PgBouncer reload：failover 後 SRE / automation 跑 pgbouncer -R、強制重連 backend
3. Connection pool drain：application 端 connection pool 設 pool_lifetime_max=5min、舊 connection 自然汰換

跟 cert-manager（TLS rotation）

Patroni REST API 跟 PostgreSQL streaming replication 都用 TLS、cert rotation 不能停服務：

1. cert-manager 自動換證後、Patroni 跟 PostgreSQL 都需要 reload（不是 restart）
2. patronictl reload <cluster> 不會觸發 failover、只 reload config
3. PostgreSQL pg_ctl reload 是 SIGHUP、平滑載入新 cert

跟 backup / PITR

Patroni 不管 backup — 但 standby promotion 後、WAL archive 必須跟新 leader 的 timeline 對齊：

1. WAL archive 命令模板含 %t（timeline）：archive_command = 'wal-g wal-push %p'
2. Backup tool（pgBackRest / WAL-G）支援 timeline 切換、archive 不會中斷
3. 詳見 PITR + WAL archiving deep article

下一步議題

• Multi-region Patroni：跨 region 部署的 DCS quorum 設計、跟單 region 的取捨完全不同
• PostgreSQL 16+ streaming replication slot 持久化：簡化 standby promotion 後 logical consumer 重連
• 跟 Kubernetes operator 整合：Patroni 跑在 K8s 時、StatefulSet + pod identity + DCS 部署模式

相關連結

• 上游 vendor 頁：PostgreSQL
• 上游 chapter：High Concurrency Access — connection / replication / HA 全鏈
• 平行 deep article：pgBouncer 配置 / Vault Dynamic Credential
• Methodology：Vendor 深度技術文章的寫作方法論

本文是 PostgreSQL overview 的 implementation-layer deep article。Overview 已說明 PG 在 OLTP 譜系的定位、本文聚焦 streaming replication topology — 從 single primary 到 multi-standby 部署的 3 個 trade-off 軸 + LSN + replication slot 機制。

Replication 的 3 個 trade-off 軸 + mode 選擇

PG streaming replication mode 選擇看起來是「async 還是 sync」、實際是 3 個獨立 trade-off 軸的組合、async / sync / quorum-based sync 是這些軸的常見組合 名稱：

跟這三軸獨立的、是 replication 機制本身的可維護性：

• LSN（Log Sequence Number）：PG 用全域 byte offset 標 WAL 進度、所有 standby 同步用 LSN 對齊、不像 MySQL 早期 binlog position + file 雙欄
• Replication slot：primary 紀錄每個 standby 已接收的 LSN、防 standby 失聯期間 WAL 被清掉、是 streaming replication 的 持久化進度追蹤

跟 MySQL Replication Topology 對比、PG 的 LSN + replication slot 直接內建 standby 進度追蹤、不像 MySQL 5.7- 要靠 binlog position + GTID 雙機制；但 slot 是 primary 紀錄、orphan slot 是 PG-specific 議題（slot 留 WAL 直到 standby 重連、standby 永久失聯 → primary disk 爆）。

Async streaming：default + 高 throughput 的代價

Async 是 PG 預設、行為：

1. Primary 寫 WAL 進 pg_wal/ 目錄、commit、回應 client OK
2. WAL sender process 把 WAL stream 給 standby
3. Standby WAL receiver 寫 standby 的 pg_wal/、startup 進程 redo 套用

Trade-off：

• Durability：primary commit 後 standby 還沒收 → primary 永久故障 → data loss（已 commit 的 transaction 在 standby 不存在）
• Latency：client 寫入延遲 = primary 自身 fsync WAL 的時間（fsync=on + synchronous_commit=on 預設、通常 < 1ms 在 SSD / NVMe）
• Consistency：standby 可能 lag、application 讀 standby 會 stale；用 pg_stat_replication.write_lag / flush_lag / replay_lag 看

配置：

1# postgresql.conf on primary
2wal_level = replica          # 至少 replica（logical 是 superset）
3max_wal_senders = 10         # 並行 WAL sender process 數（依 standby 數量）
4wal_keep_size = 1024MB       # WAL 保留量（slot 為主、但 backup buffer）
5synchronous_commit = on      # 預設、primary 自己 fsync WAL
6# synchronous_standby_names 留空 = async

適用：

• 主流選擇（90% 場景）
• Failover loss 在容忍範圍（多數 web 應用容忍 1-2 秒 data loss）
• Read scaling 為主要 driver、絕對 durability 非首要

Sync streaming：至少一個 standby flush WAL 才 commit

Sync mode 在 async 基礎上加 primary 等指定 standby flush WAL 才回 client：

1. Primary 寫 WAL、send to standby
2. Standby 收到 WAL、寫進 pg_wal/、fsync、回 ack
3. Primary 等 ack → commit → 回 client

synchronous_commit 有 5 個 level、不是 binary：

配置（synchronous）：

1synchronous_commit = on
2synchronous_standby_names = 'FIRST 1 (standby1, standby2)'
3# 'FIRST 1' = 第一個 active standby ack 即可
4# 'ANY 2 (s1, s2, s3)' = 任 2 個 ack 即可（quorum-based）

Quorum-based sync：用 ANY N 語法、達到 N 個 ack 就 commit、提高 latency stability（不依賴特定 standby）：

1synchronous_standby_names = 'ANY 2 (standby1, standby2, standby3)'
2# 3 個 standby 中任 2 個 ack 即 commit

適用：

• 金融交易 / 訂單 / payment ledger（不允許 data loss）
• 已有 multi-AZ deploy、replica 物理上可靠
• 可接受寫入延遲 +1-3ms (跨 AZ)

不適用：

• 跨 region sync（RTT 50-200ms）— 寫吞吐砍半、改用 region-local sync + cross-region async
• 寫吞吐 > 50K WPS + 容忍 sub-second loss — async 即可

LSN + Replication Slot：PG 的進度追蹤機制

PG 每個 WAL 寫入都標 LSN（64-bit byte offset）。Standby 紀錄 已收到 / 已 flush / 已 replay 的 LSN、primary 透過 streaming protocol 知道每個 standby 進度。

Replication slot 是 primary 端的 standby 進度紀錄：

1-- 建 physical replication slot（給 streaming replication 用）
2SELECT * FROM pg_create_physical_replication_slot('standby1_slot');
3
4-- 查 slot 狀態
5SELECT slot_name, active, restart_lsn, confirmed_flush_lsn,
6       pg_size_pretty(pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)) AS lag
7FROM pg_replication_slots;

Slot 的核心責任：

• 防 WAL premature deletion：standby 失聯（restart / network blip）、primary 仍保留 slot 對應 LSN 之後的 WAL、standby 重連可繼續 stream
• 無需 base backup re-build：跟沒 slot 的 standby 對比、有 slot 的 standby 失聯後重連、不用重建

Slot 跟 wal_keep_size：

• wal_keep_size（PG 13+）/ wal_keep_segments（< 13）：minimum WAL 保留量、不依賴 slot
• Slot 是 動態保留：直到 slot 的 standby 推進 LSN 才釋放對應 WAL
• 兩者組合：wal_keep_size 是底線、slot 是 standby-specific 動態保留

Standby 配置（用 slot）：

1# standby1 postgresql.conf
2primary_conninfo = 'host=primary.example.com port=5432 user=replication password=...'
3primary_slot_name = 'standby1_slot'   # 用 primary 上預先建的 slot
4hot_standby = on                       # 讓 standby 接受 read query

standby.signal 空檔案在 PG_DATA 內、告訴 PG 這是 standby、進入 recovery mode。

配置 step-by-step（sync streaming + slot）

實務最常見組合：sync streaming + replication slot + cross-AZ replica。

Step 1：Primary 配置

 1# postgresql.conf
 2wal_level = replica
 3max_wal_senders = 10
 4max_replication_slots = 10
 5synchronous_commit = on
 6synchronous_standby_names = 'FIRST 1 (standby1, standby2)'
 7wal_keep_size = 1024MB
 8
 9# pg_hba.conf — 允許 replication 連線
10host replication replication 10.0.0.0/16 scram-sha-256

Restart primary 套用。

Step 2：建 replication user + slot

1CREATE USER replication WITH REPLICATION PASSWORD '...';
2SELECT * FROM pg_create_physical_replication_slot('standby1_slot');
3SELECT * FROM pg_create_physical_replication_slot('standby2_slot');

Step 3：Standby base backup

1# 在 standby 上跑
2pg_basebackup -h primary.example.com -D /var/lib/postgresql/data \
3  -U replication -P -X stream \
4  -S standby1_slot -R
5# -R: 自動生成 standby.signal + primary_conninfo
6# -X stream: 邊 backup 邊 stream 增量 WAL（避免 backup 期間 WAL gap）

Step 4：Standby 啟動

1# standby /var/lib/postgresql/data/postgresql.auto.conf 已有：
2# primary_conninfo = 'host=primary.example.com user=replication password=... application_name=standby1'
3# primary_slot_name = 'standby1_slot'
4
5pg_ctl -D /var/lib/postgresql/data start

Step 5：驗證

1-- Primary: 確認 standby 連上
2SELECT application_name, state, sync_state, write_lag, flush_lag, replay_lag
3FROM pg_stat_replication;
4-- 應顯示 standby1 / streaming / sync / 各 lag
5
6-- Standby: 確認在 recovery + 收到 WAL
7SELECT pg_is_in_recovery(), pg_last_wal_receive_lsn(), pg_last_wal_replay_lsn();

5 個 Production 踩雷

1. Standby lag 暴衝 — Single replay process bottleneck

PG standby 是 single startup process 套用 WAL（不像 MySQL multi-thread replication）、primary 高並發寫入時 standby 跟不上、lag 從 < 100ms 飆到分鐘級。常見觸發：批次 UPDATE / DELETE、大 transaction、index 建立、autovacuum 大量 dead tuple cleanup。

修法：

• Parallel WAL apply（PG 14+）：max_parallel_workers_per_gather 增加 background worker、但仍受 startup process 主導
• 對 read scaling 場景接受 standby lag、application 用 primary read 對 latency-critical query
• Cascading replication 對 high-fan-out 解決 sender CPU bottleneck、但 standby replay 仍 single-thread

監控：pg_stat_replication.replay_lag 是 最後一個 commit 到 standby replay 的時間差、超過 threshold 即告警。

2. Sync standby 失聯時 primary commit 卡住

synchronous_standby_names = 'FIRST 1 (standby1)' + standby1 down → primary commit 等永遠。Application 全部 timeout。

修法：

• 用 ANY N quorum：synchronous_standby_names = 'ANY 1 (standby1, standby2)' — 任一 standby ack 即可
• 設多 standby、防單一失聯
• 監控 sync standby 健康、自動 failover 切 sync mode 到其他 standby（Patroni 自動做）
• 緊急情況：在 primary 跑 ALTER SYSTEM SET synchronous_standby_names = ''; SELECT pg_reload_conf(); 暫時退 async（接受 data loss risk）

3. Orphan replication slot — Primary disk 爆

Standby 失聯（永久故障 / 重 decommission 但忘了 drop slot）、primary slot 持續保留 WAL、pg_wal/ 累積到 disk 滿、primary 也掛。

修法：

• 監控 pg_replication_slots.active — false 持續 > N 小時是警訊

• 監控 slot lag：

  1SELECT slot_name, active,
  2       pg_size_pretty(pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)) AS retained_wal
  3FROM pg_replication_slots WHERE retained_wal > 10GB;

• 設 max_slot_wal_keep_size（PG 13+）— slot 對應 WAL 超過 limit 自動 invalidate slot（standby 之後要 base backup 重來）

• DR runbook 紀錄 standby 退役流程 必須包含 pg_drop_replication_slot('xxx')

4. Cascading replication 雪崩

Topology primary → standby1 → standby2 → ...（每層遞迴 stream）。Standby1 startup process 卡住、後續 standby 都被 block、整條 chain 雪崩。

修法：

• 避免超過 2 層 cascade（primary → tier1 → tier2 是上限）
• 跨 region 用 region-local tier1 + cross-region tier2、不是長 chain
• 真的大規模、改用 binlog server style：Citus / PgCat 等中介、或 logical replication 解耦

5. Failover 後 timeline 分歧

Primary 失敗、standby1 promote 為新 primary、其他 standby（standby2 / 3）原本連舊 primary、必須重新連 standby1。但 PG 用 timeline（每次 promotion 增 1）標 WAL 分支、原 standby 的 timeline 跟新 primary 不同。重連時看到 timeline mismatch、報錯。

修法：

• pg_rewind 工具：對比新 primary 跟舊 standby 的 timeline 分歧點、把舊 standby 上 新 primary 沒有的 WAL 倒退、然後從分歧點重新跟新 primary 同步
• Base backup re-build：對舊 standby 重建 — 慢但保證乾淨
• Patroni 自動處理 pg_rewind / base backup 選擇

容量 / cost 對照

跨 AZ sync 通常加 1-3ms、跨 region 加 50-200ms — 寫密集 workload 跨 region sync 通常不划算、改用 region-local sync + cross-region async chain。

整合 / 下一步

Patroni HA

Patroni 是 PG HA 自動 failover 標準、依賴 DCS（etcd / Consul）+ 本文 replication topology。Patroni 自動：

• 偵測 primary 失聯、promote 適合 standby
• 處理 timeline 分歧（pg_rewind）
• 重配 sync standby（避免 sync standby 失聯卡 primary）

Logical Replication + Debezium

Logical replication + Debezium 是 跟 streaming replication 共用 WAL 但不同 abstraction — logical decoding output event、streaming replication output physical bytes。Logical replication slot 跟 physical slot 共存、各自獨立 retention。

PITR + WAL Archiving

PITR + WAL Archiving 用 archive_command 把 WAL ship 到 S3、跟 streaming replication 並行：

• Streaming：給 活的 standby（real-time read scaling / HA）
• Archive：給 PITR + 新 standby base backup source

兩者使用同一 WAL stream、不衝突。

Connection 路由（PgBouncer + read/write split）

PgBouncer 不做 read/write split（transaction pool 不看 SQL）。Read replica routing 通常用 application-level 或 HAProxy 監控 standby health。

跟 MySQL Replication Topology 對比

兩者 high-level 對等、低層機制有顯著差異。詳見 MySQL Replication Topology。

相關連結

• PostgreSQL vendor overview
• PG Patroni HA（HA failover、依賴本文 replication topology）
• PG Logical Replication + Debezium（不同 abstraction、共用 WAL）
• PG PITR + WAL Archiving（streaming + archive 並行）
• PG PgBouncer（connection pool、不做 read/write split）
• MySQL Replication Topology（sibling、不同機制）
• quorum 卡片 / stale-read 卡片 / eventual-consistency 卡片
• 官方：PG Streaming Replication / pg_basebackup

本文是 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

本文是 PostgreSQL overview 的 implementation-layer deep article。Overview 已說明 PG 在 OLTP 譜系的定位、本文聚焦 connection scaling 的根因 — 為什麼 PG 比多數 DB 更需要 pooler、跟 pgbouncer-config 是 根因 vs 配置 的關係。

Connection-per-Process Model 是 PG 的結構性選擇

PG 接受 client connection 時的行為跟多數現代 DB 不同：每個 connection 由 postmaster fork() 一個獨立的 OS process（backend）來服務。這個 process 在 connection lifetime 內專屬該 client、不跟其他 client 共享。

對比常見 DB 的 connection model：

PG 選 process 不選 thread 是 1990s 設計決定 — 當時 thread library 在多 UNIX 平台不穩定、process 隔離性更好（一個 backend crash 不會帶倒整個 DB）。這個 trade-off 一路保留到今天、是 PG 在 high-connection-count workload 的 結構性負擔。

量化：connection 數量對 RAM 跟 CPU 的壓力

一個 PG backend process 的 RAM footprint 由三部分組成：

1backend_rss ≈ shared_buffers_attach + process_private + work_mem 高水位

shared_buffers 是所有 backend 共享的、不重複計、但 process_private（catalog cache / plan cache / temp buffer）跟 work_mem 是 per-backend：

500 個 connection、平均 30MB 各 ≈ 15GB RAM 給 backend processes（還沒算 shared_buffers）。這是 PG 在 cloud instance 上很快撞到 RAM ceiling 的根因。

CPU 層面、fork() 系統呼叫在 Linux 通常 1-3ms、context switch ~3-5μs。100 connection burst 在 1 秒內進來、accumulated fork cost 100-300ms、加 query 本身的 CPU 跟 scheduler latency、平均 query 延遲會跳 2-5x。

三個 GUC 互動：max_connections / shared_buffers / work_mem

PG 的 memory 規劃由這三個 GUC 互動決定、不能獨立調：

1total_RAM ≈ shared_buffers + (max_connections × work_mem 高水位) + OS overhead

實務 sizing 規則（16GB instance、OLTP workload）：

max_connections = 1000 是常見 anti-pattern — 真實 active query 可能只 50-100、剩下都 idle、但每個還是吃 RAM 跟 process slot、context switch overhead 還在。

Pooler 為什麼是 production prerequisite

本段是「為什麼必裝」、實際 PgBouncer 配置看 pgbouncer-config。

Pooler 的核心責任是 把 N 個 application connection multiplex 成 M 個 PG backend（M ≪ N）：

1Application (3000 connection)
2   ↓
3Pooler（PgBouncer / PgCat）
4   ↓
5PostgreSQL (50 backend process)

Application 看到的是 無限 connection 池、PG 看到的是 穩定 50 個 backend。三個層次的效益：

1. RAM 節省：3000 connection × 30MB = 90GB → 50 backend × 30MB = 1.5GB
2. Fork() cost 攤平：backend 重用、不是每個 client 都 fork
3. Connection storm 緩衝：application 重啟 / scaling event 不會直接打到 PG

Pooler 有三種 pool mode、各有 application 層相容性 trade-off：

Production 多數選 transaction pool — 救 RAM 又保留 transaction semantics、代價是 application 不能用 session-level SET、LISTEN/NOTIFY、prepared statement（部分 pooler 已支援）。

Application-side Pool vs Middleware Pool vs RDS Proxy

三層 pool 都能解 connection 問題、但解的問題不同：

典型 production 拓撲：

1Application (HikariCP pool 10/instance × 50 instance = 500)
2   ↓
3PgBouncer transaction pool（50 backend）
4   ↓
5PostgreSQL primary

Application pool 救 fork cost、PgBouncer 救 backend 總量、兩層各做各的事不衝突。

雙層 pool 配置容易出錯：application pool size 5 + PgBouncer default_pool_size 50 + 100 個 app instance、application 願意開 500 connection、PgBouncer 只給 50 個 backend — 多 450 個 application connection wait、看起來像「DB 慢」但實際是 pool 不足。

5 個 Production 踩雷

Case 1：Connection storm（重啟 / autoscale 同時打進來）

情境：Kubernetes rolling restart、200 個 pod 同時重連、每 pod 開 20 個 connection、瞬間 4000 個 connection 嘗試打到 PG。

PG max_connections = 500 直接拒絕 3500 個、application 看到 FATAL: sorry, too many clients already、retry storm 雪上加霜。

修法：

• PgBouncer 在前面、application 連 PgBouncer 不直連 PG
• reserve_pool_size = 5 給管理流量留 buffer
• Application 端加 jittered exponential backoff、避免 retry 同步

Case 2：fork() cost 在 burst 流量

情境：Cron job 每分鐘整點觸發、500 個 worker 同時開 short-lived connection 跑 30ms query、結束關閉。

每分鐘 500 次 fork() + 500 次 exit()、fork cost 500-1500ms、CPU spike、其他 OLTP query 延遲飆。

修法：

• Worker 改 connect 到 PgBouncer transaction pool、backend 重用、fork 只在 PgBouncer 首次拓展時
• 或 worker 改成 long-lived process + 內部 task queue、避免每分鐘重 fork

Case 3：shared_buffers 跟 max_connections 互相壓縮

情境：16GB instance、shared_buffers = 8GB（50%）、max_connections = 800、work_mem = 16MB。

預估 RAM：8GB + 800 × ~30MB = 32GB ≫ 16GB instance、OOM kill 來訪。

修法（重新分配）：

1shared_buffers = 4GB           # 25%
2max_connections = 200          # 透過 PgBouncer multiplex
3work_mem = 16MB
4effective_cache_size = 12GB
5maintenance_work_mem = 512MB

關鍵：max_connections 不是調更大救 connection 不足、是調 PgBouncer pool size 拓展 application 容量。

Case 4：Double-pool 配置失敗

情境：Application HikariCP pool size = 50、50 個 instance、PgBouncer default_pool_size = 20、PG max_connections = 100。

Application 願意開 2500 個 connection、PgBouncer 只給 20 個 backend、application thread 大量 block 在 PgBouncer 等 backend 釋出。

修法：

• 計算 application 願意的並發 vs PgBouncer 允許的 backend vs PG max_connections 三層匹配
• 通常 application_total_connection ≪ pgbouncer_max_client_conn + pgbouncer_default_pool_size + reserve ≪ pg_max_connections
• Monitor PgBouncer SHOW POOLS 的 cl_waiting、長期 > 0 表示 pool 不足

Case 5：max_connections 設太大反而慢

情境：team 看到 connection refused、把 max_connections 從 200 調到 2000、想說「給更多 connection 應該更好」。

調完 throughput 反而降 30% — context switch overhead、planner cache 競爭、lock manager 競爭都跟 connection 數線性放大。

修法：

• max_connections 上限通常 200-500、超過要靠 pooler multiplex
• 用 pg_stat_activity 看真實 active connection（state != ‘idle’）、通常 < 100
• 真實上限 = active 高水位 × 安全係數 1.5、不是「未來可能會用到的數量」

跟 MySQL connection model 對比

MySQL thread-per-connection model 讓它在 high-connection-count workload 上 看起來 更省 — 但 PG 透過 PgBouncer 達到的 application 看到的容量跟 MySQL 直連是一樣的、只是多一層 indirection。

實務影響：

• MySQL 直連 1000 connection 還 OK、PG 直連 1000 connection 通常 OOM
• PG + PgBouncer 1000 application connection、後端 50 backend、表現跟 MySQL 1000 直連相當
• 沒有 PG 更耗 RAM 的本質結論、是 PG 預設不 multiplex、需要外掛 multiplex 層

PG 17+ 的 connection 進展

PG 17（2024）對 connection 仍維持 process-per-connection、但有幾個減壓改進：

• Per-process memory 降低：catalog cache 改 generational allocator、idle backend RAM 降 ~20%
• Subscriber-side parallel apply：logical replication 減少 connection 開銷
• io_combine_limit：buffered read 合併、降 syscall overhead

但 process-per-connection model 本身 沒換 — 短期內 PG 仍需 pooler。長期方向（PG 18+ 討論）可能引入 thread-based backend、但目前是 experimental patch。

相關連結

• pgbouncer-config：PgBouncer 操作配置 + 5 case
• replication-topology：Read replica + connection 分流
• query-optimization：work_mem 影響 plan
• mvcc-lock-model：connection idle in transaction 卡 vacuum
• autovacuum-tuning：autovacuum 也吃 connection slot

下一步

• 連到 pgbouncer-config 學配置細節
• 看 PostgreSQL overview 回到全圖

本文是 PostgreSQL overview 的 implementation-layer deep article。Overview 已說明 PG 在 OLTP 譜系的定位、本文聚焦 index 選型 — 何時用哪種 index、跟 query-optimization 的「為什麼這個 plan 慢」互補。

6 種 Index Method 對應 Workload

PG 有 6 種 index access method、各有自己擅長的 query pattern：

選錯 index 的代價：

• Write workload：每 write 都更新所有相關 index、5 個 unused index = 5x write 放大
• Storage：JSONB 加 GIN 可能比表本身還大
• Plan misjudge：planner 看到 index 不一定用、EXPLAIN 才確認

B-tree：預設選擇、95% workload 適用

B-tree 是 PG 預設 index、CREATE INDEX 不指定 method 就是 B-tree：

1CREATE INDEX idx_orders_user_id ON orders (user_id);
2CREATE INDEX idx_orders_created_at ON orders (created_at);

B-tree 擅長的 query：

 1-- 等值
 2SELECT * FROM orders WHERE user_id = 42;
 3
 4-- 範圍
 5SELECT * FROM orders WHERE created_at BETWEEN '2025-01-01' AND '2025-01-31';
 6
 7-- IS NULL
 8SELECT * FROM orders WHERE shipped_at IS NULL;
 9
10-- Prefix LIKE
11SELECT * FROM products WHERE sku LIKE 'ABC%';

B-tree 不擅長：

• LIKE '%suffix'（前綴 wildcard）→ 改 trigram + GIN
• column @> array（包含）→ 改 GIN
• JSON 內部 path query → 改 GIN on JSONB

Multi-column B-tree 的順序很重要：

1-- 假設常 query: WHERE user_id = ? AND status = ?
2CREATE INDEX idx_orders_user_status ON orders (user_id, status);  -- 對
3CREATE INDEX idx_orders_status_user ON orders (status, user_id);  -- 錯（status 選擇性低）

順序原則：

1. 等值 column 在前（高選擇性）
2. 範圍 column 在後（B-tree leftmost 規則）
3. selectivity 高的在前（filter 更多 row）

GIN：JSONB / FTS / Array 的標配

GIN（Generalized Inverted Index）對「一個 value 內含多個 sub-element」的 column 高效：

 1-- JSONB
 2CREATE INDEX idx_products_metadata ON products USING GIN (metadata);
 3
 4-- Array
 5CREATE INDEX idx_articles_tags ON articles USING GIN (tags);
 6
 7-- Full-text search
 8CREATE INDEX idx_articles_content ON articles USING GIN (to_tsvector('english', content));
 9
10-- Trigram（fuzzy match）
11CREATE EXTENSION pg_trgm;
12CREATE INDEX idx_products_name_trgm ON products USING GIN (name gin_trgm_ops);

GIN 代價：

• Write 慢 2-10x：每個 sub-element 都要更新 inverted index
• Storage 大：可能比表還大
• Vacuum 沉重：bloat 累積快

Operator class 選擇影響大：

只用 @> query 時、jsonb_path_ops 救大量 storage。

GiST：範圍 / 空間 / 自訂

GiST（Generalized Search Tree）擅長範圍跟空間：

1-- 範圍 type（PostgreSQL 內建 int4range / tsrange 等）
2CREATE INDEX idx_bookings_period ON bookings USING GiST (period);
3
4-- 空間（PostGIS）
5CREATE INDEX idx_locations_geom ON locations USING GiST (geom);
6
7-- Exclusion constraint（範圍不重疊）
8ALTER TABLE bookings ADD CONSTRAINT no_overlap
9EXCLUDE USING GiST (room_id WITH =, period WITH &&);

GiST vs GIN 對 FTS 的選擇：

多數 FTS workload 選 GIN — read 占多、index size 換 query latency 划算。

BRIN：大表 + Physical Order Correlated

BRIN（Block Range Index）對 physical 儲存順序跟 logical 順序強相關 的 column 高效：

1-- timestamp column（append-only insert、physical 順序 = 時間順序）
2CREATE INDEX idx_events_created_at ON events USING BRIN (created_at);

BRIN 機制：每個 block range（預設 128 page）記 min/max、query 時跳過 range 外的 block。

適用場景：

• append-only 表：log、metrics、events
• 大表（10GB+）：B-tree 太貴、BRIN 1/1000 大小
• column physical order 跟 query 一致：時間欄、自增 id

BRIN 失效情境：

• UPDATE 破壞 physical order（row 被 vacuum 移到別 block）→ BRIN 失效
• 隨機 insert（uuid / hash id）→ BRIN range 完全沒選擇性

何時不該用 BRIN：表 < 1GB（沒省 storage 收益）、column 沒 physical order correlation（CLUSTER 後可能改善）。

Partial Index：條件式 index 救 storage

對 只 query 部分 row 的 column、partial index 救大量 storage：

 1-- 只 index unshipped order
 2CREATE INDEX idx_orders_unshipped ON orders (created_at)
 3WHERE shipped_at IS NULL;
 4
 5-- 只 index active user
 6CREATE INDEX idx_users_active ON users (email)
 7WHERE status = 'active';
 8
 9-- 只 index 高金額 transaction
10CREATE INDEX idx_orders_high_value ON orders (user_id)
11WHERE total > 1000;

Partial index 的 query 要 完全匹配 WHERE 條件 才用得到：

1-- 用得到 partial index
2SELECT * FROM orders WHERE shipped_at IS NULL AND created_at > '2025-01-01';
3
4-- 用不到（planner 不 prove WHERE 包含 partial 條件）
5SELECT * FROM orders WHERE created_at > '2025-01-01';

實務 size 救法：unshipped order 只 1% 總量、partial index 1/100 大小。

Expression Index：對函式結果 index

 1-- 對 lowercased email index（case-insensitive search）
 2CREATE INDEX idx_users_email_lower ON users (lower(email));
 3SELECT * FROM users WHERE lower(email) = lower('USER@example.com');
 4
 5-- 對 JSONB 內部欄位
 6CREATE INDEX idx_products_category ON products ((metadata->>'category'));
 7SELECT * FROM products WHERE metadata->>'category' = 'shoes';
 8
 9-- 對日期截斷
10CREATE INDEX idx_orders_day ON orders (date_trunc('day', created_at));

Expression 必須 IMMUTABLE — now() / random() 不能用、timezone('UTC', ts) 可以。

Covering Index（INCLUDE）：避免回表

PG 11+ 支援 INCLUDE column：

1-- 只 index user_id、但 query 常要 email
2CREATE INDEX idx_users_user_id_covering ON users (user_id) INCLUDE (email);
3
4-- Index-only scan：不用回表
5SELECT email FROM users WHERE user_id = 42;

INCLUDE column 不參與 sorting / equality、只放 leaf node、救 IO。

Index 選擇決策樹

 1Query pattern 是什麼？
 2
 3├─ 等值 / 範圍 / prefix LIKE / IS NULL
 4│  └─ B-tree（90% 場景）
 5│     ├─ 只 query 部分 row？→ Partial B-tree
 6│     ├─ 對函式結果？→ Expression B-tree
 7│     └─ 需要回表更多 column？→ Covering（INCLUDE）
 8│
 9├─ JSONB 內部 query / array 包含 / FTS
10│  └─ GIN
11│     ├─ 只用 @>？→ jsonb_path_ops 救 storage
12│     └─ FTS write-heavy？→ 改 GiST
13│
14├─ 範圍 type（int4range / tsrange）/ 空間
15│  └─ GiST
16│
17├─ 大表 + append-only + physical order correlated
18│  └─ BRIN
19│
20├─ 純 equality + 簡單 column
21│  └─ Hash（很少用、B-tree 通常更好）
22│
23└─ Non-balanced 樹（IP prefix / quad-tree）
24   └─ SP-GiST（罕見）

5 個 Production 踩雷

Case 1：過度 index（write 放大）

情境：team「為了 query 快」對 20 個 column 各建 index、寫入量大時 INSERT 慢 10x。

每個 INSERT 要更新 20 個 index、WAL volume 也跟著放大、replication lag 拉長。

修法：

• 用 pg_stat_user_indexes 找 idx_scan = 0 的 index、可能根本沒用
• 用 pg_stat_statements 找實際被執行的 query、反推真正需要的 index
• 同 column 多 index（user_id 單欄 + (user_id, status) 多欄）通常可拆掉單欄

Case 2：Partial index 條件跟 query 不匹配

情境：建 WHERE status = 'active' partial index、application query 寫 WHERE status IN ('active')、planner 不 prove 等價、不用 index。

修法：

• Partial 條件用最 generic form（避免 IN / OR 跟 = 的差異）
• 寫完用 EXPLAIN 驗證 query 真的用到 partial index
• Application 統一 query 寫法、不要混 = 跟 IN 跟 ANY

Case 3：B-tree 對 JSONB 內部欄位無效

情境：對 metadata JSONB column 建 B-tree、query metadata->>'category' = 'shoes' 不用 index。

B-tree 對 整個 JSONB 排序、但 path query 不是整個 JSONB 的比對。

修法：

• 對固定 path 建 expression index：CREATE INDEX ... ON products ((metadata->>'category'))
• 對動態 path 建 GIN index：CREATE INDEX ... USING GIN (metadata)
• 兩者並存可、EXPLAIN 看 planner 選哪個

Case 4：BRIN 對非 correlated 資料無效

情境：對 user_id 建 BRIN index（user_id 是隨機 UUID）、query 完全跑 seq scan。

UUID 沒 physical order correlation、每個 block range 的 min/max 涵蓋整個 ID space、BRIN 完全沒 prune 效果。

修法：

• BRIN 只用 timestamp / 自增 id / 其他自然 correlate 的 column
• 用 pg_stats 看 correlation value、< 0.1 就不適合 BRIN
• 真要對 random column 加 index、回 B-tree

Case 5：Multi-column index 順序錯

情境：常見 query WHERE status = 'pending' AND user_id = 42、建 index (status, user_id)、效能差。

status 只 5 個 distinct value、選擇性 1/5；user_id 1M distinct、選擇性 1/1M。Index leftmost 是 status、scan range 太大。

修法：

1-- 拆兩個或調順序
2CREATE INDEX idx_user_status ON orders (user_id, status);
3
4-- 或加 partial 限定低選擇性 column
5CREATE INDEX idx_orders_pending ON orders (user_id) WHERE status = 'pending';

跟 MySQL Index 差異

PG index 系統比 MySQL 表達力高、但代價是 選對 index method 是 application 責任、MySQL 預設 B-tree 多數場景夠用。

相關連結

• query-optimization：EXPLAIN 看 index 用沒用
• jsonb-deep-dive：JSONB + GIN 細節
• full-text-search：FTS + GIN
• autovacuum-tuning：index bloat
• online-schema-change：CREATE INDEX CONCURRENTLY

下一步

• 看 query-optimization 驗證 index 有沒有被 plan 用到
• 回 PostgreSQL overview 看全圖

本文是 PostgreSQL overview 的 implementation-layer deep article。Overview 已說明 PG 在 OLTP 譜系的定位、本文聚焦 Citus distributed extension — 把 PG 變成 sharded cluster 的方式。

當 PG single-primary 寫吞吐撞上單機極限（50K-100K WPS）、選項三條：

1. Application 層 sharding：應用層自管 shard routing
2. Citus：PG extension、自動 routing + cross-shard query
3. Distributed SQL（CockroachDB / Aurora DSQL / Spanner）：不同 engine

選 Citus 的核心 driver：保留 PG SQL syntax + extension 生態。但「應用層幾乎不必改」是樂觀說法 — 實際上 application 必須圍繞 distribution column 重設計（query 加 filter / transaction 限定同 shard / reference table 量控制）、跟 Vitess 比 cross-shard query 自動化弱。代價是 coordinator / worker 部署複雜度 + cross-shard query 限制 + application schema 改造工作量。

閱讀本文前可先對齊 Database Sharding 的 shard key、routing、resharding 與 cross-shard query 語意；容量失衡時再接 Hot Partition。

跟 MySQL Vitess sharding 的核心差異：Citus 是 PG extension（PG 自己跑）、Vitess 是 獨立 proxy + tablet 系統（包 MySQL）。Citus 用 PG 原生機制（FDW / extension hook）、Vitess 是 外部包裝。

Citus 架構：Coordinator + Worker

 1                ┌─────────────────┐
 2   Application  │   Coordinator   │  ← 對外 PG wire protocol、planner、routing
 3                │   (Citus + PG)  │
 4                └────┬─────┬──────┘
 5                     │     │
 6              ┌──────┘     └──────┐
 7              ▼                   ▼
 8        ┌──────────┐         ┌──────────┐
 9        │ Worker 1 │         │ Worker 2 │  ← 各跑 PG + Citus extension
10        │  (PG)    │         │  (PG)    │
11        │ shard 1,3│         │ shard 2,4│
12        └──────────┘         └──────────┘

Coordinator：

• 對 application 看起來像 PG（同 port / 同 wire protocol）
• 接 SQL → Citus planner 把 query 分解 + route 給 worker
• 不存 data（distributed table 的 shard 在 worker 上）
• 存 metadata（哪個 shard 在哪個 worker）

Worker：

• 標準 PG instance + Citus extension
• 各存若干 shard
• 接 coordinator 來的 query、跑 local execute、回結果

Shard：

• Distributed table 拆成 N 個 shard（預設 32）
• 每 shard 是 worker 上的 physical PG table（含 _<shardid> 後綴）
• 行為跟一般 PG table 一樣、可以直接連 worker 用 PG 工具 access

3 種 Table Type

Distributed table — 跨 shard 切分

 1-- 建一般 PG table
 2CREATE TABLE orders (
 3    id BIGSERIAL,
 4    user_id BIGINT NOT NULL,
 5    amount DECIMAL(10,2),
 6    created_at TIMESTAMP,
 7    PRIMARY KEY (user_id, id)  -- PK 必須含 distribution column
 8);
 9
10-- 用 Citus 把它變 distributed
11SELECT create_distributed_table('orders', 'user_id');

user_id 是 distribution column — Citus 用它的 hash 決定 row 屬哪個 shard。PK 必須含 distribution column（跟 MySQL partitioning 同要求）。

跟 Vitess Vindex 對比：

• Citus：hash distribution column → shard（單一 hash function、不可選 algorithm）
• Vitess：Vindex 可選多種（hash / lookup_hash / xxhash / null）

Reference table — 全 shard 共有

1CREATE TABLE products (
2    id SERIAL PRIMARY KEY,
3    name VARCHAR(100),
4    price DECIMAL
5);
6
7SELECT create_reference_table('products');

products 在 每個 worker 都有完整 copy、寫入 coordinator 廣播給所有 worker。

用途：

• 小 lookup table（country code / product category 等）
• 跨 distributed table JOIN 時、reference table 在每 worker 上、不必 cross-shard
• 寫入頻率低（廣播 cost 跟 worker 數 linear）

Local table — Coordinator 上的 PG table

1CREATE TABLE audit_log (
2    id SERIAL PRIMARY KEY,
3    event JSONB
4);
5-- 不調用 Citus function、預設留在 coordinator

行為跟一般 PG table 一樣。用於 不需 distribute 的 table（如 admin metadata）。

Colocation：跨 distributed table 同 shard 對齊

當兩個 distributed table 都用 同 distribution column（例如 user_id）+ 同 shard count、Citus 自動 colocate：

1SELECT create_distributed_table('orders', 'user_id');
2SELECT create_distributed_table('user_addresses', 'user_id', colocate_with => 'orders');

Colocate 後：

• user_id = 100 的 orders 跟 user_addresses 在 同一 worker shard
• JOIN 不跨 worker、效率高
• 可用 PG 原生 FK constraint（cross-table 但同 shard）

Colocate 是 Citus 設計的核心 跨 table 一致性 機制。沒 colocate 的 cross-table query 變 cross-worker、效率大降。

配置 step-by-step（local cluster）

Production 用 Citus Cloud（Microsoft 託管）或 Azure Cosmos DB for PostgreSQL（同 engine）。Self-hosted：

Step 1：Coordinator + worker 都裝 PG + Citus

1# 在每個 node（coordinator + 2 worker）
2apt install postgresql-14
3apt install postgresql-14-citus-12.0
4
5# postgresql.conf
6shared_preload_libraries = 'citus'
7
8systemctl restart postgresql

1-- 在每個 node 跑
2CREATE EXTENSION citus;

Step 2：Coordinator 註冊 worker

1-- 在 coordinator 跑
2SELECT citus_add_node('worker1.example.com', 5432);
3SELECT citus_add_node('worker2.example.com', 5432);
4
5-- 確認
6SELECT * FROM citus_get_active_worker_nodes();

Step 3：建 distributed table

1CREATE TABLE orders (
2    id BIGSERIAL,
3    user_id BIGINT NOT NULL,
4    amount DECIMAL(10,2),
5    created_at TIMESTAMP,
6    PRIMARY KEY (user_id, id)
7);
8
9SELECT create_distributed_table('orders', 'user_id');

Citus 自動把 orders 拆成 32 個 shard（orders_102008 等）、分配到 worker。

Step 4：Application 連 coordinator

Application connection string 連 coordinator IP / port（不必知道 worker 存在）。

1-- 從 application 跑 query、Citus 透明 route
2INSERT INTO orders (user_id, amount) VALUES (12345, 50);
3-- → Citus 看 user_id=12345 hash 屬 shard 17、route 給對應 worker
4
5SELECT * FROM orders WHERE user_id = 12345;
6-- → Single-shard query、極快
7
8SELECT count(*) FROM orders;
9-- → Cross-shard aggregation、Citus 並行跑、合併結果

5 個 Production 踩雷

1. Distribution column 選錯 — Cross-shard query 變主流

選 created_at 或 id（auto increment）作 distribution column、看起來均勻、實際 application query 多以 user_id 為主、變成 每個 query 都 cross-shard、performance 雪崩。

修法：

• Distribution column 選 application 最常 filter / join 的 column（通常是 tenant_id / user_id）
• Audit application top query、確認 distribution column 對齊 query pattern
• 改 distribution column 要 rewrite 所有 shard、像 resharding、大工程

2. Cross-shard transaction 限制

跨多 shard 的 transaction（如：UPDATE 兩個 user_id 不同的 row）Citus 用 2PC（two-phase commit）但有限制：

• Multi-statement transaction 跨 shard 需明確開 SET citus.multi_shard_modify_mode = 'sequential'
• 部分 isolation level 不保證 serializable across shards
• DDL 跨 shard 是 sequential

修法：

• Schema design 避免 cross-shard transaction（同 colocation group 內 transaction 沒問題）
• 必要 cross-shard 場景明確設 multi-shard mode
• 對 strict cross-shard consistency、考慮 distributed SQL（CockroachDB / Aurora DSQL）

3. Reference table 過大 — 寫入廣播 cost 爆

Reference table 在每 worker 都有 copy、寫入 廣播給所有 worker。Reference table 100K row + 高頻寫入 → 寫一次寫 N worker、cost N x。

修法：

• Reference table 限 小 + 寫入頻率低 的 lookup data
• 超大表不該是 reference table、考慮 distributed
• 監控 reference table 寫入 rate、超 threshold 重新評估

4. Colocate 沒對齊 — 隱性 cross-shard JOIN

1-- 看似可以、實際 cross-shard 慢
2SELECT * FROM orders o JOIN user_addresses ua ON o.user_id = ua.user_id;

若 user_addresses 沒 colocate_with => 'orders'、兩表 shard 分配獨立、JOIN 跨 worker。

修法：

• 建相關 table 時 colocate_with 對齊
• 用 SELECT * FROM citus_tables 看 colocation_id、確認對齊
• 跨非 colocate table 的 JOIN 用 materialized view 或 application 層拆 query 避開

5. Worker failover — Coordinator 必須知道

Worker 故障、Citus 預設 coordinator 看到 query 失敗、不自動 failover。

修法（Citus 11+）：

• 用 shard replication（citus.shard_replication_factor = 2）— 每 shard 在 2 個 worker 有 copy
• 配 PG streaming replication 在 worker 層、外加 Patroni 管 failover
• Coordinator 失敗 → 整個 cluster 失能、coordinator 也要 HA（Patroni）

跟 Vitess 對比 Citus 的 HA story 較弱、production 必須認真規劃。

何時用 Citus

容量規劃

• Coordinator: 中等 CPU + RAM、metadata 不大、不存 data
• Worker: per-worker spec 同 single PG production
• Shard count: 預設 32、實務常設 worker count × 4-8
• Replication factor: production 至少 2

跟其他模組整合

跟 Replication topology

Coordinator + worker 各跑 PG streaming replication、Citus 不取代 PG replication。Worker failover 用 Patroni / streaming replication。詳見 Replication Topology。

跟 PG Extensions

Citus 跟其他 PG extension 多數兼容（pgvector / TimescaleDB / pg_stat_statements）— 它維持 extension 形態，保留 PostgreSQL 生態接點。詳見 PG Extension Ecosystem 篇（待寫）。

跟 MySQL Vitess

Citus 對 PG-native 場景更平順、Vitess 對 MySQL-native 場景更平順、不直接競爭。詳見 MySQL Vitess Sharding。

相關連結

• PostgreSQL vendor overview
• PG Replication Topology（per-worker replication）
• PG MVCC + Lock Model（cross-shard transaction lock 行為）
• 1.11 全球分散式 OLTP（Citus vs CockroachDB vs Spanner）
• MySQL Vitess Sharding（sibling、不同實作）
• Cosmos DB vendor（Azure Cosmos DB for PostgreSQL = managed Citus）
• 官方：Citus Documentation / Citus on GitHub

本文是 PostgreSQL overview 的 implementation-layer deep article。Overview 已說明 PG 在 OLTP 譜系的定位、本文聚焦 SQL features baseline — PG 早期就有的、MySQL 8.0 才補的、PG 仍領先的、給從 MySQL 評估 PG 的讀者 reference。

PG SQL 工程深度的歷史錨點

PG 在 SQL feature 上長期領先 MySQL：

• 2009 (PG 8.4)：CTE / window function / recursive query
• 2013 (PG 9.3)：lateral derived table / materialized view
• 2014 (PG 9.4)：JSONB / partial index 早就有 / GIN index
• 2015 (PG 9.5)：UPSERT (ON CONFLICT)
• 2017 (PG 10)：declarative partitioning / logical replication / multi-column statistics

MySQL 8.0（2018）才補 CTE / window / lateral / JSON_TABLE / hash join — PG 早 9 年起步。

對 從 MySQL 評估 PG 的讀者來說、PG 的 SQL 工程深度不只是「該有的都有」、更多是「PG 結構性領先的特性 + MySQL 8.0 補了哪些 + PG 仍領先哪些」。

跟 MySQL Modern SQL Features 對比視角：

• MySQL 8.0 視角：「我終於補齊 + 跟 PG 對比」
• PG 視角：「我長期領先 + MySQL 8.0 才追上某些、其他我仍領先」

PG 結構性領先特性（MySQL 沒對應 / 弱對應）

1. Materialized View

PG 9.3+ 內建 materialized view：

1CREATE MATERIALIZED VIEW orders_summary AS
2SELECT user_id, COUNT(*) AS order_count, SUM(amount) AS total
3FROM orders GROUP BY user_id;
4
5-- 手動 refresh
6REFRESH MATERIALIZED VIEW orders_summary;
7-- 或 concurrent refresh（PG 9.4+、不 lock read）
8REFRESH MATERIALIZED VIEW CONCURRENTLY orders_summary;

用途：

• 預計算複雜 aggregation、查詢時極快
• Concurrent refresh 不 lock read
• 可建 index on materialized view

MySQL 對應：沒原生 materialized view。常見替代：

• Trigger + summary table（手動維護）
• Application 層 caching layer
• 用 view + cache layer（不是 materialization）

MySQL 8.0+ 仍無原生 materialized view。

2. Partial Index

PG 預設支援 partial index — 對 滿足條件的 row 才建 index：

1-- 只對 active user 建 index
2CREATE INDEX idx_users_active_email ON users(email) WHERE status = 'active';
3
4-- Index size 比 full index 小很多、query 性能跟 full index 一樣
5SELECT * FROM users WHERE status = 'active' AND email = 'x@y.com';

用途：

• Soft-delete 場景：對 deleted_at IS NULL 建 partial index
• Hot subset 場景：對 status = 'pending' 等熱資料建 partial
• Index 大小 / 寫入成本大降

MySQL 對應：MySQL 沒原生 partial index。MySQL 8.0+ 有 functional index 但跟 partial 不同。MySQL 替代：

• Generated column + index（接近、但維護複雜）
• 或接受 full index cost

3. Foreign Data Wrapper (FDW)

PG FDW 讓 query 跨外部資料源：

 1CREATE EXTENSION postgres_fdw;
 2
 3CREATE SERVER remote_db FOREIGN DATA WRAPPER postgres_fdw
 4OPTIONS (host 'remote.example.com', dbname 'analytics');
 5
 6CREATE USER MAPPING FOR localuser SERVER remote_db
 7OPTIONS (user 'remoteuser', password '...');
 8
 9CREATE FOREIGN TABLE remote_orders (id INT, ...) SERVER remote_db OPTIONS (table_name 'orders');
10
11-- 在 local PG query remote table
12SELECT * FROM remote_orders WHERE id = 100;

支援 FDW：postgres_fdw / mysql_fdw / oracle_fdw / mongo_fdw / file_fdw / redis_fdw 等。

MySQL 對應：MySQL 8.0+ 有 FEDERATED engine（受限、不推薦）。實務上 MySQL 跨 DB query 用 application 層處理。

4. JSONB + GIN Index（PG 結構性優勢）

PG JSONB 是 binary 儲存 + 可 直接 GIN index：

 1CREATE TABLE products (
 2    id SERIAL PRIMARY KEY,
 3    metadata JSONB
 4);
 5
 6-- GIN index over JSONB
 7CREATE INDEX idx_products_metadata ON products USING GIN (metadata);
 8
 9-- 快 query
10SELECT * FROM products WHERE metadata @> '{"category": "shoes"}';
11SELECT * FROM products WHERE metadata @? '$.variants[*].price > 100';

MySQL 對應：MySQL 8.0 JSON_TABLE 是 SQL standard、但 index 必須 generated column workaround（不能 GIN index over JSON）。

詳見 MySQL Modern SQL Features JSON_TABLE vs PG JSONB 對比段。

5. Range Types + Exclusion Constraints

PG range types + exclusion constraints 防止 時間範圍重疊：

 1CREATE TABLE reservations (
 2    id SERIAL PRIMARY KEY,
 3    room_id INT,
 4    during TSRANGE,
 5    EXCLUDE USING GIST (room_id WITH =, during WITH &&)
 6);
 7
 8-- INSERT 重疊 booking 自動 reject
 9INSERT INTO reservations (room_id, during)
10VALUES (1, '[2026-05-19 10:00, 2026-05-19 12:00)');
11INSERT INTO reservations (room_id, during)
12VALUES (1, '[2026-05-19 11:00, 2026-05-19 13:00)');
13-- ERROR: conflicting key value violates exclusion constraint

MySQL 對應：完全沒對應、必須 application 層 enforce。

6. CHECK Constraint + Domain Type

PG CHECK constraint 真執行（MySQL 8.0 才補）+ user-defined DOMAIN：

1CREATE DOMAIN positive_int AS INT CHECK (VALUE > 0);
2CREATE TABLE orders (
3    id SERIAL PRIMARY KEY,
4    quantity positive_int NOT NULL,
5    amount DECIMAL CHECK (amount >= 0)
6);

MySQL 對應：8.0+ 有 CHECK constraint enforcement（5.7 可寫但不執行）。沒 user-defined DOMAIN。

7. Extension Ecosystem

PG extension 是 結構優勢：

• pg_partman：自動 partition lifecycle
• pg_repack：online table rewrite
• pg_stat_statements：query stats
• pgvector：vector similarity search
• pg_cron：scheduled job
• PostGIS：GIS
• TimescaleDB：time-series
• Citus：sharding

MySQL 對應：MySQL plugin 機制有、生態遠遠不如。詳見 PG Extension Ecosystem 篇（待寫）。

MySQL 8.0 補齊的 PG 既有特性

MySQL 8.0 是 補齊 9 年 SQL standard 落後、不是 新領先 PG。

PG 仍領先的特性

對應「MySQL 8.0 補了 → PG 仍沒輸」的視角。以下 14 條中、production 影響最大 的是 Materialized view / Partial index / JSONB GIN / Full-text search 跟 Range / Exclusion constraints（schema-level expressiveness）；次要但常用 的是 Multi-column statistics 跟 Procedural language；非典型但 niche 重要 的是 User-defined DOMAIN / Generic table inheritance（讀者不必然知道、但 ORM 跟 schema migration 工具會用）：

對「從 MySQL 評估 PG」的讀者

讀者通常從 MySQL 8.0 過來、問題是 「PG 比 MySQL 強在哪、弱在哪」：

PG 比 MySQL 強

• SQL 工程深度：上面列的 7 個結構優勢
• Extension ecosystem：pgvector / TimescaleDB / Citus / pg_partman 等
• Optimizer：planner 對複雜 query 更成熟
• Concurrency model：MVCC + 少 lock（MVCC + Lock Model）

PG 比 MySQL 弱

• Replication 機制簡潔度：MySQL GTID 比 PG WAL + replication slot 配置簡單（Replication Topology）
• Sharding ecosystem：Vitess / PlanetScale 比 Citus 規模驗證高
• Operational tooling 廣度：pt-toolkit / gh-ost / Orchestrator 等
• VACUUM 維護：PG MVCC 必須 VACUUM、autovacuum 配錯議題多（Autovacuum Tuning）

選 PG 的核心 driver

對 SQL 工程深度、extension、複雜 query / OLAP-style workload 的場景、PG 仍是首選。對純簡單 OLTP + 大規模 sharding、MySQL + Vitess 仍 competitive。

跟其他模組整合

• MVCC + Lock Model：PG MVCC 是 SQL feature 的並行控制基礎
• Query Optimization：PG planner 對 window / CTE / hash join 成熟
• Citus Distributed：extension 之一、體現 extension 生態
• Autovacuum Tuning：MVCC 代價、跟 SQL feature 並行控制相關

相關連結

• PostgreSQL vendor overview
• PG MVCC + Lock Model（concurrency 基礎）
• PG Query Optimization（planner 成熟度）
• PG Citus Distributed（extension example）
• PG Autovacuum Tuning（MVCC 維護）
• MySQL Modern SQL Features（sibling、反向視角）
• 官方：PostgreSQL Features

本文是 PostgreSQL overview 的 implementation-layer deep article。Overview 已說明 PG 在 OLTP 譜系的定位、本文聚焦 multi-master / active-active replication — 不是 PG 預設、需要 extension。

PG 預設沒 multi-master、得用 extension

PG core 是 single-primary streaming replication：

• 寫入只能進 primary
• Standby 接受 read（hot_standby）但拒絕 write
• Failover 後新 primary 接管、不能多入口

對需要 active-active（多 region 各自接受 local write）的場景、PG 提供 3 條 extension 路徑：

每條路徑有不同 trade-off。對 99% PG production case、不需要 multi-master — single-primary streaming replication + read replica scaling 已夠。Multi-master 是 特殊需求（跨 region active-active write / 不可中斷 maintenance）才上。

跟 MySQL Group Replication 對比：MySQL GR 是 官方內建（5.7+）、PG 沒對應內建選項。MySQL 用戶 GR / InnoDB Cluster 直接套、PG 用戶要選 extension + license trade-off。

Multi-master 三方案對比

方案 1：BDR (EDB Postgres Distributed)

EDB 商業 distributed 方案、跑在 EDB Postgres Advanced Server 或 PG community 上。

特性：

• 雙向 logical replication、N-way active-active
• Built-in conflict detection + resolution（LWW / column-level / user-defined）
• Eager（sync）跟 async 兩種 mode
• Tightly integrated with EDB tooling

Trade-off：

• 商業 license、EDB 訂閱
• 對 cross-region multi-master 成熟（北美 enterprise 廣用）
• 對 新 PG version 通常滯後幾個月

方案 2：pgEdge（基於 Spock extension）

pgEdge 開源 multi-master、基於 Spock extension（從 BDR 衍生）：

特性：

• 開源、可自管
• 跟 BDR 架構接近、無 license fee
• Conflict resolution 用 LWW + column-level
• 對 edge / 地理分散 場景設計

Trade-off：

• 較新（2023+）、社群驗證度低於 BDR
• Conflict resolution policy 比 BDR 簡單
• 部分 EDB 商業 feature 沒對應

方案 3：Bucardo

PG community async multi-master、Perl 寫、trigger-based：

特性：

• 完全開源
• Trigger-based（不依賴 logical replication）
• 支援 multi-source replication（fan-in / fan-out）

Trade-off：

• Async only — higher latency conflict
• Trigger overhead（影響 primary 寫吞吐）
• 維護 Perl + tools chain 不普及
• 對 Sync 一致性 需求不適用

Multi-Master Conflict Model

任何 multi-master 方案都要解決 同一 row 兩地同時改 的 conflict：

Conflict 來源

1Region A (primary 1)          Region B (primary 2)
2UPDATE orders                 UPDATE orders
3SET status='shipped'          SET status='cancelled'
4WHERE id=100                  WHERE id=100
5     ↓                              ↓
6   合併？哪個贏？

跨 region 兩地各自 commit、replication lag 期間發現 conflict、必須 自動 resolve（不能丟給 application）。

Conflict Resolution Strategies

1. Last-Write-Wins (LWW) — 最常見：

• 比較 transaction commit timestamp、晚的贏
• 簡單但 data loss（前一個 commit 的變更被覆蓋）
• 需要 clock 同步（NTP）— clock skew 造成不可預測

2. Column-level conflict resolution：

• 不同 column 各自 LWW（status column 跟 amount column 獨立解）
• 比 row-level LWW 細、但需 application semantics 配合

3. User-defined trigger：

• 寫 PG function 解 conflict
• 對 特殊 business logic（如：金額相加、不是覆蓋）有用
• 維護成本高

4. Manual reconciliation：

• Conflict 寫進 log table、application / DBA 手動處理
• 對 無法自動 resolve 場景（如金融）
• 高 ops cost

對 99% case 用 LWW、接受 small data loss、application 設計 idempotent / commutative 操作避免衝突。

Conflict 機率取決於 application pattern

• Tenant-isolated application（user_id 各自寫自己的 row）：基本無 conflict
• Shared counter / inventory application：高 conflict、multi-master 不適合
• Append-only event log：conflict 低、適合 multi-master

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

pgEdge 開源、最常見的 self-hosted 選擇。

Step 1：在每個 region node 裝 pgEdge

1# Install pgEdge CLI
2curl -fsSL https://pgedge-upstream.s3.amazonaws.com/REPO/install.py | python3
3
4# Setup PG + Spock + pgEdge
5./pgedge install pg16
6./pgedge install spock

Step 2：配置每個 node

1-- 在 node1（us-east） 跑
2SELECT spock.node_create(node_name := 'node1', dsn := 'host=node1.example.com port=5432 dbname=production');
3
4-- 在 node2（eu-west）跑
5SELECT spock.node_create(node_name := 'node2', dsn := 'host=node2.example.com port=5432 dbname=production');

Step 3：建 replication set + subscribe

 1-- 在 node1 建 default replication set + 加 tables
 2SELECT spock.repset_add_all_tables('default');
 3
 4-- 在 node1 subscribe node2
 5SELECT spock.sub_create(
 6    subscription_name := 'sub_n1_n2',
 7    provider_dsn := 'host=node2.example.com port=5432 dbname=production'
 8);
 9
10-- 在 node2 subscribe node1（雙向）
11SELECT spock.sub_create(
12    subscription_name := 'sub_n2_n1',
13    provider_dsn := 'host=node1.example.com port=5432 dbname=production'
14);

Step 4：設 conflict resolution

1-- 設 LWW（預設）
2SELECT spock.conflict_resolution_setting_set(
3    conflict_type := 'update_origin_change',
4    resolution_setting := 'apply_remote'
5);

Step 5：驗證

1-- 看 subscription 狀態
2SELECT * FROM spock.subscription;
3
4-- 看 replication lag
5SELECT * FROM pg_stat_replication;

5 個 Production 踩雷

1. LWW data loss — Application 沒設計 commutative

LWW 預設、兩 region 同時 UPDATE 同 row → 晚的 commit 贏、早的丟失。Application 看不到「我寫的不見了」、debug 困難。

修法：

• Application schema 設計 tenant-isolated（user_id 各自寫自己 row）
• 對 shared counter / inventory 用 commutative operation（INCREMENT not SET）
• 重要寫入加 audit log — conflict 仍寫到 audit、application 看 audit 知道發生過
• 真的需要 strict consistency 別用 multi-master、用 single-primary + reader 或 distributed SQL

2. Sequence collision — Two region 各自 next 同號

SERIAL / IDENTITY 用 sequence、兩 region 各自 nextval 可能拿到同 number、INSERT 衝突（PK duplicate）。

修法：

• 用 staggered sequence range：node1 用 1-1M、node2 用 1M+1 到 2M（用 setval）
• 或用 UUID（v4 / v7）作 PK、跨 node 無 collision
• 或 sequence per-node namespace：CREATE SEQUENCE orders_id_node1 START 1 INCREMENT 2（odd vs even）

3. DDL replication 不自動

PG logical replication（pgEdge / BDR 基礎）不自動 replicate DDL。每 node CREATE TABLE / ALTER TABLE 必須 分別跑。

修法：

• 用 deployment automation（Ansible / Terraform）對所有 node 同時跑 DDL
• pgEdge 提供 spock.replicate_ddl(...) 把 DDL 轉成可 replicate event
• BDR Enterprise 有 DDL replication（商業 feature）
• DDL 變更前確認 所有 node 都健康、減少 partial state

4. Conflict log 治理 — Log table 爆滿

每個 conflict 寫進 spock.conflict_log / bdr.conflict_history 等 table、log 累積 disk 爆。

修法：

• 設 log retention：cron 定期 archive + delete 老 conflict log
• 監控 conflict rate — 高 conflict rate 是 application 設計問題（不是 ops 問題）
• 對 strict business conflict 寫進 application-level audit table、不只 system log

5. Failover 後 timeline 分歧

Multi-master 設計上 每 region 是 primary、Region A 掛了 Region B 接管 — 但 Region A 復活後 仍認為自己是 primary。如果 Region A 復活前已有寫入沒 replicate 出去、resolution 跟 LWW 衝突。

修法：

• Fence Region A 復活：物理 fence（network firewall）+ 手動 unfence 流程
• 用 etcd / Consul 跟 BDR / Spock 整合 leader election（避免 split-brain）
• 對 cross-region multi-master、必須有 runbook 處理 region 復活流程、不靠自動

何時用 multi-master vs 不用

跟 MySQL Group Replication 對比

MySQL GR 內建 + Oracle 推、PG 沒對應內建。對 multi-master 需求重的 org、MySQL 走 GR 路徑更直接。

跟其他模組整合

跟 Replication Topology

Multi-master 是 streaming replication 之上的 logical replication 加雙向、不取代 streaming。Streaming 仍給 standby / failover、multi-master 給 active-active write。詳見 Replication Topology。

跟 Logical Replication

pgEdge / BDR 都基於 logical replication slot、跟 Logical Replication + Debezium 共用 PG logical decoding infrastructure、但 配置 + tooling 不同。

跟 MVCC

Multi-master 的 conflict 在 commit 後 偵測（async）、不在 transaction 內。跟單機 MVCC（同 cluster 內 transaction snapshot）不同層。詳見 MVCC + Lock Model。

相關連結

• PostgreSQL vendor overview
• PG Replication Topology（streaming + multi-master 共存）
• PG Logical Replication + Debezium（logical decoding 基礎）
• PG MVCC + Lock Model（multi-master conflict vs 單機 MVCC）
• PG Patroni HA（single-primary HA 替代方案）
• 1.11 全球分散式 OLTP（multi-master vs distributed SQL）
• MySQL Group Replication（sibling、不同實作）
• 官方：EDB BDR / pgEdge / Spock GitHub / Bucardo

本文是 PostgreSQL overview 的 implementation-layer deep article。Overview 已說明 PG 在 OLTP 譜系的定位、本文聚焦 query optimization — EXPLAIN ANALYZE / auto_explain / pg_hint_plan 三層工具跟 4 個實際 case。

4 個常見 production case

PG query 慢的 root cause 多數是 planner 選錯 plan。從以下 4 個 case 進入 query optimization：

Case 1：5 秒 → 50ms — Seq scan vs index

1-- 慢 (5 秒)
2SELECT o.id, o.amount, c.name
3FROM orders o JOIN customers c ON o.customer_id = c.id
4WHERE c.region = 'TW' AND o.created_at > '2026-05-01';

EXPLAIN (ANALYZE, BUFFERS)：

1Hash Join  (cost=20000..50000 rows=100 width=...) (actual time=4900..5000 rows=10000)
2  ->  Seq Scan on customers c  (cost=0..20000 rows=1000000 width=...)
3      Filter: (region = 'TW')
4      Rows Removed by Filter: 900000
5  ->  Hash  (cost=...)
6      ->  Index Scan on orders_created_idx

問題：customers.region 沒 index、planner 選 seq scan、實際 region=TW 只 10% row。修法：

1CREATE INDEX CONCURRENTLY idx_customers_region ON customers(region);
2ANALYZE customers;  -- 更新 statistics、讓 planner 看到新 index

加完 5 秒降 50ms。

Case 2：30 秒 → 200ms — Hash join 沒觸發、用 nested loop

1SELECT u.name, count(o.id)
2FROM users u LEFT JOIN orders o ON o.user_id = u.id
3GROUP BY u.name;

EXPLAIN ANALYZE 顯示 Nested Loop 跑 1M 次 inner loop、執行 30 秒。Planner 估錯 row count、選 nested loop。Hash join 應該 < 200ms。

修法：

1ANALYZE users;
2ANALYZE orders;
3-- 提高 default_statistics_target 對 critical column
4ALTER TABLE orders ALTER COLUMN user_id SET STATISTICS 1000;
5ANALYZE orders;

統計精度提升、planner 估 row count 準、自動切 hash join。

Case 3：8 秒 → 100ms — Multi-column 統計缺

1SELECT * FROM orders WHERE status = 'pending' AND region = 'TW';

status = 'pending' 5% row、region = 'TW' 10% row。Planner 假設兩 column 獨立、估 0.5% (5K row)。實際 status=‘pending’ 跟 region=‘TW’ 強相關（TW 訂單多 pending）、實際 4% (40K row)。Planner 估錯 8x、選錯 plan。

修法（PG 10+）：

1CREATE STATISTICS stats_orders_status_region (dependencies, ndistinct, mcv)
2ON status, region FROM orders;
3ANALYZE orders;
4-- 之後 planner 知道 status+region 相關度、估準

Case 4：20 秒 → 5 秒 — Parallel query 沒觸發

1SELECT region, count(*), sum(amount) FROM orders GROUP BY region;

orders 100M row、預期 PG parallel scan + parallel aggregate、實際 single worker 跑 20 秒。

EXPLAIN：Workers Planned: 0。

修法：

1# postgresql.conf
2max_parallel_workers_per_gather = 4
3max_parallel_workers = 8
4max_worker_processes = 16
5parallel_setup_cost = 100        # 預設 1000、降低讓 planner 更敢 parallel
6parallel_tuple_cost = 0.01       # 預設 0.1

並行後 5 秒。

EXPLAIN 三層工具

Tool 1：EXPLAIN — Plan preview

1EXPLAIN SELECT ...;

輸出每個 node 的 估計 cost / row count / width。用於 quick plan check。

關鍵欄位：

• Plan node 類型：Seq Scan < Index Scan < Index Only Scan、警訊看 unexpected node type
• cost=START..END：planner 估的 cost、START 是 startup cost、END 是 total
• rows：估計 output row 數
• width：每 row average byte（影響 sort / hash memory）

Tool 2：EXPLAIN ANALYZE — 實際執行 + 對比 estimate

1EXPLAIN (ANALYZE, BUFFERS, VERBOSE) SELECT ...;

差別：實際 跑 query、輸出實際 row count / time、跟 estimate 對比：

1Hash Join  (cost=20000..50000 rows=100) (actual time=400..500 rows=10000 loops=1)

rows=100 (estimate) vs rows=10000 (actual) — 估錯 100x、planner 可能選錯 plan。BUFFERS 顯示 disk read vs buffer cache hit。

注意：EXPLAIN ANALYZE 實際跑 query、修改性 query（UPDATE / DELETE）會真的改 data。讀 query 安全。修改性 query 包 transaction：

1BEGIN;
2EXPLAIN ANALYZE UPDATE orders SET status = 'x' WHERE ...;
3ROLLBACK;

Tool 3：auto_explain — Production query 自動 capture

auto_explain extension 自動 log slow query 的 plan：

1# postgresql.conf
2shared_preload_libraries = 'auto_explain'
3auto_explain.log_min_duration = '1s'    # 超過 1 秒 log plan
4auto_explain.log_analyze = on            # 含 ANALYZE 統計
5auto_explain.log_buffers = on
6auto_explain.log_format = 'json'         # JSON 格式給工具消費

Production slow query 自動進 log、不必手動 EXPLAIN。組合 pg_stat_statements + auto_explain 是 PG 標準 query observability。

pg_hint_plan vs Planner GUC

PG 兩種方式 nudge planner：

Planner GUC（global）

postgresql.conf 內：

• enable_seqscan = off — 禁用 seq scan（force index）
• enable_nestloop = off — 禁用 nested loop（force hash/merge join）
• random_page_cost = 1.1 — SSD 設低（預設 4 是 HDD assumption）
• effective_cache_size = '16GB' — buffer pool + OS cache 估、影響 planner

GUC 是 global — 影響所有 query。對 單一 query 用 hint：

pg_hint_plan extension（per-query hint）

1-- 強制特定 plan
2/*+ IndexScan(orders idx_orders_status) NestLoop(orders customers) */
3SELECT ... FROM orders JOIN customers ON ...;

Hint 形態：

• IndexScan(t1 idx_name) — 強制 index scan
• SeqScan(t1) — 強制 seq scan
• HashJoin(t1 t2) / NestLoop(t1 t2) / MergeJoin(t1 t2)
• Leading(t1 t2 t3) — 強制 join order
• Rows(t1 t2 #100) — 強制 row 估計

推薦：

• 全 cluster 行為：用 GUC（如 random_page_cost）
• 單 query 行為：用 pg_hint_plan（不污染其他 query）
• 不要過度 hint — planner 多數時候 是對的、hint 是 last resort

5 個 Production 踩雷

1. Statistics 過時 — Planner 估錯 row count

ANALYZE 是 autovacuum 一部分、預設 autovacuum_analyze_scale_factor=0.1（10% row 變動才 analyze）。對 快速 grow 的表（log / event）、ANALYZE 跟不上、planner 用過時 statistics。

修法：

• 對 critical table 設 較 aggressive autovacuum_analyze_scale_factor：

  1ALTER TABLE events SET (autovacuum_analyze_scale_factor = 0.02);

• 對 大批量寫入後、手動 ANALYZE events;

• 監控 pg_stat_user_tables.last_analyze — 跟 row count 比、判定是否需手動 trigger

2. Multi-column statistics — Planner 假設 column 獨立

如 Case 3、單 column statistics 對 相關 column 估錯。

修法：

• 對 常一起 query 的 column 組合、建 CREATE STATISTICS（PG 10+）
• 3 種 type：dependencies（functional dependency）、ndistinct（multi-column distinct count）、mcv（most common value combinations）
• 設完 必須跑 ANALYZE 才生效

3. Cost-base setting 不對齊硬體 — Planner 偏 seq scan

預設 random_page_cost = 4、seq_page_cost = 1 是 HDD assumption（random IO 比 sequential 慢 4x）。SSD / NVMe random / seq IO 差別小、planner 不該 4x penalty random。

修法：

1-- SSD
2ALTER SYSTEM SET random_page_cost = 1.1;
3
4-- NVMe
5ALTER SYSTEM SET random_page_cost = 1.0;
6
7SELECT pg_reload_conf();

random_page_cost 改了 planner 對 index scan 的 cost 估計更準、自動選 index 更積極。

4. effective_cache_size 不對齊實際 RAM

effective_cache_size 預設 4 GB、planner 假設 buffer pool + OS cache 共 4 GB。實際 server 64 GB RAM、shared_buffers = 16GB、OS page cache ~30 GB、實際可用 cache 46 GB。

修法：

1ALTER SYSTEM SET effective_cache_size = '46GB';  -- shared_buffers + OS cache 估

提升後 planner 估 query 多數 page 在 cache、降低 估計 random IO cost、選 index 更積極。

5. Parallel query 不觸發

預設 max_parallel_workers_per_gather = 2、有些 workload 不夠。或 table size 太小、min_parallel_table_scan_size = 8MB 預設、小表不 parallel。

修法：

1ALTER SYSTEM SET max_parallel_workers_per_gather = 4;
2ALTER SYSTEM SET parallel_setup_cost = 100;
3ALTER SYSTEM SET parallel_tuple_cost = 0.01;
4ALTER SYSTEM SET min_parallel_table_scan_size = '0';  -- 任何 size 都 parallel

監控 EXPLAIN 的 Workers Planned 數量、看是否真 parallel。

觀測 metric

Production 持續 monitor：

• pg_stat_statements：每個 query digest 累計 calls / time / rows / IO
• auto_explain log：slow query 的實際 plan + ANALYZE 統計
• pg_stat_user_tables.last_analyze / last_autoanalyze：statistics 新鮮度
• pg_stat_user_indexes.idx_scan：每個 index 使用次數 — 0 表示沒用、可考慮 drop

把這些丟進 Datadog / Prometheus（用 postgres_exporter / pg_exporter）做 trend analysis。

跟 MySQL Query Optimization 對照

PG planner 整體成熟、複雜 OLAP-style query 處理較好。MySQL 8.0 補了不少（histograms / hash join）但複雜 query 仍弱於 PG。詳見 MySQL Query Optimization。

跟其他模組整合

跟 Autovacuum Tuning

ANALYZE 是 autovacuum 一部分、autovacuum 跟不上 → statistics 過時 → planner 估錯。詳見 Autovacuum Tuning。

跟 Replication Topology

Standby 上跑 query 用同 statistics（streaming replication copy 整個 system catalog）、planner 行為一致。但 standby 有 hot_standby_feedback 影響 primary autovacuum / ANALYZE 行為。詳見 Replication Topology。

跟 Partitioning

Partition pruning 跟 query plan 緊密 — EXPLAIN 看是否 prune 對的 partition。詳見 Declarative Partitioning。

何時用 pg_hint_plan vs GUC

相關連結

• PostgreSQL vendor overview
• PG Autovacuum Tuning（ANALYZE 跟 statistics 新鮮度）
• PG Replication Topology（standby planner 行為）
• PG Declarative Partitioning（partition pruning）
• MySQL Query Optimization（sibling、不同 optimizer 成熟度）
• 官方：EXPLAIN / pg_hint_plan / auto_explain

本文是 PostgreSQL overview 的 implementation-layer deep article。Overview 已說明 PG 在 OLTP 譜系的定位、本文聚焦 MVCC + lock model — PG 並行控制機制跟跟 MySQL lock-based 不同。

PG MVCC：每次更新都 新增 tuple、不改舊版

PG 的並行控制核心是 Multi-Version Concurrency Control — UPDATE 不修改原 row、是 新增 一個 tuple version、舊 version 留在 table 直到 VACUUM 清理：

1原 row:    (id=1, status='pending', xmin=100, xmax=NULL)
2                 ↓ UPDATE status='shipped'
3新 tuple:  (id=1, status='shipped', xmin=200, xmax=NULL)
4舊 tuple 標 xmax=200（不刪、給其他 transaction 看舊 version）

xmin / xmax 是 creator transaction id / destroyer transaction id。每個 SELECT 用 snapshot（含當下 active transaction list）判斷哪些 tuple 對自己可見：

• 自己 transaction id > tuple.xmin 且 (tuple.xmax = NULL 或自己 transaction id < tuple.xmax) → 可見
• 否則 → 看不到（過去 / 未來版本）

結果：

• Readers 不 lock writers：SELECT 看 snapshot、不 block UPDATE
• Writers 不 lock readers：UPDATE 寫新 tuple、不影響正在跑的 SELECT snapshot
• Writers 只 lock 同一 row 的 writers：兩個 UPDATE 同 row 才 conflict

跟 MySQL InnoDB lock-based（Lock Contention）對比：

• MySQL：SELECT FOR UPDATE 用 gap lock 防 phantom、deadlock 機率高
• PG：MVCC + snapshot 自然防 phantom（read 看 snapshot）、deadlock 少

但 PG 代價是 VACUUM 治理 — dead tuple 不清理會佔 disk + 影響 query 效率。詳見 Autovacuum Tuning。

PG 4 種 lock

PG 仍有 lock、但場景跟 MySQL 不同：

1. Row-level lock — 主要由 UPDATE / DELETE / SELECT FOR UPDATE 取

1BEGIN;
2SELECT * FROM orders WHERE id = 100 FOR UPDATE;
3-- 對 id=100 row 加 ROW EXCLUSIVE lock
4-- 其他 transaction 試 UPDATE / DELETE id=100 必須等

Row-level lock 不 block reader（SELECT 看 snapshot、不檢查 lock）。

2. Table-level lock — DDL 跟少數 SELECT FOR 場景

PG 有 8 種 table lock mode、嚴重程度遞增：

DDL（ALTER / DROP）拿 ACCESS EXCLUSIVE、跟所有衝突。Production 跑 ALTER 必須短時間或走 Online Schema Change。

3. Advisory lock — Application 自己控

PG 提供 advisory lock 給 application 用、不關 row / table 結構：

1-- Session 1
2SELECT pg_advisory_lock(12345);
3-- 跑 critical section
4SELECT pg_advisory_unlock(12345);
5
6-- Session 2
7SELECT pg_try_advisory_lock(12345);  -- 試取、不阻塞、返回 false

用途：

• Application-level 互斥（如：cron job 同時只跑一個）
• 跨 connection 同步（PG-managed mutex）
• Distributed transaction coordinator（lightweight）

跟 row lock 不同：advisory lock 不關 row、application 自定義 lock ID 語義。

4. Predicate lock — SERIALIZABLE isolation 才用

PG SERIALIZABLE 用 Serializable Snapshot Isolation (SSI)、追蹤 predicate（query 條件）而不是 row：

1SET TRANSACTION ISOLATION LEVEL SERIALIZABLE;
2BEGIN;
3-- Predicate lock 紀錄這個 query 看了哪些 predicate
4SELECT * FROM orders WHERE status = 'pending';
5-- 其他 transaction INSERT pending order
6-- 提交時：PG 偵測 anomaly、rollback 之一
7COMMIT;

跟 MySQL gap lock 不同：

• MySQL gap lock：pre-lock、防 phantom 在 query 期間
• PG predicate lock：post-detect、commit 時偵測 anomaly、退回 transaction

PG SSI 對 寫入吞吐影響低（不 pre-lock）、但 transaction rollback 機率高（要 application retry）。

PG 預設 isolation：READ COMMITTED

PG 預設 READ COMMITTED、跟 MySQL InnoDB 預設 REPEATABLE READ 不同：

對 application code 含意：

• PG REPEATABLE READ 對 寫入吞吐 影響低（不 pre-lock、只 retry）
• 沒 gap lock → INSERT 不被 lock-induced 阻塞
• Deadlock 機率比 MySQL 低數量級

實務 PG production：用預設 READ COMMITTED 即可、SERIALIZABLE 留給 strict consistency 需求（金融 / 訂單）但接受 retry。

5 個 Production 踩雷

1. Idle transaction 卡 vacuum — Bloat 暴增

PG MVCC 仰賴 VACUUM 清理 dead tuple。VACUUM 只清理 沒 active transaction 看得到的 dead tuple。如果有 idle in transaction session 持續開著（application connection pool 連線忘關 transaction）、VACUUM 看不到 該 transaction snapshot 之後的 dead tuple、累積 bloat。

修法：

• 監控 pg_stat_activity 看 state = 'idle in transaction' 持續時間
• 設 idle_in_transaction_session_timeout = '5min' — 超時 PG 自動 kill 該 session
• Application connection pool 配置 不留 transaction 開著（如：pgBouncer transaction pool 自動 commit / rollback）

2. SELECT FOR UPDATE 跨 transaction — Application retry 麻煩

跟 MySQL 不同：PG SELECT FOR UPDATE 不會 block 其他 SELECT（讀仍可繼續）、但 block 其他 UPDATE / FOR UPDATE。若 application 在 transaction 內 SELECT FOR UPDATE、其他 transaction 等。

如果 application 設計 跨 transaction 持 lock（如：取 lock + return UI + 等用戶操作 + commit）、容易撞 idle in transaction 跟其他 transaction wait。

修法：

• Transaction 短：取 FOR UPDATE → 立刻處理 → commit、不跨 user interaction
• 跨 user interaction 用 advisory lock 或 application-level state machine、不依賴 row lock

3. Advisory lock 沒釋放 — Session 結束才自動釋放

pg_advisory_lock() 拿了、沒 pg_advisory_unlock()、lock 直到 session 結束 才自動釋放。Connection pool 重複使用同 connection、可能繼承前面留的 lock。

修法：

• 用 pg_advisory_lock 必 try/finally pg_advisory_unlock
• 或用 session-level 用 transaction-scoped：pg_advisory_xact_lock() — commit / rollback 自動釋放
• 監控 pg_locks 看 advisory lock count、長期累積是警訊

4. Bloat 不只是 vacuum 沒跑、是 active transaction 阻擋 vacuum

第 #1 點延伸：vacuum 已跑、但 bloat 仍持續成長、原因不是 vacuum 不夠、是 active transaction 阻擋 vacuum 看 dead tuple。

修法：

• 不只看 last_vacuum、看 VACUUM 跑了但沒收回多少
• SELECT * FROM pg_stat_progress_vacuum 看 VACUUM 進度
• SELECT * FROM pg_stat_activity WHERE backend_xmin IS NOT NULL ORDER BY backend_xmin — 看誰阻擋 vacuum
• 詳見 Autovacuum Tuning

5. SERIALIZABLE 下 transaction rollback — Application 必須 retry

SET TRANSACTION ISOLATION LEVEL SERIALIZABLE 後、PG SSI 偵測到 anomaly 會 rollback transaction、application 看到 serialization failure、必須 retry。

對 不知道要 retry 的 application、SERIALIZABLE 變 production bug。

修法：

• Application code 加 retry middleware：catch SQLSTATE 40001 (serialization_failure) → exponential backoff retry
• 不必所有 transaction 走 SERIALIZABLE — 只對 strict consistency 需求 場景 set
• 高並發 SERIALIZABLE workload 容易 rollback storm、考慮拆 transaction 縮短時間

觀測 metric

Production 監控：

• pg_stat_activity：active session / idle in transaction / wait_event
• pg_locks：當前 lock 列表、用 join 看誰 block 誰
• pg_stat_database.deadlocks：deadlock 計數（PG 較低、但仍要監控）
• pg_stat_user_tables.n_dead_tup / n_live_tup：dead tuple 比例 — bloat 指標
• pg_stat_progress_vacuum：VACUUM 進度

跟 MySQL Lock Model 對比

兩者解決同一問題（並行控制）、用不同策略。PG 用 空間換時間（保留多版本 tuple、讀寫不互鎖、但需 VACUUM 清理）、MySQL 用 時間換空間（lock 等待、但不必清舊版本）。

選擇判讀：

• High 並發 OLTP、寫 / 讀都重：PG MVCC 通常更好（讀不 block 寫）
• 簡單 OLTP + 不想管 VACUUM：MySQL InnoDB 對 ops 簡單
• 需要 SERIALIZABLE 強一致：PG SSI 對寫吞吐影響低
• 已有 MySQL 生態 / 工具鏈：MySQL Lock 知識可繼續用

詳見 MySQL Lock Contention — 完整 MySQL lock 機制。

跟其他模組整合

跟 Autovacuum Tuning

MVCC 仰賴 VACUUM、autovacuum 是 PG 並行控制的 維護成本。VACUUM 跑慢 / 沒跑 → bloat → query 慢。詳見 Autovacuum Tuning。

跟 Replication Topology

hot_standby_feedback = on 讓 standby 上 long-running query 不被 vacuum 取消、但 standby 把 oldest xmin 推回 primary、primary autovacuum 變保守、增加 bloat。詳見 Replication Topology。

跟 Connection Pool

pgBouncer transaction pooling 模式下、advisory lock / SELECT FOR UPDATE 跨 transaction 行為 broken（不同 transaction 可能進不同 backend connection）。詳見 pgBouncer Config。

跟 Query Optimization

長 transaction 跑慢 query 期間、其他 transaction 看到 snapshot bloat、planner 估錯 dead tuple ratio。詳見 Query Optimization。

相關連結

• PostgreSQL vendor overview
• PG Autovacuum Tuning（VACUUM 是 MVCC 必要成本）
• PG Replication Topology（hot_standby_feedback 影響）
• PG pgBouncer（transaction pooling 跟 lock 互動）
• PG Online Schema Change（DDL lock 議題）
• PG Query Optimization（snapshot bloat 影響 planner）
• MySQL Lock Contention（sibling、不同模型）
• Isolation Level 卡片
• 官方：PG MVCC / PG Concurrency Control / Explicit Locking

本文是 PostgreSQL overview 的 implementation-layer deep article。Overview 已說明 PG 在 OLTP 譜系的定位、本文聚焦 JSONB deep dive — binary storage + GIN index 的結構性優勢。

JSON vs JSONB：選 JSONB

PG 9.2 加 JSON type、9.4 加 JSONB。99% 場景用 JSONB：

JSONB 唯一缺點是 binary 儲存（不保留 key order / whitespace / duplicate）。99% application 不在意這些。

從 application semantics 視角、JSONB 是 PG JSON 的 the right type、JSON 是 legacy / niche。

JSONB GIN Index：核心結構性優勢

PG GIN（Generalized Inverted Index）可以對 JSONB 內所有 key/value pair 建 inverted index：

1CREATE TABLE products (
2    id SERIAL PRIMARY KEY,
3    metadata JSONB
4);
5
6-- GIN index
7CREATE INDEX idx_products_metadata ON products USING GIN (metadata);