本文的驗收標準是：你能比較 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。

本文的驗收標準是：你能記錄 failover timeline、replication lag snapshot、client error sample、data validation query 與 incident decision log entry。實際觸發方式依 Patroni、managed PostgreSQL 或雲平台而異；lab 重點是 evidence。

Pre-Failover Baseline

Pre-failover baseline 的核心責任是確認 primary / standby 狀態與 client route。

1SELECT pg_is_in_recovery();
2SELECT now(), pg_current_wal_lsn();
3SELECT application_name, state, sync_state, replay_lag
4FROM pg_stat_replication;

在 standby 查：

1SELECT pg_is_in_recovery();
2SELECT now(), pg_last_wal_receive_lsn(), pg_last_wal_replay_lsn();

Baseline 要保存 primary host、standby host、replication lag、application connection string、pooler route 與 current timeline。

Client Workload

Client workload 的核心責任是讓 failover 對 application 的影響可見。

1while true; do
2  date -u
3  psql "$DATABASE_URL" -c "INSERT INTO restore_markers(marker) VALUES ('failover-drill') RETURNING id, created_at;"
4  sleep 1
5done

這個 loop 會在 failover 期間產生成功、timeout、connection reset 或 read-only error。正式演練要用 synthetic workload，避免影響真實使用者。

Trigger Failover

Trigger failover 的核心責任是以受控方式促成 promotion。Patroni lab 可以用 patronictl failover；managed service 則用 provider failover / reboot with failover 功能。

1failover_start_time:
2trigger_method:
3old_primary:
4candidate:
5operator:
6reason:

Failover 觸發前要先確認這是演練，並且 workload、backup、rollback 與 stakeholder 都已對齊。

Observe Promotion

Observe promotion 的核心責任是記錄資料庫與 client 的時間線。

Promotion timeline 要保留秒級時間戳。這是評估 RTO、client retry 與 pooler behavior 的基礎。

Data Validation

Data validation 的核心責任是確認 failover 後資料一致性。

1SELECT count(*) FROM restore_markers WHERE marker = 'failover-drill';
2SELECT max(created_at) FROM restore_markers;
3SELECT status, count(*) FROM accounts GROUP BY status;

若 workload 有 idempotency key，還要檢查 duplicate。若外部 side effect 參與交易，例如 payment 或 queue，必須有 reconciliation query。

Pooler and Client Behavior

Pooler and client behavior 的核心責任是確認 failover 後連線能重新指向新 primary。

檢查項目：

1. Application retry 是否有 backoff / jitter。
2. PgBouncer / proxy 是否清掉舊 server connection。
3. DNS / endpoint TTL 是否符合 RTO。
4. Read-only error 是否被正確分類。
5. Migration / background job 是否暫停。

Failover 的完成標準包含 database promote、client reconnect 與 pooler stable。若 client 長時間連到舊 primary 或 pooler 卡住，服務仍處於 unavailable 狀態。

Incident Decision Log

Incident decision log 的核心責任是把演練變成可審查紀錄。

1Incident / drill id:
2Decision: promote standby
3Reason:
4Accepted data loss:
5RTO observed:
6Client impact:
7Validation result:
8Follow-up:

每次 drill 都要產生 follow-up。常見 follow-up 是調整 retry、降低 DNS TTL、補 pooler command、增加 validation query 或改善 monitoring。

下一步路由

完成本篇後，HA 架構讀 Patroni HA；跨區災難復原讀 Cross-region DR；connection retry 與 pooler 行為讀 Connection Pool Lab。

本文的驗收標準是：你能啟動本地 PostgreSQL，套用 schema，跑 sample workload，取得 pg_stat_activity / pg_stat_database snapshot，最後 teardown 並重建。

Docker Compose

Docker Compose 的核心責任是讓 lab 環境可重建。建立 docker-compose.yml：

 1services:
 2  postgres:
 3    image: postgres:16
 4    environment:
 5      POSTGRES_USER: lab_admin
 6      POSTGRES_PASSWORD: lab_admin_pw
 7      POSTGRES_DB: appdb
 8    ports:
 9      - "54329:5432"
10    command:
11      - "postgres"
12      - "-c"
13      - "log_min_duration_statement=100"
14      - "-c"
15      - "shared_preload_libraries=pg_stat_statements"

啟動：

1docker compose up -d
2export DATABASE_URL="postgres://lab_admin:lab_admin_pw@localhost:54329/appdb?sslmode=disable"

Baseline Schema

Baseline schema 的核心責任是建立可測 transaction、index、lock 與 migration 的資料模型。

 1psql "$DATABASE_URL" <<'SQL'
 2CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
 3
 4CREATE TABLE accounts (
 5  id bigserial PRIMARY KEY,
 6  tenant_id uuid NOT NULL,
 7  owner_name text NOT NULL,
 8  status text NOT NULL CHECK (status IN ('active', 'closed')),
 9  created_at timestamptz NOT NULL DEFAULT now()
10);
11
12CREATE TABLE ledger_entries (
13  id bigserial PRIMARY KEY,
14  account_id bigint NOT NULL REFERENCES accounts(id),
15  amount_cents bigint NOT NULL CHECK (amount_cents <> 0),
16  idempotency_key text NOT NULL UNIQUE,
17  created_at timestamptz NOT NULL DEFAULT now()
18);
19
20CREATE INDEX idx_ledger_entries_account_created
21ON ledger_entries(account_id, created_at DESC);
22SQL

這組 schema 後續可用於 migration、lock、PITR 與 pool lab。

Seed and Workload

Seed and workload 的核心責任是產生可觀察的資料與查詢。

 1psql "$DATABASE_URL" <<'SQL'
 2INSERT INTO accounts(tenant_id, owner_name, status)
 3VALUES
 4  ('00000000-0000-0000-0000-000000000001', 'Ada', 'active'),
 5  ('00000000-0000-0000-0000-000000000002', 'Lin', 'active');
 6
 7INSERT INTO ledger_entries(account_id, amount_cents, idempotency_key)
 8SELECT 1, 100, 'seed-ada-' || g
 9FROM generate_series(1, 100) AS g;
10
11SELECT a.owner_name, SUM(l.amount_cents) AS balance_cents
12FROM accounts a
13JOIN ledger_entries l ON l.account_id = a.id
14GROUP BY a.owner_name;
15SQL

Sample workload 要保留 SQL 與輸出，作為後續 migration / restore validation 的 baseline。

Basic Evidence

Basic evidence 的核心責任是把 lab 狀態保存成可比較 snapshot。

 1psql "$DATABASE_URL" <<'SQL'
 2SELECT current_database(), current_user, version();
 3SELECT relname, n_live_tup FROM pg_stat_user_tables ORDER BY relname;
 4SELECT datname, numbackends, xact_commit, xact_rollback
 5FROM pg_stat_database
 6WHERE datname = current_database();
 7SELECT pid, state, wait_event_type, query
 8FROM pg_stat_activity
 9WHERE datname = current_database();
10SQL

這些查詢是 PostgreSQL lab 的最小 evidence。正式服務要再加入 slow query、lock wait、replica lag、backup status 與 pooler metrics。

Teardown

Teardown 的核心責任是讓 lab 可重跑。

1docker compose down -v

重建後應能重新套用 schema 與 seed。若 lab 需要跨章節沿用資料，先用 pg_dump 保存 fixture，再 teardown。

下一步路由

完成本篇後，連線壓力進入 Connection Pool Lab；migration evidence 進入 Schema Migration Evidence Lab；backup / PITR 進入 PITR Restore Drill。

本文的驗收標準是：你能記錄 base backup 時間、target time、restore duration、validation query 與 RPO / RTO note。實際命令會依 pgBackRest、Barman、cloud snapshot 或 managed service 而變；本文提供 vendor-neutral drill frame。

Prepare Recovery Point

Prepare recovery point 的核心責任是建立可辨識 transaction。先寫入一筆 marker，記錄時間。

 1psql "$DATABASE_URL" <<'SQL'
 2CREATE TABLE IF NOT EXISTS restore_markers (
 3  id bigserial PRIMARY KEY,
 4  marker text NOT NULL,
 5  created_at timestamptz NOT NULL DEFAULT clock_timestamp()
 6);
 7
 8INSERT INTO restore_markers(marker) VALUES ('before-bad-change');
 9SELECT id, marker, created_at FROM restore_markers ORDER BY id DESC LIMIT 1;
10SQL

把 created_at 記為 target time。正式 drill 要用 UTC，並記錄 timezone、operator、backup set 與 WAL archive status。

Create Bad Change

Create bad change 的核心責任是模擬需要 PITR 的錯誤。

1psql "$DATABASE_URL" <<'SQL'
2INSERT INTO restore_markers(marker) VALUES ('bad-change-after-target');
3UPDATE accounts SET status = 'closed';
4SELECT status, count(*) FROM accounts GROUP BY status;
5SQL

這一步在 lab 中代表誤操作。Production 事故中，bad change 可能是誤刪、錯誤 batch、壞 migration 或 application bug。

Restore Workflow

Restore workflow 的核心責任是把 backup tool 的操作轉成固定 evidence。不同工具命令不同，但流程一致：

1. 選定 base backup。
2. 設定 recovery target time。
3. 套用 WAL 到 target time。
4. Promote restored instance。
5. 跑 validation query。
6. 啟動 application smoke test。

Example pseudo-runbook：

1restore_target_time = 2026-05-21T10:15:30Z
2base_backup = latest backup before target
3wal_archive = available through target
4restore_path = isolated environment

Restore 必須在隔離環境先完成。直接覆蓋 production 會讓 evidence 與 rollback 空間消失。

Validation Query

Validation query 的核心責任是確認 restore 到正確時間點。

1psql "$RESTORED_DATABASE_URL" <<'SQL'
2SELECT marker, created_at
3FROM restore_markers
4ORDER BY id;
5
6SELECT status, count(*)
7FROM accounts
8GROUP BY status;
9SQL

預期結果是存在 before-bad-change，且 bad-change-after-target 尚未出現。accounts 狀態應維持 target time 前的分布。

RPO / RTO Evidence

RPO / RTO evidence 的核心責任是把 drill 結果轉成服務語言。

PITR 的成功標準是資料與 application 都可用。只讓 PostgreSQL 啟動成功，還不足以交付服務。

Drill Retrospective

Drill retrospective 的核心責任是把演練缺口轉成下一步。

常見缺口：

1. 找不到正確 base backup。
2. WAL archive 缺段。
3. target time timezone 混亂。
4. Restore 太慢，超過 RTO。
5. Application secret / config 指不到 restored DB。
6. Validation query 缺少 business invariant。

完成本篇後，跨區恢復讀 Cross-region DR；備份策略讀 PITR + WAL Archiving。

本文的驗收標準是：你能設計 expand migration、量測 lock、跑 backfill validation、建立 contract migration 的 fail-forward / rollback 判準。

Expand Migration

Expand migration 的核心責任是先加入向後相容 schema。以下範例新增 accounts.email，先允許 null。

1psql "$DATABASE_URL" <<'SQL'
2\timing on
3BEGIN;
4ALTER TABLE accounts ADD COLUMN email text;
5COMMIT;
6SQL

新增 nullable column 通常是低風險操作，但仍要記錄 timing 與 lock。正式服務要在低流量窗口或 staging 上先測。

Lock Evidence

Lock evidence 的核心責任是讓 migration 的阻塞風險可見。開另一個 terminal，在 migration 前後查 lock。

1psql "$DATABASE_URL" <<'SQL'
2SELECT locktype, relation::regclass, mode, granted, pid
3FROM pg_locks
4WHERE relation IN ('accounts'::regclass, 'ledger_entries'::regclass)
5ORDER BY granted, mode;
6SQL

Release gate 要保存 lock mode、duration、blocked session 與 application impact。高風險 DDL 要先改成 expand / backfill / contract。

Backfill and Validation

Backfill and validation 的核心責任是把資料補齊並證明結果符合 domain。

1psql "$DATABASE_URL" <<'SQL'
2UPDATE accounts
3SET email = lower(owner_name) || '@example.test'
4WHERE email IS NULL;
5
6SELECT count(*) AS missing_email
7FROM accounts
8WHERE email IS NULL;
9SQL

大型表要分 batch backfill，避免 WAL、replica lag、autovacuum 與 lock 壓力。每個 batch 要記錄 row count、duration、error 與 lag。

Add Constraint Safely

Add constraint safely 的核心責任是把資料驗證和 constraint 生效拆開。

1psql "$DATABASE_URL" <<'SQL'
2ALTER TABLE accounts
3ADD CONSTRAINT accounts_email_present
4CHECK (email IS NOT NULL) NOT VALID;
5
6ALTER TABLE accounts
7VALIDATE CONSTRAINT accounts_email_present;
8SQL

NOT VALID 讓 constraint 先約束新資料，再用 validation 掃既有資料。這是 PostgreSQL online migration 常用技巧。

Query Plan Evidence

Query plan evidence 的核心責任是確認 migration 後 query 仍走正確路徑。

1psql "$DATABASE_URL" <<'SQL'
2EXPLAIN (ANALYZE, BUFFERS)
3SELECT *
4FROM accounts
5WHERE email = 'ada@example.test';
6SQL

若 email 查詢成為正式 path，要新增 index，並用 CREATE INDEX CONCURRENTLY 評估 lock 與時間。

Contract Migration

Contract migration 的核心責任是在 application 都改用新欄位後，收斂舊欄位或舊 constraint。Contract migration 要比 expand 更謹慎，因為 rollback 空間更小。

Contract release gate：

1. 所有 app version 已停止讀舊欄位 / 舊行為。
2. Backfill validation 為零缺口。
3. Query plan 與 index evidence 已保存。
4. Rollback path 是 fail-forward 或 restore，兩者擇一寫清楚。
5. PITR / backup window 符合風險。

Release Gate Note

Release gate note 的核心責任是形成可交付 artifact。

1Migration: add accounts.email
2Expand DDL duration:
3Backfill rows:
4Validation query:
5Lock evidence:
6Query plan:
7Rollback / fail-forward:
8Owner:

完成本篇後，複雜 migration 回到 Online Schema Change；需要跨 DB 遷移則讀 Database Migration Playbook。