PgBouncer トランザクション プーリングの説明

PgBouncer には 3 つのモードがあり、Postgres サーバー接続がいつ共通プールに戻るかだけが異なります。公式ドキュメントでは、それらに session、 transaction 、 statement という名前が付けられています (pgbouncer.org/features.html、「プーリング モード」セクション、2026 年 8 月 24 日にアクセス)。

セッション モードは最も寛容ですが、スケーラビリティの点で最も効果的ではありません。Postgres 接続は、2 つのリクエストの間に何も行わない場合でも、接続されたままである限りクライアント用に予約されたままになります。ステートメント モードは、非常に特殊なケース (読み取り専用プロキシ、ヘルスチェック) のために予約されており、従来の明示的なトランザクションも中断します。トランザクション モードは、REST API で実際に主流となる妥協案です。通常、各 HTTP リクエストは単一の短い Postgres トランザクションに対応します。

トランザクション モードでは、PgBouncer は、クライアントがトランザクションを開いたときにのみサーバー接続をクライアントに接続し、COMMIT または ROLLBACK 時にそれをプールに返します。 2 つのトランザクション間で、同じクライアントがまったく異なるサーバー接続に再割り当てされる場合があります。

具体的には、default_pool_size が 20 の場合、PgBouncer は、実際に進行中のトランザクションが数個しかない数百の同時クライアントを吸収できます。この比率により、トラフィックは多いがトランザクションが短い REST API のトランザクション モードが正当化されます。まれなリソース (サーバー側のメモリに高価な Postgres 接続) は、厳密に必要な時間だけ占有されます。

[pgbouncer]
listen_port = 5432

; La connexion serveur est libérée dès la fin de chaque transaction
pool_mode = transaction

default_pool_size = 80
max_client_conn = 1000

; Ne pas utiliser avec des sessions stateful (SET, advisory locks, LISTEN/NOTIFY)

この最後のコメントは要点を要約しています。トランザクション モードは、「アプリケーション セッション」と「Postgres 接続」の間のリンクを意図的に切断するため機能します。このリンクに基づくものはすべて壊れます。次のセクションでは、正確に何をリストします。

PgBouncer の公式ドキュメントには、同じクライアントからの 2 つのリクエスト間でサーバー接続が再利用されるとすぐに意味を失う PostgreSQL の機能が明示的にリストされています。

最新の Postgres ドライバーは、アプリケーション コードが明示的に要求することなく、デフォルトでプロトコル側で名前付き要求を準備します。まさにこれが、この罠の予測を困難にしている理由です。

プロトコル準備済みステートメントは、 Parseの時点で名前が付けられ、特定のサーバー接続にキャッシュされます。トランザクション モードでは、同じ論理クライアントからの 2 つのリクエストの間に、この接続を別のクライアントに再割り当てできます。その後、ドライバーが準備されていない接続上で同じステートメント名を再実行すると、Postgres は明示的なエラー (通常、sqlx クライアントの場合は prepared statement "sqlx_s_N" does not exist) で応答します。この動作は断続的です。呼び出しごとに再現できる決定的なバグではなく、負荷の下で接続がどのように実行されるかによって決まります。

クライアント側の修正は言語に関係なく同じです。トランザクション モードでプーラーを通過するプールに対して、名前付きプリペアド ステートメントのキャッシュを無効にするか、名前のないクエリを強制します。 Rust と sqlx では、接続オプションで statement_cache_capacity(0) を通過します。

let connect_options = url
    .parse::<PgConnectOptions>()?
    .statement_cache_capacity(0);

// 同等のもの: asyncpg -> statement_cache_size=0、pgjdbc -> prepareThreshold=0

バージョン 1.21 以降、PgBouncer はサーバー側の問題の一部を軽減します。トランザクション モードでプロトコルの準備済みステートメントに従い、割り当てられた接続上でオンザフライでステートメントを準備できます。接続ごとの LRU キャッシュのサイズは max_prepared_statements経由で調整されます。これによりミスの数は減りますが、 search_path があるリクエストから別のリクエストに変更されるマルチテナント プールでクライアント キャッシュを無効にすることが免除されるわけではありません。キャッシュされたプランは Parseの時点で解決されたテーブルの内部識別子 (OID) をフリーズし、別のスキーマで再実行すると、単純なエラーではなく間違ったテナントからデータが返される可能性があります。

Aurabase リポジトリは、共有データプレーン (deploy/helm/aurabase/templates/infra/pgbouncer.yaml) の前に PgBouncer を pool_mode=transaction としてデプロイし、テナントの各専用 Postgres インスタンス (deploy/cnpg/tenant-pooler.yaml) の前に同一に設定された Pooler CNPG をデプロイします。どちらのパスにも、上で説明したのと同じ規律が適用されます。

ソース コードには、安定性だけの理由ではなく、この選択の具体的なセキュリティ上の理由が文書化されています。テナント間で共有される Postgres プールは、再利用された接続上でプロジェクトごとに異なる search_path を配置します。キャッシュされたプリペアド ステートメントは、 Parseの時点で解決されたテーブルの OID をフリーズします。同じ接続上の別のテナントに対してクエリを再実行すると、単なるアプリケーション エラーではなく、最初のテナントのスキーマに対してクエリが実行され、分離バイパスが行われます。 したがって、statement_cache_capacity(0) は、トランザクション モードで CNPG プーラーも通過する専用インスタンスを含め、例外なく適用されます。

2 番目のセッション衛生対策: 各接続がプールに戻ると、フックによって DISCARD ALL が実行されます (設定のリセット、サーバー側で準備されたステートメントの割り当て解除、アドバイザリー ロックの解放、カーソルと一時テーブルのパージ)。このフックがないと、前のリクエストによって発生したセッションの残留物が、同じリサイクルされた接続を再利用する別のテナントからの次のリクエストでリークする可能性があります。

Exception accepted: dedicated PostgREST instances remain in direct connection to the primary, without going through the pooler. PostgREST schema reloading relies on LISTEN/NOTIFY, which assumes a persistent connection, exactly the functionality that transaction mode breaks (detail already documented in our article on PostgREST compatibility at Aurabase). RLS settings per request are passed to SET LOCAL within an explicit transaction, the only way to remain compatible with a pool that can change server connections at any COMMIT (see our article onmulti-tenant RLS isolation).

短いチェックリスト。Postgres の直接接続からトランザクション モードの PgBouncer に移行するバックエンドに適用できます。

1. アプリケーション コードを監査します。 非トランザクション SET、 LISTEN/NOTIFY、セッション勧告ロック、 WITH HOLD カーソル、およびクエリ間で再利用される一時テーブルを探します。
2. 明示的なトランザクション内のセッション SET を LOCAL SET に置き換えます。これは、次の接続でリークするのではなく、COMMIT/ROLLBACK でクリーンアップされるため、接続のリサイクル後に適切に存続する唯一の設定です。
3. プールがプーラーを通過し、スキーマまたはロールがリクエスト間で変更される場合は、ドライバー側のプリペアド ステートメント キャッシュ を無効にします。パフォーマンスのコストは実際のものですが測定可能であり、テナント間の漏洩のリスクよりもはるかに低くなります。
4. セッション モード (移行、管理スクリプト、LISTEN/NOTIFY に依存するもの) を本当に必要とする接続を、他のすべてのトラフィックに対してトランザクション モードを放棄するのではなく、直接の非プーラー接続に分離します。
5. default_pool_size および max_client_conn のサイズは、別のプロジェクトからコピーした任意の数値ではなく、Postgres の実際の max_connectionsを基準にします。
6. 単なるスモークテストではなく、実際の負荷の下でテストします。 準備されたステートメントのエラーとセッション設定のリークは、単一のローカル接続ではほとんど発生しません。
7. 運用環境に入ったら、PgBouncer 管理コンソールから SHOW POOLS および SHOW STATS を監視し、クライアント側でプールの飽和が表示される前にそれを特定します。

いいえ、しかし、これは大部分の REST API にとって正しいデフォルトの選択です。セッション モードは、すぐにリファクタリングできないセッション機能に大きく依存するレガシー アプリケーションや、プールのゲインが移行作業を補えない低トラフィックの場合には、引き続き推奨されます。

このプーリング モデルの実装は PgBouncer だけではありません。Supavisor (Supabase) と PgCat は最近の 2 つの代替案であり、負荷分散とクラスタリングに異なるトレードオフがあります。トポロジに応じて 3 つのうちのいずれかを選択するには、詳細な比較「 PgBouncer vs Supervisor vs PgCat」を参照してください。

実稼働環境でトランザクション モードがアクティブ化されると、最も頻繁に生じる質問です。