待寫章節

• event.schema.json 完整欄位解說
• 欄位設計原則（source 標明來源 / data 自由欄位 / v 版本演進）
• Schema 版本演進策略（backward compatible 的增量變更）
• 跟 OpenTelemetry 的 schema 差異對照

跨分類引用

• SOT repo：tarrragon/monitor 的 schema/event.schema.json
• ← testing 模組二：log 點設計產出的事件需符合本 schema
• → monitoring 模組七 資安：schema 中哪些欄位需要 redaction

本章是 01 模組的基礎章節之一、結合 1.3 transaction boundary（交易範圍）、1.7 schema migration rollout evidence（演進證據）與 1.10 KV / Document 容量規劃（partition key 設計）一起讀。讀完後能回答：table 怎麼切、index 怎麼選、什麼時候 denormalize、partition 怎麼設、命名怎麼治理。

先定義狀態責任

資料模型第一步是定義狀態責任：哪些欄位代表正式狀態、哪些欄位是派生值、哪些欄位只為追蹤與審計。這個分層會直接決定 table 邊界與 relation 方向。

在訂單服務中、訂單主檔、付款狀態、庫存扣減屬於正式狀態；展示排序欄位、快取摘要屬於派生值；版本號、更新時間與來源欄位屬於可追蹤證據。把三類混在同一模型裡、後續查詢與演進成本會持續上升。

詳見 1.8 State Ownership 與 Query Boundary。

Table 與 Relation

table 切分要對齊業務聚合邊界。聚合內需要交易一致性的欄位、放在同一交易可控範圍；跨聚合流程透過事件或引用關係接續。relation 的責任是表達資料約束、不是替代流程編排。

主鍵策略要先回答「如何穩定識別」與「如何支援查詢」。自然鍵可讀性高但變動風險高；代理鍵穩定且易擴展、常搭配業務唯一鍵一起使用。外鍵策略則要平衡完整性與演進自由度：正式核心域可強約束、跨域整合可由應用層保護並保留遷移彈性。

主鍵選擇實務：

ID 設計不只是「選個格式」，而是在五個維度做取捨。先理解取捨、再按場景選型。

ID 設計的五個取捨維度

ID 類型選型矩陣

選型決策流程

1需要跨機器唯一？
2  └─ 否 → Bigint sequence（最簡單、效能最好）
3  └─ 是 → ID 對外部可見？
4           └─ 是 → 隱私敏感？
5                    └─ 是 → UUID v4（不可預測）
6                    └─ 否 → UUID v7（有序、DB 友好）
7           └─ 否 → 空間敏感（8 byte vs 16 byte）？
8                    └─ 是 → Snowflake（需要 machine_id 協調）
9                    └─ 否 → UUID v7（簡單、標準）

有序 ID 的 DB 效能影響

B-tree 索引的插入效能和 key 的分布有直接關係。UUID v4 的隨機分布導致每次插入都可能落在 B-tree 的不同 leaf page，造成大量隨機 I/O（page split、cache miss）。UUID v7 的時間戳前綴讓插入集中在 B-tree 的尾端，接近 sequential insert。

上表數字是基於 NVMe SSD 環境的量級估算（源自 UUID v4 的 random page split 成本約為 sequential 的 1/3-1/4 這個 B-tree 特性推導），實際效能依硬體和 workload 而定。核心結論：UUID v7 的插入效能約為 v4 的 3 倍，接近 bigint sequential。

隱私考量：v4 vs v7

UUID v7 的前 48 bit 是 Unix 時間戳（毫秒精度）。攻擊者拿到 UUID v7 可以推算「這個 ID 在幾點幾分產生」。這在不同場景有不同風險：

經驗法則：對外暴露給不可信第三方的 ID 用 v4（不可預測），內部 ID 用 v7（有序、效能好）。

各語言的標準庫支援

Go 的 google/uuid v1.6+ 內建 uuid.NewV7()，效能約 350ns/op（含 crypto/rand），和 JSON 解析（5-10μs）、DB 寫入（200μs）相比不是瓶頸。

對應 KV 案例：9.C5 Amazon Ads partition key、9.C15 Tixcraft composite key 都是主鍵策略的延伸。

Index 設計

index 設計要從查詢路徑反推、不是從欄位列表前推。每個高頻查詢至少要回答三件事：過濾條件是什麼、排序規則是什麼、回傳範圍有多大。這三件事能否由索引覆蓋、決定了 latency 與成本。

Index 類型對照：

常見設計原則：

1. 先保護交易關鍵查詢、再處理報表與後台查詢
2. 複合索引依查詢過濾與排序順序排列、避免僅憑欄位熱門度排列
3. 大表變更前先評估索引建立成本與回退方案、避免在高峰時段同步放大風險
4. 定期 review 未用 index（PostgreSQL pg_stat_user_indexes、MySQL sys.schema_unused_indexes）— 寫入吞吐被舊 index 拖垮
5. partial index 對 boolean / status column 特別有用 — 只 index 「pending」「failed」等小集合

Index 反模式：

• 每個欄位都建 index：寫入吞吐被拖垮
• 不看 EXPLAIN 就建 index：可能跟 query planner 不對齊
• 用 OR 條件依賴單一 index：query planner 不一定能用
• 大表 ALTER INDEX 不分批：lock 整個表

Denormalization 模式

normalize 是 SQL 的預設、但 denormalize 有時是更好的工程選擇。

Precomputed aggregate：

• 把 COUNT / SUM 結果存在 parent row 而非每次 query 算
• 例：posts.comment_count 存實際值、不每次 SELECT COUNT
• 風險：consistency（comment 寫入後 count 沒更新）
• 對策：用 trigger 或應用層 transaction 確保同步、或定期 reconcile

Embedded one-to-many：

• 小量 1-many 關係可以 embed 成 JSONB / nested column
• 例：order.line_items JSON column、不另建 line_items table
• 風險：個別 line item 查詢不便
• 適合：line items 通常一起讀寫（同 transaction boundary）

Materialized view：

• 預計算 query 結果、定期 refresh
• 適合：複雜 JOIN / aggregation 重複跑
• 風險：refresh window 內看到舊資料

Read model（CQRS）：

• 寫入路徑跟讀取路徑用不同 schema
• 寫入 normalize、讀取 denormalize 成不同 read model
• 詳見 1.8 State Ownership

對應案例：

• 9.C27 Disney+ watch list — denormalize 用戶 metadata、跨裝置查詢方便
• 9.C5 Amazon Ads — DynamoDB single-table design 是極端 denormalization

Partition 策略

單表 > 1 TB 時、partition 是必要的維運手段。partition 不是「擴 storage」、是「讓 vacuum / index / DROP 可分批跑」。

Partition 類型：

• Range partition：按 timestamp / id 範圍切。orders_2024_q1, orders_2024_q2…
• List partition：按枚舉值切。orders_us, orders_eu…
• Hash partition：按 hash 均勻切。適合無自然切分維度的大表

Partition 設計要點：

1. partition key 必須出現在 多數 query 的 WHERE clause（partition pruning 才能生效）
2. partition 數量 適中（10-100）— 太少 partition 太大、太多 partition metadata 開銷大
3. 老 partition 可以 DROP 或 archive、儲存成本可控
4. cross-partition unique constraint 限制 — 唯一鍵必須含 partition key

對應案例：

• 9.C4 DraftKings — 200 個獨立 Aurora cluster 是極端 partition by business
• 9.C5 Amazon Ads — DynamoDB 透明 partition、應用層不必管

Schema Evolution 友好設計

schema 從 day 1 就要為演進設計、不能假設「以後不會改」。

避免 breaking changes：

• 加欄位：safe（nullable 或 default）
• 刪欄位：unsafe（先讓所有 code 不再讀 → 部署 → 再刪）
• 改欄位類型：unsafe（先加新欄位、雙寫、backfill、移除舊欄位）
• 改欄位名：unsafe（同上）
• 加 NOT NULL constraint：unsafe（先 backfill default、再加 constraint）

Evolution-friendly schema 原則：

1. 欄位 nullable by default：除非業務不允許 null、否則先 nullable、之後再 tighten
2. 避免大表 ALTER TABLE：用 Expand / Contract 模式
3. predict breaking changes：訂版本、跟 application code 同步演進
4. schema version column：每 row 帶 version、應用層按版本處理
5. migration 工具版本控：Flyway / Liquibase / Atlas / golang-migrate 必須有

詳見 1.6 Database Migration Playbook 跟 1.7 Schema Migration Rollout Evidence。

Naming 與一致性

命名規則的責任是維持跨版本可讀性。table、column、index 的命名若沒有一致語意、migration 與故障排查會持續變慢。穩定做法是把命名和業務語意對齊、並保留可辨識版本與作用域。

Naming 慣例：

• Table：複數名詞、snake_case（orders, payment_methods）
• Column：snake_case、明確語意（created_at 不是 ts）
• Foreign key：{referenced_table}_id（user_id 指 users.id）
• Boolean：is_* / has_* / can_*（is_active, has_subscription）
• Timestamp：*_at for events（created_at, paid_at）、*_on for dates（born_on）
• Index：idx_{table}_{cols}（idx_orders_user_id_created_at）
• Unique constraint：uq_{table}_{cols}
• Foreign key constraint：fk_{table}_{ref}

避免的反模式：

• 縮寫不一致（u_id vs user_id）
• 隱性意義（status 是 enum、值在哪裡？）
• 跨表同義不同名（user.name vs customer.full_name）
• 反向命名（name_first vs 業界 first_name）

schema 演進時、命名與結構要一起考慮。欄位重命名、拆欄位、合併欄位都應配合 Expand / Contract 與 schema migration 策略、讓新舊版本在過渡期可共存。

判讀訊號

常見誤區

把 schema 設計等同於「先能寫入就好」、會把結構債延後到流量成長與事故時一次爆發。資料模型的工程價值在於可演進性、不在於初版欄位數量最少。

把索引當成效能補丁、忽略查詢模型與資料責任、也會讓後續維護成本持續疊加。索引與查詢要一起設計、才能在演進中保持穩定。

把 normalize 當成 絕對守則、忽略 denormalize 的工程效益。1NF / 2NF / 3NF 是理論起點、不是 production 必須。

案例對照

案例回寫

資料建模議題可以用 GitHub 2018 Oct21 MySQL Topology Incident 做回寫練習。讀這個事件時、先看跨區拓樸切換如何影響資料一致性、再回到本章檢查三件事：聚合邊界是否清晰、交易查詢與對帳查詢是否分層、修復時是否有可追蹤欄位與對帳鍵。

這個案例主要支撐的是「查詢與資料模型邊界」判讀、不直接支撐 transaction retry 或 queue replay 調校；若問題是重試放大、應轉到 1.3 或 3.x 章節處理。

當事件呈現長時間人工比對或查詢語意漂移時、先修正本章的 query boundary 與 naming 一致性、再補 1.6 資料庫轉換實作 的驗證與回退路徑。

跨模組路由

schema 設計會直接影響後續可靠性與事故處理。

1. 與 1.3 的交接：交易一致性邊界落在 transaction boundary。
2. 與 1.6 的交接：演進策略落在 資料庫轉換實作。
3. 與 1.7 的交接：欄位責任進入 production rollout 時、讀 Schema Migration Rollout 證據實作示範。
4. 與 1.8 的交接：state ownership 跟 query boundary 設計落在 State Ownership。
5. 與 1.10 的交接：KV / Document 的 partition key 設計落在 KV / Document 容量規劃。
6. 與 4.20 的交接：查詢與資料驗證證據進入 Observability Evidence Package。
7. 與 6.11 的交接：高風險 schema 變更進入 Migration Safety。
8. 與 8.19 的交接：資料修復與回退決策記錄進入 Incident Decision Log。

下一步路由

• 平行：1.3 Transaction Boundary、1.8 State Ownership
• 下游：1.6 Database Migration Playbook / 1.7 Schema Migration Rollout Evidence / 1.10 KV / Document 容量規劃
• Vendor：PostgreSQL index 設計、MySQL InnoDB clustered index、DynamoDB single-table design
• DynamoDB schema 深入：single-table design / partition key 反模式 / GSI / LSI 設計
• MongoDB schema 深入：schema design pattern / shard key 選型
• Cosmos DB schema 深入：partition key 設計

本文是 Google Cloud Pub/Sub overview 的 implementation-layer deep article。Overview 回答「Pub/Sub 該不該選、跟 Kafka / SQS 差在哪」；本文回答「ordering key 怎麼設、DLT 怎麼擋 poison message、schema 怎麼守契約，各自踩哪些坑」。閱讀前可先讀 overview 的 ordering / DLT / schema 各段建立 context。

文中 gcloud 指令的語法以 Pub/Sub emulator 實機驗證（topic / subscription / schema / ordering key / DLT / push 各操作均跑通），標準版的雲端配額、IAM 與計費行為依官方文件。

三道治理共用同一個交付骨架

Pub/Sub 的 ordering key、dead-letter topic、schema enforcement 看似三個獨立功能，實際都掛在同一個交付骨架上：subscription 是消費進度的 first-class 抽象、訊息經 ackDeadline 控制重投、失敗訊息經投遞次數計數決定去留。理解這個骨架之後，三道治理只是骨架上的三個切面 — ordering 切的是「投遞順序」、DLT 切的是「投遞次數上限」、schema 切的是「投遞前的內容守門」。

這條骨架跟 Kafka 思路不同。Kafka 的消費進度綁在 consumer group + partition offset；Pub/Sub 的 topic 是 first-class，subscription 才是 consumer 抽象，一個 topic 可以掛 N 個 subscription、各自有獨立進度與獨立的 ackDeadline / DLT / ordering 設定。同一份 event 流，A subscription 可以開 ordering 嚴格有序、B subscription 可以不開 ordering 換吞吐，互不影響。

把這三道治理寫進一篇的理由是：它們在 production 會互相牽制。Ordering key 開了之後 DLT 的隔離行為會變（有序流裡一則 poison message 會卡住整把 key 的後續訊息）；schema enforcement 擋下的不相容 publish 不會進 DLT（根本沒進 topic）。分開讀三個官方頁面看不到這層耦合。

subscription 是 first-class：ackDeadline 與 extension

subscription 承擔「這個消費者讀到哪、還有多少沒 ack」的責任。每則訊息投遞給 subscriber 後，Pub/Sub 啟動一個 ackDeadline 倒數；倒數內收到 ack 就移除訊息、倒數結束沒收到 ack 就重投。預設 ackDeadline 是 10 秒、上限 600 秒。

 1# subscription 的 ackDeadline 預設 10 秒、retention 預設 7 天
 2gcloud pubsub subscriptions describe demo-sub
 3# ackDeadlineSeconds: 10
 4# messageRetentionDuration: 604800s   # 7 天
 5
 6# 建 subscription 時可顯式設更長的 ackDeadline 與更短的 retention
 7gcloud pubsub subscriptions create cfg-sub \
 8  --topic=demo-topic \
 9  --ack-deadline=120 \
10  --message-retention-duration=3d
11# ackDeadlineSeconds: 120
12# messageRetentionDuration: 259200s   # 3 天

ackDeadline 是一道「處理時間預算」。設太短，處理還沒完訊息就被重投，consumer 會收到重複；設太長，consumer crash 後訊息要等滿 deadline 才重投，延遲拉高。長任務不靠把 ackDeadline 一次設到 600 秒解決，而是靠 ack deadline extension：consumer 在處理中週期性發 modifyAckDeadline 把單則訊息的 deadline 往後延，處理完才 ack。

1# pull 一則但不 auto-ack，拿到 ackId
2ACKID=$(gcloud pubsub subscriptions pull demo-sub --limit=1 --format='value(ackId)')
3
4# 處理中動態延長這則訊息的 ackDeadline 到 300 秒
5gcloud pubsub subscriptions modify-message-ack-deadline demo-sub \
6  --ack-ids="$ACKID" \
7  --ack-deadline=300

實務上不手動發 modifyAckDeadline，而是用 client library 的自動 lease 管理：client 在背景對 outstanding 訊息週期性續約，直到 application code 回 ack / nack。這跟 SQS 的 visibility timeout 語意類似 — 都是「訊息正在被處理、暫時別重投」的租約 — 但 Pub/Sub 是 per-message lease + client 自動續約，SQS 是 per-receive visibility window + 手動 ChangeMessageVisibility。

ackDeadline 的陷阱在 batch 邊界。client library 常以 batch 為單位 pull，但 ackDeadline lease 是 per-message。若 application 把整個 batch 當一個工作單元處理、處理時間超過單則 ackDeadline 且 client 未對每則續約，未 ack 的訊息會被重投。Mercari 的 actionable history pipeline 揭露的正是這個 client library 行為：ack deadline 以整批 batch 為粒度運作，同批只要有一則過期或被 nack，已 ack 的訊息會跟著一起重投（3.C63）。

Push、Pull、Streaming Pull 與 flow control

subscription 有兩種交付方向，pull 之下又分 unary pull 與 streaming pull。三者對應不同的下游承壓能力。

Push 把投遞節奏交給 Pub/Sub：endpoint 回 2xx 視為 ack、回非 2xx 或逾時視為 nack 並 backoff 重投。Pull 把節奏交給 consumer：consumer 想拉才拉、拉多少自己定。Streaming pull 是 production 高吞吐場景的主力 — client library 預設用它，因為它能在單一長連線上做精細的 flow control。

flow control 是 pull 的核心優勢：consumer 用 max_outstanding_messages 與 max_outstanding_bytes 設定「同時最多持有多少未 ack 訊息」，超過上限 client 就暫停從連線拉取，等 application ack 釋放額度才繼續。這讓 consumer 能把消費速率對齊到下游能吃的速率，而不是被 broker 灌爆。

Push vs pull 不是實作偏好，是「下游能否接受 push 衝擊」的判讀。Mercari 把外部行銷 webhook（Braze）轉成 Pub/Sub event 後，下游 worker 刻意用 pull subscription 精確控制每秒處理訊息數，因為下游要呼叫的外部 LINE API 有 RPS 限制 — push 會把瞬間流量直接打到受限的外部 API（3.C65）。下游有硬性 RPS 上限時，pull + flow control 是讓消費速率可控的手段。

Ordering Key：有序的代價是吞吐

Ordering key 讓「帶同一個 ordering key 的訊息，在 subscription 端按 publish 順序投遞」。它把全域無序的 Pub/Sub 變成 per-key 有序 — 不同 key 之間仍可並行、亂序，只有同 key 內部保證順序。要生效需要兩端配合：subscription 建立時開 --enable-message-ordering，publish 時帶 --ordering-key。

1# subscription 端開啟 ordering
2gcloud pubsub subscriptions create ord-sub \
3  --topic=ord-topic \
4  --enable-message-ordering
5# describe 可見 enableMessageOrdering: true
6
7# publish 端帶 ordering key（同一 key 的訊息會保序）
8gcloud pubsub topics publish ord-topic --message=m1 --ordering-key=user-123
9gcloud pubsub topics publish ord-topic --message=m2 --ordering-key=user-123

Ordering key 的設計責任在於選對 key 的粒度。粒度太粗（例如所有訊息共用一個 key）會把整條 topic 退化成單線序列、吞吐崩塌；粒度太細（例如每則訊息一個 key）等於沒開 ordering。正確做法是按「需要保序的業務實體」選 key — 同一個 user-123 的事件要保序、不同 user 之間不需要 — 這樣並行度等於活躍 key 數，既保序又不犧牲整體吞吐。

跟 Kafka 對照能看清取捨。Kafka 用 partition + 同 key hash 到同 partition 達成保序，partition 數是固定預先規劃的並行上限；Pub/Sub 沒有顯式 partition，ordering key 的並行度是動態的、由活躍 key 數決定。代價是 Pub/Sub 的有序投遞要求同 key 訊息送到同一個內部處理單元，這個約束讓單一 ordering key 的吞吐有上限（官方標稱單 ordering key 約 1 MB/s）。

Ordering 跟 DLT 在 production 會耦合：有序流裡若一則訊息反覆失敗、Pub/Sub 為維持順序不會跳過它去投後面的訊息，整把 key 的後續訊息全卡住，直到該訊息 ack 或送進 DLT。沒開 ordering 時 poison message 只卡自己；開了 ordering 後它卡住整條 key 序列。這是下一節 DLT 要解的問題在 ordering 場景下被放大的原因。

Dead-Letter Topic：投遞次數上限決定隔離時機

Dead-letter topic 是 poison-message quarantine 在 Pub/Sub 的實作：subscription 對每則訊息計數投遞次數，超過 max-delivery-attempts 就把訊息轉發到另一個 topic（DLT），主 subscription 不再重投它，後續正常訊息得以前進。

 1gcloud pubsub topics create main-topic
 2gcloud pubsub topics create dl-topic
 3
 4gcloud pubsub subscriptions create main-sub \
 5  --topic=main-topic \
 6  --dead-letter-topic=dl-topic \
 7  --max-delivery-attempts=5
 8# deadLetterPolicy:
 9#   deadLetterTopic: projects/<proj>/topics/dl-topic
10#   maxDeliveryAttempts: 5

DLT 是 topic 不是 queue，這是 Pub/Sub 跟 SQS DLQ 的關鍵差異。SQS 的 DLQ 是另一個 queue、消費者直接 receive；Pub/Sub 的 DLT 是 topic，要再掛一個 subscription 才能讀。好處是 DLT 上可以同時掛多個 subscription — 一個給人工檢視、一個給自動 replay、一個給長期歸檔 — fan-out 內建。代價是多一層 subscription 配置，且 DLT 也有自己的 retention（同樣預設 7 天，poison message 要在這之內處理掉）。

max-delivery-attempts 設定的是「容忍多少次暫時性失敗」與「多快放棄」之間的平衡。設太低（例如 1-2 次），下游短暫抖動就把訊息丟進 DLT、誤殺可恢復的訊息；設太高（例如 50 次），一則真正壞掉的訊息會反覆重試半天、占用 consumer 資源、在有序流裡還會長時間卡住整條 key。官方允許範圍 5-100，常見起點是 5。

搭配 retry policy 的 backoff 能讓重投不至於太密集：

1gcloud pubsub subscriptions create retry-sub \
2  --topic=main-topic \
3  --min-retry-delay=10s \
4  --max-retry-delay=600s
5# retryPolicy:
6#   minimumBackoff: 10s
7#   maximumBackoff: 600s

啟用 DLT 需要把 Pub/Sub service account 授權對主 subscription 有 subscriber、對 DLT 有 publisher（emulator 不校驗 IAM，正式環境若漏授權，訊息超過 max attempts 後不會進 DLT、而是繼續留在主 subscription 重投，看起來像 DLT 沒生效）。授權細節依 GCP 官方 IAM 文件。

Mercari 的商品 feed 同步示範了 DLT 的標準用法：pull subscription + 自家 batch requester、成功 ack 整批、失敗 nack 讓 Pub/Sub 重送、重試多次仍失敗送 DLT、後續訊息優先處理；同一個 topic 還兼當突發流量的 load-leveling buffer（3.C64）。

Schema Enforcement：投遞前的契約守門

Schema enforcement 把 event schema compatibility 從「應用層約定」提升到「broker 強制」。topic 綁定一個 Avro 或 Protobuf schema 後，不符 schema 的 publish 在進 topic 前就被拒絕 — 訊息根本不會被儲存、不會投遞、不會進 DLT。

1# 1. 建 schema（Avro，一個必填 string 欄位 id）
2gcloud pubsub schemas create order-schema \
3  --type=avro \
4  --definition='{"type":"record","name":"Order","fields":[{"name":"id","type":"string"}]}'
5
6# 2. topic 綁 schema + 指定 message encoding
7gcloud pubsub topics create sch-topic \
8  --schema=order-schema \
9  --message-encoding=json

綁定後的 publish 行為（emulator 實機驗證 enforce）：

 1# 符合 schema：通過
 2gcloud pubsub topics publish sch-topic --message='{"id":"abc"}'
 3# messageIds: ['4']
 4
 5# 欄位不符 schema：被拒
 6gcloud pubsub topics publish sch-topic --message='{"wrong":123}'
 7# ERROR: INVALID_ARGUMENT: Could not parse message
 8
 9# 非 JSON 垃圾：被拒
10gcloud pubsub topics publish sch-topic --message='not-json'
11# ERROR: INVALID_ARGUMENT: Could not parse message

schema 守門的價值在於把契約破壞擋在 producer 端、而不是 consumer 端。沒有 schema enforcement 時，producer 改了 payload 結構、不相容的訊息照樣進 topic、要到 consumer 解析失敗才爆 — 此時訊息已經在系統裡流動、可能已 fan-out 到多個 subscription、修復成本高。有 schema enforcement 時，不相容的 publish 在源頭就失敗，問題暴露在「誰送了壞訊息」而不是「誰收到壞訊息」。

schema evolution 要在「擋住破壞性改版」與「不阻塞合理演進」之間取捨。新增可選欄位或帶預設值的欄位維持相容、可以平滑演進；新增必填欄位、刪欄位、改型別是破壞性改版，會讓既有 producer 或 consumer 失效。設計上先定相容性等級（backward / forward / full）再演進，刪欄位分兩步（先停用再移除），避免一次破壞性改版打掛下游。

跟 Kafka Schema Registry 對照：Kafka 的 schema 校驗在 client 端（producer / consumer 各自向 Registry 查 schema、序列化時校驗），broker 本身不認識 schema；Pub/Sub 的 schema 綁在 topic、校驗在 broker 端 publish 路徑上。前者校驗點分散、靈活但要求所有 client 守規矩；後者校驗點集中在 broker、強制但耦合到 topic 配置。

五個 Production 故障演練

deep article 的差異化價值在故障演練。以下五個徵兆對應前述三道治理在 production 的典型失效。

演練一：Ordering key 把吞吐限到單線

徵兆：開了 ordering 後整條 topic 的吞吐從數萬 msg/s 掉到數百 msg/s，subscription backlog（num_undelivered_messages）持續攀升、oldest_unacked_message_age 越拉越長，但 consumer CPU 並不滿載 — consumer 在等訊息、不是在忙。

根因：ordering key 粒度太粗。最常見是「所有訊息共用同一個 ordering key」（例如固定字串、或單一租戶 ID），整條 topic 退化成單一有序序列，並行度等於 1。單一 ordering key 的吞吐有上限（官方標稱約 1 MB/s），所有訊息擠進一個 key 就被這個上限封頂。

判讀與修法：

1. 確認 ordering key 的基數（cardinality）。gcloud pubsub topics publish 帶的 --ordering-key 在 production 是業務欄位映射來的 — 檢查映射邏輯是否塌縮成低基數。
2. 把 key 粒度對齊到「真正需要保序的業務實體」：同一筆訂單 / 同一個 user / 同一個 device 內要保序，跨實體不需要。粒度從「全域一個 key」改成「per-user 一個 key」，並行度從 1 拉到活躍 user 數。
3. 評估是否真的需要 ordering。多數 pipeline 靠 consumer 端 idempotency + 版本號就能容忍亂序，不需要 broker 層保序 — 把保序成本從吞吐換成 consumer 設計（見 3.7 event contract 的 idempotency key 段）。

演練二：Ack deadline 太短導致重複投遞

徵兆：consumer 處理邏輯正確、下游也成功，但同一則訊息被處理多次；DELIVERY_ATTEMPT 計數異常偏高、下游出現重複副作用（重複扣款 / 重複發信）。Backlog 不一定高，但「處理量」遠大於「publish 量」。

根因：ackDeadline 比實際處理時間短。預設 10 秒對「呼叫一個慢的外部 API」「處理大 payload」這類任務不夠，訊息在 application 還沒 ack 前就過了 deadline、被 Pub/Sub 重投，於是同一則訊息有多個 consumer 副本在跑。若 client library 的自動 lease extension 沒生效（例如 application 阻塞在同步呼叫、background lease thread 餓死），重投更嚴重。

判讀與修法：

1. 量測 p99 處理時間，把 ackDeadline 設到 p99 之上留 buffer，但不要不加判斷地設到 600 秒上限 — deadline 越長，consumer crash 後訊息重投的延遲越長。
2. 長任務靠 lease extension 而非長 ackDeadline：確認 client library 的自動續約有在跑，application code 不要在處理迴圈裡阻塞到讓 background 續約 thread 餓死。
3. consumer 端做 idempotency：用 message 的 dedup key（3.7）讓重複投遞變成無害 — at-least-once 交付下重複是常態，不靠調 ackDeadline 消除、靠 consumer 設計吸收。

演練三：DLT max delivery attempts 設定誤判

徵兆：兩種反向徵兆。其一，DLT 堆滿了「其實能恢復」的訊息 — 下游一抖動就被丟進 DLT，DLT backlog 暴增、人工 replay 不完。其二，主 subscription 卡著一則壞訊息反覆重投半天都不進 DLT、後面訊息（尤其在 ordering 流裡）全堵住。

根因：第一種是 max-delivery-attempts 設太低（1-2 次），暫時性失敗就被當成 poison。第二種是設太高（數十次）或根本沒設 DLT，真正的 poison message 反覆重試、占資源、卡序列。

判讀與修法：

1. 區分「暫時性失敗」與「結構性失敗」。暫時性（下游超時、限流）需要重試容忍度，結構性（payload 解析不了、業務規則永久拒絕）越早隔離越好。
2. max-delivery-attempts 起點設 5，搭配 retry policy backoff（--min-retry-delay / --max-retry-delay）讓重試之間有間隔、給下游恢復時間，而不是密集重打。
3. 確認 DLT 真的接得到訊息：檢查 Pub/Sub service account 對 DLT 的 publisher 授權（漏授權會讓訊息超過 attempts 後繼續留在主 subscription、看起來像沒進 DLT）。
4. DLT 要掛 subscription 才讀得到 — DLT 是 topic 不是 queue，建完 DLT 還要建 DLT 的 subscription 並設好 retention，否則 poison message 在 DLT 裡放滿 7 天後一樣丟失。

演練四：Push endpoint 500 觸發 retry storm

徵兆：push subscription 的下游 HTTP endpoint 開始大量回 500，Pub/Sub backoff 重投、但 endpoint 仍 500，重投量隨 backlog 累積越滾越大；endpoint 一旦短暫恢復就被積壓的重投流量瞬間打回 500，形成「恢復即再掛」的震盪。

根因：push 的 flow control 由 Pub/Sub 掌握、按 ack 動態調速 — endpoint 回 2xx 視為 ack、非 2xx 視為 nack 並重投。當 endpoint 因下游依賴（DB / 外部 API）掛掉而持續 500，Pub/Sub 的 backoff 重投跟累積的 backlog 疊加，恢復瞬間的流量遠超 endpoint 平時負載。這正是「下游能否接受 push 衝擊」的反面 — push 沒有 consumer 端的 flow control 閥門。

判讀與修法：

1. 先判訊息毒性 vs endpoint 健康。若是 endpoint 整體掛（所有訊息都 500），是容量 / 依賴問題；若是特定訊息 500（多數成功、少數失敗），是 poison message，該走 DLT。
2. endpoint 整體掛的場景，push 不是好選擇 — 改 pull + flow control，讓 consumer 用 max_outstanding_messages 把消費速率對齊到下游能吃的速率，避免恢復瞬間被積壓流量打垮（對照 3.C65 的下游 RPS 限制場景）。
3. 對 push 配 DLT，把反覆 500 的特定訊息隔離出去，避免單一 poison message 混在正常流量裡放大 retry。
4. endpoint 側對「Pub/Sub 重投」做 idempotency，因為 push 也是 at-least-once、500 後的重投會帶來重複。

演練五：Schema enforcement 擋下不相容 publish

徵兆：某次 producer 部署後，該 service 的 publish 開始大量回 INVALID_ARGUMENT: Could not parse message，訊息發不出去；但 consumer 端風平浪靜、沒有任何解析錯誤、backlog 也沒異常。

根因：這通常不是故障、是 schema enforcement 正常運作。producer 改了 payload 結構（加必填欄位 / 改型別 / 漏欄位），新 payload 不符 topic 綁定的 schema，broker 在 publish 路徑上擋下、訊息根本沒進 topic。徵兆出現在 producer 端（publish 失敗）而非 consumer 端（解析失敗），正是 schema 守門把問題前移到源頭的設計意圖。

判讀與修法：

1. 先確認是「該擋」還是「誤擋」。對照 producer 的新 payload 與 topic schema：若是破壞性改版（加必填欄位 / 改型別），enforcement 擋對了 — 該回滾 producer 或先演進 schema。
2. 用 gcloud pubsub schemas validate-message 在部署前 dry-run 校驗 payload 對 schema，把「不相容」暴露在 CI 而不是 production publish。
3. schema 演進走相容路徑：新增欄位帶預設或設可選、刪欄位分兩步、避免一次破壞性改版。先升 schema 再升 producer，順序反了就會出現這個徵兆。
4. 區分 schema enforcement 失敗與 DLT：schema 擋下的訊息不進 topic、不進 DLT（DLT 隔離的是「進了 topic 但消費反覆失敗」的訊息）。兩者是交付管線的不同關卡，徵兆與修法都不同。

容量與選型邊界：標準版 vs Pub/Sub Lite

前述配置適用標準版 Pub/Sub。標準版的計費與容量模型偏向「全域路由內建、按用量計費、不需預先規劃容量」；當吞吐極高且 region 確定時，Pub/Sub Lite 的 partition-based / zonal 模型成本更低。

Pub/Sub Lite 是獨立的 CLI surface（gcloud pubsub lite-topics / gcloud pubsub lite-subscriptions），不是標準版的一個 flag。選 Lite 的代價是要自己 provision partition 數與 throughput capacity（回到接近 Kafka 的容量規劃），換來的是高吞吐穩定流量下顯著更低的成本。判準是吞吐「夠高且夠穩定到值得自己管容量」— 流量彈性大、或不想管 partition 的場景仍該留在標準版。

Spotify 的 autoscaling 案例揭露 backlog 不等於 consumer healthy：下游 export 失敗時 consumer 不 ack 仍持續耗 CPU，autoscaling 把 CPU 越拉越高、反而擴出更多空轉 consumer；解法是 exponential backoff 抑制 CPU 消耗（3.C61）。容量規劃的 autoscale signal 要看「處理成功率」而非「CPU + backlog」，否則擴縮方向會反。

整合與下一步

BigQuery / Cloud Storage subscription：免 consumer 的落地路徑

標準版提供兩種「不需要自寫 consumer」的 subscription，直接把訊息落地到分析 / 儲存層：

• BigQuery subscription（--bigquery-table）：訊息直接寫進 BQ table，免 Dataflow 中介，適合 streaming analytics。可搭配 --use-topic-schema 讓 BQ table schema 對齊 topic schema — schema enforcement 在這裡延伸成「落地結構也受契約約束」。
• Cloud Storage subscription（--cloud-storage-bucket）：訊息批次寫成 GCS object，適合 data lake / 歸檔。

這兩種 subscription 把「event 流 → 分析 / 儲存」的常見管線收進 Pub/Sub 配置，省掉一層自管 consumer。它們仍受同一套 ackDeadline / DLT 骨架管轄。

Cross-link

• 上游 vendor 頁：Google Cloud Pub/Sub overview — 選型層、跟 Kafka / SQS 取捨
• 契約與重播邊界：3.7 Event Contract 與 Replay Boundary — schema / idempotency key / replay window 先於 broker 選型
• 知識卡：Event Schema Compatibility（schema enforcement 守的契約等級）、Poison-Message Quarantine（DLT 的隔離機制）
• 對應 case：3.C64 Mercari Item Feed DLT、3.C65 Mercari LINE flow control、3.C61 Spotify autoscaling、3.C63 Mercari actionable history
• 方法論：Vendor 深度技術文章的寫作方法論

何時 revisit

• ordering key 吞吐撞上單 key 上限、且無法再細分 key：評估改用 Kafka partition 模型，或把保序成本移到 consumer 端 idempotency
• 高吞吐穩定流量 + 成本壓力浮現：評估標準版 → Pub/Sub Lite，接受自管 partition 容量換成本
• schema 需要跨多 vendor 共用契約（同一份 event 同時進 Pub/Sub 與 Kafka）：評估把 schema source of truth 抽到 broker 外的 registry

本文是 SQLite overview 的 implementation-layer deep article。Overview 已說明 SQLite 的 embedded / single-file 定位；本文聚焦 schema version、ALTER TABLE boundary、table rebuild migration 與 application release compatibility。

SQLite schema migration 的核心責任是讓單檔資料庫隨 application release 安全演進。SQLite 沒有獨立 database server，也沒有 DBA 在 server 端統一套 migration；migration 常在 application startup、CLI command、mobile app upgrade 或 desktop app launch 時發生，因此 schema version、binary compatibility、backup 與 rollback 要放在同一個 release contract 中設計。

本文的判讀錨點是：SQLite migration 同時改資料庫檔案與 application 能讀的資料格式。只要使用者或服務可能拿舊 binary 打開新 database，或新 binary 打開舊 database，migration 就要處理 forward / backward compatibility，而不只是 SQL 成功執行。

Version model

SQLite schema versioning 的服務責任是讓 application 能判斷 database file 目前處於哪個契約。SQLite 提供 PRAGMA user_version 作為 application-controlled integer；更複雜的服務也可以用 migration table 記錄多步驟版本、checksum 與執行時間。

1PRAGMA user_version;
2PRAGMA user_version = 2026052101;

Version model 要在第一版就定義。沒有版本欄位的 SQLite file 仍可 migration，但 application 只能靠 introspection 猜 schema，會讓 upgrade / downgrade runbook 複雜化。

ALTER TABLE boundary

SQLite ALTER TABLE 的核心責任是處理有限集合的 schema 變更。官方文件說明 SQLite 支援 rename table、rename column、add column、drop column；更複雜的變更要走 table rebuild pattern。

SQLite schema 存在 sqlite_schema 的 SQL text 中；這讓檔案格式簡潔，但也讓 ALTER TABLE 的安全條件和 server SQL 不同。Production migration 應優先用官方建議的 rebuild procedure，而非直接修改 sqlite_schema。

Table rebuild migration

Table rebuild migration 的服務責任是安全完成 SQLite 直接 ALTER 難以表達的變更。官方 ALTER TABLE 文件建議的 generalized procedure 是建立新 table、copy data、drop old、rename new、重建 index / trigger / view、跑 foreign key check、commit。

 1BEGIN;
 2PRAGMA foreign_keys = OFF;
 3
 4CREATE TABLE new_orders (
 5  id INTEGER PRIMARY KEY,
 6  status TEXT NOT NULL,
 7  paid_at TEXT
 8);
 9
10INSERT INTO new_orders (id, status, paid_at)
11SELECT id, status, paid_at
12FROM orders;
13
14DROP TABLE orders;
15ALTER TABLE new_orders RENAME TO orders;
16
17PRAGMA foreign_key_check;
18PRAGMA user_version = 2026052101;
19COMMIT;
20PRAGMA foreign_keys = ON;

這段範例是教學骨架，而非可直接複製到所有 schema 的萬用腳本。真實 migration 要先保存 index、trigger、view 與 FK reference，再依 schema 重建；有資料量時還要考慮 copy duration、disk 空間與 rollback snapshot。

App release compatibility

SQLite migration 的 application compatibility 來自 binary 與 DB file 的同步問題。Server SQL migration 通常有 central deploy order；SQLite file 可能跟著使用者裝置、desktop profile、CLI artifact 或 edge deploy 留在不同版本。

Compatibility 的核心是先決定支援範圍。Mobile app 常要支援舊版資料庫升級；internal CLI 可能只支援最新版本；test fixture 則需要每次 migration 後重新產生。

Migration evidence

Migration evidence 的責任是證明 schema 變更已完成且資料仍可用。SQLite migration evidence 比 server DB 簡單，但更依賴 application-level validation。

這些 evidence 應接到 Observability Evidence Package 或 release note。SQLite migration 失敗時，最清楚的 rollback 通常是回到 migration 前 snapshot，而非在同一檔案上繼續試錯。

Production 踩雷

Case 1：startup migration 讓 app 啟動卡住

Startup migration 的核心風險是把長時間 table rebuild 放在使用者啟動路徑。小表新增 column 可能很快；大表 rebuild、index 重建或 vacuum 類操作會讓 app 啟動、CLI command 或 API cold start 變慢。

修正方向是先估資料量。短 migration 可在 startup；長 migration 要有 explicit command、progress、backup 與 rollback route。

Case 2：fixture schema 升級漏掉 production gap

Fixture schema drift 的核心風險是測試 DB 和 production DB 的 dialect / constraint 不一致。SQLite fixture 很快，但 production 若是 PostgreSQL / MySQL，type、date、NULL、constraint 與 transaction 行為都可能不同。

修正方向是把 SQLite fixture 明確標成 contract test 層。Repository error mapping、domain invariant 可以用 SQLite；production-specific SQL 要用 production database container 驗證。

Case 3：直接改 sqlite_schema

直接改 sqlite_schema 的核心風險是產生語法正確但語意破壞的 database file。SQLite 官方文件提供 writable schema route，但同時強調錯誤修改可能讓 database corrupt / unreadable。

修正方向是讓 writable schema 成為最後手段。一般 migration 優先用 ALTER TABLE 或 table rebuild；需要特殊修復時先複製原檔，在副本驗證。

操作檢查清單

SQLite migration runbook 至少要記錄：

1. DB file 目前 user_version 與 application release version。
2. Migration 是否可重入、是否可中斷後恢復。
3. Migration 前 backup / snapshot 位置。
4. 需要 table rebuild 的 table、資料量、index / trigger / view 清單。
5. Validation query、row count、foreign key check、integrity check。
6. 舊 binary / 新 binary 的相容策略。
7. Fixture DB 是否已重新產生並被 contract test 使用。

下一步路由

• 上游：SQLite overview
• 操作：Migration fixture lab
• 平行：Test Fixture Best Practice
• 遷移：SQLite to PostgreSQL
• 官方：SQLite ALTER TABLE、SQLite PRAGMA