教學路線：Distributed SQL 與跨雲一致性

CockroachDB 服務頁的教學目標是把 PostgreSQL-like 介面背後的 range sharding、Raft replication、serializable transaction、leaseholder 與 region placement 說清楚。讀者讀完後要能判斷 distributed SQL 何時能取代自管 sharding，何時會把 latency 與 retry 壓力推回應用層。

定位：Spanner 的開源 / 跨雲替代

CockroachDB 跟 Spanner 解決同一個問題（跨 region 強一致 SQL）、但定位不同：

• Spanner：GCP managed service、用 TrueTime hardware
• CockroachDB：開源（雙授權）、可自管 + Cockroach Cloud、跨 AWS / GCP / Azure / on-prem、用 HLC + Raft

選 CockroachDB 的核心訴求：需要跨 region 強一致 SQL + 想避免雲商 lock-in、想自管或跨雲部署。

詳見 1.11 全球分散式 OLTP 的 CockroachDB 段。

容量特性

節點即容量單位：

• 跟 Spanner 同樣設計、節點數量決定容量
• 每節點承擔 query + storage + replication
• 線性擴展（理論）、實際依 query pattern

跨 region 配置：

• multi-region survival goal（zone-level / region-level）
• 跨 region quorum 必要、決定 latency
• 跟 Spanner 同樣的物理限制（跨洲 100ms+）

Replication：

• Raft consensus per range
• 預設 3-replica
• 可配置每個 region 不同 replica count（Survival Goals）

適用場景

1. 需要跨 region 強一致 SQL + 跨雲：

• multi-region active-active write
• GCP-only（Spanner）或 AWS-only（Aurora DSQL）和部署策略不合
• 對應 1.11 全球分散式 OLTP 的選型決策

2. PostgreSQL wire protocol 相容路徑：

• 既有 PostgreSQL 應用想升級到分散式
• 應用層改動小（保留 PostgreSQL driver / ORM）
• 注意：PostgreSQL 相容要以實際 query、extension 與 migration test 驗證

3. 自管 on-prem / hybrid：

• 金融 / 受監管產業需要 on-prem
• Spanner / Aurora DSQL 以 cloud service 為主
• CockroachDB 可自管

4. 想避免單一 vendor 全球分散式 lock-in：

• 開源 + 跨雲、可遷移性高
• 但企業版功能要付費（CockroachDB Cloud 或 Enterprise license）

不適用場景

1. single-region OLTP 夠用：

• 90% 場景 PostgreSQL / Aurora 已夠
• CockroachDB 有分散式 overhead（每個寫經 Raft）
• 替代：PostgreSQL、Aurora、MySQL

2. 極端高吞吐 single-query：

• CockroachDB 寫入有 Raft 開銷、單機吞吐 < PostgreSQL
• 整體吞吐靠 scale-out 達成、單一 query latency 較高

3. 跨洲低延遲（< 50ms）：

• 跟 Spanner 同樣物理限制
• 跨洲 quorum 100ms+ 是物理成本

4. 預算極敏感的小 workload：

• CockroachDB 至少 3 個節點（Raft quorum）
• 跟 single-instance PostgreSQL 比較貴

5. 需要 PostgreSQL 進階特性：

• 部分 PostgreSQL extension 或行為需要替代方案
• partial index、exclusion constraint 等可能缺

跟其他 vendor 的取捨

vs Spanner（GCP）：

• CockroachDB：開源、跨雲、可自管
• Spanner：GCP-only、TrueTime hardware、Google 規模驗證
• 選 CockroachDB：跨雲 / on-prem 需求
• 選 Spanner：GCP 生態 + managed operation + Google 規模驗證的成熟度

vs Aurora DSQL（AWS 2024）：

• CockroachDB：跨雲、生產驗證較久
• Aurora DSQL：AWS-only、serverless、新（2024）
• 選 CockroachDB：跨雲、想避免 AWS lock-in
• 選 Aurora DSQL：AWS 生態 + 已用 PostgreSQL + serverless 訴求

vs TiDB：

• CockroachDB：PostgreSQL wire、英語 / 歐美生態深
• TiDB：MySQL wire、亞洲生態深、HTAP（OLTP + OLAP 同庫）
• 選 CockroachDB：PostgreSQL 應用、跨雲
• 選 TiDB：MySQL 應用、需要 OLAP 整合、亞洲市場

vs PostgreSQL（傳統）：

• CockroachDB：分散式、跨 region 強一致
• PostgreSQL：single-primary、跨 region 是 async replication
• 選 CockroachDB：需要跨 region 強一致
• 選 PostgreSQL：single-region 夠用（90% 場景）

vs Aurora（single-region scaling）：

• CockroachDB：multi-region 強一致
• Aurora：single-region scaling、跨 region 是 async Global Database
• 選 CockroachDB：需要 multi-region write
• 選 Aurora：single-region scaling + AWS 生態

vs MySQL + Vitess（self-managed distributed MySQL）：

• CockroachDB：PostgreSQL wire、transparent sharding（range-based）、跨 region 強一致內建
• MySQL + Vitess：MySQL wire、application 層配 keyspace + shard key、跨 region 靠 application + async replication
• 選 CockroachDB：PostgreSQL 應用 + transparent multi-region + 想避開 Vitess operation burden
• 選 MySQL + Vitess：MySQL 應用 + 有 DBA 養 Vitess + 已是 YouTube / Slack 規模

容量規劃要點

1. Node count + zone / region 配置：

• 至少 3 個節點（Raft quorum）
• multi-region 通常 9+ 節點（3 region × 3 replica）
• Survival Goals 配置決定每 region 復原能力

2. Range（CockroachDB 的 partition）：

• 跟 DynamoDB partition、Spanner split 同類
• CockroachDB 自動 split 大 range
• application 主要管理 query locality、transaction retry 與 region placement

3. Locality 配置：

• 跟 Spanner 一樣可以指定 voting region
• 寫入 locality 影響跨 region latency

4. Backup / restore：

• CockroachDB 原生 backup 支援 cluster-level snapshot
• 增量 backup 支援
• 注意：incremental backup chain 可能很長、定期 full backup

5. Self-managed vs Cockroach Cloud：

• Self-managed：需要 ops team、可跨雲 / on-prem
• Cockroach Cloud：managed、跨 cloud（AWS / GCP / Azure）、可考慮 serverless tier

Deep article（已完成）

本批 deep article 覆蓋 CockroachDB 從 consensus 機制、multi-region 配置到 managed 形態選型的核心 production 議題：

DB4 cross-vendor entry：先看 aurora-dsql-spanner-decision-tree 識別 driver path、再進個別 vendor 深度。

multi-region-table-config 與 locality-aware-schema 切分：前者主寫「三種 table locality 怎麼選 + 選錯重配代價」、後者主寫「schema 怎麼配合 locality 設計（合規 boundary、跨州業務邏輯、Outposts 拓樸）」、兩者互補、survival goal 機制以 survival-goals 為 SSoT。

後續擴充（仍待補）

• PostgreSQL 相容性 audit（partial index / extension / SQL 行為 gap 清單）
• Backup / restore 與 PITR 操作（incremental chain 管理、restore 演練）
• Changefeed / CDC 配置（CockroachDB 原生 CDC 到 Kafka / sink）

「從 PostgreSQL 遷到 CockroachDB（playbook）」已由 PostgreSQL → CockroachDB migration 涵蓋、不再列為待補。

Anti-recommendation 與升級路由

CockroachDB 的 PostgreSQL-like 介面會降低導入門檻，但 distributed SQL 的成本會出現在 transaction retry、range lease、multi-region latency 與操作拓樸。這一段先說何時維持 PostgreSQL / Aurora，再說何時升級 CockroachDB、Cockroach Cloud、Spanner、Aurora DSQL 或 Vitess。

CockroachDB 的簡單路徑是先證明 distributed SQL 的價值大於 retry 與 latency 成本。若 workload 仍是 single-region OLTP，PostgreSQL / Aurora 通常提供更低成本；若跨 region 寫入與一致性是產品承諾，CockroachDB 才成為主要候選。

Transaction retry 的升級路徑要進入 application contract。Serializable default 能保護一致性，但 retry 會把 idempotency、timeout、user-visible latency 與 workflow compensation 帶回應用層；這些條件要在 migration playbook 前先盤點。

已知 limitation 與後續路由

CockroachDB overview 目前完成 distributed SQL 判斷。下一輪 deep article / playbook 應補 HLC + Raft、range / leaseholder、multi-region table locality、transaction retry pattern、PostgreSQL compatibility audit、Cockroach Cloud operation 與 PostgreSQL → CockroachDB migration。

案例對照

CockroachDB 在 09 案例庫已有三條直接 case 軸線（OLTP 寫入擴展、polyglot 補位、合規邊界），另外兩條對比參考軸線（Spanner 設計理念、受監管金融）一併保留。

Direct case（CockroachDB 為主角）

對比參考案例

CockroachDB direct case 的讀法是「寫入擴展（DoorDash）→ polyglot 補位（Netflix）→ 合規邊界（Hard Rock Digital）」三條軸線；對比案例則提醒讀者：Spanner 提供 global consistency 的成熟對照，受監管金融類案例提醒部署位置、合規邊界與自管能力常和一致性需求同時決定 vendor。

反向 sibling 路由

CockroachDB 的反向 sibling 路由用來把 PostgreSQL 相容性和 distributed SQL 責任拆開。若讀者從 PostgreSQL 章節過來，先讀 PostgreSQL → CockroachDB migration；若只是要 managed SQL 與 storage autoscale，先回 Aurora vendor；若要 Google Cloud 原生 external consistency 與 fully managed control plane，再對照 Spanner vendor。

這條路由的判準是「應用是否能承擔 distributed transaction 的語意差異」。SQL dialect 相近只降低 migration entry cost，真正的交付風險在 transaction retry、hot range、survival goal、backup restore 與 locality design。

常見陷阱

• single-region 用 CockroachDB：浪費分散式開銷、PostgreSQL 便宜很多
• 跨洲 active-active 期待低延遲：物理限制、跨洲 quorum 100ms+
• PostgreSQL extension 假設：部分 extension 或 SQL 行為需要替代方案，應用要驗證
• 不規劃 Survival Goals：default 配置可能不符合 RTO / RPO 需求
• backup chain 過長：incremental 不 full、recovery time 變長

下一步路由

• 完整 T1 對照：01-database vendors index
• 平行：Spanner vendor、Aurora vendor、PostgreSQL vendor
• 上游：1.11 全球分散式 OLTP — 完整選型對比
• 跨模組：9.6 容量規劃模型、9.12 SLO 與 Performance Budget
• Last reviewed：2026-05-22（PostgreSQL compatibility / survival goal / managed offering 屬時間敏感 claim）
• 官方：CockroachDB Documentation

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

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

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

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

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

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

Citus 架構：Coordinator + Worker

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

Coordinator：

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

Worker：

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

Shard：

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

3 種 Table Type

Distributed table — 跨 shard 切分

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

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

跟 Vitess Vindex 對比：

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

Reference table — 全 shard 共有

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

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

用途：

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

Local table — Coordinator 上的 PG table

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

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

Colocation：跨 distributed table 同 shard 對齊

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

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

Colocate 後：

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

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

配置 step-by-step（local cluster）

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

Step 1：Coordinator + worker 都裝 PG + Citus

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

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

Step 2：Coordinator 註冊 worker

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

Step 3：建 distributed table

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

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

Step 4：Application 連 coordinator

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

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

5 個 Production 踩雷

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

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

修法：

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

2. Cross-shard transaction 限制

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

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

修法：

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

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

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

修法：

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

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

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

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

修法：

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

5. Worker failover — Coordinator 必須知道

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

修法（Citus 11+）：

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

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

何時用 Citus

容量規劃

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

跟其他模組整合

跟 Replication topology

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

跟 PG Extensions

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

跟 MySQL Vitess

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

相關連結

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