教學路線：SQL baseline 與交易演進

PostgreSQL 服務頁的教學目標是建立 SQL baseline。讀者讀完後要能用 PostgreSQL 理解 transaction、schema evolution、query boundary、connection pressure 與 managed / distributed SQL 的比較基準。

定位：OLTP 預設、SQL 工程深度

PostgreSQL 跟 MySQL 是兩大 SQL OLTP 主流、但設計取捨明顯不同：

• PostgreSQL 偏 特性深度 — JSON、GIS、full-text search、partial index、CTE、window function 都成熟
• MySQL 偏 簡單 query 效能 + 分片生態 — Vitess / PlanetScale 提供超大規模 database sharding

選 PostgreSQL 的核心訴求：需要進階 SQL 特性、需要長期 schema evolution 彈性、信任 community-driven 演進、想避免單一 vendor lock-in（PostgreSQL 是 open source、可跨雲 / on-prem）。

容量特性

PostgreSQL 沒有「vendor 給的容量數字」、要靠 instance 配置 + tuning 推估。但有幾個工程上限要知道：

單一 primary 寫吞吐：

• 一般 m5.4xlarge 級 instance：5K-10K WPS（依 schema、index、commit fsync）
• 高階 r6i.16xlarge + io2 storage：30K-50K WPS
• 超過這個級別 → 應用層 database sharding 或換 Aurora / Spanner

Connection 上限：

• 預設 100 connection、每個 connection ~10MB RAM
• 1000+ connection 必須 pgBouncer / PgCat 共享 pool
• 對應 9.C29 Lemino case — RDB connection limit 是 surge 場景的隱性 bottleneck

Read replica：

• streaming replication：1 個 primary + 多個 standby（async / sync）
• 跨 AZ replication lag 通常 < 100ms、跨 region 可能秒級
• 跟 Aurora 比、自管 PostgreSQL replication lag 較大

Storage 上限：

• 單一 table 32 TB（PostgreSQL 設計上限）
• 實務上單表超過 1 TB 開始有 vacuum / index 問題、建議 partition

適用場景

1. 多用途 OLTP、複雜查詢：

• 複雜 JOIN、CTE、window function、subquery
• 訂單系統、會員系統、訂閱方案、權限 RBAC
• 需要 strong consistency + ACID transaction

2. JSON / 半結構化資料：

• JSONB column 支援 indexing、partial query
• 比 MongoDB 適合 主要結構化 + 部分 JSON workload
• 不適合主要 document workload（用 MongoDB / Cosmos DB）

3. 地理 / 全文檢索：

• PostGIS 是業界標準 GIS extension
• 全文檢索（ts_vector）對中等規模夠用、超大規模用 Elasticsearch

4. 進階特性需求：

• partial index（WHERE 條件下才建 index）
• exclusion constraints（避免 booking 重疊）
• range types（時間 / 數字範圍）
• logical decoding / CDC（Debezium、pgcapture）
• foreign data wrapper（query 跨 DB）

5. 跨雲 / on-prem 部署：

• 不想 vendor lock-in
• 可用 Patroni / Stolon / pg_auto_failover 做 HA
• 對應 1.11 全球分散式 OLTP 的 CockroachDB / Aurora DSQL 比較段

6. 中小規模高峰場景：

• 流量 < 10K WPS 級別、PostgreSQL 自管或 RDS 通常夠
• 流量更高、考慮 Aurora（同 wire protocol、storage 升級）

不適用場景

1. 極高寫入吞吐（單機 > 50K WPS）：

• 必須進入 database sharding 或分散式 SQL
• 替代：CockroachDB、TiDB、Spanner、應用層 sharding

2. 全球 multi-region active-active write：

• PostgreSQL 是 single primary、不支援 multi-region active-active
• 替代：Aurora DSQL、Spanner、CockroachDB multi-region

3. KV 簡單查詢 + sub-10ms p99：

• PostgreSQL connection 開銷 + parsing + planning 已經 1-3ms
• KV-pattern workload 用 DynamoDB / Redis / Cosmos DB 更便宜更快

4. 大規模 OLAP：

• PostgreSQL 定位在 OLTP，analytics workload 交給 OLAP 系統
• 大數據分析用 ClickHouse / BigQuery / Snowflake / Redshift / Synapse

5. 連線量極大 SaaS（每個用戶一個 connection）：

• 即使有 pgBouncer、超大連線量仍是 PostgreSQL 結構性限制
• 對應 9.C29 Lemino 案例 — 流量上升 connection 爆是換 DynamoDB 的主因

跟其他 vendor 的取捨

vs MySQL：

• PostgreSQL：SQL 特性深、JSON / GIS / window 完整、replication 較簡單但 lag 較大
• MySQL：簡單 query 效能好、replication 機制成熟、Vitess 分片生態強
• 選 PostgreSQL：需要進階 SQL、複雜 query、JSON workload
• 選 MySQL：高併發簡單 query、需要 sharding、已用 MySQL 生態

vs Aurora（同 PostgreSQL wire protocol）：

• PostgreSQL：自管 / RDS、特性接近 upstream、跨雲可用
• Aurora：AWS managed、storage / compute 分離、更多 read replica
• 選 PostgreSQL：跨雲、想最新特性、預算敏感
• 選 Aurora：AWS 生態、需要更快 failover + 更多 read replica
• 詳見 Aurora vendor page

vs CockroachDB（PostgreSQL wire protocol 相容）：

• PostgreSQL：single-primary OLTP、SQL 特性完整
• CockroachDB：multi-region 強一致 SQL、PostgreSQL wire 相容但部分特性缺
• 選 PostgreSQL：single-region 或 read replica 跨 region 夠
• 選 CockroachDB：必須 multi-region active-active write
• 詳見 1.11 全球分散式 OLTP

vs Spanner / Aurora DSQL（全球分散式 SQL）：

• PostgreSQL：傳統設計、跨 region 是 async replication
• Spanner / Aurora DSQL：全球線性化、跨 region 強一致
• 選 PostgreSQL：90% 場景夠用、便宜、容易
• 選 Spanner / Aurora DSQL：金融交易、ticketing inventory、必須全球強一致

vs DynamoDB：

• 詳見 1.10 KV / Document DB 容量規劃 的 connection model 對比段

vs Neon（PostgreSQL serverless）：

• PostgreSQL：standard、自管或 RDS
• Neon：branch-based、scale-to-zero、適合 dev / preview environment
• 選 Neon：dev / preview、稀疏 workload、CI 用
• 選 PostgreSQL：production sustained workload

容量規劃要點

1. Connection pool 必須有：

• 直接連 1000+ connection 會壓垮 PostgreSQL
• pgBouncer（最簡單、transaction pooling）
• PgCat（rust 寫的進階替代、支援 sharding）
• application 層 pool（HikariCP、SQLAlchemy pool）
• 通常組合使用：application pool 30-50 connection × 多 instance → pgBouncer 共享 → PostgreSQL 200 connection
• 對應 Connection Pool 卡片

2. Replication 配置：

• streaming replication：async / sync / quorum
• 跨 AZ async：lag 通常 < 100ms、failover 1-2 分鐘
• 跨 AZ sync：lag 接近 0、但寫入要等 standby ack、會降寫吞吐
• 跨 region 通常 async
• HA 工具：Patroni（最常見）、pg_auto_failover、Stolon

3. Vacuum 跟 bloat 治理：

• PostgreSQL MVCC 會留下 dead tuples、必須 vacuum
• autovacuum 配置：throttle 大表、避免在 peak 跑
• bloat 監控：pg_stat_user_tables 看 dead_tup ratio
• 大表 vacuum 可能要 hours、影響 maintenance window

4. 大表 partitioning：

• 單表 > 1 TB 建議 partition（按時間、按 tenant）
• partition pruning 讓 query 只掃需要的 partition
• partition 限制：cross-partition unique constraint、跨 partition join 較慢

5. Index 策略：

• 預設 B-tree、適合大多數 query
• partial index 對 boolean / status column 特別有用
• GIN / GiST 對 JSON / full-text / GIS
• index 太多會拖累寫入、定期 review 未用 index（pg_stat_user_indexes）

安全、DR 與角色分工

PostgreSQL 的 production 完整性不只來自 SQL 特性，也來自資料存取、備份復原、升級責任與事故證據的分工。這一段補上 PG baseline 原本留在 limitation 的三個缺口：Security / RLS / audit logging、cross-region DR、application developer vs DBA / SRE 視角。

Access control / RLS 的判讀重點是把資料責任放在資料層與 application 層之間分工。PostgreSQL 支援 role、grant、schema、function security 與 row-level security；但 RLS 會把授權邏輯拉進 database，適合 multi-tenant row isolation、資料平台或共享 reporting schema，日常 OLTP 仍要保留 application authorization 與 audit trail。

TLS / credential 的判讀重點是連線安全與憑證生命週期。Self-managed PostgreSQL 要處理 server cert、client cert、DB user rotation 與 connection pool 重連；managed PostgreSQL 常把 certificate、IAM auth 或 secret integration 交給平台，但 application pool、migration tool 與 read replica 仍要一起更新。

Cross-region DR 的判讀重點是 RPO / RTO 與資料一致性。自管 PostgreSQL 可用 streaming replication、WAL archiving、PITR 與 Patroni 做 region failover；Aurora 把 backup、PITR 與 Global Database 交給 AWS；真正 active-active 或 global strong consistency 需求要回到 CockroachDB、Spanner 或 Aurora DSQL，single-primary PostgreSQL 保留為 region failover 與 async DR 路線。

Developer / DBA split 的判讀重點是把日常責任寫進流程。Application developer 擁有 query shape、transaction boundary、repository adapter 與 migration contract；DBA / SRE 擁有 backup、replication、pooler、extension、vacuum、index maintenance 與 DR drill；release gate 需要把兩邊 evidence 合在同一份 decision log。

Managed PG 與相容變體路由

PostgreSQL wire protocol 已成為 managed SQL 與 distributed SQL 的相容目標。選型時要區分「PostgreSQL 本體」、「managed PostgreSQL」、「PostgreSQL-compatible distributed SQL」與「PostgreSQL extension ecosystem」四種不同責任。

Managed PG 變體的引用規則是先查 compatibility，再談 migration。Extension whitelist、backup / restore API、logical replication 支援、connection endpoint 行為與 pricing 都是時間敏感 claim；實作前要回到官方文件確認版本，並把確認日期留在 migration plan 或 decision log。

Deep article + Migration playbook（已完成）

補充正文路由

當前 deep article、migration playbook、補充正文與 hands-on 已 cover replication / HA / OSC / connection / CDC / sharding / multi-master / MVCC / query opt / index / partitioning / JSONB / FTS / extension（含 TimescaleDB / pgvector / PostGIS）/ backup / slot / SQL features / upgrade / migration / security / DR / managed variant 等維度。下列補充正文用來承接 overview 中提到的延伸議題：

• Logical decoding plugins deep dive：wal2json / pgoutput / decoderbufs 對位、CDC pipeline 整合
• pg_partman advanced：retention 跟 child partition 自動 management
• Connection pooler comparison：PgBouncer vs Pgcat vs Odyssey 細部對比
• Aurora I/O-Optimized vs standard：cost model 取捨
• AlloyDB / Cloud SQL 比較：GCP managed PG 選型

上述補充篇已完成正文，並保留既有引用路徑。Logical decoding 接 Logical Replication + Debezium 與 Replication Slot Management；pg_partman advanced 接 Declarative Partitioning；pooler comparison 接 Connection Scaling 與 pgBouncer Config；Aurora cost 接 → Aurora；AlloyDB / Cloud SQL 接 Managed PG Comparison。

案例對照

PostgreSQL 沒有直接的 09 case（多數 09 case 用 managed vendor）、但作為 baseline 跟遷移源頭 在許多 case 出現：

已知 Limitation 與 Audit 紀錄

本 vendor 頁的 22 篇 deep article + 6 篇 migration playbook 經過 4-reviewer audit（A 寫作規範 / B 跨檔一致性 / C 技術準確性 / D 框架偏誤）、Phase 1-3 修法完成。承認以下 limitation：

• PG narrative bias：pgvector / TimescaleDB / extension-ecosystem / Citus 四篇對「PG 取代專業 DB」描述偏 PG-favoring；對手 vendor（Pinecone / InfluxDB / Vitess）的優勢段相對簡短。讀者選型時、請以 cost / ops / scale 三軸綜合判斷、不依本 vendor 頁單一視角。
• Anti-recommendation 深度不一：bdr-multi-master / extension-ecosystem 有「99% 不需要」明確邊界、其他篇章邊界較柔（如「Vector 量 > 5-20M」是粗略門檻）。實際 production 決策請參考多 vendor 對照 + 自家 workload 量測。
• Sibling cross-link 狀態：MySQL ↔ PG sibling、PG 既有 ↔ 新章節 cross-link 已補（refer #136 卡）；本輪同步補 Aurora / CockroachDB / Spanner / Cosmos DB / DynamoDB vendor 頁的反向 sibling 路由，剩餘精修可在各 migration playbook 補更細的 step-by-step 對照。
• 時間敏感 vendor claim：Aurora DSQL（2024-12 preview / 2025-05 GA）/ pgvector（0.8 iterative scan）/ TimescaleDB version matrix / DSQL extension 支援範圍持續演進、本 vendor 頁以 2025-2026 公開狀態為準、實作前請以 vendor 官方 docs 為準（refer #137 卡）。
• 補充維度已正文化：Security / RLS / audit logging、cross-region DR、application developer vs DBA 視角分工、YugabyteDB / TiDB migration playbook、specialized PG variants 已補成正文。本輪也補上跨 vendor 反向連結與時間敏感 claim 路由；下一輪可集中在 migration playbook 的操作步驟與 lab 化。

詳細 audit findings 跟修法見 #136 Sibling Vendor Cross-Link Bidirectionality / #137 Vendor Feature 時間敏感性 / #138 Cross-Reviewer Convergence。

常見陷阱

• connection 沒 pool 直接連：1000 application instance × 30 connection = 30K connection、PostgreSQL 撐不住
• 沒 vacuum 治理：dead tuple 累積、table bloat、query 變慢
• 大表沒 partition：> 1 TB 單表的 vacuum / index rebuild 變成事故
• index 不 review：寫吞吐被舊 index 拖垮
• 跨 AZ sync replication 給寫入吞吐高的 workload：每次 commit 等 standby ack、寫吞吐減半
• logical replication 拖太多 publication：可能造成 primary WAL 堆積、disk 爆

下一步路由

• 完整 T1 對照：01-database vendors index
• 平行：MySQL vendor、Aurora vendor（managed PostgreSQL）
• 操作：PostgreSQL Hands-on（local lab、pool、PITR、migration evidence、HA drill）
• 上游：1.1 高併發資料存取、1.3 Transaction Boundary
• 下游：1.10 KV / Document DB 容量規劃（PostgreSQL 不適用時的替代）/ 1.11 全球分散式 OLTP（PostgreSQL 不夠用時的升級路徑）
• 跨模組：9.5 瓶頸定位流程 — connection / replication lag / vacuum 都是 PostgreSQL 常見 bottleneck 源
• 官方：PostgreSQL Documentation

升級前的相容性評估

大版本升級不只是換一個二進位檔——新版本可能改變 SQL 行為、儲存格式、認證方式與預設值。在動任何生產資源之前，先在本地或測試環境把相容性問題找出來。

MySQL 5.7 → 8.0 的常見破壞性變更

PostgreSQL 大版本升級的檢查點

PostgreSQL 的大版本升級相對穩定，但仍有需要確認的項目：extension 版本是否跟新 PostgreSQL 版本相容（特別是 PostGIS、pg_partman、timescaledb 這類複雜 extension）、pg_upgrade 的 --check 模式可以在不實際升級的前提下驗證相容性。

1# PostgreSQL: 升級前 dry-run 檢查
2pg_upgrade --old-datadir /var/lib/postgresql/13/main \
3           --new-datadir /var/lib/postgresql/16/main \
4           --old-bindir /usr/lib/postgresql/13/bin \
5           --new-bindir /usr/lib/postgresql/16/bin \
6           --check

應用程式層的查詢相容性

把應用程式的所有 SQL 查詢（ORM 產生的也算）對新版本跑一遍。重點是行為變更而非語法錯誤——語法錯誤會立刻報錯、容易抓；行為變更（排序結果不同、型別轉換規則不同）不會報錯、但結果錯誤。

1# MySQL 升級前檢查工具
2mysqlcheck --all-databases --check-upgrade
3mysql_upgrade --upgrade-system-tables --dry-run

ORM 和 database driver 也要確認版本支援。PHP 的 mysqli 在 PHP 7.4+ 預設支援 caching_sha2_password、但舊版不支援。Node.js 的 mysql2 原生支援、但 mysql（舊套件）不支援。Python 的 mysqlclient 1.4+ 支援。

備份：升級前的保險

升級前的備份不是日常備份——它是一份明確的、經過驗證的、標記為「升級前保險點」的快照。

備份操作

1# MySQL: 完整 dump（InnoDB 用 --single-transaction 避免鎖表）
2mysqldump --all-databases --single-transaction --routines --triggers \
3  --set-gtid-purged=OFF > pre-upgrade-$(date +%Y%m%d-%H%M).sql
4
5# PostgreSQL: 完整 dump
6pg_dumpall > pre-upgrade-$(date +%Y%m%d-%H%M).sql

RDS 環境：在升級操作前手動建立 snapshot，而非依賴自動備份。自動備份在升級過程中可能被新的快照覆蓋，手動 snapshot 不會被自動清除。

1aws rds create-db-snapshot \
2  --db-instance-identifier mydb-prod \
3  --db-snapshot-identifier pre-upgrade-$(date +%Y%m%d)

備份驗證

備份存在不等於備份可用。驗證方式是把備份還原到一台獨立的測試實例、確認資料完整：

1# 還原到測試實例
2mysql -h test-instance -u admin -p < pre-upgrade-20260626-1400.sql
3
4# 驗證關鍵表的 row count
5mysql -h test-instance -e "SELECT COUNT(*) FROM orders; SELECT COUNT(*) FROM users;"

記錄還原時間：「從這份備份還原到可服務狀態需要 N 分鐘/小時」。這個數字是升級失敗時的停機時間下限——管理層需要這個數字來評估升級的風險。

平行驗證策略

在生產環境切換之前，先在新版本的平行環境上跑完所有驗證。平行驗證的目標是讓切換那一刻的風險降到最低——切換時已經知道新版本在相同資料和相同負載下的行為。

建立平行環境

驗證項目

平行驗證至少跑一週。時間越長、覆蓋到的邊界情境越多——月結批次、週期性報表、低頻排程任務都可能觸發只在特定條件下才出現的相容性問題。

切換策略

切換策略的選擇取決於三個變數的取捨：操作複雜度、停機時間、回退速度。

In-place 升級

直接在原實例上升級版本。RDS 的操作是修改 engine version、等待升級完成。

• 停機：升級期間實例不可用（MySQL 5.7→8.0 在 RDS 上約 10-30 分鐘，視資料量而定）
• 回退：從 pre-upgrade snapshot 還原，需要 snapshot restore 時間（分鐘到小時級）
• 適用：可接受計畫性停機的環境、資料量不大

Blue-green 切換

在新版本上建立獨立實例、透過 replication 同步資料、切換應用程式的連線端點。

• 停機：接近零（DNS TTL 或 endpoint 切換的傳播時間）
• 回退：把連線端點切回舊實例，舊實例持續運行
• 複雜度：需要維護兩個實例的同步、切換時要處理複寫延遲
• 適用：不能接受停機的 production 環境

RDS 從 2022 年開始提供原生的 Blue/Green Deployments 功能，簡化了同步與切換的操作：

1aws rds create-blue-green-deployment \
2  --blue-green-deployment-name mydb-upgrade \
3  --source arn:aws:rds:ap-northeast-1:123456789012:db:mydb-prod \
4  --target-engine-version 8.0.35

Read replica 升級後提升

建立指定新版本的 read replica，replica 同步完成後提升為獨立實例，應用程式切換連線。

• 停機：提升 replica 的幾秒 + 連線切換
• 回退：舊 primary 仍在，切回即可
• 限制：不是所有版本組合都支援跨版本 replica

選型判準

升級後的驗證與監控

切換完成後的 48-72 小時是觀察期。這段時間舊實例保持可用狀態，直到確認新版本穩定才退役。

切換後立即驗證

1. 應用程式的所有關鍵路徑可正常操作（登入、查詢、寫入、交易）
2. 連線池行為正常（沒有持續的 authentication failure 或 connection reset）
3. 排程任務（cron job、背景 worker）正常連線並執行

效能監控

比較升級前後的關鍵指標：

1# 觀察升級後的 slow query 數量
2mysql -e "SHOW GLOBAL STATUS LIKE 'Slow_queries';"
3
4# 比較 p99 延遲（需要 application-level metrics）
5# CloudWatch: DBInstanceIdentifier → ReadLatency, WriteLatency

升級後效能退化的常見原因：optimizer 行為改變（新版本選了不同的執行計畫）、buffer pool 冷啟動（升級後快取是空的、前幾小時延遲偏高是正常的）。如果 48 小時後延遲仍未回到基線，檢查 slow query log 找出退化的具體查詢。

舊實例退役

觀察期結束、新版本確認穩定後：

1. 停止舊實例的 replication（如果仍在同步）
2. 保留舊實例的 final snapshot
3. 刪除舊實例（先確認 deletion protection 關閉是刻意的、不是誤操作）
4. 更新文件：記錄升級日期、版本號、升級過程中遇到的問題

時程與管理層溝通

向管理層說明時的關鍵框架：資料是不可重建的，升級策略是「在旁邊建一個新版本的資料庫、驗證它在相同資料和相同負載下行為正確、然後切過去」。多出來的時間買的是「切換那一刻的信心」和「出問題時能快速回退」——兩者對生產服務都是必要的保險。

跨分類引用

• → 升級的共通操作框架：四階段模型的通用說明
• → Stateful 資源保護與依賴表達：multi-AZ、備份、deletion protection 的 IaC 描述
• → 無 SSH 環境的資料庫備份與變更管理：接手環境的資料庫備份策略

 1type BasicStorage interface {
 2    Store(event Event) error
 3    Query(filter QueryFilter) ([]Event, error)
 4    Close() error
 5    Downsample() error
 6    Purge() error
 7}
 8
 9type AnalyticsStorage interface {
10    BasicStorage
11    Aggregate(spec AggregateSpec) (AggregateResult, error)
12    Funnel(steps []string, timeWindow Duration) (FunnelResult, error)
13    Cohort(groupBy string, metric string) (CohortResult, error)
14}

SQLite implementation 只實作 BasicStorage。PostgreSQL implementation 實作 AnalyticsStorage。Dashboard 用 Go 的 type assertion（if as, ok := storage.(AnalyticsStorage); ok { ... }）判斷能力 — funnel/cohort 視圖在 SQLite 模式下不顯示入口，而非顯示後報錯。

選擇哪個 backend 取決於部署場景和查詢需求：

SQLite Backend（day-one 預設）

SQLite 是嵌入式資料庫，編譯進 collector binary 中，不需要額外 server。Go 用 modernc.org/sqlite（pure Go、無 CGO 依賴、效能約為 CGO driver mattn/go-sqlite3 的 60-80%，自用規模下足夠），開源使用者 go build && ./collector 就能跑，部署步驟為零。WAL mode 允許讀寫並行 — dashboard 的 SELECT 查詢不會被 ingestion 的 INSERT 阻塞，反之亦然。寫入之間的競爭由 busy_timeout 處理。

能力範圍

• 索引查詢：按 type、name、timestamp 建索引，查詢從全表掃描變成索引查找
• SQL 聚合：SELECT name, COUNT(*) FROM events WHERE type='error' GROUP BY name — 一行 SQL 完成分群計數
• 跨欄位過濾：WHERE type='error' AND name LIKE 'terminal.%' AND ts > '2026-06-18'
• 寫入：WAL mode 下每秒數千筆 append 寫入

Events 主表 DDL

Events 表的欄位從 event.schema.json 的 JSON 結構推導。Source 的 nested object 攤平成獨立 column — 方便 SQL 查詢和索引，不需要每次從 JSON 裡 extract。

 1CREATE TABLE events (
 2    id INTEGER PRIMARY KEY AUTOINCREMENT,
 3    v INTEGER NOT NULL DEFAULT 1,
 4    type TEXT NOT NULL,
 5    name TEXT NOT NULL,
 6    ts TEXT NOT NULL,
 7    source_sdk TEXT,
 8    source_app TEXT,
 9    source_version TEXT,
10    source_platform TEXT,
11    source_os TEXT,
12    session_id TEXT,
13    session_started TEXT,
14    level TEXT,
15    data TEXT,
16    error_message TEXT,
17    error_stack TEXT,
18    error_type TEXT,
19    receive_ts TEXT
20);

source_sdk 獨立成 column 讓「按 SDK 來源篩選」（WHERE source_sdk = 'python'）不需要從 JSON extract。data 用 TEXT 存 JSON。SQLite 沒有原生 JSON 型別，但 3.38+ 支援 json_extract() 函式做查詢（WHERE json_extract(data, '$.duration_ms') > 1000）。session_id 獨立成 column 讓 session 回放的 JOIN 不需要 JSON extract。error_stack 獨立成 column 讓 error 調查時全文搜尋 stack trace 不需要 JSON extract。receive_ts 是 collector 收到事件的時間，和 SDK 端的 ts 對照可估算 clock drift。

PostgreSQL 版本的差異：data 改成 JSONB 型別（原生索引和查詢）、source_* 可保持為 nested JSON（PostgreSQL 的 JSONB 查詢效能足夠）或維持攤平（和 SQLite 版本保持一致）。

建議索引

建表時一起建索引，覆蓋 dashboard 的核心查詢模式：

1CREATE INDEX idx_type_ts ON events(type, ts);    -- 按 type + 時間過濾（error 列表、趨勢圖）
2CREATE INDEX idx_session ON events(session_id);   -- 按 session 回放
3CREATE INDEX idx_name ON events(name);            -- 按 name 分群計數（功能使用排行）

Day-one 建表時就建，不是效能出問題後才加。

適用規模

單日事件量在十萬筆以下、SQLite 資料庫在 1GB 以下。索引查詢在毫秒級完成。自用工具和小型團隊的日常使用通常在這個範圍。

分層保留與降採樣

保留策略從查詢需求反推，每一種查詢需要的資料粒度和回溯深度不同。回溯越深的查詢需要的粒度越粗 — debug 需要最近幾天的逐筆事件，cohort 留存需要一整年的資料但每週一筆聚合數字就夠。

SQLite 中的實作是三張摘要表加定期 job：

 1-- 摘要表
 2CREATE TABLE hourly_summary (
 3    hour TEXT, type TEXT, name TEXT,
 4    count INTEGER, error_count INTEGER,
 5    UNIQUE(hour, type, name)
 6);
 7CREATE TABLE daily_summary (
 8    date TEXT, type TEXT, name TEXT,
 9    count INTEGER, unique_sessions INTEGER,
10    UNIQUE(date, type, name)
11);
12
13-- 降採樣（Downsample，每小時跑一次，幂等 — 重跑只更新不重複）
14INSERT OR REPLACE INTO hourly_summary (hour, type, name, count, error_count)
15SELECT strftime('%Y-%m-%dT%H:00:00', ts), type, name,
16       COUNT(*), SUM(CASE WHEN type='error' THEN 1 ELSE 0 END)
17FROM events
18WHERE ts >= datetime('now', '-1 hour')
19GROUP BY 1, 2, 3;
20
21-- 清理（Purge，每天跑一次，分批刪除避免長時間鎖定）
22DELETE FROM events WHERE rowid IN (
23  SELECT rowid FROM events WHERE ts < datetime('now', '-7 days') LIMIT 10000
24);
25-- 重複執行直到影響行數為 0
26DELETE FROM hourly_summary WHERE hour < datetime('now', '-90 days');
27DELETE FROM daily_summary WHERE date < datetime('now', '-365 days');

保留期限由 collector config 設定，數字的來源是「哪些查詢需要回溯多遠」：

1retention:
2  raw_events: 7d
3  hourly_summary: 90d
4  daily_summary: 365d
5  monthly_summary: forever

Storage interface 的 Downsample() 和 Purge() 由 collector 的定時排程觸發（Go 的 time.Ticker）。每個 storage backend 各自實作 — SQLite 用上述 SQL、PostgreSQL 用相同邏輯但可以加 partial index 加速、時間序列 DB 的 continuous aggregate 和 retention policy 原生支援。

為什麼是聚合而非抽樣

原始事件的保留期到期後，需要決定如何保留歷史統計。降採樣有兩種思路。抽樣保留是同事件名稱（name 欄位）同小時保留一筆原始事件、刪除其餘，保留了逐筆查詢能力但喪失準確計數。聚合摘要是把一小時內的事件壓成一筆計數記錄，喪失逐筆細節但保留準確統計。

Collector 選擇聚合摘要——捨棄逐筆細節，換取準確計數。降採樣後的資料用途是趨勢圖和長期統計，這些查詢需要「過去 30 天每小時的 error 總數」而非「某一筆原始 error 的 stack trace」。

這意味著原始事件 purge（定期清理過期事件）後，超過保留期的逐筆查詢會回傳空結果。Dashboard 在回溯超過原始事件保留期的時間範圍時，應切換到上方的摘要表（hourly_summary/daily_summary）查詢——顯示趨勢圖而非事件列表。設計方向是查詢 API 的 from 參數超過 retention.raw_events 時自動降級到摘要表，或回傳提示告知 client 該時間範圍只有聚合資料（初版 collector 尚未實作此降級邏輯）。

觸發切換到 PostgreSQL 的訊號

寫入爭搶：SQLite 是單寫者模型。高併發寫入（多個 SDK 同時 flush、每秒數百筆以上持續發生）會出現 database is locked 錯誤。WAL mode 能緩解但不能根治。

聚合查詢效能不足：Dashboard 需要的聚合查詢（「過去 30 天每小時的 error 數量趨勢」「funnel 的每步轉換率」）在資料量成長後變慢。SQLite 沒有 parallel query 和 partial index 等進階 OLAP 能力。

跨實例需求：需要多個 collector 實例共用同一個資料庫時，SQLite 的單檔案模型無法跨主機存取。

PostgreSQL Backend（分析觸發）

PostgreSQL 是獨立的資料庫 server，提供多連線並行寫入、進階索引（GIN for JSONB、partial index）和完整的 SQL 分析能力。切換到 PostgreSQL 意味著 collector 從「零依賴單一 binary」變成「binary + 外部 DB」，運維複雜度上升。

觸發條件

SQLite 的寫入爭搶或聚合效能成為瓶頸時切換。具體訊號：database is locked 錯誤頻率超過每分鐘一次、或 dashboard 的聚合查詢超過 3 秒。

切換方式

切換是 config change：把 --storage=sqlite 改成 --storage=postgres --dsn=postgres://...。資料遷移用匯出 + 匯入完成：

1. 從 SQLite 匯出事件為 JSONL（monitor export --format=jsonl）
2. 在 PostgreSQL 建立 events 表（schema 和 SQLite 相同，data 欄位改用 JSONB）
3. 匯入 JSONL 到 PostgreSQL（monitor import --storage=postgres --file=events.jsonl）
4. 切換啟動參數、確認查詢正常後停用 SQLite 檔案

Storage interface 保證 collector 的 ingestion、query、rule engine 邏輯不需要改動 — 只有 storage implementation 層切換。

能力增量

• 並行寫入：多個 SDK 同時 flush 不會 lock
• JSONB 索引：對 data 欄位的特定 key 建索引（CREATE INDEX ON events ((data->>'name'))）
• Window function：funnel 和 cohort 分析的 SQL 基礎
• Read replica：寫入和查詢分離，dashboard 的查詢不影響 ingestion 效能

時間序列 DB Backend（長期演進）

時間序列資料庫（TimescaleDB、InfluxDB、VictoriaMetrics）專門為高頻 append 寫入和時間分桶聚合設計。TimescaleDB 基於 PostgreSQL 擴展，Storage interface 的 PostgreSQL implementation 可以直接複用、加上 hypertable 和 continuous aggregate。

觸發條件

每秒數萬筆以上的持續寫入、或需要自動 downsampling（每分鐘的原始資料保留 7 天、每小時的聚合保留 90 天、每天的聚合永久保留）。多數自用工具和小型團隊不會到達這個規模。

能力增量

• 時間分桶原生操作：time_bucket('1 hour', ts) 替代手動 DATE_TRUNC
• Continuous aggregate：預計算的聚合結果自動更新
• 壓縮：歷史資料自動壓縮，TB 級資料可查詢
• Retention policy：按時間自動清理舊資料

JSONL 匯出（debug 用途）

JSONL 不作為主要 storage backend，而是作為匯出格式保留人類可讀性和 grep 友好性。monitor export --format=jsonl 把 storage 中的事件匯出為每行一個 JSON 物件的檔案，讓開發者可以用 grep / jq 做臨時查詢或把資料搬到其他工具。

JSONL 匯出也是備份和遷移的中介格式 — SQLite 損壞時從 JSONL 重建、切換到 PostgreSQL 時從 JSONL 匯入。

匯出使用 streaming — 從 storage 逐筆讀取、逐行寫出檔案，記憶體使用和事件總量無關。300 萬筆事件（約 900MB JSONL）的匯出不需要載入全部資料到記憶體。匯出的 JSONL 檔案包含事件明文（已 redaction 的欄位除外），匯出後不受 collector 的存取控制保護，應注意存放位置和存取權限。

演進原則

按觀察到的瓶頸切換。database is locked 錯誤頻率、聚合查詢延遲、磁碟使用量 — 這些是可觀察的訊號。「未來可能有百萬筆事件」是預測。按訊號行動，不按預測行動。

切換是 config change。Storage interface 確保切換 backend 時 collector 的其他邏輯（ingestion、query API、rule engine、dashboard）不需要改動。切換的成本是資料遷移，不是程式碼重寫。

SQLite 是安全的起點。多數開源使用者會停留在 SQLite backend — 單日萬筆以下、索引查詢毫秒級、零依賴部署。只有明確的效能瓶頸才值得引入外部 DB 的運維成本。

下一步路由

• Collector 的整體架構 → Collector 架構
• 查詢 API 的設計（跨 backend 統一） → 查詢 API 設計
• 資料庫選型的通用指南 → backend 01 資料庫
• 效能瓶頸的判讀方法 → backend 09 效能容量
• 水平擴展的基礎概念 → DevOps 水平擴展
• Error fingerprint 的 DDL 擴充 → Error Fingerprint 與去重分群

SQLite 層：開發者工具

SQLite 層提供的功能聚焦在「開發者自己 debug 和監控」。所有查詢都是單一維度的 — 按時間、按類型、按名稱過濾，不需要跨事件 JOIN 或跨使用者聚合。

承載的功能

這些功能覆蓋開發者日常 debug 和監控的核心操作 — 查錯誤、看時間軸、回放 session、設規則告警。

對應的 Dashboard 視圖

對應的事件消費

SQLite 層消費所有四類事件，但消費方式是「單筆或單 session 級查詢」：

PostgreSQL 層：行為分析

PostgreSQL 層在 SQLite 層的基礎上加入「跨 session、跨使用者的聚合分析」。這些查詢需要 JOIN 多張表、計算時間窗口、處理大量資料的 GROUP BY — SQLite 的單寫者模型和有限的查詢最佳化器在這些場景下效能不足。

觸發引入 PostgreSQL 的功能需求

判斷公式

1需要 funnel / cohort / RFM 任一 → PostgreSQL
2需要跨使用者聚合（不只看自己的資料） → PostgreSQL
3需要高併發寫入（多個 SDK 同時 flush 且持續出現 database is locked 錯誤） → PostgreSQL
4以上都不需要 → SQLite 足夠

對應的 Dashboard 視圖（SQLite 層不提供）

對應的事件消費

PostgreSQL 層消費的事件和 SQLite 相同（Ingestion 不變），但消費方式從「單筆/單 session」擴展到「跨 session/跨使用者」：

Domain 的分層影響

Ingestion 和 Rule 兩個 domain 和 storage backend 無關 — 事件進來的方式和規則評估的邏輯不因 backend 改變。Query 和 Dashboard 是分層影響最大的兩個 domain — PostgreSQL 層的查詢能力決定了 Dashboard 能提供什麼視圖。

實作邊界

Storage interface 用 Go 的 interface composition 分成兩層：

 1type BasicStorage interface {
 2    Store(event Event) error
 3    Query(filter QueryFilter) ([]Event, error)
 4    Close() error
 5    Downsample() error
 6    Purge() error
 7}
 8
 9type AnalyticsStorage interface {
10    BasicStorage
11    Aggregate(spec AggregateSpec) (AggregateResult, error)
12    Funnel(steps []string, timeWindow Duration) (FunnelResult, error)
13    Cohort(groupBy string, metric string) (CohortResult, error)
14}

SQLite implementation 只實作 BasicStorage。PostgreSQL implementation 實作 AnalyticsStorage。Dashboard 用 Go 的 type assertion（if as, ok := storage.(AnalyticsStorage); ok { ... }）判斷能力 — funnel/cohort 視圖在 SQLite 模式下不顯示入口，而非顯示後報錯。

下一步路由

• 可插拔 Storage Backend 的架構 → 規模演進
• 事件枚舉方法（哪些事件要收） → 事件枚舉與補齊檢查
• 分層保留策略 → 規模演進的分層保留段
• Funnel 分析的完整方法論 → Funnel analysis
• 查詢消費模式（各場景需要什麼事件）→ 查詢消費模式

定義 funnel 步驟

Funnel 分析的第一步是列出每一步和對應的事件名稱。以一個透過 WebSocket 連接遠端終端機的 app 連線流程為例：

SQLite 層：每步事件計數

SQLite backend 能做的 funnel 是「每步有多少事件觸發」— 單表 GROUP BY，不需要跨事件 JOIN。

1SELECT name, COUNT(*) as count
2FROM events
3WHERE name IN ('terminal.connect.start', 'auth.biometric.success',
4               'terminal.connect.done', 'terminal.input.submit')
5  AND ts >= datetime('now', '-7 days')
6GROUP BY name;

步驟 N 的轉換率 = 步驟 N 的事件數 / 步驟 N-1 的事件數。流失率 = 1 - 轉換率。

能做的

• 每步事件計數（單表 GROUP BY）
• 按 source.version 或 source.platform 分群（加 WHERE 條件）
• 按天/按週看趨勢（strftime 分桶 + GROUP BY）

做不到的

• Session 級轉換率：「同一個 session 完成步驟 1 到步驟 4 的比例」需要 JOIN 同 session 的多個事件、跨所有 session 聚合。SQLite 能做這個 JOIN，但在大量 session 時效能不足。
• 步驟間耗時：「使用者在步驟 1 和步驟 2 之間等了多久」需要 self-join on session_id + timestamp 差值計算。
• 漏斗順序驗證：確認使用者是按 1→2→3→4 順序完成、不是跳步。

PostgreSQL 層：Session 級 funnel

PostgreSQL backend 提供 window function 和高效 JOIN，能做完整的 session 級 funnel 分析。

 1WITH session_steps AS (
 2  SELECT session_id, name,
 3         ROW_NUMBER() OVER (PARTITION BY session_id ORDER BY ts) as step_order
 4  FROM events
 5  WHERE name IN ('terminal.connect.start', 'auth.biometric.success',
 6                 'terminal.connect.done', 'terminal.input.submit')
 7    AND ts >= NOW() - INTERVAL '7 days'
 8),
 9session_max_step AS (
10  SELECT session_id, MAX(step_order) as reached
11  FROM session_steps
12  GROUP BY session_id
13)
14SELECT reached, COUNT(*) as sessions
15FROM session_max_step
16GROUP BY reached
17ORDER BY reached;

新增能力

• Session 級轉換率：每個 session 到達了哪一步、在哪一步流失
• 步驟間耗時：LAG window function 計算相鄰步驟的 timestamp 差值
• 漏斗順序驗證：用 ROW_NUMBER + CASE 確認步驟順序
• Cohort 分群的 funnel：按使用者註冊日期 / 版本 / 平台分群看不同 cohort 的 funnel 差異

JSONL 匯出後的臨時分析

Collector 的 monitor export --format=jsonl 可以匯出事件為 JSONL 格式。匯出後用 grep + jq 做一次性的臨時分析：

1for step in terminal.connect.start auth.biometric.success terminal.connect.done terminal.input.submit; do
2  count=$(grep "\"name\":\"$step\"" exported-events.jsonl | wc -l)
3  echo "$step: $count"
4done

JSONL 臨時分析適合「快速看一眼大概數字」的場景。持續性的 funnel 監控應該用 SQLite 或 PostgreSQL 的 SQL 查詢，結果穩定且可重現。

自架 vs 商業方案

自用工具場景下，SQLite 層的每步事件計數通常足夠。商業產品需要 session 級分析時，PostgreSQL 層的 SQL 能力和商業方案的分析能力在功能上對等，差異在 UI 和設定便利性。

下一步路由

• Funnel 分析的完整方法論 → Funnel analysis
• 事件設計如何影響分析品質 → 行為事件設計
• 功能分層定義 → 功能分層與 Backend 選擇
• 去識別化是分析的入場條件 → 模組七 資安與隱私

本文是跨 vendor migration playbook、cross-link 到 MySQL 跟 PostgreSQL。本文是 Migration playbook methodology Type A 的標準形態實證。

三類 SQL dialect diff sample：先看具體差距

 1-- 1. Auto increment / sequence
 2-- MySQL
 3CREATE TABLE users (id INT AUTO_INCREMENT PRIMARY KEY);
 4-- PostgreSQL
 5CREATE TABLE users (id SERIAL PRIMARY KEY);
 6-- 或 PG 10+:
 7CREATE TABLE users (id INT GENERATED ALWAYS AS IDENTITY PRIMARY KEY);
 8
 9-- 2. String concatenation
10-- MySQL: CONCAT(a, b) 或 a || b 在 ANSI mode
11SELECT CONCAT(first_name, ' ', last_name) FROM users;
12-- PostgreSQL: a || b 或 CONCAT(a, b)
13SELECT first_name || ' ' || last_name FROM users;
14-- 注意: PostgreSQL 對 NULL || x = NULL、MySQL CONCAT 對 NULL 處理不同
15
16-- 3. UPSERT
17-- MySQL
18INSERT INTO users (id, name) VALUES (1, 'Alice')
19ON DUPLICATE KEY UPDATE name = VALUES(name);
20-- PostgreSQL (9.5+)
21INSERT INTO users (id, name) VALUES (1, 'Alice')
22ON CONFLICT (id) DO UPDATE SET name = EXCLUDED.name;
23
24-- 4. Index hint / FORCE INDEX
25-- MySQL
26SELECT * FROM orders FORCE INDEX (idx_created_at) WHERE created_at > '2025-01-01';
27-- PostgreSQL: 沒對應 syntax、依賴 planner + statistics
28-- 必要時用 enable_seqscan=off 或 pg_hint_plan extension
29
30-- 5. JSON path
31-- MySQL 5.7+
32SELECT data->'$.name' FROM events;
33-- PostgreSQL
34SELECT data->'name' FROM events;
35SELECT data->>'name' FROM events;  -- 取出 text

5 個 sample 看出 MySQL → PostgreSQL 主要工作是 SQL dialect translation；不是 5-10 個函數差、是 跨整個 application SQL surface 的 audit + 改寫。對應 diff dimension audit 結果：

主導維度 Schema = High、走 Type A 6-phase playbook 標準結構。

Phase 0：rule audit + SQL surface 盤點

 1-- 1. 列所有 stored procedure
 2SELECT routine_schema, routine_name, routine_type
 3FROM information_schema.routines
 4WHERE routine_schema NOT IN ('mysql', 'sys', 'information_schema', 'performance_schema');
 5
 6-- 2. 列所有 trigger
 7SELECT trigger_name, event_object_table, action_statement
 8FROM information_schema.triggers;
 9
10-- 3. 列所有 view
11SELECT table_name, view_definition
12FROM information_schema.views;
13
14-- 4. 列所有 index 含 prefix length
15SHOW INDEX FROM users;
16-- PostgreSQL 對 prefix index 處理不同、要逐個 audit

Audit 主要產出三類清單：

• Direct port：標準 SQL feature、PG 直接接受
• Translate：MySQL-specific syntax、需要改寫（UPSERT / CONCAT NULL 行為 / index hint）
• Refactor：MySQL-specific behavior（auto_increment session-level / SELECT FOUND_ROWS / GROUP BY 寬鬆 / TEXT 隱性 cast）— 不能直接 port、application code 也要改

Phase 1：schema 對位

Schema 對位表存版控、application code refactor 時對照。

Phase 2：Translation pipeline（3-tier 跟 Splunk → Elastic 類似）

Tier 1：vendor / community tool

1# pgloader：成熟工具、cover ~70-80% schema + data
2pgloader mysql://user:pass@mysql-host/dbname \
3         postgresql://user:pass@pg-host/dbname
4
5# 或 AWS DMS（managed、適合 RDS / Aurora target）
6# DMS task: Full Load + CDC

Tier 2：自家 SQL refactor

對 ORM 不能 cover 的 raw SQL：

• Manual grep application code 找 auto_increment / ON DUPLICATE KEY / FORCE INDEX / FOUND_ROWS() / CONCAT NULL
• 寫 codemod / lint rule、CI 強制 check（PG-incompatible SQL block PR）

Tier 3：tricky case manual

例：MySQL SELECT * FROM t1, t2 WHERE t1.id = t2.id GROUP BY t1.id（implicit GROUP BY 寬鬆）— PG 嚴格 GROUP BY 必須 list 所有 non-aggregate column；application code refactor 必要。

Phase 3：Parallel run

雙寫 + 雙讀比對 1-2 個月：

1Application ──→ MySQL (write + read primary)
2            └─→ PostgreSQL (write only + read shadow)
3                                    ↓
4                            Diff checker (latency / result diff)

pt-table-checksum (MySQL) + 自家 checksum scanner 對 sample table 跑 daily checksum、找 schema 對位錯。

Phase 4：Cutover

• 設 application maintenance window（30 分鐘）
• Drain MySQL write、等 last LSN propagated to PG
• Application switch connection string → PG
• 解除 maintenance、monitor 24-48 hours

Phase 5：Cleanup

• MySQL read-only 1-2 週（fallback window）
• 之後 stop replication、decommission MySQL

Production 故障演練

Case 1：Auto_increment vs SERIAL 跨 transaction 行為差

徵兆：cutover 後某 batch job 跑得比 MySQL 慢 5-10x、PG log 顯示 sequence 競爭。

根因：MySQL AUTO_INCREMENT 取值受 innodb_autoinc_lock_mode 控制（8.0 預設 mode=2 interleaved 可並行、mode=0 才是 table-level lock；詳見 Lock contention）、PG SERIAL 是 sequence-level non-transactional；mode=0 場景跟 PG SERIAL 差異最大、mode=2 跟 PG SERIAL 行為較接近（皆可亂號、皆可並行）。

修法：

1. 改 UUID v7 / bigserial：消除 sequence 競爭
2. bigserial + cache：CREATE SEQUENCE ... CACHE 100、batch 預取 100 個 ID 降 contention
3. 批量 insert 改 COPY：COPY t FROM STDIN 是 PG 對 batch 最快路徑

Case 2：Charset / collation 跑出 unicode 異常

徵兆：cutover 後某些用戶名 / 中文文字 query 對不到結果、SELECT * WHERE name = '張三' 返回空。

根因：MySQL default utf8mb3（3-byte UTF-8、不能存 emoji / 部分 unicode）、PG default UTF8 全 unicode；資料遷移時 MySQL 端的 utf8mb3 column 帶到 PG 後 bytes 不變 但 collation rule 變；string comparison 結果差。

修法：

1. Pre-migration audit：MySQL 強制 utf8mb4、avoid utf8mb3 data
2. Collation 對位：MySQL utf8mb4_unicode_ci → PG LC_COLLATE = 'C.utf8' 或 ICU collation
3. Application encoding contract：明示 UTF-8 全範圍、不接受 utf8mb3-only client

Case 3：Case sensitivity 反轉

徵兆：cutover 後 application query SELECT * FROM users 報錯 relation does not exist；但 SELECT * FROM "Users" works。

根因：MySQL Linux default table name case-sensitive、Windows case-insensitive、配置 lower_case_table_names 影響；PG all identifier folded to lowercase unless quoted。MySQL on macOS 開發環境是 case-insensitive、PG 嚴格 case-sensitive、application code 端可能用 mixed case。

修法：

1. Schema migration 階段強制 lowercase：所有 table / column name 統一 lowercase
2. Application code refactor：grep raw SQL 找 mixed case identifier、改 lowercase
3. ORM 端設定 naming_strategy：JPA / Hibernate 等明示 lowercase mapping

Case 4：Replication 行為差、CDC pipeline 失效

徵兆：MySQL 端 binlog-based CDC（Debezium MySQL connector）跑得好好的、cutover 後 PG 端要重建 CDC pipeline、初期 1-2 週 message 模式異常。

根因：MySQL binlog row format vs PG logical replication slot 完全不同 protocol；Debezium 對兩家連接器是 獨立 binary、message schema 部分對等但不直通。

修法：

1. Pre-cutover 建 PG 端 CDC：Debezium PG connector 提前部署、初期跟 MySQL CDC 並存比對
2. Schema registry 同步：Avro schema 從 MySQL 端 export、註冊 PG 端 connector 用同 schema
3. Consumer 端 idempotent：cutover 期間 dual-source、consumer 必須 idempotent 避免 duplicate

Case 5：FULLTEXT INDEX 對應 tsvector、application search broken

徵兆：cutover 後 application 全文搜尋功能失效、MATCH(name) AGAINST('xxx') 不被 PG 認；application 端 raw SQL 對 search 寫死。

根因：MySQL FULLTEXT INDEX + MATCH ... AGAINST syntax PG 不支援；PG 用 tsvector + ts_rank + to_tsquery、概念對等但 syntax 完全不同。

修法：

1. Pre-migration：列 application 用到的 fulltext search 場景、改寫成 tsvector pattern
2. 大型 search 改 Elasticsearch / Meilisearch：fulltext 是專門 search engine 的本職、不該用 RDBMS 解
3. 降級為 LIKE：簡單 case WHERE name ILIKE '%xxx%'、performance 較差但相容性好

Capacity / cost

Migration 主要 cost 在 application code refactor + dual-write window operational、不是 DB itself。

整合 / 下一步

跟 PostgreSQL → Aurora migration 串接

部分組織走 MySQL → PostgreSQL → Aurora 兩段：

• 先 MySQL → self-managed PostgreSQL（schema 對位 + application 改）
• 穩定後 self-managed PostgreSQL → Aurora（operational simplification）

不要一次跑 MySQL → Aurora PostgreSQL compat、認知負擔太大、failure mode 互相干擾。

跟 Logical Replication + Debezium 對位

PG 端 CDC pipeline 在 cutover 完成後立刻可用；可作為 downstream CDC 重建 的契機、設計 outbox pattern 更穩。

下一步議題

• MySQL 8 vs PostgreSQL 16 feature gap：MySQL 8 加了 CTE / window function / generated column；2025+ feature parity 漸高、migration ROI 評估會變
• Reverse migration（PG → MySQL）：少見、通常是 application 端 dependency lock-in（用了 MySQL-specific stored procedure）
• MariaDB → PostgreSQL：跟 MySQL → PG 類似、MariaDB 部分 syntax 略接近 PG（如 RETURNING）

相關連結

• Source / target vendor：MySQL / PostgreSQL
• 後續路線：PostgreSQL → Aurora
• 平行 migration playbook：Splunk → Elastic（同為 Type A 高 schema 差）
• Methodology：Migration playbook methodology（本文驗證 Type A 標準形態）

本文是 PostgreSQL overview 的 implementation-layer deep article。Overview 已說明 PostgreSQL 在 OLTP 譜系的定位、本文聚焦 Patroni-based HA 的 lifecycle 設計 — 從正常運作到 failover 完成的 5 段、每段配置 + failure mode + recovery。

Failover lifecycle：5 段不是一條曲線

PostgreSQL 原生沒有 auto-failover；primary 掛了、application 卡死、SRE 手動 promote standby — 整個過程通常 5-30 分鐘。Patroni 把這條鏈拆成 自動化的 5 段 lifecycle、每段有自己的 trigger、配置、失敗模式：

每段都有獨立配置、不是「設一個 timeout 就好」。後面分段展開。

Stage 1：Detection — DCS heartbeat 跟 TTL

 1# patroni.yml 核心配置
 2scope: myapp-pg-cluster
 3namespace: /db/
 4name: pg-node-1                                # 跟 hostname 一致
 5
 6etcd:
 7  hosts: etcd1:2379,etcd2:2379,etcd3:2379       # DCS quorum
 8  protocol: https
 9
10bootstrap:
11  dcs:
12    ttl: 30                                     # leader lock TTL
13    loop_wait: 10                               # patroni 主循環間隔
14    retry_timeout: 10                           # DCS retry 上限
15    maximum_lag_on_failover: 1048576            # standby 落後 1MB 內才能 promote
16    synchronous_mode: false                     # async / sync 取捨

關鍵直覺：

• TTL (30s) = leader 失聯多久才被視為 dead。設太短（< 15s）會把 transient network jitter 當 dead；設太長（> 60s）unavailability 拖長
• loop_wait + retry_timeout < TTL：Patroni 必須在 TTL 內成功跟 DCS 互動 N 次、loop_wait=10 + retry_timeout=10 給每個循環 20s buffer
• maximum_lag_on_failover：standby WAL 落後超過這個閾值就 不參與 election；防止「promote 一個落後 5 分鐘的 standby」資料丟失

Stage 2：Election — DCS quorum + watchdog 防 split-brain

1watchdog:
2  mode: required                                # required / automatic / off
3  device: /dev/watchdog
4  safety_margin: 5

Election 期間最大風險是 split-brain — network partition 下、舊 leader 還活著但跟 DCS 斷線；新 leader 從 standby 升上來、application 同時連兩個 PostgreSQL 寫。資料 divergence 後 無法自動 reconcile。

防護機制兩層：

1. DCS quorum：etcd / Consul 至少 3 node、過半 quorum 才能寫 leader key — 少數派 partition 無法 elect 新 leader
2. Watchdog (Linux kernel)：required mode 強制 — Patroni 必須定期 poke /dev/watchdog、若 Patroni 自己掛或被 OS 凍結、kernel 自動 reboot 整台機器、避免舊 leader 在 DCS 失聯後繼續接寫

Watchdog required 是 production-grade 的硬要求 — automatic / off 在 split-brain 場景下無法防護。

Stage 3：Promotion — pg_ctl + replication slot 切換

新 leader 寫 DCS key 成功後、Patroni 自動執行：

1# Patroni 內部、不要手動跑
2pg_ctl promote -D /var/lib/postgresql/data
3# postgresql.auto.conf 移除 primary_conninfo
4# postgresql.auto.conf 重新計算 timeline ID
5# 啟動接寫

Promotion 期間關鍵議題：

• timeline divergence：新 leader 開新 timeline ID（從 leader 失聯時的 LSN 開始）；其他 standby 需要 pg_rewind 把自己的 WAL fork 點對齊新 timeline
• replication slot 處理：舊 leader 上的 replication slot 在 DCS 中已 stale、新 leader 重建 slot；如果 logical replication consumer 沒 idempotent、會 replay 部分訊息
• promotion latency：通常 3-10 秒（pg_ctl 本身 < 5s、加 DCS 寫確認）

Stage 4：Reconfiguration — client routing 切換

PostgreSQL 自己升 leader 還不夠、application 不知道；要靠前端 routing 層轉發。三種典型 pattern：

1[client] → [HAProxy / pgBouncer] → [pg-node-1 (leader)]
2                                 → [pg-node-2 (standby, read)]
3                                 → [pg-node-3 (standby, read)]

Patroni REST API 暴露 /leader / /replica / /health endpoint、HAProxy 用 health check 跑這些 endpoint：

1# haproxy.cfg
2backend pg-write
3  option httpchk OPTIONS /leader
4  http-check expect status 200
5  server pg-node-1 pg-node-1:5432 check port 8008
6  server pg-node-2 pg-node-2:5432 check port 8008 backup
7  server pg-node-3 pg-node-3:5432 check port 8008 backup

Reconfiguration 期間關鍵延遲：

• HAProxy health check 間隔（預設 2s）+ failure threshold（預設 3 次）= ~6s 切換感應
• PgBouncer 不主動 health check、要靠 application 端 retry 跟 connection drop 觸發重連
• 整個 reconfiguration 端到端通常 10-20s（含 PostgreSQL promotion 時間）

Stage 5：Recovery — pg_rewind 跟 base backup 取捨

舊 leader 恢復後變 standby，但 WAL 已 divergence — 必須選一條 recovery path：

• pg_rewind：rewind 舊 leader WAL 到分歧點、重新接 streaming replication；條件 = 分歧 WAL 量小（< 幾 GB）且 timeline 可對齊
• 重 base backup：用 pg_basebackup 從新 leader 拉完整 base + WAL；條件 = 任何時候都可、但時間長（TB 級 1-4 小時）

Patroni 預設嘗試 pg_rewind、失敗才退 base backup。production 配置：

1postgresql:
2  use_pg_rewind: true
3  remove_data_directory_on_rewind_failure: true   # rewind 失敗自動清 data dir、再 base backup
4  remove_data_directory_on_diverged_timelines: true

Production 故障演練

Case 1：Split-brain due to DCS partition

徵兆：兩個 PostgreSQL node 都在接寫、application 大量寫入 conflict / unique constraint violation。

根因：DCS（etcd）partition — 兩個 etcd node 在 partition 兩側、都自認 quorum；其實是 split-vote、兩邊都不應該。Patroni 在兩邊各 elect 一個 leader。

修法：

1. DCS 必須奇數 node（3 / 5 / 7）、過半 quorum 嚴格 enforce
2. DCS 部署跨 AZ / region 時、quorum size 要考慮 partition 機率（3 AZ 各 1 node 是 production 最低標）
3. Watchdog required mode 是最後一道閘門 — DCS partition 加 quorum 失靈時、watchdog 強制 reboot 失聯 node

Case 2：Standby 落後太多、無法 failover

徵兆：primary 失聯後、Patroni log 顯示 Following members have lag greater than maximum_lag_on_failover、所有 standby 都被拒 promote、cluster unavailable。

根因：maximum_lag_on_failover 設 1MB、但 standby replication lag 累積到 50MB（write-heavy workload + slow disk on standby）。安全機制觸發、但代價是 無 standby 可升、需要人工降低門檻或等 standby catch up。

修法：

1. 預防：standby 容量 / IO 對齊 primary、避免 lag 累積；prometheus alert pg_replication_lag_bytes > 10MB 觸發前 catch
2. 臨時：手動 patronictl edit-config 把 maximum_lag_on_failover 暫時拉到 50MB、接受可能丟 50MB worth of writes、換 availability
3. 長期：sync replication（一個 standby 強制同步）、保證至少一個 standby zero-lag

Case 3：Promotion 後 application connection storm

徵兆：failover 完成後 30-120 秒內、application log 大量 connection refused / password authentication failed、application 自己 retry storm。

根因：新 leader 剛 promote、PostgreSQL max_connections 容量還在 warm up（shared memory / cache 未 prime）、application 同時湧入大量 connection request；應用 retry 不夠 jitter、queue 堆積。

修法：

1. Application 用 exponential backoff with jitter、不要 immediate retry
2. PgBouncer / connection pool 限制每 application instance 對 PG 的 connection 上限、不直連 PG
3. 預先在 standby 跑 pg_prewarm 把熱表 cache 預熱、promotion 後 cache miss 不爆

Case 4：pg_rewind 失敗、退到 base backup 沒做

徵兆：舊 leader 恢復後、Patroni log 顯示 pg_rewind failed、舊 leader 一直 STARTING、無法重接 cluster；SRE 手動跑 pg_basebackup 才恢復。

根因：remove_data_directory_on_rewind_failure: false（預設）— rewind 失敗時 Patroni 不主動清 data dir、需要 SRE 手動處理；運維沒 runbook、卡在這步幾小時。

修法：

1. Production 設 remove_data_directory_on_rewind_failure: true + remove_data_directory_on_diverged_timelines: true、讓 Patroni 自動 fallback
2. data dir 跑在獨立 PV / disk、清掉風險可控（不要跑 root disk）
3. 容量規劃：base backup 時間預估納入 RTO（TB 級 base backup 1-4 小時、不是 RTO 30 分鐘所能承受）

Case 5：Watchdog 觸發整機 reboot、誤殺

徵兆：production server 在無故障時 unexpected reboot、dmesg 顯示 watchdog: BUG: soft lockup。

根因：Patroni 主循環因 etcd 短暫慢回應卡住 60+ 秒、kernel watchdog 觸發 reboot；但實際 PostgreSQL 沒 hang、是 Patroni-watchdog 鏈過敏。

修法：

1. safety_margin 設大一點（10-15）、給 Patroni loop_wait 抖動空間
2. etcd 跟 Patroni 部署在低延遲 network 內（同 AZ < 5ms）、跨 region etcd 不建議
3. watchdog device 用 softdog（軟體模擬）vs 硬體 watchdog、debug 時 softdog 容易觀察

容量規劃

整合 / 下一步

跟 PgBouncer 整合

PgBouncer 不主動感知 Patroni failover、要靠：

1. HAProxy 在 PgBouncer 上層：HAProxy 跑 Patroni health check、PgBouncer connection 重新路由
2. PgBouncer reload：failover 後 SRE / automation 跑 pgbouncer -R、強制重連 backend
3. Connection pool drain：application 端 connection pool 設 pool_lifetime_max=5min、舊 connection 自然汰換

跟 cert-manager（TLS rotation）

Patroni REST API 跟 PostgreSQL streaming replication 都用 TLS、cert rotation 不能停服務：

1. cert-manager 自動換證後、Patroni 跟 PostgreSQL 都需要 reload（不是 restart）
2. patronictl reload <cluster> 不會觸發 failover、只 reload config
3. PostgreSQL pg_ctl reload 是 SIGHUP、平滑載入新 cert

跟 backup / PITR

Patroni 不管 backup — 但 standby promotion 後、WAL archive 必須跟新 leader 的 timeline 對齊：

1. WAL archive 命令模板含 %t（timeline）：archive_command = 'wal-g wal-push %p'
2. Backup tool（pgBackRest / WAL-G）支援 timeline 切換、archive 不會中斷
3. 詳見 PITR + WAL archiving deep article

下一步議題

• Multi-region Patroni：跨 region 部署的 DCS quorum 設計、跟單 region 的取捨完全不同
• PostgreSQL 16+ streaming replication slot 持久化：簡化 standby promotion 後 logical consumer 重連
• 跟 Kubernetes operator 整合：Patroni 跑在 K8s 時、StatefulSet + pod identity + DCS 部署模式

相關連結

• 上游 vendor 頁：PostgreSQL
• 上游 chapter：High Concurrency Access — connection / replication / HA 全鏈
• 平行 deep article：pgBouncer 配置 / Vault Dynamic Credential
• Methodology：Vendor 深度技術文章的寫作方法論

本文是 PostgreSQL overview 的 implementation-layer deep article。Overview 已說明 PG 在 OLTP 譜系的定位、本文聚焦 streaming replication topology — 從 single primary 到 multi-standby 部署的 3 個 trade-off 軸 + LSN + replication slot 機制。

Replication 的 3 個 trade-off 軸 + mode 選擇

PG streaming replication mode 選擇看起來是「async 還是 sync」、實際是 3 個獨立 trade-off 軸的組合、async / sync / quorum-based sync 是這些軸的常見組合 名稱：

跟這三軸獨立的、是 replication 機制本身的可維護性：

• LSN（Log Sequence Number）：PG 用全域 byte offset 標 WAL 進度、所有 standby 同步用 LSN 對齊、不像 MySQL 早期 binlog position + file 雙欄
• Replication slot：primary 紀錄每個 standby 已接收的 LSN、防 standby 失聯期間 WAL 被清掉、是 streaming replication 的 持久化進度追蹤

跟 MySQL Replication Topology 對比、PG 的 LSN + replication slot 直接內建 standby 進度追蹤、不像 MySQL 5.7- 要靠 binlog position + GTID 雙機制；但 slot 是 primary 紀錄、orphan slot 是 PG-specific 議題（slot 留 WAL 直到 standby 重連、standby 永久失聯 → primary disk 爆）。

Async streaming：default + 高 throughput 的代價

Async 是 PG 預設、行為：

1. Primary 寫 WAL 進 pg_wal/ 目錄、commit、回應 client OK
2. WAL sender process 把 WAL stream 給 standby
3. Standby WAL receiver 寫 standby 的 pg_wal/、startup 進程 redo 套用

Trade-off：

• Durability：primary commit 後 standby 還沒收 → primary 永久故障 → data loss（已 commit 的 transaction 在 standby 不存在）
• Latency：client 寫入延遲 = primary 自身 fsync WAL 的時間（fsync=on + synchronous_commit=on 預設、通常 < 1ms 在 SSD / NVMe）
• Consistency：standby 可能 lag、application 讀 standby 會 stale；用 pg_stat_replication.write_lag / flush_lag / replay_lag 看

配置：

1# postgresql.conf on primary
2wal_level = replica          # 至少 replica（logical 是 superset）
3max_wal_senders = 10         # 並行 WAL sender process 數（依 standby 數量）
4wal_keep_size = 1024MB       # WAL 保留量（slot 為主、但 backup buffer）
5synchronous_commit = on      # 預設、primary 自己 fsync WAL
6# synchronous_standby_names 留空 = async

適用：

• 主流選擇（90% 場景）
• Failover loss 在容忍範圍（多數 web 應用容忍 1-2 秒 data loss）
• Read scaling 為主要 driver、絕對 durability 非首要

Sync streaming：至少一個 standby flush WAL 才 commit

Sync mode 在 async 基礎上加 primary 等指定 standby flush WAL 才回 client：

1. Primary 寫 WAL、send to standby
2. Standby 收到 WAL、寫進 pg_wal/、fsync、回 ack
3. Primary 等 ack → commit → 回 client

synchronous_commit 有 5 個 level、不是 binary：

配置（synchronous）：

1synchronous_commit = on
2synchronous_standby_names = 'FIRST 1 (standby1, standby2)'
3# 'FIRST 1' = 第一個 active standby ack 即可
4# 'ANY 2 (s1, s2, s3)' = 任 2 個 ack 即可（quorum-based）

Quorum-based sync：用 ANY N 語法、達到 N 個 ack 就 commit、提高 latency stability（不依賴特定 standby）：

1synchronous_standby_names = 'ANY 2 (standby1, standby2, standby3)'
2# 3 個 standby 中任 2 個 ack 即 commit

適用：

• 金融交易 / 訂單 / payment ledger（不允許 data loss）
• 已有 multi-AZ deploy、replica 物理上可靠
• 可接受寫入延遲 +1-3ms (跨 AZ)

不適用：

• 跨 region sync（RTT 50-200ms）— 寫吞吐砍半、改用 region-local sync + cross-region async
• 寫吞吐 > 50K WPS + 容忍 sub-second loss — async 即可

LSN + Replication Slot：PG 的進度追蹤機制

PG 每個 WAL 寫入都標 LSN（64-bit byte offset）。Standby 紀錄 已收到 / 已 flush / 已 replay 的 LSN、primary 透過 streaming protocol 知道每個 standby 進度。

Replication slot 是 primary 端的 standby 進度紀錄：

1-- 建 physical replication slot（給 streaming replication 用）
2SELECT * FROM pg_create_physical_replication_slot('standby1_slot');
3
4-- 查 slot 狀態
5SELECT slot_name, active, restart_lsn, confirmed_flush_lsn,
6       pg_size_pretty(pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)) AS lag
7FROM pg_replication_slots;

Slot 的核心責任：

• 防 WAL premature deletion：standby 失聯（restart / network blip）、primary 仍保留 slot 對應 LSN 之後的 WAL、standby 重連可繼續 stream
• 無需 base backup re-build：跟沒 slot 的 standby 對比、有 slot 的 standby 失聯後重連、不用重建

Slot 跟 wal_keep_size：

• wal_keep_size（PG 13+）/ wal_keep_segments（< 13）：minimum WAL 保留量、不依賴 slot
• Slot 是 動態保留：直到 slot 的 standby 推進 LSN 才釋放對應 WAL
• 兩者組合：wal_keep_size 是底線、slot 是 standby-specific 動態保留

Standby 配置（用 slot）：

1# standby1 postgresql.conf
2primary_conninfo = 'host=primary.example.com port=5432 user=replication password=...'
3primary_slot_name = 'standby1_slot'   # 用 primary 上預先建的 slot
4hot_standby = on                       # 讓 standby 接受 read query

standby.signal 空檔案在 PG_DATA 內、告訴 PG 這是 standby、進入 recovery mode。

配置 step-by-step（sync streaming + slot）

實務最常見組合：sync streaming + replication slot + cross-AZ replica。

Step 1：Primary 配置

 1# postgresql.conf
 2wal_level = replica
 3max_wal_senders = 10
 4max_replication_slots = 10
 5synchronous_commit = on
 6synchronous_standby_names = 'FIRST 1 (standby1, standby2)'
 7wal_keep_size = 1024MB
 8
 9# pg_hba.conf — 允許 replication 連線
10host replication replication 10.0.0.0/16 scram-sha-256

Restart primary 套用。

Step 2：建 replication user + slot

1CREATE USER replication WITH REPLICATION PASSWORD '...';
2SELECT * FROM pg_create_physical_replication_slot('standby1_slot');
3SELECT * FROM pg_create_physical_replication_slot('standby2_slot');

Step 3：Standby base backup

1# 在 standby 上跑
2pg_basebackup -h primary.example.com -D /var/lib/postgresql/data \
3  -U replication -P -X stream \
4  -S standby1_slot -R
5# -R: 自動生成 standby.signal + primary_conninfo
6# -X stream: 邊 backup 邊 stream 增量 WAL（避免 backup 期間 WAL gap）

Step 4：Standby 啟動

1# standby /var/lib/postgresql/data/postgresql.auto.conf 已有：
2# primary_conninfo = 'host=primary.example.com user=replication password=... application_name=standby1'
3# primary_slot_name = 'standby1_slot'
4
5pg_ctl -D /var/lib/postgresql/data start

Step 5：驗證

1-- Primary: 確認 standby 連上
2SELECT application_name, state, sync_state, write_lag, flush_lag, replay_lag
3FROM pg_stat_replication;
4-- 應顯示 standby1 / streaming / sync / 各 lag
5
6-- Standby: 確認在 recovery + 收到 WAL
7SELECT pg_is_in_recovery(), pg_last_wal_receive_lsn(), pg_last_wal_replay_lsn();

5 個 Production 踩雷

1. Standby lag 暴衝 — Single replay process bottleneck

PG standby 是 single startup process 套用 WAL（不像 MySQL multi-thread replication）、primary 高並發寫入時 standby 跟不上、lag 從 < 100ms 飆到分鐘級。常見觸發：批次 UPDATE / DELETE、大 transaction、index 建立、autovacuum 大量 dead tuple cleanup。

修法：

• Parallel WAL apply（PG 14+）：max_parallel_workers_per_gather 增加 background worker、但仍受 startup process 主導
• 對 read scaling 場景接受 standby lag、application 用 primary read 對 latency-critical query
• Cascading replication 對 high-fan-out 解決 sender CPU bottleneck、但 standby replay 仍 single-thread

監控：pg_stat_replication.replay_lag 是 最後一個 commit 到 standby replay 的時間差、超過 threshold 即告警。

2. Sync standby 失聯時 primary commit 卡住

synchronous_standby_names = 'FIRST 1 (standby1)' + standby1 down → primary commit 等永遠。Application 全部 timeout。

修法：

• 用 ANY N quorum：synchronous_standby_names = 'ANY 1 (standby1, standby2)' — 任一 standby ack 即可
• 設多 standby、防單一失聯
• 監控 sync standby 健康、自動 failover 切 sync mode 到其他 standby（Patroni 自動做）
• 緊急情況：在 primary 跑 ALTER SYSTEM SET synchronous_standby_names = ''; SELECT pg_reload_conf(); 暫時退 async（接受 data loss risk）

3. Orphan replication slot — Primary disk 爆

Standby 失聯（永久故障 / 重 decommission 但忘了 drop slot）、primary slot 持續保留 WAL、pg_wal/ 累積到 disk 滿、primary 也掛。

修法：

• 監控 pg_replication_slots.active — false 持續 > N 小時是警訊

• 監控 slot lag：

  1SELECT slot_name, active,
  2       pg_size_pretty(pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)) AS retained_wal
  3FROM pg_replication_slots WHERE retained_wal > 10GB;

• 設 max_slot_wal_keep_size（PG 13+）— slot 對應 WAL 超過 limit 自動 invalidate slot（standby 之後要 base backup 重來）

• DR runbook 紀錄 standby 退役流程 必須包含 pg_drop_replication_slot('xxx')

4. Cascading replication 雪崩

Topology primary → standby1 → standby2 → ...（每層遞迴 stream）。Standby1 startup process 卡住、後續 standby 都被 block、整條 chain 雪崩。

修法：

• 避免超過 2 層 cascade（primary → tier1 → tier2 是上限）
• 跨 region 用 region-local tier1 + cross-region tier2、不是長 chain
• 真的大規模、改用 binlog server style：Citus / PgCat 等中介、或 logical replication 解耦

5. Failover 後 timeline 分歧

Primary 失敗、standby1 promote 為新 primary、其他 standby（standby2 / 3）原本連舊 primary、必須重新連 standby1。但 PG 用 timeline（每次 promotion 增 1）標 WAL 分支、原 standby 的 timeline 跟新 primary 不同。重連時看到 timeline mismatch、報錯。

修法：

• pg_rewind 工具：對比新 primary 跟舊 standby 的 timeline 分歧點、把舊 standby 上 新 primary 沒有的 WAL 倒退、然後從分歧點重新跟新 primary 同步
• Base backup re-build：對舊 standby 重建 — 慢但保證乾淨
• Patroni 自動處理 pg_rewind / base backup 選擇

容量 / cost 對照

跨 AZ sync 通常加 1-3ms、跨 region 加 50-200ms — 寫密集 workload 跨 region sync 通常不划算、改用 region-local sync + cross-region async chain。

整合 / 下一步

Patroni HA

Patroni 是 PG HA 自動 failover 標準、依賴 DCS（etcd / Consul）+ 本文 replication topology。Patroni 自動：

• 偵測 primary 失聯、promote 適合 standby
• 處理 timeline 分歧（pg_rewind）
• 重配 sync standby（避免 sync standby 失聯卡 primary）

Logical Replication + Debezium

Logical replication + Debezium 是 跟 streaming replication 共用 WAL 但不同 abstraction — logical decoding output event、streaming replication output physical bytes。Logical replication slot 跟 physical slot 共存、各自獨立 retention。

PITR + WAL Archiving

PITR + WAL Archiving 用 archive_command 把 WAL ship 到 S3、跟 streaming replication 並行：

• Streaming：給 活的 standby（real-time read scaling / HA）
• Archive：給 PITR + 新 standby base backup source

兩者使用同一 WAL stream、不衝突。

Connection 路由（PgBouncer + read/write split）

PgBouncer 不做 read/write split（transaction pool 不看 SQL）。Read replica routing 通常用 application-level 或 HAProxy 監控 standby health。

跟 MySQL Replication Topology 對比

兩者 high-level 對等、低層機制有顯著差異。詳見 MySQL Replication Topology。

相關連結

• PostgreSQL vendor overview
• PG Patroni HA（HA failover、依賴本文 replication topology）
• PG Logical Replication + Debezium（不同 abstraction、共用 WAL）
• PG PITR + WAL Archiving（streaming + archive 並行）
• PG PgBouncer（connection pool、不做 read/write split）
• MySQL Replication Topology（sibling、不同機制）
• quorum 卡片 / stale-read 卡片 / eventual-consistency 卡片
• 官方：PG Streaming Replication / pg_basebackup

本文是 PostgreSQL overview 的 implementation-layer deep article。Overview 已說明 PG 在 OLTP 譜系的定位、本文聚焦 online schema change — 先看 PG ALTER 哪些已 fast catalog-only、再看 pg_repack / pg-osc 何時必要。

跟 MySQL 不同：PG 大量 schema change 內建 fast catalog-only 行為、不必走 ghost table tool。MySQL 對應的 gh-ost / pt-online-schema-change 之於 PG 是 少數場景才需要的 escape hatch、不是 standard practice。

寫作 OSC 時必須 先看 PG 自身 ALTER 行為、確認真的需要再上 pg_repack / pg-osc — 否則徒增複雜度。

PG ALTER TABLE 的 fast / slow 分類

1-- ALTER TABLE 的操作大致三類

類 A：Fast catalog-only（< 1 秒、metadata 改）

PG 9.4+ / 11+ 多數 ALTER 已 catalog-only：

• ADD COLUMN col TYPE NULL DEFAULT NULL — 直接 metadata、不 rewrite
• ADD COLUMN col TYPE NOT NULL DEFAULT <constant>（PG 11+）— optimizer 把 default 存在 metadata、舊 row read 時動態返回 default、不 rewrite
• DROP COLUMN — metadata 標 dropped、實際 row 不 rewrite（VACUUM 之後逐步清理）
• ALTER COLUMN ... SET DEFAULT <constant> — metadata
• RENAME COLUMN / RENAME TABLE — metadata
• ADD CONSTRAINT ... NOT VALID — 標記 constraint 不 validate、之後 VALIDATE CONSTRAINT 才 scan
• ALTER COLUMN ... TYPE 同 binary-compat 類型（VARCHAR(10) → VARCHAR(20)、TEXT → VARCHAR 等）— catalog-only

這類 ALTER 直接跑、不必任何工具。

類 B：Lock heavy（rewrites table、production 慎用）

需要 rewrite 整張 table、ACCESS EXCLUSIVE lock 整個 ALTER 期間：

• ALTER COLUMN ... TYPE binary 不相容類型（INT → BIGINT 永遠 rewrite、TEXT → INT 也是）— 雖然語意「擴大」、底層 4-byte 跟 8-byte storage 不同、全表 rewrite + ACCESS EXCLUSIVE 不可省
• ALTER COLUMN ... SET NOT NULL 對既有 nullable column（要 scan 整 table）
• ALTER COLUMN ... DROP IDENTITY
• ALTER TABLE ... SET TABLESPACE

這類 ALTER 對大表 production 不能直接跑、要 ghost table tool。

類 C：Concurrent index / online operation（無 table lock）

• CREATE INDEX CONCURRENTLY — 不 lock 寫入、background build、慢但安全
• REINDEX INDEX CONCURRENTLY（PG 12+） — 同上
• DROP INDEX CONCURRENTLY — 短 ACCESS EXCLUSIVE lock 只在最後 swap

何時需要 ghost table tool

只在以下場景才需要 pg_repack / pg-osc：

1. Rewrite-required type change（類 B ALTER COLUMN TYPE）對大表
2. VACUUM FULL 替代：pg_repack 比 VACUUM FULL 安全（不 lock 整表）
3. Bloat 重組：大表 dead tuple 累積、想完整 rewrite

對「add column」「drop column」「create index」等場景 PG 內建 fast 已夠、不必 ghost table tool。

Tool 1：pg_repack — Trigger-based + 雙 table swap

pg_repack 是 PG community 標準 online table rewrite 工具：

1pg_repack -h primary.example.com -p 5432 -d production -U postgres \
2  --table=orders --no-superuser-check

Mechanism：

1. CREATE repack.table_<oid> 跟原表同 schema
2. 在原表加 3 個 trigger：INSERT / UPDATE / DELETE → 寫入 log table repack.log_<oid>
3. 從原表 INSERT INTO repack.table_<oid> SELECT * FROM original 複製 row
4. 邊複製邊 apply log table 紀錄的變更
5. 切換：rename 原表 → original_old、rename repack.table_ → original（atomic）
6. Drop 舊原表跟 trigger / log

Trade-off：

• Trigger overhead：每個 primary 寫入加 trigger 執行（10-30% 寫吞吐降）
• FK 處理：需要 drop & re-create FK referencing original table（pg_repack 自動處理但有 lock window）
• 適用 PG-version 綁定 — pg_repack 13 不能對 PG 14 cluster 跑

配置：

1-- Primary 安裝
2CREATE EXTENSION pg_repack;

1# Repack orders
2pg_repack -d production --table=orders
3# 監控 lock：另一 session 跑 SELECT * FROM pg_stat_activity

Tool 2：pg-osc / pg-online-schema-change — WAL-shipping style

pg-osc（Shayon Mukherjee、2023）是較新的工具、模仿 gh-ost mechanism：

Mechanism：

1. 用 logical replication slot 從 primary WAL stream 變更
2. CREATE shadow table + 套 ALTER 變更
3. Stream WAL event 同步 shadow table（不靠 trigger）
4. 完成後 swap

Trade-off：

• Primary 寫入 overhead：0（WAL 已存在）
• 比 pg_repack 較新（社群驗證度低）
• 適合 trigger overhead 不可接受 的高吞吐 production

配置：

1# 用 gem install
2gem install pg_online_schema_change
3
4# Run
5pg-online-schema-change perform \
6  --alter-statement="ALTER TABLE orders ADD COLUMN status VARCHAR(20)" \
7  --schema=public \
8  --dbname=production \
9  --host=primary.example.com

配置 step-by-step（pg_repack 為主）

實務多數 PG OSC 用 pg_repack。pg-osc 是 high-write-throughput escape hatch。

Step 1：安裝 + 確認版本

1-- 安裝 pg_repack（versioned）
2CREATE EXTENSION pg_repack;
3SELECT * FROM pg_available_extensions WHERE name = 'pg_repack';
4-- 確認 installed_version 跟 PG major version 對齊

Step 2：跑 pg_repack

1pg_repack -h primary -d production -U postgres \
2  --table=orders \
3  --jobs=4 \                       # 並行 worker
4  --wait-timeout=60 \              # 等 lock 超時（秒）
5  --no-kill-backend                # 不主動 kill 卡 lock 的 query

Step 3：監控

1-- 看 pg_repack 進度
2SELECT pid, query, state, wait_event_type, wait_event
3FROM pg_stat_activity
4WHERE query LIKE '%repack%';
5
6-- 看 lock 狀態
7SELECT * FROM pg_locks WHERE relation IN (
8  SELECT oid FROM pg_class WHERE relname IN ('orders', 'repack.table_xxx')
9);

Step 4：驗證

1-- 跑完後對比 row count + 抽樣 query
2SELECT count(*) FROM orders;
3-- 跟 pg_repack 之前 count 對比

5 個 Production 踩雷

1. ALTER 直接跑沒看是不是 fast 變 lock heavy

ALTER TABLE orders ADD COLUMN status VARCHAR(20) NOT NULL DEFAULT 'pending' — 預期 catalog-only（PG 11+）、但若 PG 10 跑這個就會 rewrite 整表、ACCESS EXCLUSIVE lock 幾小時。

修法：

• 寫 schema migration 前 確認 PG version
• 看 PG ALTER doc、each subcommand 標 Note 段是否 fast
• Production 跑前 staging 測 + 監控 pg_stat_activity lock wait

2. VACUUM FULL 誤用 — Production downtime

VACUUM FULL 等於「rewrite 整表 + ACCESS EXCLUSIVE lock」。Production 跑 = 表變 unavailable 幾分鐘到幾小時。

修法：

• 永遠用 pg_repack 取代 VACUUM FULL（除非 maintenance window）
• 對 bloat 議題、定期跑 pg_repack
• autovacuum tuning 第一優先（autovacuum-tuning 詳細）

3. pg_repack version mismatch

PG cluster 升 14、但 pg_repack extension 還是 13 版本。試 ALTER 跑 pg_repack 命令、ERROR: program "pg_repack 14.x" does not match installed extension "pg_repack 13.x"。

修法：

• 升 PG cluster 後 立即 ALTER EXTENSION pg_repack UPDATE
• 若 pg_repack 還沒釋出對應 PG 版本（早期升級）、暫時用 pg-osc 替代或等待
• 升級 runbook 紀錄 pg_repack 是 必同步升級的 extension

4. CREATE INDEX CONCURRENTLY 失敗清理

CREATE INDEX CONCURRENTLY 跑到一半被 cancel（用戶 Ctrl-C / connection drop）、產生 invalid index：

1SELECT indexrelid::regclass FROM pg_index WHERE NOT indisvalid;
2-- 顯示一個 idx_orders_status_invalid

Invalid index 仍佔 disk、但 optimizer 不會用。

修法：

• 跑 DROP INDEX CONCURRENTLY idx_orders_status_invalid
• 之後重新 CREATE INDEX CONCURRENTLY
• 避免在 connection 不穩的 session 跑長時間 CREATE INDEX CONCURRENTLY、改用 cron 或 deploy pipeline

5. Generated stored column 不能 online ADD

ADD COLUMN total NUMERIC GENERATED ALWAYS AS (price * qty) STORED — stored generated column 必須 rewrite 整表計算 column value、不是 catalog-only。

修法：

• 用 GENERATED ALWAYS AS (...) VIRTUAL（PG 18+）— 不存實際 value、catalog-only

• 或 先加 nullable column + backfill + 加 NOT NULL constraint：

  1ALTER TABLE orders ADD COLUMN total NUMERIC;
  2UPDATE orders SET total = price * qty WHERE id BETWEEN ...;  -- chunked
  3ALTER TABLE orders ALTER COLUMN total SET NOT NULL;
  4-- 之後加 trigger 或 application 層維護 total

• 或用 pg_repack 跑 rewrite ADD GENERATED STORED

容量 / 時間估算

對 100 GB 表、ADD COLUMN 加 index 為例：

跟 MySQL gh-ost / pt-osc 對照

PG OSC tool 使用頻率比 MySQL 低 — 因為 PG 內建 fast ALTER 已 cover 90% schema change、ghost table tool 只對 少數 rewrite-required 場景。

詳見 MySQL Online Schema Change Tools — sibling、不同 use case mix。

跟其他模組整合

跟 Replication topology

ALTER TABLE / pg_repack / pg-osc 都產生 WAL、會 replicate 到 standby。Standby 上的 long-running query 可能跟 ALTER 衝突、被 hot_standby_feedback 影響 primary autovacuum。詳見 Replication Topology。

跟 Autovacuum Tuning

Schema change 後常產生 dead tuple、autovacuum 需要重新 cover。詳見 Autovacuum Tuning。

跟 Logical Replication

logical replication 透過 publication / subscription 同步 — DDL 不會 logical replicate（PG 16 之前）、必須 在 publisher / subscriber 各自跑 DDL。詳見 Logical Replication + Debezium。

跟 Patroni HA

Patroni promote 新 primary 後、pg_repack extension state（slot / catalog）跟著走、新 primary 仍可繼續 pg_repack。詳見 Patroni HA。

何時用哪個

相關連結

• PostgreSQL vendor overview
• PG Replication Topology（ALTER 跟 streaming replication 互動）
• PG Autovacuum Tuning（schema change 後 vacuum 議題）
• PG Logical Replication + Debezium（DDL 不 replicate 議題）
• PG Patroni HA（HA 跟 pg_repack 整合）
• MySQL Online Schema Change Tools（sibling、tool ecosystem 不同）
• Expand / Contract 卡片（schema migration 設計原則）
• 官方：ALTER TABLE / pg_repack GitHub / pg-osc GitHub

本文是 PostgreSQL overview 的 implementation-layer deep article。Overview 已說明 PG 在 OLTP 譜系的定位、本文聚焦 connection scaling 的根因 — 為什麼 PG 比多數 DB 更需要 pooler、跟 pgbouncer-config 是 根因 vs 配置 的關係。

Connection-per-Process Model 是 PG 的結構性選擇

PG 接受 client connection 時的行為跟多數現代 DB 不同：每個 connection 由 postmaster fork() 一個獨立的 OS process（backend）來服務。這個 process 在 connection lifetime 內專屬該 client、不跟其他 client 共享。

對比常見 DB 的 connection model：

PG 選 process 不選 thread 是 1990s 設計決定 — 當時 thread library 在多 UNIX 平台不穩定、process 隔離性更好（一個 backend crash 不會帶倒整個 DB）。這個 trade-off 一路保留到今天、是 PG 在 high-connection-count workload 的 結構性負擔。

量化：connection 數量對 RAM 跟 CPU 的壓力

一個 PG backend process 的 RAM footprint 由三部分組成：

1backend_rss ≈ shared_buffers_attach + process_private + work_mem 高水位

shared_buffers 是所有 backend 共享的、不重複計、但 process_private（catalog cache / plan cache / temp buffer）跟 work_mem 是 per-backend：

500 個 connection、平均 30MB 各 ≈ 15GB RAM 給 backend processes（還沒算 shared_buffers）。這是 PG 在 cloud instance 上很快撞到 RAM ceiling 的根因。

CPU 層面、fork() 系統呼叫在 Linux 通常 1-3ms、context switch ~3-5μs。100 connection burst 在 1 秒內進來、accumulated fork cost 100-300ms、加 query 本身的 CPU 跟 scheduler latency、平均 query 延遲會跳 2-5x。

三個 GUC 互動：max_connections / shared_buffers / work_mem

PG 的 memory 規劃由這三個 GUC 互動決定、不能獨立調：

1total_RAM ≈ shared_buffers + (max_connections × work_mem 高水位) + OS overhead

實務 sizing 規則（16GB instance、OLTP workload）：

max_connections = 1000 是常見 anti-pattern — 真實 active query 可能只 50-100、剩下都 idle、但每個還是吃 RAM 跟 process slot、context switch overhead 還在。

Pooler 為什麼是 production prerequisite

本段是「為什麼必裝」、實際 PgBouncer 配置看 pgbouncer-config。

Pooler 的核心責任是 把 N 個 application connection multiplex 成 M 個 PG backend（M ≪ N）：

1Application (3000 connection)
2   ↓
3Pooler（PgBouncer / PgCat）
4   ↓
5PostgreSQL (50 backend process)

Application 看到的是 無限 connection 池、PG 看到的是 穩定 50 個 backend。三個層次的效益：

1. RAM 節省：3000 connection × 30MB = 90GB → 50 backend × 30MB = 1.5GB
2. Fork() cost 攤平：backend 重用、不是每個 client 都 fork
3. Connection storm 緩衝：application 重啟 / scaling event 不會直接打到 PG

Pooler 有三種 pool mode、各有 application 層相容性 trade-off：

Production 多數選 transaction pool — 救 RAM 又保留 transaction semantics、代價是 application 不能用 session-level SET、LISTEN/NOTIFY、prepared statement（部分 pooler 已支援）。

Application-side Pool vs Middleware Pool vs RDS Proxy

三層 pool 都能解 connection 問題、但解的問題不同：

典型 production 拓撲：

1Application (HikariCP pool 10/instance × 50 instance = 500)
2   ↓
3PgBouncer transaction pool（50 backend）
4   ↓
5PostgreSQL primary

Application pool 救 fork cost、PgBouncer 救 backend 總量、兩層各做各的事不衝突。

雙層 pool 配置容易出錯：application pool size 5 + PgBouncer default_pool_size 50 + 100 個 app instance、application 願意開 500 connection、PgBouncer 只給 50 個 backend — 多 450 個 application connection wait、看起來像「DB 慢」但實際是 pool 不足。

5 個 Production 踩雷

Case 1：Connection storm（重啟 / autoscale 同時打進來）

情境：Kubernetes rolling restart、200 個 pod 同時重連、每 pod 開 20 個 connection、瞬間 4000 個 connection 嘗試打到 PG。

PG max_connections = 500 直接拒絕 3500 個、application 看到 FATAL: sorry, too many clients already、retry storm 雪上加霜。

修法：

• PgBouncer 在前面、application 連 PgBouncer 不直連 PG
• reserve_pool_size = 5 給管理流量留 buffer
• Application 端加 jittered exponential backoff、避免 retry 同步

Case 2：fork() cost 在 burst 流量

情境：Cron job 每分鐘整點觸發、500 個 worker 同時開 short-lived connection 跑 30ms query、結束關閉。

每分鐘 500 次 fork() + 500 次 exit()、fork cost 500-1500ms、CPU spike、其他 OLTP query 延遲飆。

修法：

• Worker 改 connect 到 PgBouncer transaction pool、backend 重用、fork 只在 PgBouncer 首次拓展時
• 或 worker 改成 long-lived process + 內部 task queue、避免每分鐘重 fork

Case 3：shared_buffers 跟 max_connections 互相壓縮

情境：16GB instance、shared_buffers = 8GB（50%）、max_connections = 800、work_mem = 16MB。

預估 RAM：8GB + 800 × ~30MB = 32GB ≫ 16GB instance、OOM kill 來訪。

修法（重新分配）：

1shared_buffers = 4GB           # 25%
2max_connections = 200          # 透過 PgBouncer multiplex
3work_mem = 16MB
4effective_cache_size = 12GB
5maintenance_work_mem = 512MB

關鍵：max_connections 不是調更大救 connection 不足、是調 PgBouncer pool size 拓展 application 容量。

Case 4：Double-pool 配置失敗

情境：Application HikariCP pool size = 50、50 個 instance、PgBouncer default_pool_size = 20、PG max_connections = 100。

Application 願意開 2500 個 connection、PgBouncer 只給 20 個 backend、application thread 大量 block 在 PgBouncer 等 backend 釋出。

修法：

• 計算 application 願意的並發 vs PgBouncer 允許的 backend vs PG max_connections 三層匹配
• 通常 application_total_connection ≪ pgbouncer_max_client_conn + pgbouncer_default_pool_size + reserve ≪ pg_max_connections
• Monitor PgBouncer SHOW POOLS 的 cl_waiting、長期 > 0 表示 pool 不足

Case 5：max_connections 設太大反而慢

情境：team 看到 connection refused、把 max_connections 從 200 調到 2000、想說「給更多 connection 應該更好」。

調完 throughput 反而降 30% — context switch overhead、planner cache 競爭、lock manager 競爭都跟 connection 數線性放大。

修法：

• max_connections 上限通常 200-500、超過要靠 pooler multiplex
• 用 pg_stat_activity 看真實 active connection（state != ‘idle’）、通常 < 100
• 真實上限 = active 高水位 × 安全係數 1.5、不是「未來可能會用到的數量」

跟 MySQL connection model 對比

MySQL thread-per-connection model 讓它在 high-connection-count workload 上 看起來 更省 — 但 PG 透過 PgBouncer 達到的 application 看到的容量跟 MySQL 直連是一樣的、只是多一層 indirection。

實務影響：

• MySQL 直連 1000 connection 還 OK、PG 直連 1000 connection 通常 OOM
• PG + PgBouncer 1000 application connection、後端 50 backend、表現跟 MySQL 1000 直連相當
• 沒有 PG 更耗 RAM 的本質結論、是 PG 預設不 multiplex、需要外掛 multiplex 層

PG 17+ 的 connection 進展

PG 17（2024）對 connection 仍維持 process-per-connection、但有幾個減壓改進：

• Per-process memory 降低：catalog cache 改 generational allocator、idle backend RAM 降 ~20%
• Subscriber-side parallel apply：logical replication 減少 connection 開銷
• io_combine_limit：buffered read 合併、降 syscall overhead

但 process-per-connection model 本身 沒換 — 短期內 PG 仍需 pooler。長期方向（PG 18+ 討論）可能引入 thread-based backend、但目前是 experimental patch。

相關連結

• pgbouncer-config：PgBouncer 操作配置 + 5 case
• replication-topology：Read replica + connection 分流
• query-optimization：work_mem 影響 plan
• mvcc-lock-model：connection idle in transaction 卡 vacuum
• autovacuum-tuning：autovacuum 也吃 connection slot

下一步

• 連到 pgbouncer-config 學配置細節
• 看 PostgreSQL overview 回到全圖

本文是 PostgreSQL overview 的 implementation-layer deep article。Overview 已說明 PG 在 OLTP 譜系的定位、本文聚焦 index 選型 — 何時用哪種 index、跟 query-optimization 的「為什麼這個 plan 慢」互補。

6 種 Index Method 對應 Workload

PG 有 6 種 index access method、各有自己擅長的 query pattern：

選錯 index 的代價：

• Write workload：每 write 都更新所有相關 index、5 個 unused index = 5x write 放大
• Storage：JSONB 加 GIN 可能比表本身還大
• Plan misjudge：planner 看到 index 不一定用、EXPLAIN 才確認

B-tree：預設選擇、95% workload 適用

B-tree 是 PG 預設 index、CREATE INDEX 不指定 method 就是 B-tree：

1CREATE INDEX idx_orders_user_id ON orders (user_id);
2CREATE INDEX idx_orders_created_at ON orders (created_at);

B-tree 擅長的 query：

 1-- 等值
 2SELECT * FROM orders WHERE user_id = 42;
 3
 4-- 範圍
 5SELECT * FROM orders WHERE created_at BETWEEN '2025-01-01' AND '2025-01-31';
 6
 7-- IS NULL
 8SELECT * FROM orders WHERE shipped_at IS NULL;
 9
10-- Prefix LIKE
11SELECT * FROM products WHERE sku LIKE 'ABC%';

B-tree 不擅長：

• LIKE '%suffix'（前綴 wildcard）→ 改 trigram + GIN
• column @> array（包含）→ 改 GIN
• JSON 內部 path query → 改 GIN on JSONB

Multi-column B-tree 的順序很重要：

1-- 假設常 query: WHERE user_id = ? AND status = ?
2CREATE INDEX idx_orders_user_status ON orders (user_id, status);  -- 對
3CREATE INDEX idx_orders_status_user ON orders (status, user_id);  -- 錯（status 選擇性低）

順序原則：

1. 等值 column 在前（高選擇性）
2. 範圍 column 在後（B-tree leftmost 規則）
3. selectivity 高的在前（filter 更多 row）

GIN：JSONB / FTS / Array 的標配

GIN（Generalized Inverted Index）對「一個 value 內含多個 sub-element」的 column 高效：

 1-- JSONB
 2CREATE INDEX idx_products_metadata ON products USING GIN (metadata);
 3
 4-- Array
 5CREATE INDEX idx_articles_tags ON articles USING GIN (tags);
 6
 7-- Full-text search
 8CREATE INDEX idx_articles_content ON articles USING GIN (to_tsvector('english', content));
 9
10-- Trigram（fuzzy match）
11CREATE EXTENSION pg_trgm;
12CREATE INDEX idx_products_name_trgm ON products USING GIN (name gin_trgm_ops);

GIN 代價：

• Write 慢 2-10x：每個 sub-element 都要更新 inverted index
• Storage 大：可能比表還大
• Vacuum 沉重：bloat 累積快

Operator class 選擇影響大：

只用 @> query 時、jsonb_path_ops 救大量 storage。

GiST：範圍 / 空間 / 自訂

GiST（Generalized Search Tree）擅長範圍跟空間：

1-- 範圍 type（PostgreSQL 內建 int4range / tsrange 等）
2CREATE INDEX idx_bookings_period ON bookings USING GiST (period);
3
4-- 空間（PostGIS）
5CREATE INDEX idx_locations_geom ON locations USING GiST (geom);
6
7-- Exclusion constraint（範圍不重疊）
8ALTER TABLE bookings ADD CONSTRAINT no_overlap
9EXCLUDE USING GiST (room_id WITH =, period WITH &&);

GiST vs GIN 對 FTS 的選擇：

多數 FTS workload 選 GIN — read 占多、index size 換 query latency 划算。

BRIN：大表 + Physical Order Correlated

BRIN（Block Range Index）對 physical 儲存順序跟 logical 順序強相關 的 column 高效：

1-- timestamp column（append-only insert、physical 順序 = 時間順序）
2CREATE INDEX idx_events_created_at ON events USING BRIN (created_at);

BRIN 機制：每個 block range（預設 128 page）記 min/max、query 時跳過 range 外的 block。

適用場景：

• append-only 表：log、metrics、events
• 大表（10GB+）：B-tree 太貴、BRIN 1/1000 大小
• column physical order 跟 query 一致：時間欄、自增 id

BRIN 失效情境：

• UPDATE 破壞 physical order（row 被 vacuum 移到別 block）→ BRIN 失效
• 隨機 insert（uuid / hash id）→ BRIN range 完全沒選擇性

何時不該用 BRIN：表 < 1GB（沒省 storage 收益）、column 沒 physical order correlation（CLUSTER 後可能改善）。

Partial Index：條件式 index 救 storage

對 只 query 部分 row 的 column、partial index 救大量 storage：

 1-- 只 index unshipped order
 2CREATE INDEX idx_orders_unshipped ON orders (created_at)
 3WHERE shipped_at IS NULL;
 4
 5-- 只 index active user
 6CREATE INDEX idx_users_active ON users (email)
 7WHERE status = 'active';
 8
 9-- 只 index 高金額 transaction
10CREATE INDEX idx_orders_high_value ON orders (user_id)
11WHERE total > 1000;

Partial index 的 query 要 完全匹配 WHERE 條件 才用得到：

1-- 用得到 partial index
2SELECT * FROM orders WHERE shipped_at IS NULL AND created_at > '2025-01-01';
3
4-- 用不到（planner 不 prove WHERE 包含 partial 條件）
5SELECT * FROM orders WHERE created_at > '2025-01-01';

實務 size 救法：unshipped order 只 1% 總量、partial index 1/100 大小。

Expression Index：對函式結果 index

 1-- 對 lowercased email index（case-insensitive search）
 2CREATE INDEX idx_users_email_lower ON users (lower(email));
 3SELECT * FROM users WHERE lower(email) = lower('USER@example.com');
 4
 5-- 對 JSONB 內部欄位
 6CREATE INDEX idx_products_category ON products ((metadata->>'category'));
 7SELECT * FROM products WHERE metadata->>'category' = 'shoes';
 8
 9-- 對日期截斷
10CREATE INDEX idx_orders_day ON orders (date_trunc('day', created_at));

Expression 必須 IMMUTABLE — now() / random() 不能用、timezone('UTC', ts) 可以。

Covering Index（INCLUDE）：避免回表

PG 11+ 支援 INCLUDE column：

1-- 只 index user_id、但 query 常要 email
2CREATE INDEX idx_users_user_id_covering ON users (user_id) INCLUDE (email);
3
4-- Index-only scan：不用回表
5SELECT email FROM users WHERE user_id = 42;

INCLUDE column 不參與 sorting / equality、只放 leaf node、救 IO。

Index 選擇決策樹

 1Query pattern 是什麼？
 2
 3├─ 等值 / 範圍 / prefix LIKE / IS NULL
 4│  └─ B-tree（90% 場景）
 5│     ├─ 只 query 部分 row？→ Partial B-tree
 6│     ├─ 對函式結果？→ Expression B-tree
 7│     └─ 需要回表更多 column？→ Covering（INCLUDE）
 8│
 9├─ JSONB 內部 query / array 包含 / FTS
10│  └─ GIN
11│     ├─ 只用 @>？→ jsonb_path_ops 救 storage
12│     └─ FTS write-heavy？→ 改 GiST
13│
14├─ 範圍 type（int4range / tsrange）/ 空間
15│  └─ GiST
16│
17├─ 大表 + append-only + physical order correlated
18│  └─ BRIN
19│
20├─ 純 equality + 簡單 column
21│  └─ Hash（很少用、B-tree 通常更好）
22│
23└─ Non-balanced 樹（IP prefix / quad-tree）
24   └─ SP-GiST（罕見）

5 個 Production 踩雷

Case 1：過度 index（write 放大）

情境：team「為了 query 快」對 20 個 column 各建 index、寫入量大時 INSERT 慢 10x。

每個 INSERT 要更新 20 個 index、WAL volume 也跟著放大、replication lag 拉長。

修法：

• 用 pg_stat_user_indexes 找 idx_scan = 0 的 index、可能根本沒用
• 用 pg_stat_statements 找實際被執行的 query、反推真正需要的 index
• 同 column 多 index（user_id 單欄 + (user_id, status) 多欄）通常可拆掉單欄

Case 2：Partial index 條件跟 query 不匹配

情境：建 WHERE status = 'active' partial index、application query 寫 WHERE status IN ('active')、planner 不 prove 等價、不用 index。

修法：

• Partial 條件用最 generic form（避免 IN / OR 跟 = 的差異）
• 寫完用 EXPLAIN 驗證 query 真的用到 partial index
• Application 統一 query 寫法、不要混 = 跟 IN 跟 ANY

Case 3：B-tree 對 JSONB 內部欄位無效

情境：對 metadata JSONB column 建 B-tree、query metadata->>'category' = 'shoes' 不用 index。

B-tree 對 整個 JSONB 排序、但 path query 不是整個 JSONB 的比對。

修法：

• 對固定 path 建 expression index：CREATE INDEX ... ON products ((metadata->>'category'))
• 對動態 path 建 GIN index：CREATE INDEX ... USING GIN (metadata)
• 兩者並存可、EXPLAIN 看 planner 選哪個

Case 4：BRIN 對非 correlated 資料無效

情境：對 user_id 建 BRIN index（user_id 是隨機 UUID）、query 完全跑 seq scan。

UUID 沒 physical order correlation、每個 block range 的 min/max 涵蓋整個 ID space、BRIN 完全沒 prune 效果。

修法：

• BRIN 只用 timestamp / 自增 id / 其他自然 correlate 的 column
• 用 pg_stats 看 correlation value、< 0.1 就不適合 BRIN
• 真要對 random column 加 index、回 B-tree

Case 5：Multi-column index 順序錯

情境：常見 query WHERE status = 'pending' AND user_id = 42、建 index (status, user_id)、效能差。

status 只 5 個 distinct value、選擇性 1/5；user_id 1M distinct、選擇性 1/1M。Index leftmost 是 status、scan range 太大。

修法：

1-- 拆兩個或調順序
2CREATE INDEX idx_user_status ON orders (user_id, status);
3
4-- 或加 partial 限定低選擇性 column
5CREATE INDEX idx_orders_pending ON orders (user_id) WHERE status = 'pending';

跟 MySQL Index 差異

PG index 系統比 MySQL 表達力高、但代價是 選對 index method 是 application 責任、MySQL 預設 B-tree 多數場景夠用。

相關連結

• query-optimization：EXPLAIN 看 index 用沒用
• jsonb-deep-dive：JSONB + GIN 細節
• full-text-search：FTS + GIN
• autovacuum-tuning：index bloat
• online-schema-change：CREATE INDEX CONCURRENTLY

下一步

• 看 query-optimization 驗證 index 有沒有被 plan 用到
• 回 PostgreSQL overview 看全圖

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