本文是 PostgreSQL overview 的 implementation-layer deep article。Overview 已說明 PG 在 OLTP 譜系的定位、本文聚焦 replication slot management — physical / logical / failover slot 三類治理。

Replication Slot 兩大類

PG 兩種 replication slot：

Physical Replication Slot

對應 streaming replication（physical WAL byte-level）：

1SELECT pg_create_physical_replication_slot('standby1_slot');

用於：

• Streaming replication standby（Replication Topology）
• pg_basebackup 用 slot 防 WAL 清理
• 高 lag standby 防 WAL premature deletion

Logical Replication Slot

對應 logical replication / logical decoding：

1SELECT pg_create_logical_replication_slot('my_slot', 'pgoutput');
2-- 或用 wal2json plugin
3SELECT pg_create_logical_replication_slot('debezium_slot', 'wal2json');

用於：

• PG-to-PG logical replication（publication / subscription）
• CDC（Debezium / Maxwell / pg_logical_emitter）
• Multi-master replication（BDR / pgEdge / Spock）

logical slot 跟 physical slot 共存、各自獨立 retention。

Slot Lifecycle

1建立 → active（有 consumer）→ inactive（consumer 失聯）→ drop
2                                    ↓
3                              WAL 持續累積（直到推進 LSN 或 drop）

狀態查詢：

1SELECT slot_name,
2       slot_type,
3       active,
4       restart_lsn,
5       confirmed_flush_lsn,
6       pg_size_pretty(pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)) AS retained_wal
7FROM pg_replication_slots;

關鍵欄位：

• slot_type：physical / logical
• active：true / false（consumer 是否連著）
• restart_lsn：slot 起點 LSN、primary 必須保留這以後的 WAL
• confirmed_flush_lsn：logical slot 已 confirm flush 的 LSN
• retained_wal：當前因 slot 累積的 WAL

Failover Slot Synchronization (PG 17+)

PG 17 之前的 痛點：logical replication slot 是 primary 上的 state、failover 後 新 primary 沒這個 slot、CDC consumer 失聯、需要重建（大工程）。

PG 17 加 failover slot synchronization：

 1-- PG 17+：標 slot 為 failover-tracked
 2-- signature: pg_create_logical_replication_slot(slot_name, plugin, temporary, two_phase, failover)
 3SELECT pg_create_logical_replication_slot('my_slot', 'pgoutput', false, false, true);
 4--                                                                          ↑
 5--                                                                     failover=true（第 5 個參數）
 6-- 注意：第 4 個參數是 two_phase（這裡 false）、第 5 個才是 failover
 7
 8-- Standby 上 enable sync_replication_slots
 9ALTER SYSTEM SET sync_replication_slots = on;
10SELECT pg_reload_conf();

sync_replication_slots = on 後、physical replication 同步 slot state 到 standby。Failover promote standby 後、logical slot 仍可用、CDC consumer 重連即可。

PG 17 之前用 pgEdge / pglogical 等 extension 提供類似功能、現在 PG core 內建。

Orphan Slot 治理

active = false 的 slot 持續累積 WAL、disk 爆是 PG production 經典事故。

監控 orphan slot

1-- 找 inactive 太久的 slot
2SELECT slot_name, active, restart_lsn,
3       pg_size_pretty(pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)) AS retained_wal
4FROM pg_replication_slots
5WHERE NOT active
6  AND pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn) > 1024 * 1024 * 1024;  -- > 1 GB

自動 invalidate slot（PG 13+）

1-- postgresql.conf
2ALTER SYSTEM SET max_slot_wal_keep_size = '50GB';  -- slot 累積 > 50GB 自動 invalidate

當 slot 累積 WAL 超過 max_slot_wal_keep_size、PG 自動 invalidate slot（active=false 且不再保留 WAL）。Consumer 重連會 fail、必須重建（base backup + new slot）。

這是 trade-off：

• 設 limit → 保護 disk、但 consumer 失聯 → 大重建工作
• 不設 limit → consumer 失聯 OK、但 disk 爆

實務多數設 max_slot_wal_keep_size 給 disk capacity 50%、避免徹底 disk full。

手動 drop orphan slot

1-- 確認 slot 真的不需要
2SELECT * FROM pg_replication_slots WHERE slot_name = 'old_standby_slot';
3
4-- Drop
5SELECT pg_drop_replication_slot('old_standby_slot');

DR runbook 必須包含 standby 退役流程：先 standby fence、再 primary drop slot。

5 個 Production 踩雷

1. Orphan slot disk 爆

最經典 PG 事故：standby decomission 沒 drop slot、primary 持續保留 WAL、pg_wal/ 累積到 disk full、primary 也掛。

修法：

• 監控 pg_replication_slots + pg_size_pretty(pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)) retained_wal
• 設 max_slot_wal_keep_size（PG 13+）— hard limit
• Standby 退役 runbook 強制 先 fence、再 drop slot
• Cron job 自動 alert orphan slot

2. Logical slot lag — CDC consumer 跟不上

Logical decoding 比 physical replication 慢（per-transaction logical event 重組）。CDC consumer（Debezium）跟不上 → slot lag 累積。

修法：

• 監控 pg_replication_slots.confirmed_flush_lsn 跟 primary pg_current_wal_lsn() 對比
• CDC consumer 性能調整（throughput / batch size）
• Throttle source writes（如果不能升 consumer）
• 對 hot table 拆 publication / subscription、避免單 slot 處理所有變更

詳見 Logical Replication + Debezium。

3. Failover 後 logical slot 丟（PG 16 之前）

PG 16 之前、failover promote standby、新 primary 沒有原 logical slot。CDC consumer 試連、ERROR: replication slot "xxx" does not exist。

修法（PG 17+）：

• 用 failover slot synchronization（如上）
• pg_create_logical_replication_slot(..., failover := true)
• Standby sync_replication_slots = on

修法（PG 16-）：

• 用 pglogical 或 pgEdge extension
• Failover runbook 包含 新 primary 重建 logical slot（CDC consumer 重 snapshot）
• Pre-create slot on standby + manual sync（早期 workaround）

4. wal_keep_size 跟 slot 衝突

wal_keep_size（PG 13+）/ wal_keep_segments（< 13）跟 slot 都會保留 WAL：

• wal_keep_size：固定 minimum WAL 保留量
• Slot：動態保留直到 consumer 推進

兩者一起 set 時：實際保留 WAL = max(wal_keep_size, slot 需要的量)。

修法：

• wal_keep_size 設小（如 1-2 GB）作 minimum backup
• 主要靠 slot 動態保留 — 給 active consumer
• 監控 pg_wal/ 大小 + 拆解 retention source（wal_keep_size vs slot 各佔多少）

5. Slot 數量上限

max_replication_slots 預設 10、不夠時新 slot 建不出來、報錯。

修法：

• Production 大 cluster 設 max_replication_slots = 50 或更多
• 對 standby + logical replication + CDC consumer 同時跑、計算需要的 slot 數
• 監控 SELECT count(*) FROM pg_replication_slots 接近 limit 時告警

Slot Naming Convention

Production 大 cluster 多 slot、命名 convention 重要：

1<consumer-type>_<consumer-name>_<purpose>
2例：
3- physical_standby1_replication
4- physical_standby2_replication
5- logical_debezium_orders_cdc
6- logical_pgedge_node2_subscription
7- physical_pgbasebackup_temp（base backup 用、completed 後 drop）

清楚命名讓 看 slot 名 就知道用途、誰負責、能不能 drop。

跟其他模組整合

• Replication Topology：physical slot 給 streaming replication 用
• Logical Replication + Debezium：logical slot 給 CDC
• BDR / Multi-Master：multi-master 大量用 logical slot
• PITR + WAL Archiving：WAL archive 跟 slot 是兩種 WAL retention 機制、可並行

監控 metric

Production 持續監控：

• pg_replication_slots.active — 失聯 slot
• pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn) — slot 累積 WAL
• pg_replication_slots.confirmed_flush_lsn vs pg_current_wal_lsn() — logical slot lag
• pg_ls_waldir() 看 pg_wal/ 目錄大小
• count(*) FROM pg_replication_slots 對 max_replication_slots 比例

把這些丟進 Datadog / Prometheus + alert。

相關連結

• PostgreSQL vendor overview
• PG Replication Topology（physical slot 用途）
• PG Logical Replication + Debezium（logical slot 用途）
• PG BDR / Multi-Master（multi-master 大量 slot）
• PG PITR + WAL Archiving（WAL retention 兩種機制）
• 官方：PG Replication Slots / Logical Replication Slot

本文是 PostgreSQL overview 的 implementation-layer deep article。Overview 提到 logical decoding / Debezium CDC、本文聚焦 replication slot 生命週期 + 5 個 production failure mode 跟 recovery 的對照。

Replication slot × Failure × Recovery 對照

Logical replication 跟 Debezium CDC 的 production 議題集中在 replication slot — 它是 PostgreSQL 內保證 WAL 不被回收的 anchor point；slot 設不對、整個 CDC pipeline 失效。各 failure mode 對 slot 的影響跟 recovery 路徑：

每個 failure mode 對應的詳細配置 + recovery 步驟、下面分段展開。

Logical replication 基礎：publication + subscription + slot

1-- Primary：建 publication
2CREATE PUBLICATION app_changes FOR TABLE orders, events;
3
4-- Subscriber：建 subscription（自動建 replication slot）
5CREATE SUBSCRIPTION app_sub
6  CONNECTION 'host=primary user=replicator dbname=app'
7  PUBLICATION app_changes
8  WITH (slot_name = 'app_sub_slot', copy_data = true);

關鍵物件：

• publication（primary 端）：宣告 哪些表 + 哪些操作（INSERT/UPDATE/DELETE/TRUNCATE） 對外暴露
• subscription（subscriber 端、若是 PG-to-PG）：訂閱 + 自動建 slot + 自動 initial COPY
• replication slot：primary 端、保證 consumer 還沒消費的 WAL 不被回收

copy_data = true 觸發 initial COPY（snapshot）+ 後續 streaming；copy_data = false 只 streaming、適合 already-in-sync 場景。

Debezium CDC：用 logical replication slot 但繞過 subscription

Debezium 不是 PostgreSQL subscriber、是 直接讀 replication slot 的外部 consumer：

 1# Debezium PostgreSQL connector
 2connector.class=io.debezium.connector.postgresql.PostgresConnector
 3database.hostname=primary
 4database.dbname=app
 5plugin.name=pgoutput                            # 內建、PG 10+ 推薦
 6slot.name=debezium_app
 7publication.name=app_changes
 8publication.autocreate.mode=filtered            # debezium 自動建 publication
 9table.include.list=public.orders,public.events
10snapshot.mode=initial                            # 起始 snapshot 後 streaming

差異：

• Debezium 用 pgoutput（PG 10+ 內建）或 wal2json（外掛 plugin）解 WAL、轉成結構化事件送 Kafka
• 不像 PG-to-PG subscription、Debezium 沒 subscription object、是 外部 consumer 自管 replication slot
• Failure mode 上 consumer 端是 Debezium 自己、所以 lag 來源是 Debezium 處理速度 / Kafka 寫入速度

Production 故障演練

Case 1：consumer lag、slot LSN 不前進、primary disk 爆

徵兆：primary pg_wal 目錄持續長大、df -h 看磁碟 90%+；pg_replication_slots 看 confirmed_flush_lsn 卡在某 LSN、pg_wal_lsn_diff(pg_current_wal_lsn(), confirmed_flush_lsn) 數十 GB。

根因：consumer（Debezium / subscriber）處理慢於 primary 寫入；replication slot 保證 WAL 不回收、但 consumer 沒消費 → WAL 堆積。

修法：

1. 監測：Prometheus alert pg_replication_slot_lag_bytes > 5GB 觸發前 catch
2. 修 consumer：throttle primary 寫入 OR scale Debezium / subscriber 處理能力
3. 緊急：SELECT pg_drop_replication_slot('debezium_app') 釋放 WAL — 但 consumer 必須重 init load（資料缺一塊）
4. 架構：用 max_slot_wal_keep_size（PG 13+）設 slot 能保留 WAL 上限、超出自動 invalidate slot、保護 primary disk

Case 2：consumer crash 後 slot 變 zombie

徵兆：Debezium pod OOM crash、新 pod 起來時報 slot is active for PID X、無法 attach；primary 端 pg_replication_slots.active = true、active_pid 指向已經死掉的 process。

根因：PostgreSQL 把 slot 標 active 是基於 當下有 connection；consumer crash 但 connection 沒被 server 端發現（network 沒 RST）、slot 留在 active state。

修法：

1-- 手動清 zombie slot
2SELECT pg_terminate_backend(active_pid) FROM pg_replication_slots
3  WHERE slot_name = 'debezium_app' AND active;
4
5-- 或直接 drop（會丟資料、consumer 要重 init）
6SELECT pg_drop_replication_slot('debezium_app');

預防：

1. PostgreSQL tcp_keepalives_idle / interval / count 設較短（300 / 60 / 6）、network drop 較快被發現
2. Consumer 端用 graceful shutdown + pg_terminate_backend(active_pid) 在 startup 前主動清 stale connection

Case 3：schema change（DROP / RENAME COLUMN）斷流

徵兆：Debezium consumer 突然停 produce 訊息、log 報 column XYZ does not exist；primary 端 slot 還 active、但 confirmed_flush_lsn 不前進。

根因：pgoutput plugin 把 WAL 解成 row event 時、用的 schema 是 當下 catalog；如果中間 DROP COLUMN、之前 WAL 內的 row event 含已不存在欄位、解析失敗。

修法：

1. 預防：schema change 走 expand-contract pattern
   • Phase 1: ADD COLUMN new_col（不影響 logical replication）
   • Phase 2: application 雙寫 old + new
   • Phase 3: 等 consumer catch up old column 訊息
   • Phase 4: DROP COLUMN old_col（此時無 in-flight WAL 帶 old_col）
2. 緊急：DROP existing slot、重建 publication 跟 slot、consumer 重 init load
3. 長期：用 Debezium snapshot.mode=schema_only_recovery 在 schema 變動時不重灌資料、只 reset schema

Case 4：initial COPY 大表鎖太久

徵兆：對 1TB 表跑 CREATE SUBSCRIPTION ... WITH (copy_data=true) 後、application 對該表 query / write 阻塞 30+ 分鐘；application timeout 大量。

根因：initial COPY 默認跑在 single transaction、整個 snapshot LSN 鎖住、長 transaction 跟 vacuum 衝突；同時對 subscriber 端鎖表寫入。

修法：

1. 分階段 init：

 1-- Primary：建 publication 不 copy
 2CREATE PUBLICATION app_changes FOR TABLE big_table;
 3
 4-- Subscriber：建 subscription 不 copy
 5CREATE SUBSCRIPTION app_sub
 6  CONNECTION '...'
 7  PUBLICATION app_changes
 8  WITH (copy_data = false);
 9
10-- 手動跑 partition-by-partition COPY（若是 partition table）
11-- 或用 pg_dump / pg_basebackup 拿 snapshot

2. PG 16+ parallel init：max_sync_workers_per_subscription = 4 平行 COPY 多個表
3. Debezium replacement：用 incremental snapshot（Debezium 1.6+）、background trickle copy、不鎖長 transaction

Case 5：replay storm 後 consumer offset reset

徵兆：Debezium 修 bug / 重 deploy 後、snapshot.mode=initial 觸發整個資料重灌；Kafka topic 流量爆 10x、下游 application 看到大量 duplicate event。

根因：Debezium offset store（Kafka topic 或 file）被誤刪 / corruption；重啟時不知道從哪 LSN 開始、預設 fall back 到 initial snapshot。

修法：

1. 預防：Debezium offset store 跟 Kafka cluster backup 一起做、不要單獨依賴 Kafka topic
2. 架構：consumer side 設計 idempotent — 用 event 自帶的 (source LSN + transaction ID) 當 dedupe key
3. transactional outbox pattern：CDC 只 capture outbox 表、application 主動寫 outbox + business data 在同 transaction；duplicate 由 application 自己 dedupe

容量規劃

實務 default：

• Debezium production：1 connector per source schema、不要 1 connector 跨 50 個表
• Slot retention：max_slot_wal_keep_size = 100GB、超出 invalidate slot 保護 primary
• Monitor cadence：1 分鐘 sample lag + 5 分鐘 alert threshold

整合 / 下一步

跟 Patroni HA 整合

logical slot 在 PG 16- 不跨 failover、是長期痛點：

1. PG 16-：failover 後 logical consumer 必須重 init（slot 在新 leader 上不存在）
2. PG 16+：failover parameter 讓 logical slot 在 standby 同步、failover 後 consumer 直接接
3. Patroni 16+ 支援 logical slot persistence 配置、配合用

跟 Kafka outbox pattern

production-grade CDC 不直接 read business table、是 read outbox table：

1-- Application transaction
2BEGIN;
3  INSERT INTO orders (...) VALUES (...);
4  INSERT INTO outbox (event_type, payload, created_at) VALUES ('order_created', '...', now());
5COMMIT;

Debezium 只 capture outbox table、event payload 已是 application-shaped JSON、不用解 row event。好處：

1. Schema change 不影響 CDC（outbox table schema 穩定）
2. 跨表 transaction 對應到單 event（outbox 是業務語意層）
3. Replay 可靠 — outbox 是 append-only、可重讀

跟 partitioning 整合

partitioned table 的 logical replication：

1. PG 13+ publish_via_partition_root = true — publication 從 parent 角度看、不是 per-partition
2. Subscriber 端可 partition 不同 strategy（甚至不 partition）
3. Schema change 對 partition table 更複雜、走 expand-contract 嚴格

下一步議題

• Logical replication conflict：subscriber 端寫衝突的處理（PG 17+ 加 conflict resolution）
• bi-directional replication（pg_active）：多 region active-active、衝突解決設計
• Decoder plugin 對比：pgoutput / wal2json / decoderbufs 效能跟易用性

相關連結

• 上游 vendor 頁：PostgreSQL
• 上游 chapter：Schema Migration Rollout Evidence — schema change × CDC 對應
• 平行 deep article：Patroni HA / PITR + WAL Archiving / Replication Slot Management（slot lifecycle / orphan / failover sync）/ Replication Topology（streaming + LSN 基礎）
• Methodology：Vendor 深度技術文章的寫作方法論