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

本文是 Cloud Spanner overview 的 implementation-layer deep article、寫作參照 vendor deep article methodology。Overview 已說明 Spanner 在全球 OLTP 譜系的定位、本文聚焦 Change Streams — Spanner 把 commit 後的 row mutation 變成下游可消費事件流的 CDC 機制。

問題情境：OLTP 的變更要餵給搜尋、快取、分析三個下游

Change Streams 的責任是把 Spanner 內已 commit 的 row mutation 變成有序、可重放、攜帶 commit timestamp 的事件流、讓搜尋索引、快取、分析倉儲三類下游不用反覆 full-table scan 就能跟上主資料庫。OLTP 主庫負責正確寫入、下游各自負責自己的 query shape、兩邊之間需要一條「只送變更、不送全表」的管線、這條管線就是 CDC 的職責。

讀者徵兆通常從這幾個地方浮現：搜尋團隊每 5 分鐘跑一次 full scan 把 orders 重灌進 Elasticsearch、Spanner CPU 被掃表打到 70%；快取層靠 TTL 過期被動失效、使用者看到舊價格;分析團隊想做近即時 dashboard、卻只有每日 batch export。共同壓力是「主庫的變更沒有一條乾淨的出口」、每個下游各自發明輪子去 poll 主庫。

真實壓力場景：全球電商把訂單寫進 Spanner multi-region instance、需要把每筆訂單狀態變更同時推給 (1) 搜尋索引更新庫存可售性、(2) Pub/Sub 通知履約系統、(3) BigQuery 做近即時營收儀表板。三個下游對延遲、順序、retention 的要求不同、但都需要從同一條變更流取得資料。

Case anchor：9.C10 Cloud Spanner planetary scale 提供「全球大規模 OLTP 寫入」的壓力 anchor — Google Ads / Play 計費的寫入量級說明為什麼下游不能靠 full scan 跟上。dogfood 邊界明示：9.C10 是 Google 內部 dogfood case、未展開 change streams 實作細節；本文 change stream 的物件模型、partition 行為與 retention 上限均來自 GCP vendor 規格、不是 9.C10 case 揭露。

核心機制：data change record、partition token、commit timestamp

Change Stream 是一個用 DDL 建立、綁定到特定 table / column 集合的 schema 物件、commit 後 Spanner 把對應 row 的 mutation 寫成 data change record 供消費。它跟「在 application 層自己寫 outbox table」最大的差異是：change record 由 Spanner 內部跟 transaction commit 綁定產生、攜帶該 mutation 的 commit timestamp、繼承 external consistency 的全序性質、不需要 application 額外保證原子性。

建立語法是 DDL：

 1-- 監看整個資料庫
 2CREATE CHANGE STREAM everything_stream FOR ALL;
 3
 4-- 只監看特定 table 的特定欄位
 5CREATE CHANGE STREAM orders_stream
 6  FOR orders(status, total_amount), inventory(available_qty)
 7  OPTIONS (
 8    retention_period = '7d',
 9    value_capture_type = 'NEW_AND_OLD_VALUES'
10  );

value_capture_type 決定 record 攜帶多少資料、三個選項對下游的意義不同：

Data change record 的關鍵欄位

每筆 data change record 攜帶 commit timestamp、record sequence、transaction tag、mod type（INSERT / UPDATE / DELETE）、以及 primary key 與依 capture type 決定的 value payload。下游靠 commit timestamp + record sequence 在同一個 transaction 內重建變更順序、跨 transaction 則靠 commit timestamp 的全序。這條順序保證是 Spanner CDC 跟「自己 poll updated_at column」的根本差異：poll updated_at 在 clock skew 下會漏序、change stream 的順序由 TrueTime 撐住。

Watch partition：change stream 的 partition 模型

Change stream 的讀取單位是 partition、不是整條流。Spanner 把 change stream 依底層 key range 切成多個 partition、每個 partition 用一個 partition token 標識、消費者對每個 token 各開一個 read 呼叫並行讀。當底層資料 split 或 merge（Spanner 自動 re-balance key range）、partition 會產生 child partition — 父 partition 的 record 讀到結束時回傳 child partition token、消費者要接著去讀 child token、才不會漏掉 split 後的變更。

這個 child partition 的接力機制是 change stream 消費的核心複雜度。手刻消費者必須維護一張 partition token 的 watermark 表、處理 parent 結束 → child 開始的交棒、保證每個 token 只被一個 worker 讀。多數團隊不該手刻這層、應走 Dataflow connector（下節）讓它代管 partition 生命週期。

Scope warning：本節 data change record 欄位、value_capture_type 選項、child partition 接力語意均屬 GCP Spanner change streams 規格、實作前 cross-verify Spanner change streams 官方文件。retention_period、partition 切分行為隨版本演進、非 9.C10 case 揭露。

操作流程：建立 change stream 到 Dataflow 下游

Step 1：建立 change stream 並驗證

用 DDL 建立 change stream 後、用 information schema 確認它存在、並用 metadata 查詢確認監看範圍正確。

1CREATE CHANGE STREAM orders_stream
2  FOR orders, inventory
3  OPTIONS (retention_period = '7d');

驗證：查 INFORMATION_SCHEMA.CHANGE_STREAMS 確認 stream 已建立、查 CHANGE_STREAM_TABLES 確認監看的 table 集合符合預期。若監看範圍寫錯（漏了某 table）、下游會靜默漏掉那張表的變更、這是高代價的靜默失敗、必須在這步驗證。

Step 2：選消費路徑 — Dataflow connector 為預設

消費 change stream 有三條路徑、對應不同的下游能力與運維成本：

Dataflow connector 是預設路徑、因為它代管 partition token 的 split / merge 接力、提供 checkpoint 與 exactly-once 到下游 sink。

Step 3：部署 Dataflow pipeline 並驗證 end-to-end

用官方 Spanner-to-BigQuery 或 Spanner-to-PubSub Dataflow template 部署。驗證 end-to-end：在 Spanner 寫一筆變更、量它多久出現在下游、確認 commit timestamp 在下游被保留、確認 INSERT / UPDATE / DELETE 三種 mod type 都被正確處理（DELETE 特別容易在下游被漏掉、要專門測）。

Step 4：rollback boundary

Change stream 是可加可刪的 schema 物件、DROP CHANGE STREAM orders_stream 即停止捕捉、不影響主表寫入。rollback boundary 在「停掉 Dataflow pipeline + 標記下游資料為 stale」、不是「改主庫 schema」 — change stream 本身對 OLTP write path 的影響極小、刪除它不需要 cutover window。

失敗模式：retention 過期、下游慢於 retention、DELETE 漏處理

Retention 窗口過期導致 partition 不可讀

change stream 的 record 只保留 retention_period（預設 1 天、上限數天、查官方文件確認當前上限）。若下游消費者停機超過 retention 窗口、過期 partition 的 record 被 GC、消費者重啟後讀到 partition token 已失效的錯誤、那段變更永久漏掉。徵兆是消費者重啟後報 partition not found、下游資料出現一段空洞。修法是 retention_period 設成大於「最壞情況下游停機 + 重啟趕上」的時間、並對 change stream 的 consumer lag 設告警、lag 接近 retention 一半就 page。

Scope warning：retention_period 的預設值與上限屬 GCP 規格、隨版本變動、cross-verify 官方文件。本段 lag 告警閾值（retention 一半）是通用工程估算、不是 9.C10 case 揭露的數字。

下游消費吞吐慢於主庫寫入速率

主庫 write rate 持續高於下游消費速率、consumer lag 單調上升、最終撞 retention 窗口漏資料。這在全球大規模 OLTP 寫入下是真實壓力 — 對應 9.C10 揭露的 Google internal dogfood 寫入量級（dogfood 邊界：該量級是 Google 全使用者加總、不是單一 instance 配額）。修法是擴 Dataflow worker、確認 partition 數足夠讓消費並行、必要時把單一 change stream 依 table 拆成多條降低單條負載。判讀訊號是 Dataflow backlog metric 持續成長、不是偶發 spike。

DELETE 變更在下游被漏處理

下游 pipeline 只處理 INSERT / UPDATE 的 upsert、忘了處理 DELETE 的 tombstone、導致下游索引 / 快取殘留已刪除的資料。徵兆是搜尋結果出現主庫已不存在的項目、對帳發現下游 row count 高於主庫。修法是 pipeline 顯式 handle mod type = DELETE、依 capture type 決定能否拿到 old values 來反向補償；若用 NEW_VALUES capture、DELETE record 只攜帶 key、下游必須靠 key 刪除、不能假設拿得到完整 old row。

把 change stream 當可靠 message queue 用

change stream 是 變更捕捉、不是 general-purpose message bus。團隊若把它當成「任意事件都塞進來」的 queue、會發現它只能攜帶 row mutation、不能攜帶 application 自定義事件、且 retention 比專用 message broker 短。Anti-recommendation（何時不用）：需要長期保留、任意 payload、複雜 routing 的事件流、用 Pub/Sub 或 Kafka 當 SSoT、change stream 只負責「資料庫變更」這一類來源；把 application 業務事件硬塞進 change stream 是把 CDC 機制誤用成 event bus。

容量與觀測：consumer lag 是核心健康訊號

Change stream 的容量壓力集中在「下游能不能跟上主庫寫入」、核心 metric 是 consumer lag 與 partition 並行度。

必看 metric：

1Dataflow data freshness / system lag   → 下游落後主庫 commit 的時間
2Dataflow backlog bytes / elements      → 未消費的 record 積壓量
3Spanner change stream partition count  → 並行讀取單位、隨底層 split 變化
4Spanner CPU utilization                → change stream 讀取也消耗主 instance CPU

Change stream 的讀取消耗主 instance 的 CPU 與 read capacity、不是免費旁路。容量規劃要把「change stream 消費」當成額外 read workload 算進 instance sizing、回 9.6 容量規劃模型。用 4.20 Observability Evidence Package 把 consumer lag 跟 Spanner CPU 配成 evidence pair：lag 上升且 CPU 飽和、是 instance 容量不足；lag 上升但 CPU 有餘、是 Dataflow worker 不足。

Alert 建議：

Scope warning：上述閾值為通用工程估算、依各團隊 retention 設定與 SLA 調整、非 9.C10 case 揭露的 production 數字。

邊界與整合：跟 DynamoDB Streams 對照、何時不用 change streams

跟 DynamoDB Streams 的對照

Change Streams 跟 DynamoDB Streams 都是 managed CDC、但 partition 模型、ordering 範圍、retention 的設計取捨不同、選型時這三軸最關鍵。

關鍵差異在 ordering：Spanner change stream 繼承 external consistency、跨 partition 的 record 可用 commit timestamp 排出全序;DynamoDB Streams 只保證單 partition key 內有序、跨 partition 重組需要下游自己處理。retention 上 DynamoDB Streams 固定 24 小時、Spanner 可設更長、對「下游可能長時間停機」的場景 Spanner 較有彈性。消費模型上 DynamoDB Streams 跟 Lambda 整合最順、Spanner 跟 Dataflow / BigQuery 生態整合最順。

Scope warning：DynamoDB Streams 24 小時 retention 與 StreamViewType 屬 AWS 規格、Spanner retention 上限屬 GCP 規格、兩者均隨版本演進、cross-verify 各自官方文件。

何時不用 change streams

單純需要「下游讀到最新狀態、不在意中間每筆變更」、且主庫變更率低、定期 batch export 反而更簡單、不必引入 change stream + Dataflow 的運維成本。對延遲不敏感的分析、走 BigQuery federation 直接查 Spanner（見 sibling）比建 CDC 管線更省。Anti-recommendation 的判準是：若下游不需要「每一筆變更的順序」、只需要「定期最新快照」、CDC 是過度工程。

Sibling deep articles 路由

• bigquery-federation：不想建 CDC 管線、直接 federated query 查 Spanner 的 OLAP 路徑、跟 change stream → BigQuery 是兩條互補的整合方式
• truetime-api-depth：change stream 的 commit timestamp 全序來自 TrueTime、理解順序保證的物理基礎
• consistency-models-comparison：change stream 繼承 external consistency、跟 DynamoDB Streams 的 per-partition ordering 對照回 linearizability 定義

跟 knowledge card 的互引

• change-data-capture — 本文是這張卡的 Spanner 實作範例
• external-consistency — change stream 的全序保證來源

跟 04 / 09 章節的互引

• 4.20 Observability Evidence Package：consumer lag × Spanner CPU 的 evidence pair
• 9.6 容量規劃模型：change stream 讀取當額外 read workload 算進 sizing

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

本文不重複 MongoDB vendor overview 已寫過的 change streams 簡介 — 而是 production CDC pipeline 部署 + 失敗修復的實作層教學。

MongoDB 適用度前置判讀：進到 CDC pipeline 設計前先確認 workload 在 MongoDB 適用區（document shape 主導 / contract layer 該放哪 / 跨雲 hedging 是否需要）— 詳見 schema-design-pattern 開頭 3 軸前置判讀、本篇不重複展開。Change streams 是 已選 MongoDB 後 的 event-driven 整合議題。

問題情境：第一版 CDC pipeline 跑幾週的踩雷

典型觸發場景：application 寫 MongoDB 後還要 dual-write Elasticsearch / Redis / data warehouse、application code 越塞越多 hook、寫入失敗的補償邏輯散落各處。改用 change stream → Kafka → downstream sink 後、有了第一版 CDC pipeline、但連續工作幾週後出現：

• Downstream 漏 event 或 duplicate event
• Connector restart 後 resume token 過期（oplog 已滾掉）、整個 collection 必須重灌
• Sharded cluster 上 collection-level change stream 跟 cluster-wide change stream 行為不同、application 連 mongos 跟連 single shard 拿到不同 event

讀者徵兆：

• MongoDB Kafka Connector log ChangeStreamHistoryLost 或 ResumeTokenChanged
• Downstream Kafka topic event count vs source collection write count 不平
• Replication oplog 跟 change stream consumer 的 lag 同時升

Case anchor：CDC pipeline resume token 過期導致全量重灌的具體 incident 細節需未來 case 補完、本文以「常見 failure pattern」+ 容量公式處理、不憑空編造 incident 數字。側面引用 Spotify Kafka → PubSub migration（pipeline-level migration 經驗對照）。

核心機制

Change stream 是 MongoDB 3.6+ 原生 CDC、本質上是 oplog tail 包裝成 cursor API。可以從 collection / database / cluster 三個 scope 開：

• Collection-level：監看單一 collection 的變更
• Database-level：監看整個 database 的所有 collection
• Cluster-wide：監看整個 cluster 的所有 database

Oplog 是 capped collection、預設 size = disk 5% 或 50GB（取較小）。Resume token 對應 oplog entry 的 timestamp + UUID + documentKey。Token 必須對應仍在 oplog 內的 entry — oplog 滾掉就拿不到 token 對應的位置、ChangeStreamHistoryLost。

Resume token 兩種用法：

• _id：每個 event 都帶、application 自己存
• startAfter / resumeAfter parameter：重啟 cursor 時帶上

fullDocument: "updateLookup"：update event 預設只給 delta、加這個 option 會額外 query 一次 primary 拿完整 doc；高頻 update 下成本顯著（primary 負擔翻倍）。

Pre-image / post-image（6.0+）：可以拿到 update 前的 doc 狀態、需 collection-level option changeStreamPreAndPostImages: true。

Cluster-wide vs collection-level change stream：

• Cluster-wide 必須打 mongos、event ordering 是 global
• Collection-level 可直接打單 shard、ordering 只在該 shard 內
• Sharded cluster 上 cluster-wide stream 容易把 mongos 變單點瓶頸（所有 shard 的 event 都收斂到 mongos）

MongoDB Kafka Connector（Confluent / MongoDB 官方）：

• Source connector：把 change stream → Kafka topic
• Sink connector：把 Kafka topic → MongoDB
• At-least-once 語義、需 application 處理 idempotency

對應 knowledge card：change-data-capture、replication-channel、replication-slot（MongoDB 沒 slot、概念對照）。

操作流程

Step 1：scope 決策樹。

Step 2：oplog sizing。容量公式：

1oplog size >= peak write rate × max acceptable consumer downtime

典型設 24-72 小時可恢復窗口。例：peak 5K WPS、想容忍 48 小時 connector down、oplog 至少 5K × 86400 × 2 ÷ docs_per_GB ≈ 看實際 doc size 決定。在 Atlas 上 oplog size 可直接調、自管 cluster 改 replSetResizeOplog。

Step 3：Kafka Connector 配置。

 1{
 2  "connector.class": "com.mongodb.kafka.connect.MongoSourceConnector",
 3  "connection.uri": "mongodb://...",
 4  "database": "shop",
 5  "collection": "orders",
 6  "publish.full.document.only": "true",
 7  "change.stream.full.document": "updateLookup",
 8  "copy.existing": "true",
 9  "copy.existing.namespace.regex": "shop\\.orders",
10  "errors.tolerance": "none",
11  "offset.flush.interval.ms": "10000"
12}

關鍵欄位：

• change.stream.full.document: "updateLookup"：每 update 額外 query primary 拿完整 doc（成本意識）
• copy.existing: "true"：connector 啟動時先把現有 collection 全量複製、再切到 change stream — 適合初次部署
• errors.tolerance: "none"：sink 失敗時 batch 停在 dead-letter queue、不 silently drop

Step 4：resume token persistence。Connector 把 token 寫 Kafka __consumer_offsets 或外部 store；application 自管 change stream 時要寫到 durable store（不是 in-memory）。

Step 5：filter pipeline。Change stream 支援 aggregation pipeline 把過濾下推到 MongoDB：

1const pipeline = [
2  { $match: { "operationType": { $in: ["insert", "update", "delete"] } } },
3  { $match: { "fullDocument.region": "ap-tokyo" } }
4]
5const changeStream = db.orders.watch(pipeline)

把過濾下推減少 connector 處理量、特別是高頻 collection 上。

Step 6：downstream idempotency。Sink 收 Kafka event 時用 documentKey._id + clusterTime 做 dedup key — at-least-once 語義意味著 connector restart 後幾分鐘 event 會重發。

驗證點：

• Source collection write count vs Kafka topic event count 差異 < 0.1%
• Resume token age < oplog retention 的 50%（健康狀態）
• Connector restart drill 能 5 分鐘內接回

Rollback boundary：source connector 是 read-only 對 MongoDB 無傷；sink connector 要備份 target 才能還原；resume token 寫錯 → 從 startAtOperationTime 回退到時間點重跑。

失敗模式

Resume token 過期（oplog 滾掉）：connector down 太久、oplog 已超出 retention、ChangeStreamHistoryLost → 必須 copy.existing 全量重灌、期間 downstream 看不到新資料。預防是 oplog sizing 留 buffer + connector lag alarm + token age 監控（age > oplog retention 的 50% 預警）。

updateLookup 在高頻 update 下打爆 primary：每筆 update event 都觸發一次 primary query、primary 負擔翻倍。修法是改 collection-level pre/post image（6.0+）、由 MongoDB 自己在寫入時記錄、或在 application 補完整 doc 後再寫 Kafka、不用 updateLookup。

Sharded cluster cluster-wide stream 打爆 mongos：所有 shard 的 event 都收斂到 mongos、mongos 變單點瓶頸。修法是改 collection-level stream 多 connector 並行、每 connector 連 mongos 但只訂單一 collection。

At-least-once 變 duplicate flood：connector restart 點之後幾分鐘 event 重發、downstream 沒做 idempotency → 重複 side effect（重複發 email、重複扣款）。修法是 sink 端強制 idempotency（dedup key 寫 Redis / DB）、不能假設「我用 at-least-once 但實際不會 duplicate」。

Schema drift 突然 break sink：MongoDB 寫了新欄位 / 改型別、sink connector 的 JSON schema 不認、batch 停在 dead-letter queue。修法是 schema 變動有 validation gate（見 schema design pattern）、sink schema 設 lenient 模式吃 unknown field、或加 schema registry 統一版本。

Backup / DDL 期間 change stream 異常：reIndex / compact / dropCollection 觸發特殊 event、connector 沒處理 → consumer 停。修法是 connector 處理特殊 event 邏輯要明確、不認得的 operation type 至少 log warning 而不是 silently stuck。

Anti-recommendation：

• 簡單的 outbox pattern + application transactional write 對於低吞吐 / 單 sink 的場景比 change stream + Kafka 簡單；不是所有「需要 event 通知」的場景都要 CDC pipeline
• 若 downstream 只是同一 region 同團隊的 Elasticsearch index、$merge 寫進中介 collection 或 application 雙寫 + 對賬可能成本更低
• Resume token 過期是這條路徑最痛的事故、oplog sizing 是 投資而不是成本 — 不要為了省 storage 把 oplog 設太小

容量與觀測

關鍵 metric：

• Oplog 健康：oplog 寫入速率與保留時間
• Change stream 健康：cursor age、resume token 距 oplog 頭尾的距離
• Connector 健康：connector lag（Kafka offset 對比 source write）
• 下游健康：event count diff（source write count vs sink apply count）、event time → arrival time lag 分布

Mongo command：

• db.getReplicationInfo()：oplog 大小 / 時間範圍
• db.printReplicationInfo()：oplog 摘要
• db.currentOp({ "op": "getmore", "ns": "local.oplog.rs" })：看 change stream consumer 連線

Connector metric（Kafka Connect JMX）：source-record-poll-rate、source-record-write-rate、offset-commit-success-rate。

回到 4.20 observability evidence：oplog retention + connector lag + dedup rate 是 CDC pipeline 健康狀態 evidence 三件套。

回到 9.5 bottleneck localization：CDC lag 升高時區分 (a) source oplog 寫太快 (b) connector 處理慢 (c) downstream sink 慢。

邊界與整合

Sibling deep articles：

• shard key selection — cluster-wide vs collection-level change stream 在 sharded cluster 的選擇
• replica set read preference — change stream 對 primary load 的影響、能否走 secondary
• schema design pattern — schema validator 對下游 sink 的契約意義
• connection management and cache layer — CDC sink 在 production 跨層架構裡的角色（cache invalidation / federated DB 同步）

Migration playbook：

• MongoDB → 其他 sink 的 bulk migration 走 → Atlas Migration Service
• 遷出 MongoDB 時 change stream 是 catch-up 機制（先 bulk export、再 change stream 補增量）

跟 1.x 互引：1.7 schema migration rollout evidence 處理 schema drift 時 CDC pipeline 的對賬；1.9 reconciliation data repair 處理 CDC 失準後的對賬流程。

相關連結

• MongoDB vendor overview — 本文是該頁尾「change streams + Kafka」backlog 的深度展開
• Vendor 深度技術文章方法論
• 官方：Change Streams、MongoDB Kafka Connector、Oplog

本文是 DynamoDB overview 的 implementation-layer deep article。寫作參照 vendor deep article methodology。

訂單寫進 DynamoDB 後、搜尋索引要更新、快取要失效、要推一筆通知、要寫一筆 audit。第一版 application 在寫訂單的同一段 code 裡同步做完這四件事、結果單一步驟（推通知的外部 API）變慢、整個寫訂單路徑被拖垮。第二版改成「另一個 service 每 10 秒輪詢 table 撈新資料」、輪詢既貴（全表 scan）又慢（最差 10 秒延遲）。兩個痛點都指向同一個缺口 — 資料變更需要一條可靠、低延遲、不污染寫路徑的下游通道。這正是 DynamoDB Streams 的責任。本文展開 Streams 的 record 結構、順序保證的真實邊界、消費模式選擇與失敗處理。

事件機制前提：先確認 workload 適配 DynamoDB：事件驅動機制是已選 DynamoDB 後的議題；選型本身先過 workload 適配 4 軸 — PK 天然均勻 / control plane vs data plane / consistency 可接受 eventual / access pattern 穩定。判讀軸詳見 single-table-design-pattern 開頭 4 軸前置判讀。本文聚焦 已選 DynamoDB 後、把資料變更導向下游的事件機制。

核心機制：Stream record 與 view type

DynamoDB Streams 是 table 的 change data capture 通道 — 把 item 層級的 insert / modify / delete 變成一條時間排序的事件流。開啟後、每筆寫入產生一筆 stream record。

view type 決定 record 帶什麼：

view type 在開 stream 時定、改要重開 stream。選 NEW_AND_OLD_IMAGES 最方便但 record 最大（影響 Lambda payload 與成本）；下游只需 key 就回查的、選 KEYS_ONLY。

Scope warning：「stream record 保留 24 小時」、「Lambda 單次 batch 上限」這些屬 AWS vendor 規格、會隨版本調整、實作時 cross-verify 官方 doc。本文不含 production case 揭露的 stream 配置數字。

對應 knowledge card：change-data-capture、idempotency。

順序保證的真實邊界

這是 Streams 最常被誤解的點 — 「stream 是有序的」這句話只在特定範圍成立。

保證範圍：

• stream 切成多個 shard、每個 shard 對應 table 的一組 partition
• 同一 partition key 的所有變更、進同一個 shard、在 shard 內嚴格時間排序
• 跨 shard 沒有 全域順序保證

這代表：同一筆訂單（同 PK）的 create → update → delete 一定按序到下游；但訂單 A 跟訂單 B（不同 PK、可能不同 shard）的相對順序不保證。下游若依賴「跨實體的全域順序」、會踩雷。

shard split / merge：

table partition 會隨資料量與流量 split、stream shard 跟著變動。消費端要能處理 shard 生命週期（Lambda event source mapping 自動處理；自己用 SDK 拉的要處理 shard iterator 的 parent-child 關係）。

順序 + 冪等的組合：

Lambda 消費 stream 是 at-least-once — 同一筆 record 可能被送兩次（retry、shard 重平衡）。下游處理必須冪等：用 record 的 sequence number 或業務鍵去重、不能假設「每筆只處理一次」。每筆訊息帶獨立 message_id 的事件流天然適合 — message_id 當冪等鍵、重送不重複發。

Scope warning：上述順序與 at-least-once 語意屬 Streams vendor 規格 + 通用事件處理工程、非 production case 揭露。

消費模式：Lambda vs Kinesis

兩條主要消費路徑、責任與運維成本不同：

多數「寫入後觸發一個下游動作」用 Lambda event source mapping 最簡單。需要長 retention、多消費者 fan-out、或要重播歷史變更的、用 Kinesis Data Streams for DynamoDB。

Lambda event source mapping 的關鍵旋鈕：

• batch size：一次給 Lambda 幾筆 record（吞吐 vs 延遲）
• batch window：湊滿 batch 或等多久才觸發（低流量時的延遲控制）
• parallelization factor：一個 shard 並行幾個 Lambda（提升單 shard 吞吐、但犧牲 shard 內嚴格順序）

Scope warning：parallelization factor > 1 會在單 shard 內並行處理、放寬順序保證；需要嚴格順序的維持 factor = 1。具體上限屬 vendor 規格。

操作流程

從開 stream 到下游上線的 6 步流程。

Step 1：選 view type

依下游需要什麼決定。同步到搜尋索引要完整新 item → NEW_IMAGE；audit 要看改動 → NEW_AND_OLD_IMAGES；下游自己回查 → KEYS_ONLY。

Step 2：開 stream

1aws dynamodb update-table \
2  --table-name orders \
3  --stream-specification StreamEnabled=true,StreamViewType=NEW_AND_OLD_IMAGES

Step 3：接 Lambda event source mapping

 1def handler(event, context):
 2    for record in event["Records"]:
 3        event_name = record["eventName"]      # INSERT / MODIFY / REMOVE
 4        if event_name == "REMOVE":
 5            old = record["dynamodb"]["OldImage"]
 6            delete_from_search_index(old)
 7        else:
 8            new = record["dynamodb"]["NewImage"]
 9            upsert_to_search_index(new)
10        # 冪等：用 sequence number 或業務鍵去重
11        seq = record["dynamodb"]["SequenceNumber"]

Step 4：設定 batch 與失敗處理

1BatchSize: 依下游處理能力與延遲目標
2MaximumBatchingWindowInSeconds: 低流量湊批、控制延遲
3BisectBatchOnFunctionError: true   # 失敗時二分批、隔離壞 record
4MaximumRetryAttempts: 有限次       # 避免毒丸 record 無限重試
5DestinationConfig.OnFailure: DLQ   # 超過重試送 DLQ

Step 5：下游冪等設計

下游 upsert 用業務鍵（PK）做 idempotent write、刪除用「刪不存在不報錯」；確保同一 record 處理兩次結果相同。

Step 6：驗證點

1# 灌一筆寫入、確認下游在預期延遲內收到對應 record
2# CloudWatch: Lambda IteratorAge（消費落後程度）應接近 0
3# 製造一筆會失敗的 record、確認進 DLQ 而非卡住整個 shard

Rollback boundary：關 stream 即停止產生新 record；已產生的 record 在 retention 內仍存在。下游邏輯出錯時、修好 Lambda 後可在 retention 內讓未處理 record 重新消費（或從 DLQ 重放）。

失敗模式

production 常見的 5 個踩雷：

Case 1：下游非冪等、重送導致重複副作用

at-least-once 重送、下游每次都發一筆通知、用戶收到重複推播。修法：下游用業務鍵冪等、sequence number 去重；副作用（發通知 / 扣款）必須 idempotent。

Case 2：依賴跨實體全域順序

下游假設「所有訂單事件按全域時間到達」、實際跨 shard 無此保證、算錯聚合。修法：只依賴「同 PK 內有序」；需要跨實體順序的、在下游用 event timestamp 重排、或重新設計不依賴全域順序。

Case 3：毒丸 record 卡住整個 shard

某筆 record 讓 Lambda 永遠拋例外、預設行為是重試整個 batch、shard 卡死、IteratorAge 無限上升。修法：開 BisectBatchOnFunctionError + MaximumRetryAttempts + DLQ、隔離壞 record 讓其餘繼續。

Case 4：consumer 落後、record 過期遺失

下游處理太慢、IteratorAge 超過 stream retention、未處理 record 被清掉。這個 Case 的代價跟前三個不同層級：前三個是「重複副作用 / 算錯聚合 / shard 卡住」、都還在 stream 裡留有 record、修好邏輯後可重新消費或從 DLQ 重放。Case 4 是 record 本身已被 retention 清除、那段時間的資料變更在 stream 這條通道上永久消失、沒有回退路徑。要補回只能反向比對 table 當前狀態跟下游狀態（若下游存得了），或在源頭重跑一次寫入觸發新 record — 兩者都是事故後的人工修復、成本遠高於前三個 Case 的設定旋鈕。

因為不可逆、防線要前置在「逼近 retention 之前」而非「過期之後」：IteratorAge alarm 的閾值設在遠低於 retention 的水位、留出擴容反應時間；吞吐不足時加 parallelization factor 或改 Kinesis（更長 retention、爭取更大的落後緩衝）；下游設計要能水平擴、讓落後可被快速追平。

Case 5：parallelization factor 開了還抱怨順序錯

為提吞吐把 factor 開 > 1、又依賴 shard 內嚴格順序、兩者矛盾。修法：需要嚴格順序維持 factor = 1；要並行吞吐就接受順序放寬、或把順序敏感的處理移到下游用 PK 分組。

Anti-recommendation：只有單一同步下游、且寫路徑延遲容忍度高 → 直接在 application 寫入後同步處理可能更簡單、不必引入 stream 的運維與冪等複雜度。Streams 的價值在「多下游 / 解耦寫路徑 / 低延遲 CDC」。

容量與觀測

CloudWatch metric：

• IteratorAge（Lambda）：消費落後程度、最關鍵指標、持續上升代表下游跟不上
• Lambda Errors / Throttles：下游處理失敗 / 被限流
• DLQ 訊息數：毒丸 record 累積、需要人工介入
• stream ReadProvisionedThroughputExceeded（Kinesis 模式）：消費端讀超限

判讀：

• IteratorAge 接近 retention 上限 → 資料變更即將遺失、緊急擴消費端
• DLQ 持續累積 → 有系統性壞 record、查 Lambda 邏輯或上游資料
• Errors 尖峰但 IteratorAge 正常 → transient 失敗、retry 有在吸收

Scope warning：本文未引用 production case 的 stream metric 數字；上述指標與判讀屬 vendor 規格 + 通用事件處理觀測。

接回 4.20 Observability Evidence Package、9.5 瓶頸定位流程。

邊界與整合

Streams 跟 03 訊息佇列的責任切分

DynamoDB Streams 是 資料庫變更 的 CDC 通道、不是通用訊息佇列。兩者責任不同：

• Streams：源頭是 table 寫入、record 由 DynamoDB 自動產生、生命週期綁 table、retention 短
• 訊息佇列（SQS / SNS / Kafka）：源頭是 application 主動 publish、用於通用解耦、retention 與語意更彈性

典型組合：Streams 捕捉 table 變更 → Lambda 處理 → 需要扇出到多個獨立服務時、再 publish 到 SNS / EventBridge。當事件來源不是「資料庫變更」而是「業務事件」、直接用 03 訊息佇列模組 的 queue / topic、不要硬塞進 table 再用 stream。

Sibling 與 cross-link

• transactions-conditional-writes — transaction 寫入也觸發 stream、下游處理要冪等
• single-table-design-pattern — single-table 下不同 entity 共用 stream、下游用 type 欄位分流
• global-tables-conflict — Global Tables 跨 region 複製本身基於 stream 機制
• 替代路由：通用業務事件 / 多消費者扇出 / 長 retention → 03 訊息佇列模組
• 搜尋索引同步下游 → OpenSearch / Elasticsearch（DynamoDB 不適合做全文檢索）
• 跟 PayPay 9.C26 互引：訊息事件 message_id 天然冪等、適合 stream 下游處理

Case anchor 是 9.C21 ASOS（85,000 SKU、每週新增 5,000 件的高更新頻率 catalog、寫入後需要 search index / 推薦排序投影）。ASOS case 本身沒有揭露 Change Feed 的實作細節、本文只取它的 catalog 寫入投影壓力當情境 anchor、機制以 Azure vendor 規格與通用工程展開。

問題情境

典型觸發場景：catalog 寫入 Cosmos DB 後、下游還有一連串工作要做 — 把商品同步到 search index、刷新推薦排序、讓 cache 失效、發 event 給庫存服務。團隊一開始把這些工作塞進寫入 API 的同步路徑、寫一筆商品要等 search index 更新完才返回、寫入 latency 被下游拖垮；高峰時下游 search service 變慢、整條寫入鏈一起阻塞。

讀者徵兆：

• 「寫入 API latency 被下游投影工作拖高、想把它非同步化」
• 「下游 consumer 掛掉一段時間、重啟後要怎麼補回漏掉的變更」
• 「同一筆 document 在短時間內改三次、下游只需要最終狀態還是每次都要」
• 「要做 audit / 要知道刪除事件、但 Change Feed 預設讀不到 delete」

真實壓力：寫入路徑與下游處理耦合會讓寫入 SLA 受制於最不穩的 consumer；而把投影改成「掃全表」的 batch job 又有延遲與成本問題。Change Feed 提供的是 持久、可重讀、按 partition 有序 的變更來源、讓下游用 pull 或 trigger 模式按自己的進度消費。

核心機制：partition-scoped persistent change log

Change Feed 是 container 的內建能力、把每個 logical partition 內的寫入按發生順序記錄成一條持久序列。它的關鍵語義有幾個面向。

順序保證是 per logical partition、不是 container 全域。同一 partition key 內的變更嚴格有序、跨 partition 之間沒有全域順序 — 這跟 partition-key-design 的設計直接相關、consumer 必須假設不同 partition 的事件可能交錯到達。

進度由 continuation token 表達。consumer 讀到哪裡、用一個 continuation token 標記；下次帶 token 回來、從上次的位置繼續。token 是 per partition range 的、container 做 partition split 時 token 要能跟著 range 拆分 — 這是 change feed processor 幫忙處理的部分。

讀取是 pull-based 持久來源、不是 push 通知。Change Feed 不主動推、是 consumer 主動拉。Azure Functions 的 Cosmos DB trigger 看起來像 push、底層仍是 trigger runtime 持續 poll Change Feed。

兩種模式：latest-version vs all-versions-and-deletes

Change Feed 有兩種模式、語義差很大、選錯會在 audit / 補償場景出問題（模式名稱與可用性屬時間敏感、查 最新文件）。

Latest-version 模式（過去稱 incremental feed）只給每個 document 的 最新狀態。同一 document 在兩次消費之間改了三次、consumer 只會看到最後一個版本、中間版本看不到；delete 也看不到（document 消失、feed 裡沒有對應的 tombstone）。這個模式適合「我只要把最終狀態投影到下游」的場景 — search index 同步、cache 刷新、物化視圖更新。

All-versions-and-deletes 模式給 每一次 變更、包含中間版本與 delete / TTL 過期事件。同一 document 改三次、feed 給三筆；刪掉給一筆刪除事件。這個模式適合需要完整變更歷史的場景 — audit log、event sourcing、需要對 delete 做反應的跨 store 同步。代價是事件量更大、且這個模式對 retention 與 partition 行為有額外約束（時間敏感、查文件）。

選擇判準：問「我需要中間版本與刪除事件嗎」。投影類工作（只要最終狀態）用 latest-version；audit 與需要對刪除反應的同步用 all-versions-and-deletes。預設選 latest-version、只有明確需要歷史與 delete 時才升級。

change feed processor 的角色

直接讀 Change Feed 要自己管 partition range、lease、continuation token、failover — 這些 plumbing 用 change feed processor library 處理。它的核心元件是 lease container：一個獨立的 Cosmos DB container、記錄每個 partition range 由哪個 consumer instance 處理、處理到哪個 continuation token。多個 consumer instance 共用同一個 lease container 時、processor 自動把 partition range 分配到不同 instance、達成水平擴展與 failover。

操作流程

啟用與確認

Change Feed 對 SQL API container 是預設啟用的、不需要額外開關（latest-version 模式）。all-versions-and-deletes 模式需要在 container 層設定、且要設 retention window。

1# 確認 container 存在、Change Feed 自動可用（latest-version）
2az cosmosdb sql container show \
3  --account-name mycosmos --resource-group myrg \
4  --database-name catalog --name products \
5  --query "resource.id"

驗證：container 存在即可讀 latest-version feed。要用 all-versions-and-deletes、先確認 account / SDK 版本支援（時間敏感、查文件）並設好 retention。

change feed processor（C# SDK）

 1// lease container 獨立於 monitored container
 2Container monitored = client.GetContainer("catalog", "products");
 3Container leases = client.GetContainer("catalog", "leases");
 4
 5ChangeFeedProcessor processor = monitored
 6    .GetChangeFeedProcessorBuilder<Product>(
 7        processorName: "search-index-sync",
 8        onChangesDelegate: HandleChangesAsync)
 9    .WithInstanceName(Environment.MachineName)  // 每個 instance 唯一
10    .WithLeaseContainer(leases)
11    .Build();
12
13await processor.StartAsync();
14
15async Task HandleChangesAsync(
16    IReadOnlyCollection<Product> changes,
17    CancellationToken ct)
18{
19    foreach (var product in changes)
20    {
21        // 投影到 search index — 必須 idempotent
22        await searchIndex.UpsertAsync(product);
23    }
24    // delegate 正常返回 = processor 自動推進 lease 的 continuation token
25}

驗證：lease container 內會出現每個 partition range 的 lease document、ContinuationToken 欄位隨消費推進；多開一個 instance、觀察 lease 被重新分配到兩個 instance。失敗時 delegate 拋例外、processor 不推進該 range 的 token、下次重讀同一批（at-least-once、所以 handler 要 idempotent）。

Azure Functions trigger（消費端最省維運的形態）

 1[FunctionName("SyncSearchIndex")]
 2public static async Task Run(
 3    [CosmosDBTrigger(
 4        databaseName: "catalog",
 5        containerName: "products",
 6        Connection = "CosmosConnection",
 7        LeaseContainerName = "leases",
 8        CreateLeaseContainerIfNotExists = true)]
 9    IReadOnlyList<Product> changes,
10    ILogger log)
11{
12    foreach (var p in changes)
13        await searchIndex.UpsertAsync(p);  // idempotent
14}

Functions trigger 底層就是 change feed processor、lease 與 scale-out 由 Functions runtime 管。驗證：function 的 invocation count 隨寫入增加、Application Insights 看 changes batch size 與 lag。

Rollback boundary

Change Feed 是讀取側機制、停掉 consumer 不影響寫入。要重放：刪掉 lease container 的對應 lease（或建新 processor name）會從 container 起點或指定時間點重讀。重放前確認下游投影是 idempotent、否則重放會重複寫。

失敗模式

把 handler 寫成非 idempotent

Change Feed 是 at-least-once。consumer 在處理一批後、推進 token 前 crash、重啟會重讀同一批。handler 若是「append 一筆 audit row」這種非 idempotent 操作、重放會產生重複。徵兆是下游出現重複事件、且重複數對應 consumer 重啟次數。修法是讓投影用 upsert（以 document id + version 為 key）、audit 用 dedup key、發 event 帶 idempotency key 讓下游去重 — 對應 idempotency 的設計。

用 latest-version 模式卻期待看到 delete

team 用預設 latest-version feed 做跨 store 同步、上線後發現「source 刪掉的 document、target 還在」。latest-version 模式不發 delete 事件、刪除在 feed 裡是「該 document 不再出現」、consumer 無從得知。修法是 audit / 需要刪除反應的場景改 all-versions-and-deletes 模式；或在 application 層用 soft delete（寫一個 deleted: true 的版本、latest-version feed 就看得到這次寫入）。

lease container 配置不足成為瓶頸

lease container 自己也吃 RU、且 processor 對它有頻繁讀寫。lease container RU 配太低、processor 推進 token 被 throttle、表現成 Change Feed 消費 lag 升高、但 monitored container 看起來健康。徵兆是消費 lag 持續增長、診斷發現 429 來自 lease container 而非 source。修法是給 lease container 足夠 RU、把它跟 source container 的容量分開規劃、見 ru-cost-model-sizing。

假設 Change Feed 有跨 partition 全域順序

consumer 假設事件按全域時間到達、做了依賴順序的邏輯（例如「先建立帳號事件、後消費事件」）。Change Feed 只保證 per logical partition 有序、跨 partition 交錯。徵兆是偶發的「後續事件先到、依賴的前置事件後到」。修法是讓有順序依賴的 document 落在同一 partition key、或在 consumer 端用業務 timestamp / version 做排序與 buffer、不依賴 feed 到達順序。

Anti-recommendation：不是所有「寫入後工作」都要 Change Feed

寫入後若只是同一 request 內、同一 partition 的小量同步工作、直接在 application 寫入路徑處理、或用 stored procedure 在 partition 內做（見 stored-procedure-trigger）更簡單。Change Feed 的價值在 解耦下游、可重放、水平擴展 — 當下游處理慢、會失敗、需要重放、或要被多個獨立 consumer 各自消費時才成立。下游工作輕、不需要重放、強耦合在寫入語義內時、引入 Change Feed + lease container 是多一層維運成本。

容量與觀測

• 必看 metric：Change Feed 消費 lag（最新寫入時間 vs consumer 已處理位置）、processor 每批 changes 數量、lease container 的 NormalizedRUConsumption
• consumer 端 throughput 受 partition range 數限制 — 並行度上限約等於 physical partition 數；range 不夠多時加 consumer instance 不會更快
• 成本：Change Feed 讀取本身吃 RU、all-versions-and-deletes 模式事件量更大、lease container 額外 RU — 三項都進容量公式、見 ru-cost-model-sizing
• 回 9.6 容量規劃模型：把 Change Feed consumer 當獨立 throughput 單位、不要跟 OLTP 寫入共用同一個 RU budget 估算
• Alert：消費 lag 持續增長（consumer 跟不上寫入）、lease container 429、handler 例外率上升

邊界與整合

• Sibling deep articles：stored-procedure-trigger（partition 內同步邏輯 vs Change Feed 的非同步解耦）、synapse-link-federation（分析 workload 用 analytical store、不要用 Change Feed 自己搭 analytics pipeline）、partition-key-design（per-partition 順序的來源）、ru-cost-model-sizing（Change Feed + lease container 的 RU 成本）
• 跟 DynamoDB Streams 對照：兩者都是 partition-ordered 變更 log + at-least-once consumer。差異在 DynamoDB Streams 有固定 24 小時 retention、原生發 INSERT / MODIFY / REMOVE（含 delete）；Cosmos DB latest-version 模式預設不發 delete、要 all-versions-and-deletes 模式才有完整事件與 delete。從 DynamoDB Streams 思維過來的 team 容易假設「delete 一定看得到」、要先確認模式。對照 DynamoDB vendor
• Knowledge card：Change Data Capture / idempotency
• 回 overview：Cosmos DB vendor overview 的「忽略 Change Feed」常見陷阱

相關連結

• Cosmos DB vendor overview — 本文是該頁尾 Change Feed backlog 的深度展開
• 9.C21 ASOS case — 高更新頻率 catalog 投影壓力的情境 anchor
• stored-procedure-trigger — partition 內同步邏輯的對照
• partition-key-design — per-partition 順序的設計來源
• DynamoDB vendor — DynamoDB Streams 對照
• Change Data Capture 卡片 / Idempotency 卡片 — 概念基底
• 官方：Change feed in Azure Cosmos DB / Change feed processor

本文的判讀錨點是：plugin 選型是 CDC contract 決策。它影響 schema evolution、事件欄位、delete 表示、transaction boundary、consumer compatibility、slot lag 與故障復原。

Plugin Boundary

Plugin boundary 的核心責任是定義 database 變更如何離開 PostgreSQL。常見選項包含內建 pgoutput、測試用 test_decoding、JSON-oriented plugin，以及 Debezium connector 支援的 plugin / protocol。

pgoutput 適合標準化 CDC。它與 publication / subscription model 對齊，能保留 PostgreSQL logical replication 的主路線。

test_decoding 適合教學與排錯。它讓人看到 transaction 裡發生的 insert / update / delete，但它的定位是測試與理解，不應作為正式 event contract。

Replication Slot Responsibility

Replication slot responsibility 的核心責任是保護 consumer 進度，同時管理 WAL retention。Logical slot 會讓 PostgreSQL 保留尚未被 consumer 確認的 WAL；consumer 停住時，slot lag 會轉成 disk pressure。

Slot 是 production resource。每個 logical slot 都要有 owner、consumer、SLO、drop condition、backfill plan 與 alert。

Event Contract

Event contract 的核心責任是讓 downstream 知道每個變更代表什麼。CDC 事件至少要說明 key、before/after image、operation、commit timestamp、transaction ordering、schema version 與 delete representation。

Replica identity 是 CDC 的核心設定。沒有穩定 key 的 table 會讓 update / delete event 難以被 downstream 正確套用；這類 table 要先補 primary key 或明確設定 replica identity。

Connector Patterns

Connector patterns 的核心責任是把 plugin output 接到實際 pipeline。Debezium、custom consumer、DB native subscription 的維運責任不同。

Connector 要定義 backfill 與 streaming 的接點。最常見的事故是 snapshot 還沒完成就開始消費、或 cutover LSN 沒有被記錄，導致 downstream 重複或漏資料。

Failure Modes

Failure modes 的核心責任是把 CDC 事故分成 database、connector、schema 與 downstream 四層。

Slot lag 是最高優先訊號，因為它會占用 PostgreSQL WAL storage。Runbook 要有「何時暫停 producer」、「何時 drop slot」、「如何重建 snapshot」的明確門檻。

Selection Checklist

Selection checklist 的核心責任是讓 plugin 選型可審查。

1. Downstream 需要 DB-to-DB replication、JSON event、Protobuf event 還是 connector-managed event。
2. 每張 table 是否有 stable key 與 replica identity。
3. Initial snapshot 如何銜接 streaming。
4. Schema evolution 如何通知 consumer。
5. Slot lag、connector lag、sink lag 如何告警。
6. Consumer 是否 idempotent。
7. Disaster recovery 後 slot / offset 如何重建。

完成這份 checklist 後，再決定 plugin 與 connector。CDC 的成功標準是 downstream 能長期維持正確資料，而不只是成功建立 slot。

下一步路由

Logical decoding plugins 完成後，實作 CDC pipeline 讀 Logical Replication / Debezium；slot 維運讀 Replication Slot Management；跨資料庫搬遷讀 Database Migration Playbook。