連線池放大的物理本質

PostgreSQL / MySQL 每個連線都會在 DB server 端配一個 backend process / thread。Backend 佔 5-15 MB 記憶體、context switch 也有成本。當應用層連線數超過 DB 機器能負擔的數量，會出現三類問題：

• 記憶體吃光：500 個 backend × 10 MB = 5 GB、再加 shared buffer、可能直接 OOM
• Context switch 抖動：上百個 backend 競爭 CPU、上下文切換 overhead 變成主要消耗
• 連線建立失敗：超過 max_connections 後、新請求拿不到連線、即使現有連線多數 idle

問題的根因不是「連線多」、是「連線生命週期跟使用率不對齊」。應用層 connection pool 通常維持「每臺機器 N 個常駐連線、避免每個 request 重新建連」、但 100 臺機器各自 keep 10 個常駐就是 1000 個 idle 連線。

解法的方向不是「砍應用層連線數」（會讓 connection acquisition 變慢、影響 latency）、是「在 DB 跟應用層之間放一層 multiplexer」— 把多個應用層連線複用到少數 DB 連線上。這層中介就是 connection pooler。

Connection Pooler 三大選項

PgBouncer — 三種 pooling 模式決定一切

PgBouncer 的核心參數是 pool_mode：

• Session mode：應用層 client 拿到的連線、跟 DB backend 1:1 綁定、整個 session 結束才釋放。其實沒做 multiplexing、只是 connection caching。
• Transaction mode：每個 transaction 結束、應用層 client 的連線釋放回 pool、下個 transaction 再分配 DB backend。multiplexing 比較強、但不支援 transaction-scoped state（如 SET LOCAL、prepared statement、temporary table）。
• Statement mode：每個 statement 結束就釋放、最強 multiplexing 但不支援 transaction。極少用、只在純 stateless query workload 適用。

Transaction mode 是多數場景的 default。但要注意：應用層的 ORM / driver 可能默認用 prepared statement、跟 transaction mode 衝突。PostgreSQL 14+ 的 protocol-level prepared statement 才相容、JDBC / asyncpg 等需要特別配置。

AWS RDS Proxy — managed 換掉運維

RDS Proxy 是 PgBouncer / ProxySQL 同類功能的 managed 版本：AWS 負責部署、HA、failover、IAM 整合。應用層連到 RDS Proxy endpoint、Proxy 在背後維持跟 RDS / Aurora 的連線池。

特點：

• 連線 share 模式類似 transaction mode：自動 detect 連線是否在 transaction、空閒時釋放
• IAM auth 整合：應用層用 IAM token、不用維護 DB password
• Failover 加速：DB failover 時 Proxy 維持應用層連線不斷、background 重連 new primary。Failover 期間應用層感受最小化。
• 計價：per vCPU-hour、Aurora 約 $0.015/vCPU-hr、RDS 約 $0.02/vCPU-hr — 加在 RDS 計價上面

不適用場景：很多 read-only / analytics workload 不需要 connection pooler、純讀 replica 直接連通常更便宜。RDS Proxy 是給「寫入混合」「連線抖動嚴重」這類場景。

ProxySQL — MySQL 規則型 routing

ProxySQL 是 MySQL 生態的 connection pooler、但比 PgBouncer 更全功能：

• Query routing rules：可以按 query pattern 把 query 導去不同 backend（讀路徑去 replica、寫路徑去 primary、特定 query 強制 cache）
• Connection multiplexing：類似 PgBouncer transaction mode
• Query rewriting：可以攔截 query 改寫（debug / 漸進遷移 schema）
• Auto failover：監控 backend 健康、自動切流

ProxySQL 的代價是學習曲線跟運維成本 — 規則設計需要對 query pattern 跟 DB topology 有掌控、設錯規則會把 query 導去錯誤 backend、debug 困難。

選型對照

實務選型的關鍵變數是「DB 廠商 / managed 程度 / 規模 / 預算」：

不裝 pooler 的判讀

Connection pooler 不是必要 — 在以下情境可以暫時不裝：

• 應用層機器數 < 10：對 DB 連線總數壓力小、deferred 安裝 pooler 沒問題
• 每臺機器連線數 < 5：應用層 connection pool 已經很省、再加 pooler 改善有限
• DB 機器規格大、max_connections 充裕：高階 RDS instance 可開到 5000-10000 連線、有 buffer 之前不必加 pooler
• Workload 全是長 transaction：transaction mode pooler 在這種 workload 跟 session mode 沒差、收益低

該裝 pooler 的訊號是相反：應用層機器數 ≥ 20、每臺連線數 ≥ 10、max_connections 使用率 ≥ 70%、或 P99 connection wait time 升高。

判讀訊號

常見誤區

把 connection pooler 當「N+1 解藥」。Pooler 解的是「連線數放大」、不是「query 數量過多」。N+1 query 在裝完 pooler 後仍然慢、只是 DB 不會因為連線爆掉而當機。兩個是正交問題、各自要解。

把 RDS Proxy 當「免費功能」。Proxy 的計價跟 RDS / Aurora 本體疊加、高 connection volume 場景 Proxy 成本可能可觀。要算實際的 cost-per-request、不是預設「managed 一定值得」。

把 transaction mode 配置當「裝完就好」。Prepared statement / SET LOCAL / temporary table 都會跟 transaction mode 衝突、ORM 預設行為要 audit 過、不然會在 production 出現難 debug 的「query 隨機失敗」。

定位邊界

本章專注「連線池放大的解法」。當問題進入擴展軸選擇（要垂直 vs 水平？stateful 前提？）、回 9.13 擴展軸；進入 DB 本身的容量規劃（要多大規格 instance？要不要 read replica？）、進 9.6 容量規劃；進入 application-level connection 設計（per-request pool / persistent pool）、進 1.1 高併發 SQL。

案例回寫

09 案例庫多數案例規模到 connection pool 已是 secondary concern、但兩個案例有對應參考：

• 9.C18 Zoom：COVID 30 倍突發 — Zoom 把 stateful 資料層改用 DynamoDB、繞過 SQL connection pool 問題（KV 沒有 backend process 概念）。對照本章可問：若 Zoom 保留 SQL、connection pool 怎麼設計才撐得住 30 倍突發？
• 9.C39 DoorDash：CockroachDB 多主寫入 — DoorDash 從 Aurora single-primary 換成 CockroachDB 多主、connection pool 設計從「集中在 primary」變成「分散在多 node」。對照本章可問：CockroachDB 是否仍需要 connection pooler？

跨模組路由

1. 與 9.13 擴展軸 的交接：9.13 提出隱性成本、本章給具體解法。
2. 與 1.1 高併發 SQL 讀寫邊界 的交接：1.1 講應用層 connection pool 設計、本章補 DB 端 pooler 中介層。
3. 與 01 vendors 的交接：各 DB vendor 的內建 pooler 能力詳見 vendor deep article。
4. 與 9.6 容量規劃 的交接：pooler 加上後、DB 容量規劃的單位從「連線數」變成「DB backend 數 + Pooler vCPU」。

下一步路由

要看擴展軸選擇的完整 framing、回 9.13 擴展軸與 Stateless 前提。要看 DB-side 高併發處理、進 1.1 高併發 SQL 讀寫邊界。要看具體 vendor 的 pooler 文件、進對應 vendor deep article。

本文是 MySQL overview 的 implementation-layer deep article。Overview 已說明 MySQL 在 OLTP 譜系的定位、本文聚焦 ProxySQL 配置 — connection pool + query routing 的 4 段 lifecycle 跟 rule chain 設計。

ProxySQL Lifecycle：每個 query 走 4 段

從 application 連 ProxySQL 到拿到 response、每個 query 都走完整 4 段：

11. Connection 接入        →  application connect 到 ProxySQL（不是 MySQL）
22. Query parse + rule match  → ProxySQL 解析 query、match query rule chain
33. Backend route          →  決定走哪個 hostgroup（primary / replica）+ 哪個 server
44. Response 返回          →  將 result set 回 application、connection 可被 reuse

每段都有獨立配置 + failure mode + 觀測 metric。ProxySQL 不是 簡單的 connection pool、是 query-aware proxy — 看得到 SQL 內容才能做 read/write split、replica lag-aware routing、query mirroring。

跟 PostgreSQL pgBouncer 比、pgBouncer 是 transaction-level pool（只看連線、不看 SQL）、ProxySQL 是 query-level proxy（看 SQL、做 routing decision）。能力不同、target use case 不同。

Stage 1：Connection 接入 — Hostgroup / Server / User 三層 schema

ProxySQL 不直接 expose backend MySQL、用 hostgroup 作為 routing 抽象。Application 不知道有幾個 backend、只知道 ProxySQL。

核心 table（在 main database）：

典型部署：

 1-- 進 ProxySQL admin (6032 port)
 2mysql -uadmin -padmin -h127.0.0.1 -P6032
 3
 4-- 設 2 個 hostgroup：10=writer、20=reader
 5INSERT INTO mysql_servers(hostgroup_id, hostname, port, weight, max_connections)
 6VALUES
 7  (10, 'primary.example.com', 3306, 1000, 200),
 8  (20, 'replica1.example.com', 3306, 1000, 100),
 9  (20, 'replica2.example.com', 3306, 1000, 100);
10
11-- 自動偵測 primary（用 read_only flag）
12INSERT INTO mysql_replication_hostgroups(writer_hostgroup, reader_hostgroup, comment)
13VALUES (10, 20, 'production cluster');
14
15-- 設 application user、預設走 reader（保守）
16INSERT INTO mysql_users(username, password, default_hostgroup, max_connections)
17VALUES ('app', 'app_password', 20, 1000);
18
19-- 套用設定到 runtime
20LOAD MYSQL SERVERS TO RUNTIME;
21LOAD MYSQL USERS TO RUNTIME;
22
23-- 持久化到 disk（重啟保留）
24SAVE MYSQL SERVERS TO DISK;
25SAVE MYSQL USERS TO DISK;

注意 ProxySQL 的 三層 state：disk（持久化）→ memory（編輯區）→ runtime（實際運作）。每次改完要 LOAD ... TO RUNTIME 才生效、SAVE ... TO DISK 才能 reboot 保留。沒 SAVE 重啟後 config 消失是新手最常踩的雷。

Stage 2：Query Parse + Rule Match — query rule engine

ProxySQL 不只 forward connection、看 SQL 內容 決定怎麼 route。Query rule 是 ordered chain、match 第一個符合的 rule。

Query rule 核心欄位：

典型讀寫分離 rule：

 1-- Rule 100: SELECT ... FOR UPDATE 必須走 primary
 2INSERT INTO mysql_query_rules(rule_id, active, match_pattern, destination_hostgroup, apply)
 3VALUES (100, 1, '^SELECT.*FOR UPDATE$', 10, 1);
 4
 5-- Rule 200: 一般 SELECT 走 replica（reader）
 6INSERT INTO mysql_query_rules(rule_id, active, match_pattern, destination_hostgroup, apply)
 7VALUES (200, 1, '^SELECT', 20, 1);
 8
 9-- Rule 300: BEGIN / START TRANSACTION 走 primary
10INSERT INTO mysql_query_rules(rule_id, active, match_pattern, destination_hostgroup, apply)
11VALUES (300, 1, '^(BEGIN|START TRANSACTION)', 10, 1);
12
13-- 其他（INSERT / UPDATE / DELETE）預設走 default_hostgroup（user 設的）
14-- application user default 設 10 (writer)、所以寫入自動走 primary
15
16LOAD MYSQL QUERY RULES TO RUNTIME;
17SAVE MYSQL QUERY RULES TO DISK;

Rule 順序很重要：rule_id 100 先 match、200 再 match、依此類推。Rule 200 比 100 寬鬆（任何 SELECT）、所以 FOR UPDATE 必須先 match rule 100 才不會誤送 replica。

Stage 3：Backend Route — replica lag-aware + circuit breaker

Rule match 後 ProxySQL 從 hostgroup 內挑一個 server。Backend selection 不是 pure round-robin、考慮：

• Weight：每個 server weight 比例分配（典型用於 replica capacity 不同）
• Replica lag：若 hostgroup 設 max_replication_lag、lag 超過 threshold 的 replica 自動暫時退出
• Connection count：避免某個 server connection 滿
• Server status：mysql_servers.status (ONLINE / SHUNNED / OFFLINE_SOFT / OFFLINE_HARD) 決定是否可用

Replica lag-aware routing 配置：

1-- 給整個 reader hostgroup 設 lag threshold
2UPDATE mysql_servers
3SET max_replication_lag = 5  -- 秒
4WHERE hostgroup_id = 20;
5
6LOAD MYSQL SERVERS TO RUNTIME;

ProxySQL 內部用 monitor module 定期跑 SHOW SLAVE STATUS、lag 超過 5 秒 → 該 replica 暫時退出 reader hostgroup。讀 query 自動避開 lagging replica。

Circuit breaker（自動 shun）：server 連續失敗 → ProxySQL 自動 SHUNNED、避免持續打 broken server。但 application 層仍要處理 retry、ProxySQL 不保證 query 100% 成功。

Stage 4：Response 返回 — connection multiplexing

ProxySQL 對 application connection 跟 backend connection 是 N:M 多工：

• Application connection 跟 ProxySQL 1:1
• ProxySQL 跟 backend MySQL connection 共用 pool（multiplexing）

Multiplexing 條件：

• Transaction 內：connection 綁定特定 backend（保 transaction atomicity）
• 跨 transaction：connection 可以換 backend
• SET statement 改 session variable：connection 黏死 backend（防 session state leak）
• User variable（@var）：connection 黏死 backend

結果：application 看到的是「自己有 1000 個 connection」、ProxySQL 後端可能只有 100 connection 到 MySQL。對 connection-bound MySQL（max_connections 限制）是關鍵 cost saving。

5 個 Production 踩雷

1. Query rule 順序錯亂 — FOR UPDATE 被 SELECT route 到 replica

Rule 200（^SELECT）寫在 rule 100（^SELECT.*FOR UPDATE$）之前、ProxySQL match 第一個 rule（rule 200）就停、SELECT ... FOR UPDATE 被送 replica、replica 沒 lock、application 假設有 lock 跑 race condition。

修法：

• rule_id 排序：精確 rule（多條件 regex）放小、寬鬆 rule 放大
• 用 apply=1 強制停 chain、不要讓 query 繼續往下 match
• 跑 ProxySQL SHOW PROCESSLIST + audit log 確認 routing 正確

2. Connection 漂移 — Multiplexing 把 session variable 弄丟

Application 跑 SET sql_mode=...、ProxySQL 把這 connection 暫時黏死 backend 1。下個 query ProxySQL forget、把 connection unstick、實際 forward 到 backend 2（沒 SET sql_mode）、SQL 解析行為不同、application bug。

修法：

• 用 mysql-multiplexing=false 全 disable（最簡單但浪費 connection pool 效率）
• 或在 application init 連線後跑的 SET 全列在 mysql_users.connect_init（每個 connection ProxySQL 自動跑、不會漂移）
• 避免 application 中途改 session variable、改成全部走 ProxySQL connect_init

3. Write 不小心 route 到 replica — default_hostgroup 設錯

Application user default_hostgroup 設 20 (reader)、INSERT / UPDATE / DELETE 沒 match 到任何 rule（沒寫 catch-all write rule）、走 default → 送 replica → replica 是 read-only → error。或更糟：replica 不是 read-only mode、寫入 寫到 replica 上、replication 反向不同步、data corruption。

修法：

• Application user default_hostgroup 設 10 (writer) — 寫入預設走 primary
• Replica MySQL 一定要 read_only=1（防 stale write 寫到 replica）
• 監控 mysql_query_rules match 率、寫入 query 應該大部分透過 default_hostgroup 路由、不是個別 rule

4. Runtime / disk schema drift — 改了 runtime 沒 save、重啟 config 消失

LOAD ... TO RUNTIME 跟 SAVE ... TO DISK 是兩個獨立操作。On-call 在事故中改 ProxySQL 配置（add server、調 query rule）、LOAD 套到 runtime 但忘記 SAVE、隔天 ProxySQL 重啟（OS update / crash）、config 回到 disk 版本、半夜 alert。

修法：

• 每次 LOAD ... TO RUNTIME 後立刻 SAVE ... TO DISK（變成 habit）
• 用 IaC（Terraform / Ansible）管 ProxySQL config、不要手動改 admin
• 監控：對比 runtime_mysql_servers 跟 mysql_servers（disk）、有 diff 即告警

5. Mirror traffic 副作用 — INSERT 鏡像到 staging 寫了兩次

mirror_hostgroup 把 query 鏡像送到第二個 hostgroup（不等 response、用於 shadow test 新 schema）。但 鏡像是真實執行、不是 dry-run。鏡像 INSERT 到 staging hostgroup → staging 真的多了 row。如果 staging hostgroup 接到 production 表（誤接）、production 寫入 doubled。

修法：

• Mirror 只用於 獨立 staging cluster、不混用 production schema
• Mirror 設定要 review（規則 match_pattern 跟 mirror_hostgroup 配對）
• 開 mirror 前在 staging 跑 dry-run、確認 schema 跟 production isolated

容量規劃要點

對 100 application instance × 50 connection / instance = 5000 application connection 場景：

ProxySQL 本身需要 HA：放兩個 instance 後面接 VIP（keepalived）或 HAProxy。Application 連 VIP / HAProxy、不直接連 ProxySQL hostname（單點失效）。

跟其他模組整合

跟 Replication topology

ProxySQL 透過 monitor module 自動偵測 primary（檢查 read_only flag）+ replica lag（檢查 Seconds_Behind_Master）。這個 monitor 依賴 MySQL replication 已配好（GTID + binlog ROW format）。詳見 Replication Topology。

跟 Orchestrator HA

Orchestrator 自動 failover 後新 primary 的 read_only flag 變 0、舊 primary 變 1。ProxySQL monitor 偵測到、自動把 hostgroup 10（writer）的 server 切換、application 不必改 connection string。

詳見 Orchestrator failover 設計 篇（待寫）。

跟 OSC tool（gh-ost / pt-osc）

ProxySQL 可以 暫時 throttle application 對某張表的寫入（query rule delay 欄位）、配合 OSC tool cut-over 時段降低 metadata lock 衝突。

詳見 Online Schema Change Tools。

跟 Aurora MySQL / RDS Proxy

Aurora MySQL 推 RDS Proxy（AWS managed proxy）取代 ProxySQL — 跟 IAM 整合、failover < 30 秒。但 RDS Proxy 沒有 query routing rule engine（只做 connection pool）、不能讀寫分離。Aurora user 仍可能用 ProxySQL 在前面、再用 RDS Proxy 作 backend connection pool。

詳見 Aurora vendor page。

跟 PostgreSQL pgBouncer 對比

ProxySQL 是 query 層中介、pgBouncer 是 connection 層中介。詳見 pgBouncer 配置。

相關連結

• MySQL vendor overview
• MySQL Replication Topology（read replica routing 前提）
• MySQL Online Schema Change Tools（OSC + ProxySQL throttle 整合）
• PostgreSQL pgBouncer（PG sibling、不同抽象層）
• Aurora vendor page（RDS Proxy + ProxySQL 取捨）
• Connection Pool 卡片
• 官方：ProxySQL Documentation

本文不是 Aurora overview（請看 Aurora vendor 頁）— 而是 RDS Proxy 連線管理機制與陷阱的實作層教學。

核心機制：connection multiplexing

RDS Proxy 維護一個到 Aurora 的後端連線池，多個 client 連線共享這些後端連線。當 client 連線閒置（交易之間沒有活動），proxy 可以把對應的後端連線釋放回池子給其他 client 用：

multiplexing 生效的前提是 client 連線「閒置時可以被借走」。這只在連線處於 交易之間 的乾淨狀態時成立——一旦連線帶了交易內狀態，proxy 不能把它借給別人，這就是 pinning。

Scope warning：「RDS Proxy 支援的 engine / 連線數上限 / IAM 認證細節」屬 AWS vendor 規格、實作時 cross-verify 官方 doc 當前值。本文不含 production case 揭露的 proxy 配置數字。

對應 knowledge card：connection pool。

Pinning：multiplexing 失效的主因

Pinning 是 RDS Proxy 最常被忽略、卻直接決定省連線效果的機制。當 client 在連線上做了「跨交易持續的 session 狀態」操作，proxy 無法安全地把這條後端連線借給其他 client，於是把它 pin（綁定）到該 client 直到連線關閉——這條後端連線在 pin 期間不參與 multiplexing。

常見觸發 pinning 的操作：

• session 層級的變數設定（SET 某些 session variable）
• 建立 temp table
• prepared statement（某些情況）
• advisory lock、保持開啟的交易
• 部分 session 層級的設定語句

pinning 的後果是「明明裝了 RDS Proxy、後端連線數卻沒降下來」。若大量 client 都觸發 pinning，等於退化回「一個 client 一條後端連線」、proxy 白裝。

判讀與修法方向：

• 監控 DatabaseConnectionsCurrentlySessionPinned，看 pinning 比例
• application 端避免不必要的 session 狀態（少用 session variable、temp table；改用交易內可清理的方式）
• 真的需要 session 狀態的 workload，接受該連線會 pin、或評估這類 workload 是否適合走 proxy

Scope warning：「哪些具體語句觸發 pinning」隨 RDS Proxy 版本與 engine 演進、實作時以 AWS doc 當前清單為準；本段列舉是常見類型、非完整或固定清單。

Failover 加速

RDS Proxy 的第二個價值是縮短 failover 對 application 的中斷。沒有 proxy 時，writer failover 會讓所有 client 連線斷掉、application 要偵測、重連、重建連線池；有 proxy 時，proxy 保持與 client 的連線、在後端把流量切到新 writer，client 端感知到的中斷時間縮短。

這對連線建立成本高、或 failover 期間不能大量重連的 workload 特別有價值。但 proxy 不消除 failover 本身——in-flight 的交易仍會失敗、application 仍要有 retry；proxy 縮短的是「重建連線」這段，不是「交易不中斷」。

操作流程

從連線壓力判讀到上線的 6 步流程。

Step 1：確認是不是連線問題

先區分「Aurora 容量不夠」vs「連線管理問題」。看 DatabaseConnections 是否逼近上限、且 CPU/IOPS 還有餘量——後者是典型的連線數問題、proxy 能解；若是 CPU/IOPS 飽和，proxy 不解。

Step 2：判斷 workload 是否適合 proxy

• serverless / Lambda / 高並發短連線 → 適合（連線爆炸是主問題）
• 少量長連線、穩定的 application server → proxy 效益有限（連線數本就可控）
• 大量 session 狀態 workload → pinning 會吃掉 multiplexing 效益、要先評估

Step 3：建立 proxy

1aws rds create-db-proxy \
2  --db-proxy-name my-aurora-proxy \
3  --engine-family POSTGRESQL \
4  --auth ... \
5  --role-arn ... \
6  --vpc-subnet-ids ...

application 連到 proxy endpoint 而非直連 cluster endpoint。

Step 4：減少 pinning

review application 的 session 狀態使用、移除不必要的 SET / temp table；連線池設定避免長時間持有閒置連線。

Step 5：驗證 multiplexing 生效

1# 對照後端連線數：裝 proxy 後 Aurora 的 DatabaseConnections 應顯著低於 client 並發數
2# 看 DatabaseConnectionsCurrentlySessionPinned：pinning 比例高代表 multiplexing 沒發揮

Step 6：驗證 failover 行為

主動觸發一次 failover、測量 application 感知到的中斷時間、確認 retry 邏輯能吸收 in-flight 交易失敗。

Rollback boundary：application 可在 proxy endpoint 與直連 cluster endpoint 間切換、proxy 出問題時改回直連（但直連會回到連線爆炸風險，要先確認後端撐得住）。

失敗模式

production 常見的 5 個踩雷：

Case 1：裝了 proxy 但 pinning 比例高、連線沒降

application 大量用 session variable / temp table、多數連線被 pin、後端連線數沒降、proxy 白裝。修法：監控 pinning 比例、減少 session 狀態；理解 proxy 的省連線前提是連線可被借走。

Case 2：把 proxy 當「Aurora 容量擴充」

連線數沒問題、是 CPU/IOPS 飽和、卻裝 proxy 期待變快。修法：proxy 解連線管理、不解運算容量；容量問題要擴 instance / 加 replica。

Case 3：以為 proxy 讓 failover 零中斷

裝了 proxy 就拿掉 application 的 retry、failover 時 in-flight 交易失敗沒處理。修法：proxy 縮短重連時間、不保證交易不中斷；application 仍要 retry in-flight 交易。

Case 4：少量長連線 workload 強裝 proxy

穩定的 application server 連線數本就可控、裝 proxy 多一跳延遲、效益有限。修法：proxy 的價值在連線爆炸場景（serverless / 高並發短連線）；連線可控的 workload 不必加。

Case 5：proxy 與自管 pooler 疊加未理清責任

application 已有自管連線池（如語言層 pool）、又加 RDS Proxy、兩層 pool 互相打架、連線數行為難預測。修法：理清兩層職責——application 層 pool 管「app 到 proxy」、proxy 管「proxy 到 Aurora」；兩層設定要協調、不是各設各的。

Anti-recommendation：連線數本就可控的少量長連線 workload、或 workload 大量依賴 session 狀態（pinning 會吃掉效益）→ 不必上 RDS Proxy；它的價值集中在 serverless / Lambda / 高並發短連線的連線爆炸場景。

容量與觀測

CloudWatch metric：

• DatabaseConnections（Aurora 端）：裝 proxy 後應顯著低於 client 並發數
• DatabaseConnectionsCurrentlySessionPinned：pinning 數、判斷 multiplexing 效益
• ClientConnections（proxy 端）：client 側連線數、對照後端收斂比例
• QueryDatabaseResponseLatency：proxy 多一跳的延遲影響

判讀：

• 後端連線數沒因 proxy 下降 → pinning 比例高或 workload 不適合
• pinning 數持續高 → application session 狀態過多、需 review
• proxy 延遲明顯 → 評估這一跳對延遲敏感路徑是否值得

Scope warning：本文未引用 production case 的 proxy metric 數字；上述指標與判讀屬 vendor 規格 + 通用連線管理工程。

接回 9.5 瓶頸定位流程、1.1 高併發下的 SQL 讀寫邊界。

邊界與整合

RDS Proxy vs 自管 pgbouncer

兩者都是 connection pooler，責任切分在「managed vs 自管」：

• RDS Proxy：AWS managed、跟 Aurora / IAM / Secrets Manager 整合、零運維、含 failover 加速；綁 AWS
• 自管 pgbouncer / pgcat：自己部署運維、pooling 模式（session / transaction / statement）可細調、跨雲可攜；運維責任自負

PostgreSQL 的通用連線池機制與 pgbouncer 細節主寫於 pgbouncer-config 與 connection-pooler-comparison；本篇聚焦 RDS Proxy 這個 AWS managed 方案的機制與 pinning 陷阱。要細調 pooling 模式、或需要跨雲可攜 → 評估自管 pooler；要零運維 + Aurora 原生整合 + failover 加速 → RDS Proxy。

Sibling 與 cross-link

• serverless-v2-scaling — serverless + Lambda 場景的連線管理常與 RDS Proxy 一起出現
• cross-az-failover-rto — proxy 縮短 failover 重連時間、與 RTO 目標結合
• pgbouncer-config / connection-pooler-comparison — 通用連線池 SSoT、自管方案對照
• 1.1 高併發下的 SQL 讀寫邊界 — 連線池與 transaction 範圍控制
• 替代路由：需要細調 pooling 模式 / 跨雲 → 自管 pgbouncer

本文不重複 MongoDB vendor overview 的 Atlas / 容量規劃簡介 — 而是 production 部署 + 跨層協作 + 失敗修復的實作層教學。

問題情境：大規模 OLTP 撞三道牆

MongoDB 部署規模從中型撐到大規模時、會連環撞三道牆：

Connection ceiling：應用層 deploy 規模一上來、單一 MongoDB cluster 看到 connection storm。9.C36 Coinbase 揭露具體：Ruby + GVL + blue-green 部署把 instance 數 ×2、連線數隨之 ×2、單一 cluster 看到 60K connections / 分鐘（口徑：Coinbase 特定環境 CRuby + GVL 部署模型）。MongoDB cluster 的 connection limit 撞牆、新 deploy 連不上、線上服務 cascade 失敗。

Read scaling ceiling：讀者把所有 read 都打 secondary、replica 加到 5-7 仍撐不住 sustained 高 read（>500K reads/sec）。Replication lag 升 + secondary CPU 飽和；單靠 MongoDB cluster 內機制（replica scaling + read preference）拿不到大規模量級。

Scaling reaction lag：MongoDB cluster 擴容是天級議題、不是即時擴容。9.C36 Coinbase 揭露 reactive scaling 起點到完成 ~70 分鐘（口徑：Coinbase 特定環境、cluster tier / 資料量 / Atlas API 條件下、非 MongoDB 普遍承諾）。Surge 開始時才動來不及、預測性流量必須提前出手。

Surge 形狀又不規則：加密貨幣 surge（隨外部市場波動）/ 媒體爆量（事件驅動）/ IoT 緊急通報（雙模式並存）— 都不適合單純 reactive auto-scaling 接住、必須 predictive + reactive 兩段式。

讀者徵兆：

• MongoDB Atlas console 看到 connection count 在 deploy 後 spike 到上限
• p99 read latency 在事件時段集體爬
• Atlas auto-scaling event log 顯示 triggered too late
• Cache hit rate 跟 read latency 反向相關

Case anchor：9.C36 Coinbase 是 rich case，含具體數字（deploy 尖峰 connection event rate ~60K connections / 分鐘 / mongobetween 後 steady-state concurrent connections 由 ~30K 降到 ~2K — 兩者口徑不同、不是同一數字的連續變化；1.5M reads/sec 含 cache / 70 → 25 分鐘擴容）；9.C38 Toyota Connected 雙模式負載敘事（持續 sensor + 緊急事件）、9.C37 Forbes 媒體爆量形狀。

核心機制：三層合成 frame

跨案合成 frame（本章合成、case 原文沒這個 frame）：應用層連 MongoDB cluster 在大規模 production 是 三層協作、不是 driver 一個元件：

三層缺一都會在大規模時撞牆。本文聚焦這三層如何協作、單一層的深度議題（read preference 機制、schema 治理、aggregation pipeline）推到 sibling。

Driver / Proxy 層

MongoDB driver 原生 connection 模式：driver 在 application process 內維護 connection pool、每個 process 跟 MongoDB cluster 開固定數量 socket。但 driver 沒跨 process pool — 多個 process 共用同一台機器、每個 process 自己一份 pool、cluster 看到的是 N 倍 connection。跟 PostgreSQL 走 pgbouncer 是同樣需求。

Connection storm 的具體 trigger：

• 部署模型放大 process 數：CRuby + GVL 強制每 CPU core 一 process、blue-green 部署 instance 數 ×2、連線數隨之 ×2（9.C36 Coinbase 揭露：單 cluster 看到 60K connections/min）
• 微服務數量多：50+ microservice 各自連 cluster、每服務 connection 加總後撞上限（9.C37 Forbes 50+ 微服務情境對照）

mongobetween proxy（Coinbase 自建）：把多 application process 的連線合成少量到 MongoDB cluster 的連線。9.C36 揭露兩個獨立口徑、不是同一數字的連續變化：deploy 尖峰時 connection event rate 是 ~60K connections / 分鐘（unique connection 事件量、rate）；mongobetween 介入後 steady-state concurrent connection 數 由 ~30K 降到 ~2K（瞬時量、前後對比、一個量級）。引用時把 rate 跟瞬時 concurrent count 分開、不要壓成「60K 收斂到 2K」。

Scope warning（必明示）：mongobetween 是 Coinbase 為 Ruby + GVL 需求自建、case 自承「Go / Java / Node.js 應用因原生支援連線多工、通常不需要這層 proxy」。寫進設計文件時不可寫成「MongoDB 在大規模都需要 mongobetween」、要寫成「特定部署模型才需要」。

Cache + freshness token 層

直接打 MongoDB 不可能撐 1.5M reads/sec（口徑：users 服務應用層觀察、含 cache、非 MongoDB cluster 純讀取）。Coinbase 在 users 服務前面加 Memcached query cache、單 document query 先查 cache。

跨層一致性問題：write 進 MongoDB primary、cache 還是舊版、user 下次 read 拿到舊資料。

Freshness Token 機制：

1. Write 成功後給 client token（含 OCC version / clusterTime）
2. Client read 帶 token
3. Server 保證返回的資料版本 ≥ token
4. 必要時 bypass cache 直接打 DB

跟 DB 層 causal consistency session 對照：causal session 解 MongoDB 內 read-your-own-write、freshness token 解 DB + cache 跨層 read-your-own-write。機制細節見 replica set read preference、本文不重複展開。

Scope warning（必明示）：1.5M reads/sec 是 users 服務 + cache 合成數字、不是 MongoDB cluster 純讀取 benchmark。寫進設計文件必須明示口徑、避免讀者把 1.5M reads/sec 當成「MongoDB 單獨能撐」。

Scaling trigger 層

MongoDB cluster 擴容時間：傳統 reactive scaling 起點到完成 ~70 分鐘（9.C36 Coinbase 揭露口徑：含 instance provisioning + 資料 sync + balancer rebalance、特定 Atlas tier / 資料量條件）。

Reactive 為主撐不住快變流量：CPU / queue 觸發 reactive scaling 在 surge 開始時才動、來不及；surge 已經結束擴容才到位。

Predictive scaling 機制（Coinbase 揭露）：

• 用外部訊號（加密貨幣價格、賽事行程、票務開賣時間）訓練 ML 模型
• 提前 60 分鐘預測流量
• 預先擴容
• 把擴容啟動時間從 70 分鐘壓到 25 分鐘（口徑：trigger 提前、不是擴容本身變快）

Scope warning（必明示）：case 警示「ML 預測有 false positive / false negative、Coinbase 沒揭露準確率、所以仍保留 reactive scaling 作為 safety net」。寫進設計文件要明示兩段式設計、不可寫成「Predictive scaling 取代 reactive scaling」。

對應 knowledge card：connection-pool、stale-read、session-consistency、hot-partition（cache 失效時打穿 DB 的 hot key）。

操作流程

Step 1：connection ceiling audit。量測現有 deploy 在 peak 的 connection count、推算 deploy ×2 / 微服務新增時 connection 走勢；對照 MongoDB cluster 的 hard limit（Atlas tier 決定、典型 1500-32000）。

Step 2：部署模型判讀。

Step 3：proxy 選型。Coinbase mongobetween 是參考實作、社群還有 mongoproxy / DocumentDB 內建 connection multiplexer。自建 proxy 是 Coinbase 規模才合理、中型團隊先評估 Atlas tier 升級。

Step 4：cache layer 設計（read scaling 主路）：

• 前置 Memcached / Redis、cache key = collection + document id + version
• Write API 返回 {result, version_token} — token 含 OCC version 或 MongoDB clusterTime
• Read API 接受 optional version token、cache lookup 比對 entry version 跟 token、低於就 invalidate + bypass
• DB 層 fallback readConcern: "majority" 保證返回 version ≥ token

Step 5：predictive scaling 設計（適用「外部訊號可預測流量」）：

• 識別 driver 訊號：加密貨幣價格 / 賽事行程 / 票務開賣 / 促銷活動 / IoT 緊急事件預警
• 訓練 ML：用歷史流量 vs 訊號 correlation 訓練、輸出未來 30-60 分鐘流量預測
• 觸發擴容：預測超 threshold 時主動 trigger Atlas scaling API、不等 reactive metric
• 保留 reactive safety net：ML failure 時 reactive scaling 仍會接、不可拿掉

Step 6：全鏈路驗證。Staging 灌入 deploy ×2 模擬 connection storm、灌入 stale cache 驗證 freshness token bypass、放假流量驗證 predictive scaling trigger。

驗證點：

• Connection count 在 deploy 後不爆 cluster limit
• Cache hit rate vs freshness bypass rate 比例正常（cache hit > 90% + bypass < 5% 屬通用工程估算、case 未揭露具體數字）
• Predictive scaling 領先窗 ≥ 30 分鐘
• Reactive scaling 仍保留作 safety

Rollback boundary：

• Proxy 層可下線（流量改直連 cluster、但短時 connection storm 風險回來）
• Cache 層可下線（read 全部打 DB、需 cluster 容量能撐）
• Predictive scaling 可下線（退回純 reactive、但快變 surge 接不住）
• 三層都要設計 graceful degradation、不是全有全無

失敗模式

Connection storm during deploy：blue-green 部署 instance 數 ×2、connection 隨之爆、新 deploy 連不上 cluster、cascade 失敗。修法是 proxy 層 + cluster connection limit 預留 headroom（典型留 30% buffer、屬通用工程估算）。

Proxy 變成單點瓶頸：mongobetween / pgbouncer 風格 proxy 自己變熱點、proxy 故障時下游全死。修法是 proxy 叢集 + health check + 客戶端 retry、跟 application 同 region 共部署降低 proxy ↔ application 的網路 RTT。

Cache hit rate 崩塌：cache 失效 + 大量 read bypass、DB 突然吃 100% 流量、cluster 飽和。修法是 freshness token 設計時要監控 bypass rate、過高表示 cache invalidation 邏輯有問題、cache 沒在 write 後 update / invalidate。

Freshness token 漏寫：write 沒帶 token / client 沒帶 token、token silently 失效、user 拿到舊資料。修法是 protocol 強制（middleware 攔截 write / read、自動帶 token）、不能靠 application 自覺。

Predictive scaling false positive 浪費容量：ML 預測 surge 但實際沒來、cluster 預先擴容後閒置。接受成本、保留 ML model retraining、定期評估 precision / recall。

Predictive scaling false negative 漏接 surge：ML 沒預測到、cluster 沒提前擴、surge 來時 reactive scaling 開始動但 70 分鐘來不及。修法是 reactive safety net + 服務降級（限流 / 部分 read 降級拿舊資料 + freshness token 告警）。

三層協作脫節：proxy 擋住 connection storm 但 cluster 內部 read scaling 沒設計、application 仍打爆。三層必須一起設計、不是各自獨立。

Anti-recommendation：

• 中小流量（< 100K reads/sec、單 deploy < 50 instance）不需要這三層；Atlas tier 升級 + cluster 內 replica + 簡單 cache 就夠
• mongobetween 風格 proxy 只在 Ruby + GVL / 類似部署模型才必要、Go / Java / Node.js 通常不需要（case 自承）
• Predictive scaling 只在外部訊號可預測時有效；無預測訊號的純隨機 surge 還是回 reactive + headroom
• 大規模 OLTP 不該為了省成本拿掉 cache 層；read scaling 主路就是 cache、單靠 MongoDB cluster 拿不到 1.5M reads/sec 量級

容量與觀測

關鍵 metric：

• Connection 層：cluster connection count / Atlas tier limit / proxy 到 cluster 的 connection multiplex 比、deploy 前後 connection 走勢
• Cache 層：cache hit rate、freshness token bypass rate、cache key collision rate
• Scaling 層：predictive scaling trigger event count / 領先窗、reactive scaling fallback 觸發頻率、實際擴容啟動到完成時間、ML 預測準確率（precision / recall）

Mongo / Atlas command：

• db.serverStatus().connections：cluster 當前 connection 統計
• db.currentOp({})：看 connection 使用
• Atlas API：cluster scaling event log
• Proxy admin metric：connection multiplex 比、上下游 latency

Application observability：APM 看 connection acquire latency、cache hit rate time series、freshness token 流動完整性（write 是否發 token、read 是否帶 token、cache 是否驗 token）。

回到 4.20 observability evidence：把 connection storm event、cache hit rate / bypass rate、scaling trigger leadtime 列為跨層 evidence 三件套。

回到 9.5 bottleneck localization：大規模 OLTP 撞牆時要區分 (a) connection ceiling (b) cache hit rate 下降 (c) cluster 內 replica 飽和 (d) scaling 跟不上。

邊界與整合

Sibling deep articles：

• replica set read preference — DB 層 causal session 機制、freshness token 跨層協議；本文聚焦三層協作、那篇聚焦 DB 層機制
• shard key selection — cluster 擴容是天級議題、是 scaling layer 的 trigger；單 cluster vs 多 cluster 切分
• schema design pattern — app-layer abstraction 跟本文 cache + freshness token 同層協作、contract layer 三選一
• aggregation pipeline optimization — report dashboard 跑爆 primary 的補位路徑是本文的 cache + read scaling、不是讓 aggregation 自己優化

Migration playbook：

• Federated DB 模式（9.C36 Coinbase 揭露：MongoDB + DynamoDB）— 不是「全用 MongoDB」、document-shaped 用 MongoDB、access pattern 固定的 KV 用 DynamoDB；對應 DynamoDB vendor page 跨 vendor 對照
• 跨雲 hedging（9.C37 Forbes 跨雲彈性）— Atlas 跨 AWS / GCP / Azure 是規避未來雲商鎖定的 selection 訊號

跟 1.x 互引：

• 1.1 高併發資料存取 — connection storm 通用模式（pgbouncer / mongobetween 對應）
• 1.10 KV / Document DB 容量規劃 — 三層架構列為大規模 OLTP 容量規劃必看點
• 9.6 容量規劃模型 — predictive scaling 的 ML 訓練紀律

相關連結

• MongoDB vendor overview — 本文是該頁尾「connection management + Atlas scaling」backlog 的深度展開
• Vendor 深度技術文章方法論
• 9.C36 Coinbase — 三層合成 rich case
• 9.C37 Forbes — 媒體爆量形狀
• 9.C38 Toyota Connected — IoT 雙模式負載
• 官方：MongoDB Connection Pool Options、Atlas Auto-Scaling、mongobetween GitHub

本文不是 pgBouncer overview（請看 PostgreSQL vendor 頁 中 connection pool 段）— 而是 production 部署 + 故障演練 的實作層教學。覆蓋三層 pool（application → pgBouncer → PostgreSQL）的對齊、transaction pooling 跟 session pooling 的選擇陷阱、跟 HA failover 的整合、容量規劃。

問題情境

典型觸發場景：團隊規模從 50 人爬到 200 人、microservice 從 20 個爬到 100 個、K8s replica 從 3 個爬到每服務 5-10 個。直連 PostgreSQL 的 connection 計算：

1100 service × 6 replica × 30 application pool = 18000 connection

PostgreSQL 預設 max_connections = 100、production 設 max_connections = 500-1000 已經是上限（每多一個都加 memory + context switch cost）。18000 連線打 PostgreSQL 直接打爆。

進一步問題：

• 一半 connection 是 idle（application pool 預留、實際沒查詢）— 浪費 backend slot
• Cold start 時所有 replica 同時建 connection、瞬間 spike
• DB failover 時所有 application 同時 reconnect、prod-test pattern 跑不通
• DNS-based failover 時 application connection pool 不知道 backend 換了

pgBouncer 解這四個問題。但 引入 pgBouncer 後又會引入新的問題層（pgBouncer 跟 application pool 不對齊、transaction pooling 的 session state 限制、HA 故障時 pgBouncer 也要 failover）— 本文討論這些。

核心概念：pool mode + sizing

pgBouncer 的 first-class concept 是 pool mode、決定 application connection 跟 PostgreSQL backend connection 的綁定方式：

• Session pooling：application connection 拿到 backend connection 後、整個 session 期間都綁同一個 backend。tear-down 才釋放。語義跟「直連」一樣、不破壞 session state。但 idle connection 仍占 backend slot、收斂效率低、適合 連線數不多但要保留 session state（用了 prepared statement、temporary table、advisory lock 等）的場景。
• Transaction pooling：application connection 在 transaction 邊界 才綁 backend、commit / rollback 後立即釋放。同一個 application connection 不同 transaction 可能拿到不同 backend。收斂效率高（idle connection 完全不占 backend slot）、但 session state 限制嚴 — 不能用 SET 改 session-level setting、不能用 prepared statement（除非 application 端禁用）、不能用 advisory lock 跨 transaction。
• Statement pooling：每個 statement 完就釋放 backend。極端高收斂但 連 transaction 都不能跨 statement、絕大多數 application 用不了、只在 batch query 場景。

Production 預設選 transaction pooling、application 端禁用 prepared statement（或用 PgBouncer-supported prepared statement、需 pgBouncer 1.21+）。例外場景才開 session pooling。

Pool sizing 公式：

1PostgreSQL max_connections     = pgBouncer N × default_pool_size + reserve
2pgBouncer default_pool_size    = per-database backend connection 上限
3Application pool size          = 每 application instance 拿幾個 pgBouncer connection

實例：50 個 application replica、每 instance pool 30 個、pgBouncer 後 default_pool_size = 20（per database）、3 個 database。

1Total application → pgBouncer = 50 × 30 = 1500 connection
2pgBouncer → PostgreSQL        = 3 × 20 = 60 connection
3PostgreSQL max_connections    = 60 + reserve (50 預留 admin / migration) = 110

1500 → 110 收斂 13.6 倍、PostgreSQL 還在合理上限內。

Step-by-step 配置

pgBouncer.ini：

 1[databases]
 2mydb = host=postgres-primary.internal port=5432 dbname=mydb auth_user=pgbouncer
 3
 4[pgbouncer]
 5listen_port = 6432
 6listen_addr = 0.0.0.0
 7auth_type = scram-sha-256
 8auth_file = /etc/pgbouncer/userlist.txt
 9auth_query = SELECT usename, passwd FROM pg_shadow WHERE usename=$1
10
11pool_mode = transaction
12default_pool_size = 20
13min_pool_size = 5
14reserve_pool_size = 10
15reserve_pool_timeout = 5
16
17max_client_conn = 2000
18max_db_connections = 100
19
20server_idle_timeout = 600
21server_lifetime = 3600
22server_connect_timeout = 15
23server_login_retry = 5
24
25client_idle_timeout = 0
26client_login_timeout = 60
27
28stats_period = 60
29log_connections = 0
30log_disconnections = 0
31log_pooler_errors = 1
32
33admin_users = pgbouncer_admin
34stats_users = pgbouncer_stats

關鍵欄位解釋：

• pool_mode = transaction：絕大多數 production 場景
• default_pool_size = 20：每 database 對 PostgreSQL 的 backend connection 上限、調整時要算進 PostgreSQL max_connections
• reserve_pool_size = 10 + reserve_pool_timeout = 5：當 default_pool_size 用滿、等 5 秒還拿不到 connection 才用 reserve pool — 是 突發 spike 的 buffer、不是 baseline
• max_client_conn = 2000：application 端能連 pgBouncer 的最大數
• server_lifetime = 3600：每 1 小時強制 recycle backend connection、避免 long-lived connection 累積 memory bloat（PostgreSQL pg_stat_activity 看 connection age）
• auth_query：pgBouncer 直接從 PostgreSQL pg_shadow 拉密碼、不需要在 pgBouncer 本地維護 userlist — production 推薦做法

Application 端 pool 設定：

 1# 例：Spring Boot HikariCP
 2spring.datasource.url: jdbc:postgresql://pgbouncer.internal:6432/mydb
 3spring.datasource.hikari.maximum-pool-size: 30
 4spring.datasource.hikari.minimum-idle: 5
 5spring.datasource.hikari.connection-timeout: 30000
 6spring.datasource.hikari.idle-timeout: 600000
 7spring.datasource.hikari.max-lifetime: 1800000  # 30 min < pgBouncer server_lifetime 60 min
 8
 9# 例：SQLAlchemy
10engine = create_engine(
11    "postgresql://pgbouncer.internal:6432/mydb",
12    pool_size=30,
13    max_overflow=5,
14    pool_pre_ping=True,        # 必開、檢測 stale connection
15    pool_recycle=1800,         # 30 min、跟 pgBouncer server_lifetime 對齊
16)

Application 跟 pgBouncer 對齊：

• application max-lifetime < pgBouncer server_lifetime：避免 application 拿到已被 pgBouncer recycle 的 connection
• pool_pre_ping = True：每次 checkout 前 send SELECT 1、檢測 stale connection — 對 transaction pooling 是必要的
• application 端 不要 用 prepared statement（除非 pgBouncer 1.21+ 設 max_prepared_statements）

故障演練 / 邊界 case

Case 1：Pool exhaustion（default_pool_size 用滿）

徵兆：application log ERROR: no more connections allowed、pgBouncer log pool is full、pgBouncer admin console SHOW POOLS 顯示 cl_waiting > 0。

Debug：

1-- 連 pgBouncer admin
2\c pgbouncer
3SHOW POOLS;
4-- 看 cl_active / cl_waiting / sv_active / sv_idle
5SHOW SERVERS;
6-- 看 server connection state（active / idle / used）

修：

• 短期：調高 default_pool_size 跟 PostgreSQL max_connections、配合 reserve pool
• 中期：找 long-running query（PostgreSQL pg_stat_activity 看 query_start、kill 過長 query）
• 長期：拆 database / 改 read replica / 移 OLAP query 到 data warehouse

Case 2：Transaction pooling 下 session state 漏洞

徵兆：random 失敗 prepared statement "S_3" does not exist、relation "tmp_xxx" does not exist、advisory lock 不釋放。

原因：application 用了 prepared statement / temporary table / advisory lock、但 transaction commit 後 backend connection 釋放、下一個 transaction 拿到不同 backend、session state 不存在。

修：

• Application 框架禁用 prepared statement（JDBC prepareThreshold=0、SQLAlchemy use_native_prepared_statements=False）
• temporary table 改 unlogged table + cleanup
• advisory lock 改 row-level lock 或 application-level lock（Redis）
• 或：切到 session pooling、犧牲收斂效率

Case 3：DNS-based failover 後 application 連到舊 master

徵兆：PostgreSQL 切換 master 後、application 寫操作 時好時壞（看連到哪台）。

原因：pgBouncer 在 application 跟 PostgreSQL 之間、application 不知道 backend 換了；pgBouncer 自己也需要 reload config 才會連新 master。

修：

• pgBouncer 用 RECONNECT admin command 強制 close all backend connection、重連
• 配 Patroni / Stolon 等 HA 工具自動 trigger pgBouncer reconnect
• application 端 pool_pre_ping 開啟、stale connection 自動踢

Case 4：Server lifetime recycle 跟 in-flight transaction 衝突

徵兆：偶發 server closed the connection unexpectedly、跟 long-running transaction 重疊。

原因：pgBouncer server_lifetime = 3600 強制 recycle、但有 transaction 在跑時 pgBouncer 不會切、超過時間後仍會切。

修：

• 確認沒有 超過 1 小時 的 transaction（PostgreSQL pg_stat_activity 看 xact_start）
• 必要時調高 server_lifetime、但 memory bloat 風險上升
• application 端做 transaction timeout

Case 5：pgBouncer 自己 crash / OOM

徵兆：所有 application 同時失去 PostgreSQL 連線。

原因：pgBouncer 是 single-process（除非 1.21+ 用 so_reuseport 多 process）、memory leak / OOM / 部署事件都會打掉整個 connection layer。

修：

• 多 pgBouncer instance + load balancer（HAProxy / Envoy）前置、application 連 LB
• so_reuseport = 1（1.21+）讓多個 pgBouncer process 共用 port
• Resource limit 跟 alert：RSS > N、connection count > M
• HA mode：active-passive 配 keepalived

容量 / cost 規劃

單一 pgBouncer 容量上限：

• max_client_conn：實務 < 5000 per instance（再高 CPU 跟 file descriptor 緊）
• default_pool_size × database 數：實務 < 200 per instance
• single process CPU bound：在 10K QPS 等級已經是瓶頸、要橫向 scale

何時加 pgBouncer instance：

• application connection 數突破 3000 / pgBouncer instance
• pgBouncer CPU usage > 60%（baseline、不算 spike）
• 跨 region application 需要 region-local pgBouncer

何時改架構（pgBouncer 不夠用）：

• PostgreSQL backend connection 數突破 500（即使有 pgBouncer 也撐不住）→ 改 read replica / partitioning / sharding
• write 量太大（每秒 50K+ TPS）→ 改 sharding（Vitess / Citus）或全球分散式 SQL（1.11 全球分散式 OLTP）
• application 大量 prepared statement / session state 需求 → 改 PgCat（Rust 寫、支援更完整的 session feature）或回 session pooling

整合 / 下一步

跟 HA failover 整合（Patroni）：

• Patroni 切換 master 後 trigger pgBouncer RECONNECT
• pgBouncer 透過 service discovery（Consul / etcd）拿新 master 位址、不是寫死在 config
• application 不需感知 failover、connection 從 pgBouncer 拿到新 master 的 backend

跟監控整合：

• pgBouncer admin console SHOW STATS / SHOW POOLS / SHOW SERVERS 拉到 Prometheus（pgbouncer_exporter）
• 必看 metric：cl_waiting（等 backend 的 client 數）、sv_active（active backend 數）、avg_query_time、avg_xact_time
• Alert：cl_waiting > 0 持續 30s、server connection error rate > 0

跟 application observability 整合：

• Application APM（Datadog / Honeycomb / OpenTelemetry）的 DB span 顯示 application 看到的 latency、pgBouncer metric 顯示 pgBouncer ↔ PostgreSQL latency — 兩者差異揭露 connection wait time

何時 revisit 這個配置：

• application 數量倍增（trigger pool sizing 重算）
• PostgreSQL 升級（pgBouncer 跟 PostgreSQL 版本相容性）
• 跨 region 部署（要不要 region-local pgBouncer）
• 切換到 RDS Proxy / Aurora Cluster Endpoint（managed alternative）

相關連結

• PostgreSQL vendor overview — 本文是該頁尾「pgBouncer / PgCat 配置 best practice」backlog 的深度展開
• Connection Scaling Deep Dive — connection-per-process model 跟為什麼 pooler 是必裝（根因 vs 配置）
• 1.1 高併發資料存取 — 上游：什麼時候需要 connection pool
• Connection Pool 卡片 — 概念基底
• Vendor 深度技術文章方法論 — 本文是該方法論的 demo #1
• 9.C29 Lemino RDB connection limit case — connection 爆是 streaming surge 場景的 vendor-switch 主因
• 官方：pgBouncer Documentation

本文的驗收標準是：你能比較 direct connection 與 PgBouncer transaction pooling，取得 pg_stat_activity、PgBouncer SHOW POOLS、latency / error sample 與 failure note。

Baseline Direct Connections

Baseline direct connections 的核心責任是先看 application 直連 PostgreSQL 時的 backend 數。

1export DATABASE_URL="postgres://lab_admin:lab_admin_pw@localhost:54329/appdb?sslmode=disable"
2psql "$DATABASE_URL" -c "SELECT count(*) FROM pg_stat_activity WHERE datname = current_database();"

用多個 terminal 或簡單 workload 產生 idle connection：

1for i in 1 2 3 4 5; do
2  psql "$DATABASE_URL" -c "SELECT pg_sleep(10);" &
3done
4psql "$DATABASE_URL" -c "SELECT state, count(*) FROM pg_stat_activity WHERE datname = current_database() GROUP BY state;"

這一步證明每個 client session 會占用 PostgreSQL backend process。

Add PgBouncer

Add PgBouncer 的核心責任是把 client connection 與 server connection 拆開。以下 compose fragment 可加入 local lab：

 1  pgbouncer:
 2    image: edoburu/pgbouncer:latest
 3    environment:
 4      DB_HOST: postgres
 5      DB_USER: lab_admin
 6      DB_PASSWORD: lab_admin_pw
 7      DB_NAME: appdb
 8      POOL_MODE: transaction
 9      MAX_CLIENT_CONN: 100
10      DEFAULT_POOL_SIZE: 5
11    ports:
12      - "64329:5432"

啟動後設定 pooler URL：

1export POOL_URL="postgres://lab_admin:lab_admin_pw@localhost:64329/appdb?sslmode=disable"

Compare Pool Behavior

Compare pool behavior 的核心責任是觀察 client 多、server 少的效果。

1for i in $(seq 1 20); do
2  psql "$POOL_URL" -c "SELECT pg_sleep(1);" &
3done
4psql "$DATABASE_URL" -c "SELECT state, count(*) FROM pg_stat_activity WHERE datname = current_database() GROUP BY state;"

再進 PgBouncer admin console，實際命令依 image 設定調整：

1psql "postgres://lab_admin:lab_admin_pw@localhost:64329/pgbouncer?sslmode=disable" -c "SHOW POOLS;"

驗收重點是：client workload 增加時，PostgreSQL backend 數量被 pool size 控制，排隊發生在 pooler 層。

Pool Exhaustion

Pool exhaustion 的核心責任是看過載時的錯誤與等待。

1for i in $(seq 1 50); do
2  psql "$POOL_URL" -c "BEGIN; SELECT pg_sleep(5); COMMIT;" &
3done

觀察：

1psql "$DATABASE_URL" -c "SELECT count(*) FROM pg_stat_activity WHERE datname = current_database();"
2psql "postgres://lab_admin:lab_admin_pw@localhost:64329/pgbouncer?sslmode=disable" -c "SHOW POOLS;"

Pool exhaustion 的 evidence 包含 waiting clients、timeout、application latency 與 error message。這些要接到 production alert。

Failure Note

Failure note 的核心責任是把 lab 結果轉成 runbook。記錄三件事：

1. Direct connection baseline backend 數。
2. PgBouncer transaction pooling 下 server connection 數。
3. Pool exhaustion 時的 latency / error / queue。

若 application 使用 session state、prepared statement、temp table 或 advisory lock，還要補 transaction pooling compatibility matrix。

下一步路由

完成本篇後，回到 Connection Pooler Comparison 做選型；要看 PgBouncer production 設定讀 PgBouncer Config。