この利点には特定のコストがかかります。トランザクション モードは、あるリクエストから次のリクエストまで安定した Postgres 接続を前提とするすべてのものをサイレントに中断します。セッション SET、LISTEN/NOTIFY、勧告ロック、トランザクション後に存続するカーソル、名前付きプリペアド ステートメント。この記事では、メカニズムの詳細を説明し、これらの制限とその正確な症状をリストし、本番環境のバックエンド (リポジトリで直接検証されている) が制限に囚われずにどのように構成されているかを示します。ここで引用したパフォーマンス数値の背後にある測定方法については、ベンチマーク方法論を参照してください。
必需品
- トランザクション モード: サーバー接続は、クライアントが切断されたときではなく、各トランザクションの終了時に解放されます。これは、短い REST API タイプの接続を共有する場合に最も効率的なモードです。
- 構造上、セッション SET/RESET、LISTEN/NOTIFY、セッション アドバイザリー ロック、WITH HOLD カーソル、あるリクエストから別のリクエストに再利用される一時テーブルと互換性がありません。
- 実際の最も一般的な落とし穴: いくつかのドライバー (sqlx、asyncpg、JDBC pgjdbc ドライバー) がデフォルトでアクティブ化する名前付きプリペアド ステートメントは、別のサーバー接続で再生され、負荷がかかると
prepared statement does not existのようなエラーを引き起こす可能性があります。 - バージョン 1.21 以降、PgBouncer はトランザクション モード (サーバー接続を介した LRU キャッシュ) でプロトコル準備済みステートメントに従うことができます。これは、アプリケーションがリクエストごとに
search_pathを変更する場合に、クライアント側のキャッシュを無効にすることを妨げるものではありません。 - Aurabase コードで検証: テナント プールは
pool_mode=transactionのstatement_cache_capacity(0)および PgBouncer で実行されますが、 PostgREST は LISTEN/NOTIFY を介したスキーマのリロードのために自発的に直接接続を維持します。
PgBouncer の 3 つのプーリング モード
PgBouncer には 3 つのモードがあり、Postgres サーバー接続がいつ共通プールに戻るかだけが異なります。公式ドキュメントでは、それらに session、 transaction 、 statement という名前が付けられています (pgbouncer.org/features.html、「プーリング モード」セクション、2026 年 8 月 24 日にアクセス)。
| ファッション | サーバー接続が緩んでいる | セッションの互換性 |
|---|---|---|
| セッション (デフォルト) | クライアントの切断時 | 合計: SET、LISTEN、カーソル、すべてがライブのように動作します |
| トランザクション | 各トランザクションの終了時 (COMMIT/ROLLBACK) | 部分的: トランザクションに対してローカルに残るもののみ |
| 声明 | それぞれの個別のリクエストの後 | 最小限: 明示的なマルチクエリトランザクションは禁止されています |
セッション モードは最も寛容ですが、スケーラビリティの点で最も効果的ではありません。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 機能が明示的にリストされています。
| 影響を受ける機能 | なぜ壊れるのか | 典型的な症状 |
|---|---|---|
| 設定 / セッションの設定 | この設定は、直後にリサイクルできる接続に適用されます。 | パラメータが 2 つのリクエスト間でランダムに忘れられるようです |
| 聞く/通知する | 通知を受信するには永続的な接続を想定します | クライアントにはまったく通知されないか、断続的にのみ通知される |
| セッション勧告ロック | ロックは論理クライアントではなくサーバー接続によって保持されます。 | 予想される完了前にロックが解放される、または解放されない |
| ホールドスライダー付き | 開いたトランザクションを超えて存続する必要がある | 次の反復で「カーソルが存在しません」エラーが発生する |
| 一時テーブル | トランザクションではなく、Postgres セッションに関連する | 次のクエリでテーブルが「消える」 |
| という名前の準備済みステートメント | 特定のサーバー接続で準備され、別のサーバー接続で再生されます | ロード時に「準備されたステートメント ... が存在しません」 |
これらの制限のほとんどは、通常単一の接続がすべてのトラフィックを処理するローカル開発では現れません。これらは、複数のクライアントが実際にプールを共有し、同じ論理クライアントからの 2 つのリクエスト間でサーバー接続が実際に切り替わる場合に、実際の負荷がかかっているように見えます。煙の検査ではほとんど検出されません。
プリペアドステートメント: 最も誤解されている制限
最新の Postgres ドライバーのほとんどは、アプリケーション コードが明示的に要求しなくても、デフォルトでプロトコル側で名前付き要求を準備します。まさにこれが、この罠の予測を困難にしている理由です。
プロトコル準備済みステートメントは、 Parseの時点で名前が付けられ、特定のサーバー接続にキャッシュされます。トランザクション モードでは、同じ論理クライアントからの 2 つのリクエストの間に、この接続を別のクライアントに再割り当てできます。その後、ドライバーが準備されていない接続で同じステートメント名を再実行すると、Postgres は明示的なエラー (SQLX クライアントの場合は通常 prepared statement "sqlx_s_N" does not exist) で応答します。この動作は断続的です。呼び出しごとに再現できる決定的なバグではなく、負荷の下で接続がどのように実行されるかによって決まります。
クライアント側の修正は言語に関係なく同じです。トランザクション モードでプーラーを通過するプールに対して、名前付きプリペアド ステートメントのキャッシュを無効にするか、名前のないクエリを強制します。 sqlx を使用した Rust では、接続オプションの 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 がトランザクション モードで PgBouncer を構成する方法
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 が実行されます (設定のリセット、サーバー側で準備されたステートメントの割り当て解除、アドバイザリー ロックの解放、カーソルと一時テーブルのパージ)。このフックがないと、前のリクエストによって発生したセッションの残留物が、同じリサイクルされた接続を再利用する別のテナントからの次のリクエストでリークする可能性があります。
例外は受け入れられました: 専用の PostgREST インスタンスは、プーラーを経由せずに、プライマリに直接接続されたままになります。 PostgREST スキーマのリロードは、永続的な接続を前提とする LISTEN/NOTIFYに依存します。これは、まさにトランザクション モードが中断する機能です (詳細は、 PostgREST の互換性に関する記事で既に文書化されています Aurabase)。 リクエストごとの RLS 設定は、明示的なトランザクション内で SET LOCAL に渡されます。これは、任意の COMMIT でサーバー接続を変更できるプールとの互換性を維持する唯一の方法です (マルチテナント RLS 分離に関する記事を参照してください)。
アプリケーションを中断せずにトランザクション モードを有効にする
短いチェックリスト。トランザクション モードで直接 Postgres 接続から PgBouncer に移行するバックエンドに適用できます。
- アプリケーション コードを監査します。 非トランザクション
SET、LISTEN/NOTIFY、セッション勧告ロック、WITH HOLDカーソル、およびクエリ間で再利用される一時テーブルを探します。 - 明示的なトランザクション内のセッション SET を LOCAL SET に置き換えます。これは、次の接続でリークするのではなく、COMMIT/ROLLBACK でクリーンアップされるため、接続のリサイクル後に適切に存続する唯一の設定です。
- プールがプーラーを通過し、スキーマまたはロールがリクエスト間で変更される場合は、ドライバー側のプリペアド ステートメント キャッシュ を無効にします。パフォーマンスのコストは実際のものですが測定可能であり、テナント間の漏洩のリスクよりもはるかに低くなります。
- セッション モード (移行、管理スクリプト、LISTEN/NOTIFY に依存するもの) を本当に必要とする接続を、他のすべてのトラフィックに対してトランザクション モードを放棄するのではなく、直接の非プーラー接続に分離します。
default_pool_sizeおよびmax_client_connのサイズは、別のプロジェクトからコピーされた任意の数値ではなく、 Postgres' 実際のmax_connectionsを基準にしています。- 単なるスモークテストではなく、実際の負荷の下でテストします。 準備されたステートメントのエラーとセッション設定のリークは、単一のローカル接続ではほとんど発生しません。
- 運用環境に入ったら、PgBouncer 管理コンソールから
SHOW POOLSおよびSHOW STATSを監視し、クライアント側でプールの飽和状態が表示される前にそれを特定します。
常にセッションではなくトランザクション モードを選択する必要がありますか?
いいえ、しかし、これは大部分の REST API にとって正しいデフォルトの選択です。セッション モードは、すぐにリファクタリングできないセッション機能に大きく依存するレガシー アプリケーションや、プールのゲインが移行作業を補えない低トラフィックの場合には、引き続き推奨されます。
このプーリング モデルの実装は PgBouncer だけではありません。Supavisor (Supabase) と PgCat は、負荷分散とクラスタリングのトレードオフが異なる 2 つの最近の代替案です。トポロジに応じて 3 つのうちのいずれかを選択するには、詳細な比較 ( PgBouncer vs Supavisor vs PgCat) を参照してください。
よくある質問
実稼働環境でトランザクション モードがアクティブ化されると、最も頻繁に生じる質問です。