本文是 MySQL overview 的 implementation-layer deep article。Overview 已說明 MySQL 在 OLTP 譜系的定位、本文聚焦 CDC — Maxwell / Debezium 怎麼讀 binlog 產生 event stream。

MySQL CDC 的核心定位是 binlog consumer。

這個誤解來自跟 PostgreSQL CDC（Logical Replication + Debezium）混用名詞。PG 的 logical decoding 是 MySQL 沒有的能力 — PG 有 logical event（INSERT / UPDATE / DELETE 加上欄位 metadata）、輸出格式是 logical（人可讀、schema-aware）。MySQL 的 binlog 是 physical — 紀錄的是 row 的 binary image、不帶 schema 資訊。

Maxwell / Debezium 對 MySQL 是 binlog 第二消費者：

1Primary MySQL → binlog
2              ├→ Replica 1（讀 binlog 同步）
3              ├→ Replica 2
4              └→ Maxwell / Debezium（讀 binlog 解析、發 Kafka）

跟 replica 同一份 binlog stream，並非 separate logical decoding output。這個結構決定 CDC consumer 的設計：必須 自己處理 schema（從 information_schema 拉、跟 binlog event 對齊）、必須 自己 track position（binlog file + position 或 GTID）。

Binlog format：STATEMENT / ROW / MIXED

MySQL binlog 有 3 種 format、CDC 只能用 ROW：

ROW 是 CDC 唯一選擇、production 強制：

1binlog_format = ROW
2binlog_row_image = FULL  # FULL (all columns) / MINIMAL (only changed) / NOBLOB
3log_bin_use_v1_row_events = 0  # 用新版 event format

binlog_row_image 取捨：

• FULL：每個 row event 包含所有 column（before + after）、binlog 大、CDC 完整
• MINIMAL：只包含 changed column + primary key、binlog 省 30-50% 空間、CDC 看不到 未變 column
• NOBLOB：跟 FULL 一樣但 BLOB / TEXT column 只在 changed 時包含、平衡選擇

對 CDC 需要 full row payload（例如下游 search index 重建）必須 FULL。對 純 audit log 可以 MINIMAL。

ROW format 的 raw event 結構

Binlog ROW event 的資料形狀是 binary row image，而非 INSERT INTO orders VALUES (1, ‘foo’, 100)：

1TABLE_MAP_EVENT     - 對應 table schema metadata (table id + column type)
2                      ↓ 接續同一個 transaction 內所有 row event
3WRITE_ROWS_EVENT    - INSERT 的新 row image（column values）
4UPDATE_ROWS_EVENT   - UPDATE 的 before + after image
5DELETE_ROWS_EVENT   - DELETE 的 row image（被刪的 row）
6XID_EVENT           - transaction commit marker

CDC consumer（Maxwell / Debezium）必須：

1. 接收 binlog event stream
2. 看到 TABLE_MAP_EVENT 從中拿 table id → 對應 table name（cache 一份）
3. 看到 WRITE/UPDATE/DELETE_ROWS_EVENT 用 table id 反查 schema、把 binary 解析成 column value
4. 包成 JSON / Avro / Protobuf 推到 Kafka

關鍵：table schema 不在 binlog 內、CDC consumer 必須 獨立查 information_schema。如果 schema 變了（ALTER TABLE）、CDC 必須 invalidate cache、重新查、否則新 column 的 row event 解析錯亂。

Maxwell vs Debezium

兩個是 MySQL CDC 主流選擇、不同設計取捨：

選擇邏輯：

• 只用 MySQL + 想要 simple operations → Maxwell
• 已用 Kafka Connect、需要 schema registry、跨多種 DB → Debezium
• 需要 Avro / Protobuf schema 嚴格 governance → Debezium

配置 step-by-step（Debezium MySQL connector）

Debezium 是 Kafka Connect plugin、整套 stack：

 1# debezium-mysql.json - 部署到 Kafka Connect REST API
 2{
 3  "name": "orders-mysql-connector",
 4  "config": {
 5    "connector.class": "io.debezium.connector.mysql.MySqlConnector",
 6    "database.hostname": "primary.example.com",
 7    "database.port": "3306",
 8    "database.user": "debezium",
 9    "database.password": "...",
10    "database.server.id": "184054",          # 唯一 server ID (跟 MySQL replica 一樣)
11    "topic.prefix": "production",            # Debezium 2.x（舊 1.x 用 database.server.name）
12    "database.include.list": "orders_db",
13    "table.include.list": "orders_db.orders,orders_db.payments",
14
15    "database.history.kafka.bootstrap.servers": "kafka:9092",
16    "database.history.kafka.topic": "dbhistory.orders",
17    "include.schema.changes": "true",
18
19    "snapshot.mode": "initial",              # 或 schema_only / when_needed / never
20    "snapshot.locking.mode": "minimal",      # 避免 FLUSH TABLES WITH READ LOCK
21
22    "gtid.source.includes": "...",           # 可選 GTID filter
23    "tombstones.on.delete": "true",          # DELETE event 同 partition 跟一個 null tombstone
24    "decimal.handling.mode": "double"        # DECIMAL 處理: precise / string / double
25  }
26}

deploy：

1curl -X POST -H "Content-Type: application/json" \
2  --data @debezium-mysql.json \
3  http://kafka-connect:8083/connectors

Output topic：production.orders_db.orders / production.orders_db.payments 等 — 每張 table 一個 topic。

配置 step-by-step（Maxwell）

Maxwell 簡單很多：

 1maxwell \
 2  --host=primary.example.com \
 3  --user=maxwell \
 4  --password=... \
 5  --producer=kafka \
 6  --kafka.bootstrap.servers=kafka:9092 \
 7  --kafka_topic="maxwell.%{database}.%{table}" \
 8  --filter='exclude: *.*, include: orders_db.*' \
 9  --gtid_mode=true \
10  --output_ddl=true \
11  --output_xoffset=true

Maxwell event format：

 1{
 2  "database": "orders_db",
 3  "table": "orders",
 4  "type": "update",
 5  "ts": 1715000000,
 6  "xid": 12345,
 7  "commit": true,
 8  "data": { "id": 1, "status": "shipped", "amount": 100.50 },
 9  "old": { "status": "pending" }
10}

Debezium 對應的 event 格式更複雜（envelope + before + after + source + ts_ms 各 nested）、但跟 schema registry 整合好。

5 個 Production 踩雷

1. Binlog retention 太短 — CDC consumer 落後就 re-bootstrap

CDC consumer 失聯（Kafka Connect cluster down、network issue）超過 binlog retention（預設 binlog_expire_logs_seconds=2592000、30 天、但有些 production 縮短到 1 天）、需要的 binlog event 已被 purge、consumer error。

修法：

• Production binlog retention >= 7 天（避免為了 disk 過度縮短）
• 監控 Master_Log_File 是否還在（如果 retention 設 7 天、確認當前 file 仍存在）
• CDC consumer 失聯 alert 設 早於 retention 期（例如 6 天告警、給 24 小時修）
• 真的 missed binlog、必須 re-snapshot table（用 Debezium snapshot.new.tables）— 24 小時級工作

2. DDL event 處理 — schema change 跟 row event 對齊

ALTER TABLE orders ADD COLUMN status VARCHAR(20) 之後、UPDATE_ROWS_EVENT 多一個 column。CDC consumer 如果還用舊 schema cache、解析 row 時欄位數對不上、event 丟。

修法（Debezium）：

• include.schema.changes=true：DDL 進獨立 topic、consumer 監聽更新自己的 schema cache
• database.history.kafka.topic：Debezium 自己 track schema 歷史

修法（Maxwell）：

• --output_ddl=true：DDL 也進 stream、downstream 看到 DDL event 自己更新
• 沒有內建 schema history、要 application 層處理

修法（兩者通用）：

• 用 Online Schema Change Tools 取代直接 ALTER — 工具操作的 DDL 對 CDC consumer 更可預期
• Schema 改動 優先 add column 為 nullable、避免 backfill 期間 CDC consumer 看到 mid-state

3. binlog_row_image=MINIMAL 讓下游錯亂

MINIMAL 省 binlog 空間、但 row event 只含 changed column。下游 search index 重建 需要 full row payload 的場景下、MINIMAL 看不到未變的 column、index 缺欄位。

修法：

• CDC 需要 full payload 的場景 必須 FULL、這項成本要納入容量規劃
• 如果空間真緊、考慮 NOBLOB（BLOB / TEXT 只在 changed 時包含、其他 column 仍 FULL）
• 統一設定：production 全部 server 同一 binlog_row_image 設定

4. Kafka producer 跟 binlog reader 速度差 — lag 累積

Binlog reader 從 MySQL 讀 1000 event/sec、Kafka producer 寫得只有 800 event/sec、CDC consumer 自身 lag 累積、最終 disk 滿（producer 內部 buffer）。

修法：

• 監控 CDC consumer lag：對 Debezium 看 Kafka Connect 的 source-record-poll-rate vs source-record-write-rate
• Kafka producer tuning：batch.size / linger.ms / compression.type=snappy
• Kafka broker capacity：partition 數量 ≥ Debezium task 數量、避免 partition 瓶頸
• 避免把 過多 table 給單一 Debezium connector — 用 table grouping（按 traffic 拆 connector）

5. Schema change 跟 downstream consumer 不同步

CDC producer（Debezium）正確處理了 schema change、但 downstream Kafka consumer 用舊 schema deserialize、新 column 看不到 / type 解析錯。

修法：

• 用 Schema Registry（Confluent / Apicurio）+ Avro：consumer 訂閱 schema、自動 evolve
• 不用 schema registry 時、CDC payload 設計 backward-compatible（新 column 為 optional）
• Application 層 schema change protocol：Expand / Contract — 先加 column、deploy consumer 認 column、再 backfill、最後 application 寫新 column
• 大型 schema change 跨多服務、建議 先 freeze CDC stream、做 schema migration、resume stream（極端但確定）

容量規劃要點

對 100K WPS server、CDC pipeline cost 大致是 MySQL infra 的 5-10%。

跟其他模組整合

跟 Replication topology

CDC 是 binlog 第二消費者、需要 GTID + binlog ROW format（Replication Topology）。Debezium / Maxwell 都偏好從 replica 讀 binlog（不增加 primary 負擔）、但要小心 replica lag 加在 CDC lag 上。

跟 OSC tool

gh-ost / pt-osc 跑 schema change 時、會在 binlog 留下大量 row event（copy 既有 row 到 ghost）。CDC consumer 看到這些 event 是 normal-looking INSERT、可能誤觸發 downstream side effect。

修法：

• CDC consumer 過濾 ghost table prefix（_orders_new / _orders_gho）— 不發 downstream
• 或暫停 CDC 期間跑 OSC（用 Debezium pause API）

跟 PostgreSQL Logical Replication + Debezium

詳見 PostgreSQL Logical Replication + Debezium — 這是 sibling 對照，用來區分不同 abstraction。

跟 Aurora MySQL

Aurora MySQL 5.7 / 8.0 都支援 binlog + GTID、CDC 可用。但 Aurora 推薦走 Aurora-native database activity streams（不同 abstraction）— 跟 Debezium 共存但有 overlapping。生產上 Debezium 仍是 cross-cloud 跟 vendor-neutral 選項、優先用 Debezium。

詳見 Aurora vendor page。

Production case：Shopify sharded MySQL CDC

Sharded MySQL CDC 的核心責任是把多個 shard 的 binlog 轉成可消費、可回放、可觀測的事件流。Shopify Debezium CDC over sharded MySQL 提供的工程訊號是 100+ shard、約 150 個 Debezium connector、BFCM 期間 100K records/sec，以及 snapshot lock 與 oversized payload 對 CDC pipeline 的壓力。

這個案例要回收到三個操作判準。第一，connector 數量應跟 shard 拓撲一起設計，避免單一 connector 變成跨 shard bottleneck。第二，snapshot window 要排進 schema migration 與 event consumer 的變更計畫，避免 initial snapshot 把 production read path 壓滿。第三，oversized payload 要在 schema / outbox / topic 分流階段處理，避免 Kafka partition 與 downstream consumer 同時承受大訊息。

Shopify 案例的下一步路由是把本篇和 Database Sharding 一起讀。若讀者關心 broker 層的 partition、consumer lag 與 replay 策略，接到 Kafka vendor；若關心資料庫端壓力，回到 Replication Topology 與 Online Schema Change Tools。

相關連結

• MySQL vendor overview
• MySQL Replication Topology（binlog ROW + GTID 是 CDC pre-requisite）
• MySQL Online Schema Change Tools（OSC + CDC 整合）
• PostgreSQL Logical Replication + Debezium（PG sibling、不同 abstraction）
• Outbox pattern 卡片（CDC 跟 outbox 在 application-level event publishing 的關係）
• Expand / Contract 卡片（schema migration 跟 CDC consumer）
• 官方：Debezium MySQL Connector / Maxwell

本文是 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 深度技術文章的寫作方法論