PgBouncer 1.26.0 ドキュメント

• 1: 機能
• 2: 設定: pgbouncer.ini
• 3: PgBouncer コマンドの使用法
• 4: PgBouncer のコンパイルとインストール
• 5: ソースリリースのダウンロード
• 6: 変更履歴
• 7: コミュニティ
• 8: よくある質問

1 - 機能

• 接続をローテートする際の幾つかのレベルの厳しさ：

  セッションプーリング

  最も丁寧な方法です。クライアントが接続すると、そのクライアントが接続を維持している間は、サーバー接続が常に割り当てられます。クライアントが切断すると、そのサーバー接続はプールに戻されます。このモードは、すべての PostgreSQL 機能をサポートしています。

  トランザクションプーリング

  クライアントにサーバー接続が割り当てられるのは、トランザクション中に限られます。PgBouncer がトランザクションの終了を検知すると、サーバーはプールに戻されます。このモードでは、PostgreSQL のセッションベースの機能の一部が動作しなくなります。アプリケーションが、動作しない機能を使用しないよう協力する場合にのみ利用できます。互換性のない機能については、以下の表を参照してください。

  ステートメントプーリング

  最も攻撃的な方法です。これはトランザクションプーリングの一種ですが、複数文のトランザクションを許可しない点が特徴です。これはクライアント上で「autocommit」モードを強制することを目的としており、主に PL/Proxy を対象としています。

• メモリ要件が低く（デフォルトで接続あたり 2 kB）、これは PgBouncer が一度に完全なパケットを確認する必要がないためです。

• 単一のバックエンドサーバーに固定されません。接続先データベースは異なるホストに配置できます。

• ほとんどの設定をオンラインで再構成できます。

• so_reuseport を使った複数プロセスによるローリング再起動およびアップグレード をサポートしています。従来のオンライン再起動（-R）は 1.26.0 で削除されました。

プーリングモードのSQL機能マップ

次の表は、さまざまな PostgreSQL 機能と PgBouncer のプーリングモードとの互換性を示しています。なお、「トランザクション」プーリングは設計上、サーバーに対するクライアントの期待を破るものであり、アプリケーションが動作しない機能を使用しないよう協力する場合にのみ使用できます。

2 - 設定: pgbouncer.ini

説明

設定ファイルは “ini” 形式です。セクション名は [ と ] の間に記述します。; または # で始まる行はコメントとして扱われ、無視されます。行の途中に出現する ; および # は特殊文字として認識されません。

汎用設定

logfile

ログファイルを指定します。デーモン化する場合 (-d)、この設定または syslog のいずれかを設定する必要があります。

ログファイルは開いたまま保持されるため、ローテーション後は kill -HUP または管理コンソールで RELOAD; を実行してください。Windows ではサービスを停止してから再起動する必要があります。

logfile を設定しても、標準エラー出力へのログ出力は自動的に無効になりません。そのために、コマンドラインオプション -q または -d を使用してください。

デフォルト： 設定されていない

pidfile

PID ファイルを指定します。pidfile が設定されていない場合、デーモン化 (-d) は許可されません。

デフォルト： 設定されていない

listen_addr

TCP 接続を待受けるアドレスのリスト（カンマ区切り）を指定します。* を使用することで「すべてのアドレスで待受ける」ことを意味します。設定しない場合、Unix ソケット接続のみを受け入れます。

アドレスは数値（IPv4/IPv6）または名前で指定できます。

デフォルト： 設定されていない

listen_port

リッスンするポート。TCP および Unix ソケットの両方に適用されます。

デフォルト： 6432

unix_socket_dir

Unix ソケットの場所を指定します。この設定は、リスニングソケットおよびサーバー接続の両方に適用されます。空文字列に設定した場合、Unix ソケットは無効になります。@ で始まる値は、抽象名前空間内の Unix ソケットを作成することを示します（現在、Linux および Windows でサポートされています）。

デフォルト： /tmp（Windows では空）

unix_socket_mode

Unix ソケット用のファイルシステムモード。抽象名前空間内のソケットでは無視されます。Windows ではサポートされていません。

デフォルト： 0777

unix_socket_group

Unix ソケットで使用するグループ名。抽象名前空間内のソケットでは無視されます。Windows ではサポートされていません。

デフォルト： 設定されていない

user

設定されている場合、起動後に切り替える Unix ユーザーを指定します。PgBouncer が root として起動されている場合、またはすでに指定されたユーザーアカウントで実行されている場合にのみ有効です。Windows ではサポートされていません。

デフォルト： 設定されていない

pool_mode

サーバー接続を別のクライアントが再利用できるようになるタイミングを指定します。

• session: クライアントの切断後にサーバーがプールに戻されます。デフォルト。
• transaction: トランザクションの終了後にサーバーはプールに戻されます。
• statement: クエリの終了後にサーバーはプールに戻されます。このモードでは、複数のステートメントにまたがるトランザクションは許可されません。

max_client_conn

クライアント接続の最大数。

この設定値を増加すると、オペレーティングシステムのファイルディスクリプタ制限も増加する必要がある場合があります。ファイルディスクリプタの使用数は max_client_conn を超える可能性があることに注意してください。各ユーザーが独自のユーザー名でサーバーに接続する場合、理論上の最大使用数は次の通りです：

max_client_conn + (max pool_size * total databases * total users)

接続文字列でデータベースユーザーが指定されている場合（すべてのユーザーが同じユーザー名で接続する）、理論上の最大値は：

max_client_conn + (max pool_size * total databases)

理論上の最大値は、誰かが意図的に特殊な負荷を設計しない限り、達成されることはありません。それでも、ファイルディスクリプタの数を安全に高い値に設定すべきであることを意味します。

ulimit をお使いのシェルのマニュアルページで検索してください。注意： ulimit は Windows 環境では適用されません。

デフォルト： 100

default_pool_size

ユーザー/データベースペアあたりに許可するサーバー接続の最大数です。pool_size をデータベースおよびユーザーごとの設定で上書きできます。特定のデータベースまたはユーザーに対して pool_size が指定されていない場合、これが使用されるデフォルト値です。

デフォルト： 20

min_pool_size

この数値より少ない場合、プールにさらにサーバー接続を追加します。通常の負荷が完全な非活動期間の後に突然戻った際の動作を改善します。値はプールサイズで実質的に上限が設定されています。

プールに対して、以下のいずれかが真である場合にのみ適用されます：

• プールに対応する [databases] セクションのエントリで、user キー（強制ユーザー）に値が設定されている
• プールに少なくとも 1 つのクライアントが接続している

デフォルト： 0（無効）

reserve_pool_size

プールに許可する追加接続数（reserve_pool_timeout を参照）。0 で無効になります。

デフォルト： 0（無効）

reserve_pool_timeout

クライアントがこの時間内にサービスを受けなかった場合、予備プールからの追加接続を使用します。0 は無効化します。[秒]

デフォルト： 5.0

max_db_connections

データベースごとに許可するサーバー接続数の上限をこの数以下に制限します（ユーザーに関係なく）。この制限は、クライアントが接続した PgBouncer のデータベースを対象とし、出力接続先の PostgreSQL データベースを対象としません。

これは、[databases] セクションでデータベースごとに設定することもできます。

サーバー接続数の上限に達した場合、1 つのプールに対するクライアント接続を閉じても、別のプールに対するサーバー接続がすぐに確立されるわけではありません。これは、最初のプールのサーバー接続がまだ開いているためです。サーバー接続が閉じられると（アイドルタイムアウトにより）、待機中のプールに対してすぐに新しいサーバー接続が確立されます。

デフォルト： 0（無制限）

max_db_client_connections

1 つのデータベースあたり、PgBouncer へのクライアント接続をこの数を超えて許可しません（ユーザーに関係なく）。この制限は、クライアントが接続した PgBouncer のデータベースを対象とし、出力接続先の PostgreSQL データベースを対象としません。

これは max_db_connections 以上になるように設定する必要があります。両者の差は、アクティブな接続が終了するのを待機している状態で、特定のデータベースに対してキューに並ぶ接続数と捉えることができます。

これは、[databases] セクションでデータベースごとに設定することもできます。

デフォルト： 0（無制限）

max_user_connections

ユーザーごとのサーバー接続数をこの数を超えないように制限します（データベースにかかわらず）。この制限は、プールに関連付けられた PgBouncer ユーザーを対象とします。このユーザーは、サーバー接続に指定されたユーザー、またはその指定がない場合にはクライアントが接続したユーザーです。

これは、[users] セクションでユーザーごとに設定することもできます。

サーバー接続数の上限に達した場合、1 つのプールに対するクライアント接続を閉じても、別のプールに対するサーバー接続がすぐに確立されるわけではありません。これは、最初のプールのサーバー接続がまだ開いているためです。サーバー接続が閉じられると（アイドルタイムアウトにより）、待機中のプールに対してすぐに新しいサーバー接続が確立されます。

デフォルト： 0（無制限）

max_user_client_connections

クライアントの接続数を、ユーザーごとにこの数を超えないように制限します（データベースにかかわらず）。この値は、max_user_connections よりも大きい数に設定する必要があります。max_user_connections と max_user_client_connections の差は、ユーザーごとの接続キューの最大サイズとして捉えることができます。

これは、[users] セクションでユーザーごとに設定することもできます。

デフォルト： 0（無制限）

server_round_robin

デフォルトでは、PgBouncer はサーバー接続を LIFO（後入れ先出し）方式で再利用するため、少数の接続が最も高い負荷を受けます。これは、1 つのサーバーがデータベースを提供する場合に最適なパフォーマンスを発揮します。しかし、データベースアドレスの背後にあるラウンドロビンシステム（TCP、DNS、ホストリスト）がある場合は、PgBouncer も同様に接続をラウンドロビン方式で使用するほうが、負荷を均等に分散できます。

デフォルト： 0

track_extra_parameters

デフォルトでは、PgBouncer は、Postgres がクライアントに報告し、かつクライアントが変更できるすべてのパラメータを追跡します:

• application_name
• client_encoding
• DateStyle
• default_transaction_read_only
• IntervalStyle
• scram_iterations（PostgreSQL バージョン 16 以降）
• search_path（PostgreSQL バージョン 18 以降）
• session_authorization
• standard_conforming_strings
• TimeZone

他のパラメータを追跡対象にするには、ここに指定します。これにより、PgBouncer はそれらのパラメータをクライアント変数キャッシュに保持し、クライアントがアクティブになるたびにサーバーで復元する必要があることを認識します。

複数の値を指定する必要がある場合は、カンマ区切りのリストを使用してください（例: some_extension.setting, other_extension.setting）

注意： 多くのパラメータはこの方法では完全には追跡できません。PgBouncer が SET による変更を知ることができるのは、Postgres がクライアントに報告するパラメータのみです。Postgres には クライアントに報告するパラメータの公式リスト があります。ただし、Postgres 拡張機能はこのリストを変更できます。拡張機能は独自のパラメータを追加して報告することができ、また、Postgres が報告していない既存のパラメータを報告し始めることもできます。特に、Citus 12.0 以降では Postgres が search_path も報告するようになります。また、デフォルトで追跡されるパラメータの一部も、より新しい Postgres バージョンでのみ報告されます。default_transaction_read_only は Postgres 14 以降、scram_iterations は Postgres 16 以降、search_path は Postgres 18 以降です。

Postgres が報告しない追跡対象パラメータ（例: Postgres 18 より前のバージョンでの search_path）について、PgBouncer が知っているのは、クライアントがスタートアップパケット（またはスタートアップパラメータ options）内で指定した値のみです。この値は、クライアントがアクティブになるたびにサーバー接続に適用され、それを指定しなかったクライアントに対してはパラメータがデフォルト値にリセットされます。接続後に SET で行われた変更は、このようなパラメータについては追跡されないため、server_reset_query_always を使用しない限り、その変更はサーバー接続を共有する他のクライアントに漏出します。

Postgres プロトコルでは、パラメータ設定を、スタートアップパケット内のパラメータとして直接指定するか、options スタートアップパケット 内に含める形式で指定できます。両方の方法で指定されたパラメータは track_extra_parameters でサポートされています。ただし、options 自体を track_extra_parameters に含めることはできません。options に含まれるパラメータのみを含めることができます。

デフォルト： 空

ignore_startup_parameters

デフォルトでは、PgBouncer は起動パケット内で、追跡を維持できるパラメータのみを許可します（リストについては track_extra_parameters を参照）。それ以外のパラメータはすべてエラーを発生させます。他のパラメータを許可するには、ここに指定します。これにより、PgBouncer はそれらのパラメータが管理者によって管理されていることを認識し、無視できるようになります。

複数の値を指定する必要がある場合は、カンマ区切りのリストを使用してください（例: options,extra_float_digits）

Postgres プロトコルでは、パラメータ設定を、起動パケット内のパラメータとして直接指定するか、options 起動パケット 内に含める方法で指定できます。これらの両方の方法で指定されたパラメータは、ignore_startup_parameters でサポートされています。さらに、options 自体を ignore_startup_parameters に含めることも可能です。この場合、options 内に含まれる未知のパラメータはすべて無視されます。

デフォルト： 空

peer_id

このペアリンググループ内の PgBouncer プロセスを識別するために使用されるピア ID です。peer_id の値は、ペアリングされた PgBouncer プロセスグループ内で一意である必要があります。0 に設定すると PgBouncer ペアリングが無効になります。詳細については [peers] セクションのドキュメントを参照してください。peer_id に使用可能な最大値は 16383 です。

デフォルト： 0

disable_pqexec

Simple Query プロトコル（PQexec）を無効化します。Extended Query プロトコルとは異なり、Simple Query では1つのパケットに複数のクエリを含められるため、一部のSQLインジェクション攻撃の対象となり得ます。無効化することでセキュリティを向上させられます。当然、この設定により、専ら Extended Query プロトコルのみを使用するクライアントだけが動作し続けることになります。

デフォルト： 0

application_name_add_host

接続開始時に設定されたアプリケーション名設定に、クライアントのホストアドレスとポートを追加します。これにより、不正なクエリなどの発信元を特定しやすくなります。このロジックは接続開始時のみ適用されます。application_name が後で SET で変更された場合、PgBouncer は再度変更しません。

デフォルト： 0

conffile

現在の設定ファイルの場所を表示します。変更すると、次回の RELOAD / SIGHUP で別の設定ファイルが使用されます。

デフォルト： コマンドラインからのファイル

service_name

win32 サービス登録で使用されます。

デフォルト： pgbouncer

job_name

service_name への別名。

stats_period

SHOW コマンドで表示される平均値の更新頻度および集計統計のログ出力頻度を設定します（log_stats を参照）。[秒]

デフォルト： 60

max_prepared_statements

この値を 0 以外に設定すると、PgBouncer はトランザクションおよびステートメントプーリングモードでクライアントから送信された、プロトコルレベルの名前付きプリペアドステートメントに関するコマンドを追跡します。PgBouncer は、クライアントが準備したステートメントがバックエンドサーバー接続上で利用可能であることを保証します。ステートメントが元々別のサーバー接続で準備されていた場合でも同様です。

PgBouncer は、クライアントがプリペアドステートメントとして送信するすべてのクエリを内部で調べ、各ユニークなクエリ文字列に PGBOUNCER_{unique_id} の形式の内部名を割り当てます。同じクエリ文字列が複数回プリペアド（異なるクライアントによっても）された場合、それらは同じ内部名を共有します。PgBouncer は、実際の PostgreSQL サーバー上でステートメントをプリペアドする際に内部名のみを使用します（クライアントが提供した名前は使用しません）。PgBouncer は、各プリペアドステートメントにクライアントが割り当てた名前を追跡します。その後、プリペアドステートメントを使用する各コマンドについて、クライアント側の名前を内部名に置き換えることでリライトし（例：my_prepared_statement を PGBOUNCER_123 に置き換える）、そのコマンドをサーバーに転送します。さらに重要なのは、クライアントが実行したいプリペアドステートメントがサーバー上でまだプリペアドされていない場合（例：クライアントに割り当てられたサーバーが、クライアントがステートメントをプリペアドしたときと異なるため）、PgBouncer は透明にそのステートメントを事前にプリペアドしてから実行します。

注意： プリペアドステートメントに関するコマンドの追跡および書き換えは、SQL レベルのプリペアドステートメントに関するコマンドには適用されないため、PREPARE、EXECUTE、DEALLOCATE は Postgres にそのまま転送されます。このルールの例外は DEALLOCATE ALL および DISCARD ALL コマンドであり、これらは期待通りに動作し、このコマンドを送信したクライアントに対して PgBouncer が追跡していたプリペアドステートメントをクリアします。

この設定の実際の値は、1 つのサーバー接続上で LRU キャッシュに保持されるプリペアドステートメントの数を制御します。この設定を 0 に設定すると、トランザクションおよびステートメントプーリングのプリペアドステートメントサポートが無効になります。最高のパフォーマンスを得るには、アプリケーションで頻繁に使用されるプリペアドステートメントの数よりもこの設定値を大きくするようにしてください。この値が高くなるほど、PostgreSQL サーバー上の各 PgBouncer 接続のメモリ使用量が大きくなることに注意してください。これは、その接続上でより多くのクエリを準備したまま保持するためです。また、PgBouncer 自身のメモリ使用量も増加します。これは、クエリ文字列を追跡する必要が生じるためです。

ただし、PgBouncer のメモリ使用量への影響はそれほど大きくありません:

• 各一意のクエリはグローバルクエリキャッシュに一度だけ格納されます。
• 各クライアント接続はパケットを再書き込みするためにバッファを保持します。このバッファのサイズは、pkt_buf の最大 4 倍です。ただし、この上限に達することは通常ありません。これは、プリペアドステートメント内のクエリが pkt_buf の 2 から 4 倍のサイズである場合にのみ発生します。

したがって、次の例を想定してください：

• クライアントが1000件のアクティブな接続を保持している
• クライアントが200件の固有のクエリを準備している
• クエリの平均サイズは5kBである
• pkt_buf パラメータがデフォルトの4096（4kB）に設定されている

その後、PgBouncer はこれらのプリペアドステートメントを処理するために、最大で次の量のメモリが必要です：

200 x 5kB + 1000 x 4 x 4kB = ~17MB of memory.

プリペアドステートメントの追跡はメモリコストだけでなく、クエリの検査および再書き換えに必要なCPU使用量の増加ももたらします。複数の PgBouncer インスタンスが同じポートをリッスンすることで、複数のコアを活用して処理を行うことができます。詳細については so_reuseport オプションのドキュメント を参照してください。

ただし、プリペアドステートメントにはパフォーマンス上の利点も存在します。PostgreSQL に直接接続する場合と同様に、何度も実行されるクエリをプリペアドすることで、解析や計画の総量を削減できます。PgBouncer がプリペアドステートメントを追跡する方法は、複数のクライアントが同じクエリをプリペアドする場合に特にパフォーマンス向上に寄与します。クライアント接続がサーバー接続上でプリペアドステートメントを自動的に再利用するため、他のクライアントがプリペアドしたステートメントであっても利用可能です。たとえば、pool_size が 20 で、100 のクライアントがすべて同一のクエリをプリペアドする場合、PostgreSQL サーバー上でクエリのプリペアド（および解析）はたった 20 回で済みます。

プリペアドステートメントの再利用には一つの欠点があります。プリペアドステートメントの戻り値や引数の型が実行間で変化すると、現在の PostgreSQL は次のようなエラーを発生させます：

ERROR:  cached plan must not change result type

複数のクライアントが、同じクエリ文字列をプリペアドステートメントで使用し、異なる引数や結果の型を期待していると、このようなエラーを回避できません。この問題に遭遇する最も一般的なケースは、DDLマイグレーション中に既存のテーブルに新しい列を追加する、または列の型を変更するときです。そのような場合、マイグレーション後に RECONNECT をPgBouncer管理コンソールで実行してクエリの再準備を強制することで、エラーを解消できます。

デフォルト： 200

scram_iterations

SCRAM-SHA-256 を使用してパスワードをハッシュ化する際の計算反復回数です。反復回数を増やすと、保存されたパスワードに対するブルートフォース攻撃への耐性が高まりますが、認証は遅くなります。

デフォルト： 4096

認証設定

PgBouncer は自身のクライアント認証を処理し、独自のユーザーデータベースを持っています。これらの設定はこれを制御します。

auth_type

ユーザーの認証方法

• cert: クライアントは有効なクライアント証明書を用いた TLS 接続で接続しなければなりません。ユーザー名は証明書の CommonName フィールドから取得されます。
• md5: 認証に MD5 を使用します。これはデフォルトの認証方法です。auth_file には MD5 でハッシュ化されたパスワードと平文のパスワードの両方を含めることができます。md5 が設定されており、ユーザーに SCRAM シークレットがある場合、自動的に SCRAM 認証が使用されます。
• scram-sha-256: SCRAM-SHA-256 を使用してパスワードを検証します。auth_file には SCRAM シークレットまたは平文のパスワードを含める必要があります。
• plain: 平文のパスワードがネットワーク上を送信されます。非推奨です。
• trust: 認証は行われません。ユーザー名は auth_file に存在している必要があります。
• any: trust メソッドと同様ですが、指定されたユーザー名は無視されます。すべてのデータベースが特定のユーザーとしてログインするように設定されている必要があります。さらに、管理コンソールデータベースでは、任意のユーザーが statistics ユーザーとしてログインでき、admin_users にリストされたユーザーには管理者権限が付与されます。
• hba: 実際の認証タイプは auth_hba_file から読み込まれます。これにより、異なるアクセス経路に対して異なる認証方法を設定でき、たとえば Unix ソケット経由の接続では peer 認証方法を使用し、TCP 経由の接続では TLS を必須とします。
• ldap: ユーザーは、PostgreSQL と同様に LDAP サーバーに対して認証されます（詳細は https://www.postgresql.org/docs/current/auth-ldap.html を参照）。LDAP 接続オプションは設定 auth_ldap_options で構成するか、あるいは auth_hba_file で構成できます。
• pam: PAM を使ってユーザーを認証します。auth_file は無視されます。この方法は auth_user オプションを使用するデータベースと互換性がありません。PAM に報告されるサービス名は “pgbouncer” です。pam は HBA 設定ファイルでサポートされていません。

auth_hba_file

auth_type が hba の場合に使用する HBA 設定ファイル。詳細については、以下の HBA ファイル形式 を参照してください。

デフォルト： 設定されていない

auth_ident_file

auth_type が hba であり、ユーザーマップが定義される場合に使用する ID マップファイル。詳細については、以下の ID マップファイル形式 を参照してください。

デフォルト： 設定されていない

auth_file

ユーザー名とパスワードを読み込むファイルの名前。詳細については、以下の 認証ファイル形式 を参照してください。

ほとんどの認証タイプ（上記参照）では、auth_file または auth_user のいずれかを設定する必要があります。それ以外の場合、ユーザーが定義されません。

デフォルト： 設定されていない

auth_user

auth_user が設定されている場合、auth_file に指定されていないユーザーについては、pg_authid のデータベースで auth_query クエリを auth_user を使って実行し、その結果を取得します。auth_user のパスワードは auth_file から取得します。(auth_user がパスワードを必要としない場合は、auth_file に定義する必要はありません。)

pg_authid への直接アクセスには管理者権限が必要です。代わりに、SECURITY DEFINER 関数を呼び出すスーパーユーザー以外のユーザーを使用することを推奨します。

デフォルト： 設定されていない

auth_query

データベースからユーザーのパスワードを読み込むクエリ。

pg_authid への直接アクセスには管理者権限が必要です。代わりに、SECURITY DEFINER 関数を呼び出すスーパーユーザー以外のユーザーを使用することを推奨します。

クエリはターゲットデータベース内で実行されるため、関数が使用される場合は各データベースにインストールする必要があります。

クエリは、ユーザー名とパスワード（適切に暗号化/ハッシュされたもの）の 2 列を返す必要があります。ユーザーが存在しないことを報告するには、行を返さないか、ユーザーが NULL 値である 1 行を返します。（下記のデフォルトクエリは、存在しないユーザーに対して行を返しません。NULL 値を使用する方式は、以下の 例 に示すように、クエリがレコードを返す関数を呼び出す場合に有用です。）パスワード列の NULL 値は、ユーザーは存在するが利用可能なパスワードが存在しないことを意味し、クライアントが提示するいかなるパスワードも受け入れられません。

デフォルト： SELECT rolname, CASE WHEN rolvaliduntil < now() THEN NULL ELSE rolpassword END FROM pg_authid WHERE rolname=$1 AND rolcanlogin

auth_dbname

[databases] セクション内のデータベース名を、認証目的で使用します。このオプションはグローバルに設定可能であり、接続文字列で上書きすることもできます。

auth_ldap_options

LDAP 接続オプションは、auth_type が ldap の場合に使用します。auth_hba_file で認証が設定されている場合は使用しません。例：

auth_ldap_options = ldapurl="ldap://127.0.0.1:12345/dc=example,dc=net?uid?sub"

ログ設定

syslog

syslog の有効/無効を切り替えます。Windows では、イベントログが代わりに使用されます。

デフォルト： 0

syslog_ident

syslog にログを送信する際の名前。

デフォルト： pgbouncer (プログラム名)

syslog_facility

ログをsyslogに送信する施設を指定します。可能な値: auth, authpriv, daemon, user, local0-7。

デフォルト： daemon

log_connections

ログインが成功したことを記録します。

デフォルト： 1

log_disconnections

切断を理由とともにログに記録します。

デフォルト： 1

log_pooler_errors

クライアントに送信するプーラーのエラーメッセージをログ出力します。

デフォルト： 1

log_stats

集計統計をログに書き込み、stats_period ごとに実行します。外部監視ツールが SHOW コマンドから同じデータを取得する場合、無効にできます。

デフォルト： 1

verbose

詳細出力を増加します。コマンドラインの -v オプションと同等です。たとえば、コマンドラインで -v -v を使用することは、verbose=2 と同等です。3 が現在サポートされている最高の詳細レベルです。

デフォルト： 0

管理コンソールのアクセス制御

admin_users

コンソールへの接続とすべてのコマンドの実行を許可されるデータベースユーザーのカンマ区切りリスト。auth_type=any の場合でも、このリストが管理者権限を取得するユーザーを決定します。その他のユーザーは statistics ユーザーとしてログインできます。1.26.0 のコンソールアクセスチェック を参照してください。

デフォルト： 空

stats_users

管理コンソール上で読み取り専用クエリを実行できる接続が許可されるデータベースユーザーのカンマ区切りリスト。これはすべての SHOW コマンドを意味します。

デフォルト： 空

接続の健全性チェック、タイムアウト

server_reset_query

クライアント接続を解放した後、他のクライアントに利用可能になる前にサーバーに送信されるクエリ。その時点でトランザクションは進行中ではないため、値には ABORT または ROLLBACK を含めないでください。

このクエリは、データベースセッションに加えられた変更をクリーンアップすることを想定しており、これにより次のクライアントは明確に定義された状態の接続を取得できます。デフォルトは DISCARD ALL で、すべてをクリーンアップしますが、これにより次のクライアントは事前キャッシュされた状態を保持できなくなります。アプリケーションが一部の状態を保持しても問題ない場合は、DEALLOCATE ALL のように軽量化し、プリペアドステートメントのみを破棄するようにできます。

トランザクションプーリングを使用する場合、server_reset_query は使用されません。これは、そのモードではクライアントがセッションベースの機能を使用してはならないためです。各トランザクションは異なる接続に終了するため、セッション状態も異なります。

デフォルト： DISCARD ALL

server_reset_query_always

server_reset_query をすべてのプーリングモードで実行すべきかどうか。この設定がオフ（デフォルト）の場合、server_reset_query はセッションプーリングモードのプールでのみ実行されます。トランザクションプーリングモードの接続にはリセットクエリの実行が必要ありません。

この設定は、セッション機能を使用するアプリケーションをトランザクションプール方式の PgBouncer を介して動作させる際の不具合な設定を回避するためのものです。これにより、非決定的な障害を決定的な障害に変更します。クライアントは各トランザクションの後に常に状態を失います。

デフォルト： 0

server_check_delay

解放された接続を、server_check_query を実行せずに即時再利用可能として保持する期間。0 の場合、チェックは常に実行されます。

デフォルト： 30.0

server_check_query

接続の健全性を確認するための単純な無操作クエリ。

空文字列の場合、健全性チェックは無効になります。

<empty> の場合、健全性チェックとして空のクエリを送信します。

デフォルト： <empty>

server_fast_close

セッションプーリングモードでは、“close_needed” モード（RECONNECT、RELOAD で設定される接続設定の変更、または DNS の変更によって設定される）の場合、現在のトランザクションの終了後、または即時でサーバーを切断します。トランザクションプーリングまたはステートメントプーリングモードでは、この設定は効果がありません。これは、そのモードでは既にデフォルトの動作だからです。

この設定により、クライアントセッションの終了前にサーバー接続が閉じられた場合、クライアント接続も閉じられます。これにより、クライアントがセッションの中断を認識できるようになります。

この設定により、セッションプーリングと長時間実行されるセッションを使用する場合、接続設定の変更がより早く反映されます。ただし、クライアントセッションが設定変更によって中断される可能性があるため、クライアントアプリケーションには再接続およびセッション状態の再確立を行うためのロジックが必要です。ただし、実行中のトランザクションは中断されないため、トランザクションの損失は発生しません。

デフォルト： 0

server_lifetime

プーラーは、この期間以上に接続が維持されているが、現在クライアント接続と紐付いていない（使用されていない）サーバー接続を閉じます。0 に設定すると、接続は一度だけ使用された後、閉じられます。[秒]

これは、[databases] セクションでデータベースごとに設定することもできます。

デフォルト： 3600.0

server_idle_timeout

サーバー接続がこの秒数以上アイドル状態になると閉じられます。0 の場合はこのタイムアウトは無効になります。[秒]

デフォルト： 600.0

server_connect_timeout

接続およびログインがこの時間内に完了しない場合、接続は閉じられます。[秒]

デフォルト： 15.0

server_login_retry

サーバーへのログインに失敗した場合、接続不能または認証失敗の原因で、プーラーは再接続を試行する前にこの期間待機します。待機期間中、接続に失敗したサーバーに新たに接続を試みるクライアントは、別の接続試行をせずに即座にエラーを受け取ります。[秒]

この動作の目的は、サーバーが正常に動作していない場合に、クライアントがサーバー接続の利用可能を待って無駄にキューイングされるのを防ぐことです。ただし、サーバーが一時的に障害した場合（たとえば再起動中や設定ミスの際）、プーラーが再び接続を試みるまで最低でもこの期間が必要になることを意味します。予定されたイベント（たとえば再起動）は、この状態を避けるために通常、PAUSE コマンドを使って管理すべきです。

デフォルト： 15.0

client_login_timeout

クライアントが接続したが、この時間内にログインできなかった場合、接続は切断されます。[秒]

デフォルト： 60.0

autodb_idle_timeout

自動で作成された（* を通じて）データベースプールがこの秒数以上使用されていない場合、そのプールは解放されます。その負の側面は、統計情報も失われることです。[秒]

デフォルト： 3600.0

pool_idle_timeout

プール（特定のデータベース/ユーザーのペア）がこの秒数の間、クライアント接続もサーバー接続も持たない場合、そのプールは解放されます。これは autodb_idle_timeout と似ていますが、自動作成されたデータベース全体ではなく、個々のプールを解放します。server_idle_timeout（アイドル状態のサーバー接続を閉じますがプール自体は保持します）とは異なり、この設定はプール全体を、しかも完全に空になったときにのみ解放することに注意してください。

autodb_idle_timeout と同様、解放されたプールの統計情報が失われるという負の側面があります。SHOW STATS のデータベースごとの合計値は現在存在するプールの総和であるため、プールを解放するとこれらの合計値が減少し、監視システムがカウンターのリセットと誤読する可能性があります。このため、デフォルトでは無効になっています。0 で無効になります。[秒]

デフォルト： 0（無効）

dns_max_ttl

DNS ルックアップのキャッシュ期間。実際の DNS TTL は無視されます。[秒]

デフォルト： 15.0

dns_nxdomain_ttl

DNS エラーおよび NXDOMAIN の DNS ルックアップをキャッシュする期間。[秒]

デフォルト： 15.0

dns_zone_check_period

ゾーンシリアルが変更されたかを確認する周期。

PgBouncer はホスト名から DNS ゾーンを取得し（最初のドット以降の部分）、定期的にゾーンのシリアルが変更されているかを確認します。変更が検出された場合、そのゾーン下にあるすべてのホスト名を再び照会します。ホスト IP が変更された場合、その接続は無効化されます。

c-ares バックエンドでのみ動作します (configure オプション --with-cares で)。

デフォルト： 0.0（無効）

resolv_conf

カスタム resolv.conf ファイルの場所。これにより、グローバルなオペレーティングシステムの設定とは独立して、カスタムの DNS サーバーおよび他の名前解決オプションを指定できます。

evdns (>= 2.0.3) または c-ares (>= 1.15.0) のバックエンドが必要です。

設定ファイルの解析は PgBouncer ではなく DNS バックエンドライブラリによって行われるため、許可される構文やディレクティブの詳細についてはライブラリのドキュメントを参照してください。

デフォルト： 空（オペレーティングシステムのデフォルトを使用）

query_wait_notify

クライアントが PgBouncer によってキューに入れられた後に通知メッセージが送信されるまでの時間。[秒]

0 の値は、この通知メッセージを無効化します。

デフォルト： 5

login_notify_message

ログインの成功後にクライアントに送信されるウェルカム通知メッセージ。クライアントが postgres に直接接続するのではなく pgbouncer に接続していることを理解できるようにするために使用できます。

デフォルト： 空（ウェルカムメッセージは送信されない）

TLS 設定

設定ファイルで指定した証明書または鍵ファイルの内容が変更された場合、設定ファイル内のファイル名自体は変更されていない限り、RELOAD後に新規接続では新しいファイル内容が使用されます。既存の接続は閉じられません。セキュリティ上の理由で新規ファイルを即座にすべての接続で使用したい場合は、RELOADの後にRECONNECTを実行することを推奨します。

TLS 設定を変更すると、セキュリティ上の理由から自動的に RECONNECT が発生します。

client_tls_sslmode

クライアントからの接続に使用する TLS モード。TLS 接続はデフォルトで無効です。有効にした場合、PgBouncer がクライアント接続を受け入れるために使用する鍵と証明書を設定するために、client_tls_key_file および client_tls_cert_file も設定する必要があります。PgBouncer で使用可能な一般的な証明書ファイル形式は PEM です。

• disable: プレーンTCP。クライアントがTLSを要求しても無視されます。デフォルト。
• allow: クライアントが TLS を要求する場合、それを使用します。そうでない場合、平文の TCP を使用します。クライアントがクライアント証明書を提示した場合、検証は行われません。
• prefer: allow と同じ。
• require: クライアントは TLS を使用しなければなりません。使用しない場合、クライアント接続は拒否されます。クライアントがクライアント証明書を提示した場合、検証は行われません。
• verify-ca: クライアントは有効なクライアント証明書を使用した TLS を使用する必要があります。
• verify-full: verify-ca と同様。

client_tls_key_file

クライアント接続を受け入れるための PgBouncer の秘密鍵。

デフォルト： 設定されていない

client_tls_cert_file

秘密鍵用の証明書。クライアントはこれを検証できます。

デフォルト： 設定されていない

client_tls_ca_file

クライアント証明書を検証するためのルート証明書ファイル。

デフォルト： 設定されていない

client_tls_protocols

許可される TLS プロトコルバージョン。許可される値: tlsv1.0, tlsv1.1, tlsv1.2, tlsv1.3。ショートカット: all (tlsv1.0,tlsv1.1,tlsv1.2,tlsv1.3), secure (tlsv1.2,tlsv1.3)。

デフォルト： secure

client_tls_ciphers

許可される TLS 暗号スイート（OpenSSL 構文）。ショートカット：

• default/secure/fast/normal （すべてシステム全体の OpenSSL デフォルトを使用）
• all（すべての暗号スイートを有効にします。推奨されません）

TLS バージョン 1.2 以下の接続にのみ影響があります。バージョン 1.3 の場合は、以下の client_tls13_ciphers を参照してください。

デフォルト： default

client_tls13_ciphers

許可される TLS v1.3 の暗号スイート。空の場合は client_tls_ciphers の値を使用します。許可される値は：

• TLS_AES_256_GCM_SHA384
• TLS_CHACHA20_POLY1305_SHA256
• TLS_AES_128_GCM_SHA256
• TLS_AES_128_CCM_8_SHA256
• TLS_AES_128_CCM_SHA256

TLS バージョン 1.3 以上の接続にのみ影響します。バージョン 1.2 以下の場合は client_tls_ciphers を参照してください。

デフォルト： <empty>

client_tls_ecdhcurve

ECDH キー交換に使用する楕円曲線名。

許容される値: none (DH は無効化), auto (256 ビット ECDH), 曲線名

デフォルト： auto

client_tls_dheparams

DHE キー交換タイプ。

許容される値: none (DH は無効化), auto (2048 ビット DH), legacy (1024 ビット DH)

デフォルト： auto

server_tls_sslmode

PostgreSQL サーバーへの接続に使用する TLS モード。デフォルトのモードは prefer です。

• disable: プレーンTCP。サーバーへの TLS 要求すら行われません。
• allow: prefer と同じ動作です。最初に TLS を要求し、サーバーが TLS を拒否した場合はプレーン TCP にフォールバックします。サーバー証明書は検証されません。
• prefer: TLS 接続は常に PostgreSQL に対して最初に要求されます。拒否された場合、接続はプレーン TCP で確立されます。サーバー証明書は検証されません。デフォルト。
• require: 接続は TLS を経由しなければなりません。サーバーが拒否した場合、プレーン TCP は試行されません。サーバー証明書は検証されません。
• verify-ca: 接続は TLS を経由しなければならず、サーバー証明書は server_tls_ca_file に従って有効でなければなりません。サーバーのホスト名は証明書と照合されません。
• verify-full: 接続は TLS を経由しなければならず、サーバー証明書は server_tls_ca_file に従って有効でなければなりません。サーバーのホスト名は証明書の情報と一致しなければなりません。

server_tls_ca_file

PostgreSQL サーバー証明書を検証するためのルート証明書ファイル。

デフォルト： 設定されていない

server_tls_key_file

PgBouncer が PostgreSQL サーバーに対して認証するための秘密鍵。

デフォルト： 設定されていない

server_tls_cert_file

秘密鍵用の証明書。PostgreSQL サーバーはこれを検証できます。

デフォルト： 設定されていない

server_tls_protocols

許可される TLS プロトコルバージョン。許可される値: tlsv1.0, tlsv1.1, tlsv1.2, tlsv1.3。ショートカット: all (tlsv1.0,tlsv1.1,tlsv1.2,tlsv1.3), secure (tlsv1.2,tlsv1.3), legacy (all)。

デフォルト： secure

server_tls_ciphers

許可される TLS 暗号スイート（OpenSSL 構文）。ショートカット：

• default/secure/fast/normal （すべてシステム全体の OpenSSL デフォルトを使用）
• all（すべての暗号スイートを有効にします。推奨されません）

TLS バージョン 1.2 以下の接続にのみ影響があります。バージョン 1.3 の場合は、以下の server_tls13_ciphers を参照してください。

デフォルト： default

server_tls13_ciphers

許可される TLS v1.3 の暗号スイート。空の場合は server_tls_ciphers の値を使用します。許可される値は：

• TLS_AES_256_GCM_SHA384
• TLS_CHACHA20_POLY1305_SHA256
• TLS_AES_128_GCM_SHA256
• TLS_AES_128_CCM_8_SHA256
• TLS_AES_128_CCM_SHA256

TLS バージョン 1.3 以上の接続にのみ影響します。バージョン 1.2 以下の場合は server_tls_ciphers を参照してください。

デフォルト： <empty>

危険なタイムアウト

次のタイムアウトを設定すると、予期しないエラーが発生する可能性があります。

query_timeout

その時間より長く実行されるクエリはキャンセルされます。これはネットワーク問題にのみ対応するため、わずかに小さいサーバー側の statement_timeout と組み合わせて使用する必要があります。[秒]

デフォルト： 0.0（無効）

query_wait_timeout

クエリが実行待ちに費やすことが許される最大時間。この時間内にクエリがサーバーに割り当てられなかった場合、クライアントは切断されます。0 で無効になります。無効にした場合、クライアントは無期限にキューに残ります。[秒]

この設定は、応答しないサーバーが接続を占有するのを防ぐために使用されます。また、サーバーがダウンしている場合や、何らかの理由で接続を拒否している場合にも役立ちます。

この設定は、データベースごとおよびユーザーごとに構成することもできます。優先順位は、ユーザー、次にデータベース、次にグローバルです。選択されたレベルで明示的に 0 を指定すると、このタイムアウトは無効になります。1.26.0 のタイムアウト選択コード を参照してください。

デフォルト： 120.0

cancel_wait_timeout

キャンセル要求が実行待ちに費やすことが許される最大時間。この時間内にキャンセル要求がサーバーに割り当てられなかった場合、クライアントは切断されます。0 で無効になります。無効にした場合、キャンセル要求は無期限にキューに保持されます。[秒]

この設定は、サーバーがダウンしているためにキャンセルが転送できない場合に、クライアントがロックアップするのを防ぐために使用されます。

デフォルト： 10.0

client_idle_timeout

この秒数以上、クライアント接続がアイドル状態になっている場合は閉じられます。これはクライアント側の接続ライフタイム設定よりも大きくする必要があります。ネットワーク問題用にのみ使用してください。[秒]

デフォルト： 0.0（無効）

idle_transaction_timeout

クライアントが「トランザクション内アイドル」状態に長く滞在すると、切断されます。[秒]

デフォルト： 0.0（無効）

transaction_timeout

クライアントが「トランザクション中」状態に長く滞在している場合、接続が切断されます。[秒]

デフォルト： 0.0（無効）

低レベルのネットワーク設定

pkt_buf

パケット用の内部バッファサイズ。TCPパケットのサイズおよび一般的なメモリ使用量に影響します。実際の libpq パケットはこの値より大きくなることがあるため、大きな値に設定する必要はありません。

デフォルト： 4096

max_packet_size

PgBouncer が許可する PostgreSQL パケットの最大サイズ。1 パケットは1つのクエリまたは1つの結果セットの行を指します。完全な結果セットはこれよりも大きくなる可能性があります。

デフォルト： 2147483647

listen_backlog

listen(2) 用のバックログ引数。未回答の新しい接続試行をキューに保持する数を決定します。キューが満杯になると、さらに新しい接続試行は破棄されます。

デフォルト： 128

sbuf_loopcnt

接続ごとに処理する回数の上限。この制限がなければ、大きな結果セットを持つ接続が長時間 PgBouncer を停止させてしまう可能性があります。1 ループで処理されるデータ量は pkt_buf に等しくなります。0 は制限なしを意味します。

デフォルト： 5

so_reuseport

TCP リスニングソケットに対して SO_REUSEPORT ソケットオプションを設定するかどうかを指定します。一部のオペレーティングシステムでは、同じホスト上で同じポートをリッスンする複数の PgBouncer インスタンスを実行でき、カーネルが接続を自動的に分散します。このオプションにより、PgBouncer がより多くの CPU コアを活用できるようになります（PgBouncer はシングルスレッドであり、インスタンスごとに 1 つの CPU コアを使用します）。

詳細な動作はオペレーティングシステムのカーネルに依存します。執筆時点では、この設定は（十分に最新版の）Linux、DragonFlyBSD、FreeBSDで期待通りの効果を発揮します。（FreeBSDでは、ソケットオプション SO_REUSEPORT_LB を適用します。）他のいくつかのオペレーティングシステムではソケットオプションがサポートされているものの、期待する効果は得られません。複数のプロセスが同じポートにバインドできるようになりますが、接続はそのうちの1つのみが受信します。詳細については、お使いのオペレーティングシステムの setsockopt() ドキュメントを参照してください。

ソケットオプションをサポートしていないシステムでは、この設定を有効にするとエラーになります。

同じホスト上の各 PgBouncer インスタンスは、少なくとも unix_socket_dir および pidfile に対して異なる設定が必要であり、logfile を使用する場合はそれも同様です。また、このオプションを使用する場合、TCP/IP で特定の PgBouncer インスタンスに接続できなくなることに注意してください。これはモニタリングやメトリクス収集に影響を及ぼす可能性があります。

クエリのキャンセルが正常に動作し続けることを保証するため、異なる PgBouncer プロセス間で PgBouncer のピアリングを設定する必要があります。詳細については、peer_id 設定オプションおよび peers 設定セクションのドキュメントを参照してください。また、ピアリングと so_reuseport を使用する例については、これらのドキュメントの例セクションをご覧ください。

デフォルト： 0

tcp_defer_accept

TCP_DEFER_ACCEPT のソケットオプションを設定します。詳細については man 7 tcp を参照してください。（このオプションはブール値です。1 は有効を意味します。有効にした場合の実際の値は現在、ハードコードされており 45 秒です。）

これは現在、Linux でのみサポートされています。

デフォルト： Linux では 1、それ以外では 0

tcp_socket_buffer

デフォルト： 設定されていない

tcp_keepalive

OS のデフォルト値を使用した基本的な keepalive を有効にします。

Linux では、システムのデフォルト値は tcp_keepidle=7200、tcp_keepintvl=75、tcp_keepcnt=9 です。他のオペレーティングシステムでもおそらく同様です。

デフォルト： 1

tcp_keepcnt

デフォルト： 設定されていない

tcp_keepidle

デフォルト： 設定されていない

tcp_keepintvl

デフォルト： 設定されていない

tcp_user_timeout

TCP_USER_TIMEOUT ソケットオプションを設定します。これは、TCP 接続が強制的に閉じられる前に送信されたデータが確認されないままになる最大時間（ミリ秒単位）を指定します。0 に設定した場合、オペレーティングシステムのデフォルトが使用されます。

これは現在、Linux でのみサポートされています。

デフォルト： 0

セクション [databases]

[databases] セクションでは、PgBouncer のクライアントが接続できるデータベース名を定義し、その接続がどの場所にルーティングされるかを指定します。このセクションには、次のような key=value 形式の行が含まれます。

dbname = connection string

キーはデータベース名として、値は接続文字列として扱われます。接続文字列は、以下で説明する接続パラメータの key=value 形式のペアで構成され、libpq と似ていますが、実際の libpq は使用せず、利用可能な機能のセットも異なります。例:

foodb = host=host1.example.com port=5432
bardb = host=localhost dbname=bazdb

データベース名には、クォートなしで _0-9A-Za-z の文字を含めることができます。他の文字を含む名前は、標準の SQL 識別子のクォート記法、すなわち二重引用符で囲む必要があり、二重引用符 1 つを表すには "" を使用します。

データベース名 pgbouncer は管理コンソール用に予約されており、ここではキーとして使用できません。

* はフォールバックデータベースとして機能します。完全一致する名前が存在しない場合、その値が要求されたデータベースの接続文字列として使用されます。たとえば、次のエントリが存在する場合（他に上書きするエントリがないものとします）

* = host=foo

データベース bar を指定して PgBouncer に接続すると、実質的には次のエントリ

bar = host=foo dbname=bar

が存在するかのように動作します（dbname のデフォルトがクライアント側のデータベース名であることを利用しています。以下を参照）。

自動で作成されたデータベースエントリは、autodb_idle_timeout パラメータで指定された時間以上アイドル状態が続くとクリーンアップされます。

dbname

宛先データベース名。

デフォルト： クライアント側のデータベース名と同じ

host

接続先のホスト名または IP アドレス。ホスト名は接続時に解決され、その結果は dns_max_ttl パラメーターごとにキャッシュされます。ホスト名の解決結果が変更された場合、既存のサーバー接続は解放された時点で自動的に閉じられ（プーリングモードに従い）、新しいサーバー接続は即座に新しい解決結果を使用します。DNS が複数の結果を返す場合、それらはラウンドロビン方式で使用されます。

値が / で始まる場合、ファイルシステム名前空間内の Unix ソケットが使用されます。値が @ で始まる場合、抽象名前空間内の Unix ソケットが使用されます。

コンマ区切りのホスト名またはアドレスのリストを指定できます。この場合、接続はラウンドロビン方式で行われます。（ホストリストにDNSで複数のアドレスに解決されるホスト名が含まれる場合、ラウンドロビンの動作は独立して行われます。これは実装依存であり、変更される可能性があります。）リスト内のすべてのホストは常に利用可能でなければなりません。到達不能なホストをスキップする仕組みや、リストから利用可能なホストのみを選択する仕組みは存在しません。（これは libpq のホストリストとは異なります。）また、これは新規接続の宛先選択にのみ影響することに注意してください。既に確立されたサーバー接続へのクライアントの割り当て方法については、server_round_robin の設定を参照してください。

例:

host=localhost
host=127.0.0.1
host=2001:0db8:85a3:0000:0000:8a2e:0370:7334
host=/var/run/postgresql
host=192.168.0.1,192.168.0.2,192.168.0.3

デフォルト： 設定されていない。Unix ソケットを使用する。

port

デフォルト： 5432

user

user= が設定されている場合、宛先データベースへのすべての接続は指定されたユーザーで行われるため、このデータベースに対しては1つのプールのみが存在します。

それ以外の場合、PgBouncer はクライアントユーザー名を使って宛先データベースにログインするため、ユーザーごとに1つのプールが作成されます。

password

ここでパスワードが指定されない場合、上記で指定されたユーザーに対して auth_file から取得したパスワードが使用されます。動的なパスワード検出方法（例: auth_query）は現在サポートされていません。

auth_user

グローバルな auth_user 設定のオーバーライド（指定された場合）。

auth_query

グローバルな auth_query 設定のオーバーライド（指定された場合）。SQL 文全体をシングルクォートで囲む必要があります。

auth_dbname

グローバルな auth_dbname 設定のオーバーライド（指定された場合）。

pool_size

このデータベースのプールの最大サイズを設定します。設定されていない場合、default_pool_size が使用されます。

min_pool_size

このデータベースの最小プールサイズを設定します。設定されていない場合、グローバルな min_pool_size が使用されます。

少なくとも次のいずれかが真である場合にのみ適用されます：

• [databases] セクションのこのエントリで、user キー（強制ユーザー）に値が設定されている
• プールに少なくとも 1 つのクライアントが接続している

reserve_pool_size

このデータベース用に追加の接続を設定します。設定されていない場合、グローバルな reserve_pool_size が使用されます。互換性のため、reserve_pool はこのオプションの別名です。

connect_query

接続確立後に実行されるクエリ。クライアントが接続を使用できるようにする前に実行されます。クエリでエラーが発生した場合、ログに記録されますが、それ以外は無視されます。

pool_mode

このデータベースに固有のプールモードを設定します。設定されていない場合、デフォルトで pool_mode が使用されます。

query_wait_timeout

クエリが実行待ちに費やすことが許される最大時間。0 で無効になります。この設定を省略すると、適用されるデフォルト値を継承します。[秒]

詳細については、グローバルの query_wait_timeout 設定の説明を参照してください。

ユーザーレベルの query_wait_timeout は、このデータベース設定を上書きします。どちらも設定されていない場合、グローバルの query_wait_timeout が使用されます。

load_balance_hosts

host にコンマ区切りのリストが指定された場合、load_balance_hosts が新しい接続に使用するエントリを決定します。

注意：この設定は現在、接続文字列で複数のホストを指定した場合のロードバランシング動作のみを制御していますが、単一のホストのDNSレコードが複数のIPアドレスを参照している場合の制御は行われません。これは未実装の機能であり、今後のリリースでこの設定が両方のロードバランシング方法を制御するようになる可能性があります。

• round-robin: 新しい接続試行では、リスト内の次のホストエントリが選択されます。
• disable: 新しい接続は、接続が失敗するまで同じホストエントリを使用し続けます。接続が失敗すると、次のホストエントリが選択されます。

複数のホストが利用可能な場合に迅速な再試行を確保するため、server_login_retry をデフォルトより低く設定することを推奨します。

デフォルト： round-robin

max_db_connections

データベース全体のサーバー接続数の上限を設定します（つまり、データベース内のすべてのプールはこの数を超えるサーバー接続を持てません）。

max_db_client_connections

データベース全体のクライアント接続数の上限を設定します。max_client_conn と併用して、PgBouncer が許可する接続数を制限するために使用してください。

server_lifetime

各データベースごとに server_lifetime を設定します。設定されていない場合、データベースは server_lifetime に対してインスタンス全体で設定された値にフォールバックします。

client_encoding

サーバーに特定の client_encoding を要求します。

datestyle

サーバーに特定の datestyle を要求します。

timezone

サーバーに特定の timezone を要求します。

セクション [users]

このセクションには、次のように key=value 形式の行が含まれます。

user1 = settings

ユーザー名としてキーが使用され、値としてそのユーザーに固有の設定項目（key=value 形式）のリストが指定されます。例：

user1 = pool_mode=session

ここではわずかな設定項目しか利用できません。

auth_file が設定されている場合、このセクションでユーザーが定義されているが auth_file にリストされていない場合、auth_user が設定されていれば PgBouncer は auth_query を使ってそのユーザーのパスワードを検索しようとします。auth_user が設定されていない場合、PgBouncer はユーザーが存在するかのように振る舞い、クライアントに「no such user」（ユーザーが存在しません）というメッセージを返さない一方で、提供されたパスワードを受け入れることもありません。

pool_size

このユーザーからのすべての接続のプールの最大サイズを設定します。設定されていない場合、データベースまたは default_pool_size が使用されます。

reserve_pool_size

このユーザーに対してプールに許可する追加接続数を設定します。設定されていない場合、データベース設定またはグローバルな reserve_pool_size が使用されます。

pool_mode

このユーザーからのすべての接続に使用するプールモードを設定します。設定されていない場合、データベースまたはデフォルトの pool_mode が使用されます。

max_user_connections

ユーザーのサーバー接続数に上限を設定します（つまり、ユーザーに関連するすべてのプールの合計接続数がこの数を超えないようにします）。

query_timeout

ユーザークエリの実行可能時間の最大秒数を設定します。このタイムアウトを設定すると、上記で説明したサーバーレベルの query_timeout が上書きされます。

query_wait_timeout

クエリが実行待ちに費やすことが許される最大時間。0 で無効になります。この設定を省略すると、適用されるデフォルト値を継承します。[秒]

詳細については、グローバルの query_wait_timeout 設定の説明を参照してください。

この設定は、データベースおよびグローバルの query_wait_timeout の両方を上書きします。設定されていない場合、データベース設定が使用され、それも設定されていない場合はグローバル値にフォールバックします。

idle_transaction_timeout

ユーザーがアイドル状態のトランザクションを保持できる最大秒数を設定します。このタイムアウトを設定すると、上記で説明したサーバーレベルの idle_transaction_timeout が上書きされます。

transaction_timeout

ユーザーがトランザクションを開いたままにできる最大秒数を設定します。このタイムアウトを設定すると、上記で説明したサーバーレベルの transaction_timeout が上書きされます。

client_idle_timeout

クライアントが PgBouncer インスタンスにアイドル状態で接続できる最大時間を秒単位で設定します。このタイムアウトを設定すると、上記で説明したサーバーレベルの client_idle_timeout が上書きされます。

このタイムアウトは、潜在的に危険であることに注意してください。

max_user_client_connections

クライアント接続数のユーザーごとの上限を設定します。これは max_client_conn 設定のユーザー版 です。

セクション [peers]

セクション [peers] は、PgBouncer がキャンセル要求を転送できるピアおよびそのキャンセル要求のルーティング先を定義します。

PgBouncer プロセスは、すべての PgBouncer プロセスの設定ファイルに peer_id 値と [peers] セクションを定義することで、グループ内でピアリングできます。このようにピアリングされた PgBouncer プロセスは、キャンセル対象のクエリを受け取ったプロセスにキャンセル要求を転送できます。これは、複数の PgBouncer プロセス（異なるサーバー上に存在する可能性あり）が同じ TCP ロードバランサーの背後にある場合にキャンセルが正しく動作するようにするためです。キャンセル要求は、キャンセル対象のクエリと異なる TCP 接続を経由して送信されるため、TCP ロードバランサーがキャンセル要求の接続を意図したプロセスとは異なるプロセスに送信する可能性があります。ピアリングにより、キャンセル要求は最終的に正しいプロセスに到達します。詳細な説明は、この 会議発表の録画 で提供されています。

このセクションには、次のような key=value 形式の行が含まれます。

peer_id = connection string

接続パラメータのキーとして peer_id を使用し、値として接続文字列を指定します。接続文字列は、以下で説明する key=value 形式のパラメータペアで構成され、libpq と似ていますが、実際の libpq は使用せず、利用可能な機能のセットも異なります。例:

1 = host=host1.example.com
2 = host=/tmp/pgbouncer-2  port=5555

注意 1: ピアリングが機能するためには、グループ内の各 PgBouncer プロセスの peer_id はピアリンググループ内で一意でなければなりません。また、[peers] セクションには、そのグループ内のすべてのピア ID に対応するエントリを含めることが推奨されます。例については、このドキュメントの 例のセクションをご覧ください。[peers] セクションに、設定ファイルが対象とする PgBouncer の peer_id を含めるのは 許可されていますが、必須ではありません。このようなエントリは無視されますが、設定管理を容易にするために許可されています。これにより、複数の設定ファイルで同じ [peers] セクションを再利用できるようになります。

注意 2: すべてのピアが v1.21.0 バージョン境界の同一側にある限り、バージョン間のピアリングがサポートされています。v1.21.0 では、キャンセルトークンのエンコード方法に破壊的な変更が加えられ、以前のバージョンで作成されたものと互換性がなくなりました。

host

接続先のホスト名または IP アドレス。ホスト名は接続時に解決され、dns_max_ttl パラメータごとに結果がキャッシュされます。DNS が複数の結果を返す場合、ラウンドロビン方式で使用されます。ただし、一般的に複数の IP アドレスに解決されるホスト名を使用することは推奨されません。なぜなら、その場合、キャンセル要求が誤ったノードに転送される可能性があり、再度転送が必要になるためです（最大3回までしか許可されません）。

値が / で始まる場合、ファイルシステム名前空間内の Unix ソケットが使用されます。値が @ で始まる場合、抽象名前空間内の Unix ソケットが使用されます。

例:

host=localhost
host=127.0.0.1
host=2001:0db8:85a3:0000:0000:8a2e:0370:7334
host=/var/run/pgbouncer-1

port

デフォルト： 6432

pool_size

同時にピアに対して送信可能なキャンセル要求の最大数を設定します。キャンセル要求は、バックエンドの Postgres サーバーが遅延または停止している場合など、バーストで到着することがあります。したがって、pool_size が低すぎず、これらのバーストを処理できるようにすることが重要です。

設定されていない場合、default_pool_size が使用されます。

Include ディレクティブ

PgBouncer の設定ファイルには、別の設定ファイルを読み込んで処理するための include ディレクティブを含めることができます。これにより、設定ファイルを物理的に別々の部分に分割できます。include ディレクティブは次の形式です：

%include filename

ファイル名が絶対パスでない場合、現在の作業ディレクトリを基準とした相対パスとして扱われます。

認証ファイル形式

このセクションでは、auth_file 設定で指定されたファイルの形式について説明します。このファイルは次の形式のテキストファイルです。

"username1" "password" ...
"username2" "md5abcdef012342345" ...
"username2" "SCRAM-SHA-256$<iterations>:<salt>$<storedkey>:<serverkey>"

フィールドは2つ以上で、それぞれ二重引用符で囲む必要があります。最初のフィールドはユーザー名、2番目のフィールドはプレーンテキスト、MD5 ハッシュされたパスワード、または SCRAM シークレットのいずれかです。PgBouncer は行の残りの部分を無視します。フィールド値内の二重引用符は、二重の二重引用符でエスケープできます。

PostgreSQL MD5-ハッシュ化パスワード形式：

"md5" + md5(password + username)

したがって、パスワード 1234 を持つユーザー admin の MD5 ハッシュ化パスワードは md545f2603610af569b6155c45067268c6b になります。

PostgreSQL SCRAM シークレット形式:

SCRAM-SHA-256$<iterations>:<salt>$<storedkey>:<serverkey>

詳細については、PostgreSQL のドキュメントおよび RFC 5803 を参照してください。

認証ファイルに格納されたパスワードまたはシークレットは、2つの目的で使用されます。まず、パスワードベースの認証方法が設定されている場合、受信するクライアント接続のパスワードを検証するために使用されます。次に、バックエンドサーバーがパスワードベースの認証を必要とする場合、出力接続のパスワードとして使用されます（データベースの接続文字列でパスワードが直接指定されている場合は除く）。

制限事項

パスワードが平文で保存されている場合、バックエンドサーバーで使用される任意のパスワードベースの認証に使用できます。平文、MD5、または SCRAM（詳細については https://www.postgresql.org/docs/current/auth-password.html を参照）です。

MD5 でハッシュ化されたパスワードを使用できます。これは、バックエンドサーバーが MD5 認証を使用している場合、または特定のユーザーが MD5 でハッシュ化されたパスワードを持っている場合に限ります。

SCRAM シークレットは、クライアント認証も SCRAM を使用する場合にのみ、サーバーへのログインに利用できます。また、PgBouncer のデータベース定義でユーザー名が指定されておらず、PgBouncer と PostgreSQL サーバーで SCRAM シークレットが同一（同じソルトと反復回数、単に同じパスワードであるだけでなく）である必要があります。これは SCRAM の本質的なセキュリティ特性によるものです：保存された SCRAM シークレット自体ではログイン資格情報を導出できません。

認証ファイルは手動で作成できますが、他のユーザーとパスワードのリストから生成するのも便利です。./etc/mkauth.py を参照して、pg_authid システムテーブルから認証ファイルを生成するサンプルスクリプトを確認してください。あるいは、別途認証ファイルを管理しなくて済むように、auth_query を auth_file の代わりに使用することもできます。

マネージドサーバーに関する注意事項

バックエンドサーバーが SCRAM パスワード認証を使用するように構成されている場合、PgBouncer は、次のいずれかの情報を知らなければ正常に認証できません。a) ユーザーのパスワードを平文で知っている、または b) 対応する SCRAM シークレットを知っている。

一部のクラウドプロバイダ（例：AWS RDS）では、パスワードを取得するためにPostgreSQLのセンシティブなシステムテーブルへのアクセスが禁止されています。最も特権的なユーザー（例：rds_superuser のメンバー）に対しても、select * from pg_authid は ERROR: permission denied for table pg_authid を返します。これは既知の動作です（blog ）。

したがって、SCRAM シークレットが管理対象のサーバーに格納された後は、それを再取得することは不可能であるため、PgBouncer が同じ SCRAM シークレットを使用するように設定することが難しくなります。ただし、以下のテクニックを用いることで、両方の側で SCRAM シークレットを設定および使用することは可能です。

任意のパスワードに対して SCRAM シークレットを生成するには、シークレットを出力できるツールを使用します。たとえば psql --echo-hidden とコマンド \password を使用すると、サーバーに送信する前にシークレットを管理コンソールに出力できます。

$ psql --echo-hidden <connection_string>
postgres=# \password <role_name>
Enter new password for user "<role_name>":
Enter it again:
********* QUERY **********
ALTER USER <role_name> PASSWORD 'SCRAM-SHA-256$<iterations>:<salt>$<storedkey>:<serverkey>'
**************************

クエリから取得した SCRAM シークレットを記録し、PgBouncer の userlist.txt に設定してください。

psql --echo-hidden 以外のツールを使用した場合、SCRAM シークレットをサーバーにも設定する必要があります（その際、ALTER ROLE <role_name> PASSWORD '<scram_secret>' を使用できます）。

HBA ファイル形式

HBA ファイルの場所は設定 auth_hba_file で指定されます。これは auth_type が hba に設定されている場合にのみ使用されます。

このファイルは、PostgreSQL の pg_hba.conf ファイルの形式に従います（https://www.postgresql.org/docs/current/auth-pg-hba-conf.html を参照）。

• サポートされるレコードタイプ: local、host、hostssl、hostnossl。
• データベースフィールド: all、replication、sameuser、@file、複数の名前をサポートします。非対応: samerole、samegroup。
• ユーザー名フィールド: all、@file、複数の名前をサポートします。サポートしない: +groupname。
• アドレスフィールド: all、IPv4、IPv6 をサポートします。サポートしない: samehost、samenet、DNS名、ドメインプレフィックス。
• 認証方法フィールド: PgBouncer の auth_type でサポートされる方法に加え、peer と reject もサポートされますが、any と pam はグローバルでのみ動作します。
• ユーザー名マップ (map=) パラメータは、auth_type が cert または peer の場合にのみサポートされています。

Ident マップファイル形式

ident マップファイルの場所は設定 auth_ident_file で指定されます。auth_type が hba に設定されている場合にのみ読み込まれます。

ファイル形式は、PostgreSQL の ident マップファイル（https://www.postgresql.org/docs/current/auth-username-maps.html を参照）の簡略化されたバージョンです。

• サポートされる行は、形式 map-name system-username database-username のみです。
• ファイルやディレクトリのインクルードはサポートされていません。
• システムユーザー名フィールド：正規表現はサポートされていません。
• データベースユーザー名フィールド: all または単一の Postgres ユーザー名をサポートします。サポートされない: +groupname、正規表現。

例

小さな設定例:

[databases]
template1 = host=localhost dbname=template1 auth_user=someuser

[pgbouncer]
pool_mode = session
listen_port = 6432
listen_addr = localhost
auth_type = md5
auth_file = users.txt
logfile = pgbouncer.log
pidfile = pgbouncer.pid
admin_users = someuser
stats_users = stat_collector

データベースの例:

[databases]

; foodb over Unix socket
foodb =

; redirect bardb to bazdb on localhost
bardb = host=localhost dbname=bazdb

; access to destination database will go with single user
forcedb = host=localhost port=300 user=baz password=foo client_encoding=UNICODE datestyle=ISO

auth_query 用のセキュアな関数の例：

CREATE OR REPLACE FUNCTION pgbouncer.user_lookup(in i_username text, out uname text, out phash text)
RETURNS record AS $$
BEGIN
    SELECT rolname, CASE WHEN rolvaliduntil < now() THEN NULL ELSE rolpassword END
    FROM pg_authid
    WHERE rolname=i_username AND rolcanlogin
    INTO uname, phash;
    RETURN;
END;
$$ LANGUAGE plpgsql
   SECURITY DEFINER
   -- Set a secure search_path: trusted schema(s), then 'pg_temp'.
   SET search_path = pg_catalog, pg_temp;
REVOKE ALL ON FUNCTION pgbouncer.user_lookup(text) FROM public, pgbouncer;
GRANT EXECUTE ON FUNCTION pgbouncer.user_lookup(text) TO pgbouncer;

so_reuseport を使用してマルチコアの PgBouncer 環境を構築するための、2 つのピアリングされた PgBouncer プロセスの設定例。最初のプロセスの設定：

[databases]
postgres = host=localhost dbname=postgres

[peers]
1 = host=/tmp/pgbouncer1
2 = host=/tmp/pgbouncer2

[pgbouncer]
listen_addr=127.0.0.1
auth_file=auth_file.conf
so_reuseport=1
unix_socket_dir=/tmp/pgbouncer1
peer_id=1

2 番目のプロセスの設定:

[databases]
postgres = host=localhost dbname=postgres

[peers]
1 = host=/tmp/pgbouncer1
2 = host=/tmp/pgbouncer2

[pgbouncer]
listen_addr=127.0.0.1
auth_file=auth_file.conf
so_reuseport=1
; only unix_socket_dir and peer_id are different
unix_socket_dir=/tmp/pgbouncer2
peer_id=2

関連項目

pgbouncer(1) - 一般使用および管理コンソール コマンドのマニュアルページ

https://www.pgbouncer.org/

3 - PgBouncer コマンドの使用法

概要

pgbouncer [-d][-v][-u user] <pgbouncer.ini>
pgbouncer -V|-h

Windows では、次のオプションが利用可能です：

pgbouncer.exe [-v][-u user] <pgbouncer.ini>
pgbouncer.exe -V|-h

Windows サービスの設定に追加で使用できるオプション：

pgbouncer.exe --regservice   <pgbouncer.ini>
pgbouncer.exe --unregservice <pgbouncer.ini>

説明

pgbouncer は PostgreSQL のコネクションプーラーです。任意の対象アプリケーションは、pgbouncer にあたかも PostgreSQL サーバーであるかのように接続できます。このとき、pgbouncer は実際のサーバーへの接続を作成するか、既存の接続を再利用します。

pgbouncer の目的は、PostgreSQL への新しい接続を開く際のパフォーマンスへの影響を低減することです。

接続プーリングのトランザクションセマンティクスを損なわないようにするため、pgbouncer は接続をローテーションする際に複数のプーリング方式をサポートしています。

セッションプーリング

最も丁寧な方法です。クライアントが接続すると、クライアントが接続を維持している間はそのクライアントにサーバー接続が割り当てられます。クライアントが切断すると、そのサーバー接続はプールに戻されます。これがデフォルトの方法です。

トランザクションプーリング

クライアントにサーバー接続が割り当てられるのは、トランザクション中のみです。 PgBouncer がトランザクションの終了を検知すると、サーバー接続はプールに戻されます。

ステートメントプーリング

最も積極的な方法です。クエリの実行が完了した直後に、サーバー接続はプールに戻されます。複数文のトランザクションは破損するため、このモードでは許可されません。

pgbouncer の管理インターフェースは、特別な「仮想」データベース pgbouncer に接続した際に利用可能ないくつかの新しい SHOW コマンドで構成されています。

バージョン 1.26.0 以降、PgBouncer はログイン時に pgbouncer.version、pgbouncer.pool_mode、pgbouncer.max_prepared_statements の ParameterStatus 値をクライアントに送信します。ドライバーはこれらの値を使用して PgBouncer を検出し、動作を適応させることができます。オプションの login_notify_message 設定は、ログイン成功後にウェルカム NOTICE を送信します。

クイックスタート

基本的な設定と使用方法は以下の通りです。

1. pgbouncer.ini ファイルを作成します。詳細は pgbouncer(5) を参照してください。簡単な例：

    [databases]
    template1 = host=localhost port=5432 dbname=template1
   
    [pgbouncer]
    listen_port = 6432
    listen_addr = localhost
    auth_type = md5
    auth_file = userlist.txt
    logfile = pgbouncer.log
    pidfile = pgbouncer.pid
    admin_users = someuser
   

2. 接続を許可するユーザーを記載した userlist.txt ファイルを作成します：

    "someuser" "same_password_as_in_server"
   

3. pgbouncer を起動します：

    $ pgbouncer -d pgbouncer.ini
   

4. アプリケーション（または psql クライアント）が PostgreSQL サーバーに直接接続するのではなく、 pgbouncer に接続するようにしてください。

    $ psql -p 6432 -U someuser template1
   

5. pgbouncer を管理するには、特別な管理データベース pgbouncer に接続し、SHOW HELP; を実行して開始します：

    $ psql -p 6432 -U someuser pgbouncer
    pgbouncer=# SHOW HELP;
    NOTICE:  Console usage
    DETAIL:
      SHOW [HELP|CONFIG|DATABASES|POOLS|CLIENTS|SERVERS|SOCKETS|LISTS|VERSION|...]
      SET key = arg
      RELOAD
      PAUSE
      RESUME
      SHUTDOWN
      [...]
   

6. pgbouncer.ini ファイルに変更を加えた場合、次のように再読み込みできます：

    pgbouncer=# RELOAD;
   

コマンドラインスイッチ

-d、--daemon

バックグラウンドで実行します。これを行わない場合、プロセスはフォアグラウンドで実行されます。

デーモンモードでは、pidfile に加えて logfile または syslog を設定する必要があります。バックグラウンドに移行後は、stderr へのログ出力は行われません。

注意：Windows では動作しません。pgbouncer は Windows 上でサービスとして実行する必要があります。

-u USERNAME、--user= USERNAME

起動時に指定されたユーザーに切り替えます。

-v、--verbose

出力の詳細度を増加します。複数回使用できます。

-q、--quiet

静黙モード：stderr へのログ出力を抑制します。ログの詳細度には影響しません。stderr が使用されなくなるだけです。init.d スクリプトでの利用を想定しています。

-V、--version

バージョンを表示。

-h、--help

短いヘルプを表示します。

--regservice

Win32: PgBouncer を Windows サービスとして実行するように登録します。service_name 設定パラメーターの値が、登録時の名前として使用されます。

--unregservice

Win32: Windows サービスの登録を解除します。

管理コンソール

管理コンソールは、データベース pgbouncer に通常通り接続することで利用できます。

$ psql -p 6432 pgbouncer

設定パラメーター admin_users または stats_users にリストされたユーザーのみが、管理コンソールにログインできます（auth_type=any の場合は例外で、任意のユーザーが stats_user としてログインできます）。

さらに、ユーザー名 pgbouncer は、ログインが Unix ソケット経由で行われ、クライアントの Unix ユーザー UID が実行中のプロセスと同一の場合、パスワードなしでログインが許可されます。

管理コンソールは現在、シンプルなクエリプロトコルのみをサポートしています。 すべてのコマンドに拡張クエリプロトコルを使用するドライバは、これに対応していません。

SHOW コマンド

SHOW コマンドは情報を出力します。各コマンドの説明は以下の通りです。

SHOW STATS

統計情報を表示します。このコマンドおよび関連コマンドでは、合計値はプロセス起動以降の値であり、平均値は stats_period ごとに更新されます。

database

統計情報はデータベースごとに表示されます。

total_xact_count

pgbouncer がプールしている SQL トランザクションの合計数。

total_query_count

pgbouncer がプールしている SQL コマンドの合計数。

total_server_assignment_count

サーバーがクライアントに割り当てられた合計回数

total_received

pgbouncer が受信したネットワークトラフィックの合計バイト数。

total_sent

pgbouncer が送信したネットワークトラフィックの合計バイト数。

total_xact_time

pgbouncer が PostgreSQL に接続してトランザクション（トランザクション内でのアイドル状態またはクエリの実行のいずれか）に費やした合計マイクロ秒数。

total_query_time

pgbouncer が PostgreSQL にアクティブに接続してクエリを実行している間に費やした合計マイクロ秒数。

total_wait_time

クライアントがサーバー接続を待つ時間（マイクロ秒単位）。クライアント接続がバックエンド接続に割り当てられたときに更新されます。

total_client_parse_count

クライアントが作成したプリペアドステートメントの合計数。名前付きプリペアドステートメント追跡モードでのみ適用されます。max_prepared_statements を参照してください。

total_server_parse_count

サーバー上で pgbouncer が作成したプリペアドステートメントの合計数。名前付きプリペアドステートメント追跡モードでのみ適用されます。max_prepared_statements を参照してください。

total_bind_count

クライアントが実行準備を済ませ、pgbouncer が PostgreSQL に転送したプリペアドステートメントの合計数。名前付きプリペアドステートメント追跡モードでのみ適用されます。max_prepared_statements を参照してください。

total_client_login_count

成功したクライアントログインの合計数。

avg_xact_count

直近の統計期間における 1 秒あたりの平均トランザクション数。

avg_query_count

直近の統計期間における 1 秒あたりの平均クエリ数。

avg_server_assignment_count

直近の統計期間における、サーバーがクライアントに割り当てられた 1 秒あたりの平均回数。

avg_recv

クライアントからの平均受信バイト数（1 秒あたり）。

avg_sent

クライアントへの平均送信バイト数（1 秒あたり）。

avg_xact_time

平均トランザクション実行時間（マイクロ秒単位）。

avg_query_time

平均クエリ実行時間（マイクロ秒単位）。

avg_wait_time

クライアントがサーバーを待つ時間（現在の stats_period の間にバックエンドに割り当てられたクライアントの待機時間の平均）をマイクロ秒単位で示します。

avg_client_parse_count

クライアントが作成したプリペアドステートメントの 1 秒あたりの平均数。名前付きプリペアドステートメント追跡モードでのみ適用されます。max_prepared_statements を参照してください。

avg_server_parse_count

サーバー上で pgbouncer が作成したプリペアドステートメントの 1 秒あたりの平均数。名前付きプリペアドステートメント追跡モードでのみ適用されます。max_prepared_statements を参照してください。

avg_bind_count

クライアントが実行準備を済ませ、pgbouncer が PostgreSQL に転送したプリペアドステートメントの 1 秒あたりの平均数。名前付きプリペアドステートメント追跡モードでのみ適用されます。max_prepared_statements を参照してください。

avg_client_login_count

1 秒あたりの成功したクライアントログインの平均数。

SHOW STATS_TOTALS

SHOW STATS の total_ フィールドに対応する、データベースごとの累積統計を表示します。出力の列名からは total_ プレフィックスが省かれます。たとえば、total_query_count は query_count という列名になります。

SHOW STATS_AVERAGES

SHOW STATS のうち、平均値（avg_）を示すサブセット。

SHOW TOTALS

SHOW STATS と同様ですが、すべてのデータベースにわたって集計されています。

SHOW SERVERS

type

S、サーバー用。

user

pgbouncer がサーバーへの接続に使用するユーザー名。

database

データベース名。

replication

サーバー接続がレプリケーションを使用するかどうか。none、logical、physical のいずれかになります。

state

PgBouncer サーバー接続の状態。以下のいずれか：active、 idle、used、tested、new、active_cancel、 being_canceled。

addr

PostgreSQL サーバーの IP アドレス。

port

PostgreSQL サーバーのポート。

local_addr

ローカルマシン上の接続開始アドレス。

local_port

ローカルマシン上の接続開始ポート。

connect_time

接続が確立された時。

request_time

最終リクエストが発行された時刻。

wait

サーバー接続には使用されません。

wait_us

サーバー接続には使用されません。

close_needed

設定ファイルの再読み込みや DNS 更新により接続情報が変更された場合、または RECONNECT が発行された場合に、接続ができるだけ早く閉じられるときは 1 になります。

ptr

この接続に対する内部オブジェクトのアドレス。

link

このサーバーが紐付けられているクライアント接続のアドレス。

remote_pid

サーバーのバックエンドプロセスの PID。Unix ソケット経由で接続された場合、OS がプロセスID情報を取得できる場合はその OS の PID を使用する。そうでない場合は、サーバーが送信したキャンセルパケットから抽出する。PostgreSQL がサーバーの場合、これは PID であるべきだが、別の PgBouncer がサーバーの場合、ランダムな数値となる。

tls

TLS 接続情報の文字列、TLS を使用しない場合は空。

application_name

クライアント接続で設定された application_name を含む文字列、 またはその設定が行われていない場合、または関連する接続が存在しない場合に空。

prepared_statements

サーバー上で準備されたプリペアドステートメントの数。この数は max_prepared_statements 設定によって制限されます。

id

サーバーの固有ID。

SHOW CLIENTS

type

C、クライアント用。

user

クライアント接続ユーザー。

database

データベース名。

replication

クライアント接続がレプリケーションを使用するかどうか。none、logical、physical のいずれか。

state

クライアント接続の状態。以下のいずれか：active（サーバー接続と紐づけられたクライアント接続）、idle（処理待ちのクエリのないクライアント接続）、waiting、active_cancel_req、または waiting_cancel_req。

addr

クライアントの IP アドレス。

port

クライアントのソースポート。

local_addr

ローカルマシン上の接続終端アドレス。

local_port

ローカルマシン上の接続終端ポート。

connect_time

接続時刻のタイムスタンプ。

request_time

最後のクライアント要求のタイムスタンプ。

wait

現在の待機時間（秒単位）。

wait_us

現在の待機時間のマイクロ秒部分。

close_needed

クライアントには使用されません

ptr

この接続に対する内部オブジェクトのアドレス。

link

クライアントが紐付けられているサーバー接続のアドレス。

remote_pid

クライアントが Unix ソケット経由で接続している場合、OS がプロセス ID を取得できる場合に限り、プロセス ID を表示します。

tls

TLS 接続情報の文字列、TLS を使用しない場合は空。

application_name

クライアントがこの接続で設定した application_name を含む文字列。設定されていない場合は空。

prepared_statements

クライアントが準備したプリペアドステートメントの数

id

クライアントの固有ID。

SHOW POOLS

各 (database, user) の組に対して新しいプールエントリが作成されます。

database

データベース名。

user

ユーザー名。

cl_active

サーバー接続に紐付けられているか、処理待ちのクエリがないアイドル状態にあるクライアント接続。

cl_waiting

クエリを送信したが、まだサーバー接続を取得していないクライアント接続。

cl_active_cancel_req

クエリのキャンセルをサーバーに転送済みで、サーバーの応答を待機しているクライアント接続。

cl_waiting_cancel_req

まだクエリのキャンセルをサーバーに転送していないクライアント接続。

sv_active

クライアントに紐付けられているサーバー接続。

sv_active_cancel

現在、キャンセル要求を転送中のサーバー接続。

sv_being_canceled

通常であればアイドル状態になれるはずのサーバーですが、このサーバー上のクエリをキャンセルするために送信された進行中のキャンセル要求がすべて完了するまで、アイドル状態への移行を待機しています。

sv_idle

クライアントクエリに即座に利用可能な、使用されていないサーバー接続。

sv_used

server_check_delay を超えてアイドル状態が続いているサーバー接続。再び使用するには、事前に server_check_query を実行する必要があります。

sv_tested

現在 server_reset_query または server_check_query を実行中のサーバー接続。

sv_login

現在ログイン処理中のサーバー接続。

maxwait

キュー内の最初（最も古い）クライアントが待機した時間（秒単位）。 この値が増加し始めた場合は、現在のサーバーのプールがリクエストを十分に迅速に処理できていないことを示します。 原因は、サーバーの過負荷、または pool_size 設定が小さすぎることのいずれかの可能性があります。

maxwait_us

最大待機時間のマイクロ秒部分。

pool_mode

使用中のプーリングモード。

load_balance_hosts

プールのホストにコンマ区切りのリストが含まれている場合、使用される load_balance_hosts。

SHOW PEER_POOLS

各設定されたピアごとに、新しい peer_pool エントリが作成されます。

peer_id

設定されたピアエントリの ID。

cl_active_cancel_req

クエリのキャンセルをサーバーに転送済みで、サーバーの応答を待機しているクライアント接続。

cl_waiting_cancel_req

まだクエリのキャンセルをサーバーに転送していないクライアント接続。

sv_active_cancel

現在、キャンセル要求を転送中のサーバー接続。

sv_login

現在ログイン処理中のサーバー接続。

SHOW LISTS

次の内部リストとそれぞれの要素数を、リストごとに 1 行ずつ、list 列と items 列に表示します：

databases

データベース数。

users

ユーザー数。

peers

設定されたピアの数。

pools

プール数。

peer_pools

ピアプール数。

free_clients

クライアントの空き数。切断されたクライアントであり、将来のクライアントの再利用のために割り当てられたメモリを保持しているため、メモリの再割り当てを回避できる。

used_clients

使用中のクライアント数。

login_clients

login 状態のクライアント数。

free_servers

空きサーバーの数。これらのサーバーは切断されていますが、PgBouncer は将来のサーバー用に再利用できるよう、それらに割り当てられたメモリを保持しています。

used_servers

使用中のサーバー数。

dns_names

キャッシュ内の DNS 名の数。

dns_zones

キャッシュ内の DNS ゾーン数。

dns_queries

進行中の DNS クエリの数。

dns_pending

使用されません

SHOW USERS

name

ユーザー名

pool_size

ユーザーが上書きした pool_size。設定されていない場合は空文字列。

reserve_pool_size

ユーザーの上書き設定による reserve_pool_size。設定されていない場合は空文字列。

pool_mode

ユーザーが上書きした pool_mode の値、または設定されていない場合は NULL。

max_user_connections

ユーザーの max_user_connections 設定。この特定のユーザーに対してこの設定が指定されていない場合、デフォルト値が表示されます。

current_connections

このユーザーがすべてのサーバーに対して開いているサーバー接続の現在の数。

max_user_client_connections

ユーザーの max_user_client_connections 設定。この特定のユーザーに対してこの設定が指定されていない場合、デフォルト値が表示されます。

current_client_connections

このユーザーが PgBouncer に対して開いているクライアント接続の現在の数。

SHOW DATABASES

name

設定されたデータベースエントリの名前。

host

PgBouncer が接続するホスト。

port

PgBouncer が接続するポート。

database

PgBouncer が接続する実際のデータベース名。

force_user

ユーザーが接続文字列に含まれている場合、クライアントユーザーに関係なく、PgBouncer と PostgreSQL の接続は指定されたユーザーに強制されます。

pool_size

サーバー接続の最大数。

min_pool_size

サーバー接続の最小数。

reserve_pool_size

このデータベースに対する追加接続数の最大値。

server_lifetime

このデータベースのサーバー接続の最大有効期間

pool_mode

データベースの上書き pool_mode、またはデフォルトが使用される場合の NULL。

load_balance_hosts

データベースの load_balance_hosts は、ホストにコンマ区切りのリストが含まれている場合に使用されます。

max_connections

max_db_connections によって（グローバルまたはデータベースごとに）設定された、このデータベースに対して許可されるサーバー接続数の最大値。

current_connections

このデータベースの現在のサーバー接続数。

max_client_connections

このデータベースで許可されるクライアント接続の最大数。グローバルまたはデータベースごとの max_db_client_connections で設定された値。

current_client_connections

このデータベースの現在のクライアント接続数。

paused

このデータベースが現在一時停止されている場合は 1、それ以外の場合は 0。

disabled

このデータベースが現在無効になっている場合は 1、それ以外の場合は 0。

SHOW PEERS

peer_id

設定されたピアエントリの ID。

host

PgBouncer が接続するホスト。

port

PgBouncer が接続するポート。

pool_size

このピアへのサーバー接続の最大数

SHOW SOCKETS, SHOW ACTIVE_SOCKETS

ソケット、またはアクティブなソケットのみに関する低レベルの情報を表示します。 これは SHOW CLIENTS および SHOW SERVERS で表示される情報に加えて、他のより低レベルな情報も含みます。

SHOW CONFIG

現在の設定値を1行に1つずつ表示し、以下の列を用います。

key

設定変数名

value

設定値

default

設定のデフォルト値

changeable

yes または no で、変数を実行中に変更できるかどうかを示します。 no の場合、変数は起動時のみ変更可能です。実行中に変更するには SET を使用します。

SHOW MEM

さまざまな内部メモリ割り当ての現在のサイズに関する低レベルの情報を表示します。表示される情報は変更される可能性があります。

SHOW DNS_HOSTS

DNS キャッシュ内のホスト名を表示します。

hostname

ホスト名。

ttl

次回の照会までの秒数。

addrs

コンマ区切りのアドレスリスト。

SHOW DNS_ZONES

キャッシュ内の DNS ゾーンを表示します。

zonename

ゾーン名。

serial

現在のシリアル。

count

このゾーンに属するホスト名。

SHOW VERSION

PgBouncer のバージョン文字列を表示します。

SHOW STATE

PgBouncer の状態設定を表示します。現在の状態は active と paused です。

プロセス制御コマンド

PAUSE [db]

PgBouncer はすべてのサーバーとの接続を切断しようとします。各サーバー接続の切断は、サーバープールのプーリングモードに従って、その接続が解放されるのを待機します（トランザクションプーリングモードではトランザクションの完了まで、ステートメントモードではステートメントの完了まで、セッションプーリングモードではクライアントの切断まで待機します）。すべてのサーバー接続が切断されるまで、このコマンドは戻りません。データベースの再起動時に使用します。

データベース名が指定された場合、そのデータベースのみが一時停止されます。

一時停止されたデータベースへの新しいクライアント接続は、RESUME が呼び出されるまで待機します。

DISABLE db

指定されたデータベースへの新しいクライアント接続をすべて拒否します。

ENABLE db

前の DISABLE コマンドの後に新しいクライアント接続を許可します。

RECONNECT [db]

指定されたデータベース、またはすべてのデータベースのオープンなサーバー接続を、（プーリングモードに従って）解放された後に閉じます。ライフタイムがまだ満了していなくても閉じられます。新しいサーバー接続はすぐに作成でき、プールサイズの設定に従って必要に応じて接続されます。

このコマンドは、サーバー接続の設定が変更された場合に有用です。たとえば、新しいサーバーへの段階的なスイッチオーバーを実行する際に使用します。pgbouncer.ini の接続文字列を変更して再読み込みした場合（RELOAD を参照）や、DNS 解決が変更された場合、このコマンドを実行する必要はありません。そのような場合、同様の処理が自動的に実行されるためです。このコマンドが必要となるのは、PgBouncer の下流で接続をルーティングしているものがある場合に限ります。

このコマンドを実行した後、一部のサーバー接続が古い宛先に、別のサーバー接続が新しい宛先に向かう状態が長期間続く可能性があります。これは、読み取り専用レプリカ間で読み取り専用トラフィックを切り替える場合や、マルチマスターレプリケーション構成のノード間で切り替える場合にのみ適切であると考えられます。すべての接続を同時に切り替える必要がある場合は、代わりに PAUSE が推奨されます。待機せずにサーバー接続を閉じる必要がある場合（たとえば、段階的なスイッチオーバーではなく緊急フェイルオーバーのシナリオ）は、KILL の検討もしてください。

KILL [db]

指定されたデータベースまたはすべてのデータベース（管理データベースを除く）のすべてのクライアント接続とサーバー接続を即座に切断します。

KILL が実行されたデータベースへの新しいクライアント接続は、RESUME が呼び出されるまで待機します。

KILL_CLIENT id

指定されたクライアント接続を、そのクライアントに対するすべてのサーバー接続とともに即座に切断します。切断対象のクライアントは、SHOW CLIENTS コマンドで確認できる id 値によって識別されます。

コマンドの例は KILL_CLIENT 1234 のようになります。

RESUME [db]

前の KILL または PAUSE コマンドからの作業を再開します。

SHUTDOWN

PgBouncer プロセスは終了します。

SHUTDOWN WAIT_FOR_SERVERS

新しい接続の受付を停止し、すべてのサーバーが解放された後にシャットダウンします。 これは PAUSE と SHUTDOWN を実行するのと基本的に同じですが、 PAUSE を待つ間も新しい接続の受付を停止し、 サーバー接続を待機しているクライアントを積極的に切断する点が異なります。 UNIX ソケットはシャットダウン中に開いたままになりますが、 PgBouncer 管理コンソールへの接続のみを受け付けます。

SHUTDOWN WAIT_FOR_CLIENTS

新しい接続の受付を停止し、既存のすべてのクライアントが切断されたらプロセスをシャットダウンします。UNIX ソケットはシャットダウン中に開いたままになりますが、pgbouncer 管理コンソールへの接続のみを受け付けます。このコマンドは、以下の手順に従って2つの PgBouncer プロセスをゼロダウンタイムでローリング再起動する際に使用できます。

1. so_reuseport を使用して、同じポートで 2 つ以上の PgBouncer プロセスを実行します （ピアリングの設定 は推奨されますが、必須ではありません）。 再起動時のダウンタイムをゼロにするため、これらのプロセスを 1 つずつ再起動します。これにより、1 つのプロセスを再起動している間も、他のプロセスが接続を受け入れ続けます。
2. 最初に再起動するプロセスを選択します。これを A と呼びます。
3. プロセス A に SHUTDOWN WAIT_FOR_CLIENTS を実行します（または SIGTERM を送信します）。
4. すべてのクライアントが再接続するようにします。クライアント側のプーラーが server_idle_timeout（または同様の設定）によって再接続を引き起こすまでしばらく待つことで実現できます。クライアント側のプーラーが使用されていない場合は、クライアントを再起動することで実現できます。すべてのクライアントが再接続すると、プロセス A は自動的に終了します。接続しているクライアントがもういないためです。
5. プロセス A を再度起動します。
6. 残りの各プロセスに対してステップ 3、4、5 を 1 つずつ繰り返し、すべてのプロセスを再起動するまで続けます。

RELOAD

PgBouncer プロセスは設定ファイルを再読み込みし、変更可能な設定を更新します。これにはメイン設定ファイルおよび設定 auth_file と auth_hba_file で指定されたファイルが含まれます。

PgBouncer は、設定ファイルの再読み込みによってデータベース定義の接続パラメーターが変更されたことを検出します。既存のサーバー接続は、プーリングモードに従って次回接続を解放するタイミングで古い宛先に対して閉じられ、新しいサーバー接続は即座に更新された接続パラメーターを使用します。

WAIT_CLOSE [db]

指定されたデータベースまたはすべてのデータベースのすべてのサーバー接続が “close_needed” 状態を解除するまで待機します（SHOW SERVERS を参照）。これは RECONNECT や RELOAD の後に呼び出すことで、たとえばスイッチオーバースクリプトで、それぞれの設定変更が完全に有効になるまで待機するために使用できます。

その他のコマンド

SET key = arg

設定値を変更します（詳細は SHOW CONFIG を参照）。たとえば：

SET log_connections = 1;
SET server_check_query = 'select 2';

（このコマンドは PgBouncer 管理コンソールで実行され、PgBouncer の設定を変更します。SET コマンドを他のデータベースで実行しても、他の SQL コマンドと同様に PostgreSQL バックエンドに渡されます。）

シグナル

SIGHUP

設定の再読み込み。管理コンソール上で RELOAD コマンドを実行したのと同じです。

SIGTERM

スーパーセーフシャットダウン。既存のすべてのクライアントの切断を待ちますが、新しい接続は受け付けません。これは管理コンソール上で SHUTDOWN WAIT_FOR_CLIENTS を実行することと同じです。シャットダウンがすでに進行中の状態でこのシグナルを受け取った場合、「スーパーセーフシャットダウン」の代わりに「即時シャットダウン」がトリガーされます。PgBouncer 1.23.0 より前のバージョンでは、このシグナルは「即時シャットダウン」を引き起こしていました。

SIGINT

セーフシャットダウン。管理コンソールで SHUTDOWN WAIT_FOR_SERVERS を実行したのと同じです。 シャットダウンがすでに進行中の間にこのシグナルを受け取った場合、「セーフシャットダウン」の代わりに「即時シャットダウン」がトリガーされます。

SIGQUIT

即時シャットダウン。管理コンソールで SHUTDOWN を実行したのと同じです。

SIGUSR1

管理コンソールで PAUSE を実行したのと同じです。

SIGUSR2

管理コンソールで RESUME を実行したのと同じです。

Libevent 設定

Libevent のドキュメントより：

環境変数 EVENT_NOEPOLL、EVENT_NOKQUEUE、EVENT_NODEVPOLL、EVENT_NOPOLL または EVENT_NOSELECT をそれぞれ設定することで、epoll、kqueue、devpoll、poll または select のサポートを無効にできます。

環境変数 EVENT_SHOW_METHOD を設定すると、libevent は使用するカーネル通知メソッドを表示します。

関連項目

pgbouncer(5) - 設定項目の説明のマニュアルページ

https://www.pgbouncer.org/

4 - PgBouncer のコンパイルとインストール

ビルド

PgBouncer は、Autoconf ベースのビルドシステムでも、より新しい、まだ実験的な Meson ビルドシステムでもビルドできます。現時点では、本番用のビルドおよびパッケージングには Autoconf が推奨されます。Meson ビルドは将来のリリースでデフォルトになり、Autoconf ビルドは削除される見込みのため、Meson のテストと問題の報告を歓迎します。コンパイルにはいくつかの要素が必要です：

• Libevent 2.0+
• pkg-config
• OpenSSL 1.0.1+（TLS サポート用）
• C11 対応の C コンパイラー
• (オプション) c-ares は Libevent の evdns の代替として利用可能
• (オプション) LDAP ライブラリ
• (オプション) PAM ライブラリ

Meson ビルドにはさらに Meson 0.58+ と Ninja が必要であり、Autoconf ビルドには GNU Make 3.81+ が必要です。

依存関係がインストールされたら、Autoconf でビルドします：

$ ./configure --prefix=/usr/local
$ make
$ make install

または Meson でビルドします（実験的）：

$ meson setup build --prefix=/usr/local
$ meson compile -C build
$ meson install -C build

Git からビルドする場合、または Windows 用にビルドする場合は、以下の別途のビルド手順を参照してください。

DNS ルックアップサポート

PgBouncer は、設定の読み込み時に一度だけではなく、接続時にホスト名のルックアップを行います。これには非同期 DNS 実装が必要です。以下の表は、サポートされるバックエンドとその検出順序を示しています。

1. EDNS0 は、1 つのホスト名の背後に 8 件を超えるアドレスがある場合に必要です。
2. SOA の照会は、ゾーンシリアルの変更時にホスト名を再確認するために必要です。
3. EDNS0 を有効にするには、options edns0 を /etc/resolv.conf に追加してください。

c-ares は最も機能が充実しており、ほとんどの用途およびバイナリパッケージング（十分に新しいバージョンが利用可能な場合）に推奨されます。Libevent の組み込み evdns も、記載された制限を除き多くの用途に適しています。他のバックエンドは現在、ほとんどがレガシーな選択肢であり、テストもほとんど行われていません。

デフォルトでは、c-ares が見つかった場合に使用されます。使用を強制するには -Dcares=enabled（configure の場合は --with-cares）、無効化するには -Dcares=disabled（configure の場合は --without-cares）を指定します。c-ares を使用しない（見つからないか無効化されている）場合、Libevent が使用されます。Libevent の evdns の使用を無効にして libc ベースの実装にフォールバックするには、-Devdns=false（configure の場合は --disable-evdns）を指定してください。

オプション機能

PAM、LDAP、systemd の各機能は meson によって自動検出されます。-Dpam、-Dldap、-Dsystemd の各オプションのデフォルトは auto であり、それぞれのライブラリが存在する場合にその機能がビルドされます。-D<feature>=enabled で強制的に有効に、-D<feature>=disabled で強制的に無効にできます。Autoconf ビルドはこれらの機能を自動検出しません。--with-pam、--with-ldap、または --with-systemd で明示的に有効にしてください。

PAM 認証

PAM サポート付きでコンパイルした場合、PAM を通じてユーザーを検証する新しいグローバル認証タイプ pam が利用可能になります。

LDAP 認証

LDAP サポート付きでコンパイルした場合、LDAP を通じてユーザーを検証する新しいグローバル認証タイプ ldap が利用可能になります。

systemd 統合

systemd サポートでは、Type=notify（systemd 253 以降を使用している場合は Type=notify-reload）およびソケット活性化を利用できます。例については etc/pgbouncer.service および etc/pgbouncer.socket を参照してください。

Git からビルドする

Autoconf ビルドでは、configure を実行する前にヘッダーファイルおよび設定ファイルを生成する必要があります：

$ git clone --branch pgbouncer_1_26_0 https://github.com/pgbouncer/pgbouncer.git
$ cd pgbouncer
$ ./autogen.sh
$ ./configure
$ make
$ make install

デフォルトでは、すべてのファイルが /usr/local にインストールされます。 configure に 1 つ以上のコマンドラインオプションを指定できます。 利用可能なオプションおよび設定をカスタマイズする環境変数を確認するには、./configure --help を実行してください。

Git からの Autoconf ビルドに追加で必要なパッケージ: autoconf, automake, libtool, pandoc

Meson ビルドでは、チェックアウトから直接ビルドできます。 man ページをビルドするには pandoc が必要です：

$ meson setup build
$ meson compile -C build
$ meson install -C build

利用可能な -D オプションを一覧表示するには、meson configure build を実行してください。

テスト

テストディレクトリ内の README.md ファイル を参照して、テストの実行方法を確認してください。

Windows 上でのビルド

Windows でサポートされている唯一のビルド環境は MinGW です。Cygwin および Visual $ANYTHING はサポートされていません。

MinGW でビルドするには、通常の Autoconf ビルドを行います：

$ ./configure
$ make

または実験的な Meson ビルドを行います：

$ meson setup build
$ meson compile -C build

Autoconf を使って Unix からクロスコンパイルする場合:

$ ./configure --host=i586-mingw32msvc

LDAP ビルドオプションは現在、Windows ではサポートされていません。

Windows 上での実行

コマンドラインからの実行は通常通りですが、-d（デーモン化）と -u（ユーザー切り替え）のスイッチは機能しません。

Windows サービスとして PgBouncer を実行するには、service_name パラメーターを設定してサービス名を指定する必要があります。その後、以下を実行します。

$ pgbouncer -regservice config.ini

サービスをアンインストールするには：

$ pgbouncer -unregservice config.ini

Windows イベントログを使用するには、設定ファイルで syslog = 1 を設定してください。 ただし、その前に pgbevent.dll の登録が必要です。

$ regsvr32 pgbevent.dll

登録を解除するには、次のようにします：

$ regsvr32 /u pgbevent.dll

5 - ソースリリースのダウンロード

PgBouncer 1.26

PgBouncer 1.25

PgBouncer 1.24

PgBouncer 1.23

PgBouncer 1.22

PgBouncer 1.21

PgBouncer 1.20

PgBouncer 1.19

PgBouncer 1.18

PgBouncer 1.17

PgBouncer 1.16

PgBouncer 1.15

PgBouncer 1.14

PgBouncer 1.13

PgBouncer 1.12

PgBouncer 1.11

PgBouncer 1.10

PgBouncer 1.9

PgBouncer 1.8

PgBouncer 1.7

PgBouncer 1.6

PgBouncer 1.5

PgBouncer 1.4

PgBouncer 1.3

PgBouncer 1.2

PgBouncer 1.1

PgBouncer 1.0

バイナリパッケージ

さまざまな OS ディストリビューションには、PgBouncer のネイティブなパッケージまたはポートが用意されています。そのため、まずあなたの OS で既に利用可能かどうかを確認することをお勧めします。

専用ビルドは、ディストリビュータのリポジトリに公開されているバージョンよりも新しい場合があります。

• RPM: yum.postgresql.org
• Deb: apt.postgresql.org

6 - 変更履歴

PgBouncer 1.26.x

2026-09-23 - PgBouncer 1.26.0 - 「これまでのすべての search_path を無視」

• セキュリティ
  • CVE-2026-19888 の修正：1.26.0 より前の PgBouncer は、SCRAM client-final-message に nonce が含まれていることをチェックしていませんでした。認証されていないリモート攻撃者は、nonce を含まない client-final-message を送信することで PgBouncer をクラッシュさせることができました。存在しないユーザーについても同様です。PgBouncer はそのようなユーザーに対して模擬的な SCRAM 交換を実行するためです。このバグは、PgBouncer 1.11.0 で SCRAM サポートが追加されて以来存在していました。
  • CVE-2026-6668 の修正：1.26.0 より前の PgBouncer におけるパケットバッファ拡張ロジックの整数オーバーフローにより、PgBouncer が無限ループでハングする可能性がありました。これには単一のパケットバッファに大量のデータを送信する必要がありますが、max_packet_size がデフォルト値のままの場合、事前に認証しなくても可能です。PgBouncer はシングルスレッドであるため、このハングが発生すると、プロセスが強制終了されるまでどのクライアントにも対応できなくなっていました。
  • CVE-2026-6669 の修正：1.26.0 より前の PgBouncer は、サーバーから受け入れる SCRAM イテレーション回数に上限を設けていませんでした。悪意のある、または侵害された PostgreSQL サーバーは、単一のログイン中に PgBouncer に無制限の作業を行わせ、その間に他のすべてのクライアントとデータベースへの対応を停止させることができました。イテレーション回数は現在、最大 1000000 である必要があります。
• 機能
  • PostgreSQL がデフォルトで報告するすべてのパラメータを追跡するようになりました。特に重要な点として、search_path（PostgreSQL 18 以上）と default_transaction_read_only（PostgreSQL 14 以上）がデフォルトで追跡されるようになります。以前は、トランザクションプーリングモードで SET search_path や SET default_transaction_read_only = true を実行したクライアントが、後から同じサーバー接続を使用する他のクライアントに影響を与える可能性がありました。(#1580 , #1573 )
  • しばらく使用されていないプールをクリーンアップする pool_idle_timeout 設定を追加しました。これは、頻繁に接続しない多数の異なるユーザーが存在する構成で有用です。この設定を有効にしない場合、そのような構成ではプールの数が無制限に増加します。プールを削除するとその統計情報も失われるため、この設定はデフォルトで無効になっています。(#1491 )
  • query_wait_timeout をユーザーごとおよびデータベースごとに設定できるようになりました。(#1449 )
  • SHOW STATS に client_login_count 統計を追加しました。これはクライアントのログイン成功をカウントします。これにより、接続を頻繁に張り替えるクライアントを検出できます。(#1457 )
  • ログイン時に、PgBouncer 固有の ParameterStatus メッセージ（pgbouncer.version、pgbouncer.pool_mode、pgbouncer.max_prepared_statements）をクライアントに送信するようになりました。これにより、クライアントとドライバーは、PgBouncer 経由で接続していることを検出し、それに応じて動作を調整できます。(#1490 )
  • login_notify_message 設定を追加しました。設定すると、その値はクライアントのログイン後に NOTICE メッセージとして送信されます。これにより、クライアントが PostgreSQL に直接接続しているのではなく PgBouncer 経由で接続していることを明確にできます。(#1488 )
  • UCRT64 環境を使用した Windows ビルドを含む、meson による PgBouncer のビルドサポートを追加しました。Autoconf によるビルドも引き続きサポートされます。(#1524 , #1426 , #1568 , #1585 , #1602 , #1607 )
  • ロゴを追加しました。(#1609 )
• 変更点
  • 非推奨となっていたオンライン再起動（-R、別名テイクオーバー）機能を、それをサポートするためだけに存在していた SHOW FDS および SUSPEND 管理コマンドとともに削除しました。代わりに、so_reuseport を使ったローリング再起動 を使用してください。(#1581 )
  • パスワードの最大長を、libpq に合わせて 65535 バイトに増やしました。(#1310 , #1520 )
  • auth_query が NULL のユーザー名を返した場合に、エラーとして扱うのではなく、行が返されなかった場合と同じように扱うようにしました。(#1569 )
  • 管理データベースで SET extra_float_digits を受け入れるようになりました。新しい PostgreSQL JDBC ドライバーが接続確立時に送信してくるためです。(#1550 )
  • mkauth.py が、出力ファイルとして - を渡すことで stdout に書き込めるようになりました。(#1514 )
  • OpenSSL 3 に対してビルドした場合に、クライアントからの予期しない EOF に関するノイズの多いエラーをログに出力しないようにしました。(#1507 )
  • OpenSSL 3 に対してビルドした場合に、TLS エラーメッセージに基となるシステムエラーを含めるようにしました。(#1492 )
  • C11 コンパイラを必須にしました。(#1417 )
  • サーバー接続がエビクトされた原因となった上限をログに記録するようになりました。切断理由は、単なる evicted ではなく、evicted for max_db_connections、evicted for pool_size、evicted for max_user_connections になりました。(#1597 )
• 修正
  • トランザクションプーリングモードで、遅延した COPY メッセージがプール枯渇を引き起こす問題を修正しました。これにより、トランザクションプーリングモードでは明示的なトランザクションの外でも COPY が動作するようになりました。(#1471 )
  • LDAP URL の最大長を増やすことで、長い DN による LDAP 認証の失敗を修正しました。(#1497 )
  • SCRAM パススルーが強制ユーザーのキャッシュされた資格情報を破損する問題を修正しました。この問題により、本物のサーバーが SCRAM プルーフを拒否するため、サーバーログインが失敗していました。(#1612 )
  • サーバーへの再接続後に、保存された SCRAM シークレットで SCRAM パススルーが「password is SCRAM secret but client authentication did not provide SCRAM keys」というエラーで失敗する問題を修正しました。(#1504 、バグは 1.25.1 で導入)
  • レプリケーションクライアントの切断時に、そのサーバー接続がまだログイン中だった場合に発生する use-after-free クラッシュを修正しました。(#1577 )
  • プールが満杯の場合の、レプリケーションクライアントに対するアイドルサーバー接続のエビクションを修正しました。以前は、単一のレプリケーションクライアントが、1 つだけではなくプール内のすべてのアイドルサーバーをエビクトする可能性があり、予約プールやキャンセル要求のためにプールが pool_size を超えてサーバーを保持している場合は、エビクションがまったく発生しませんでした。(#1597 )
  • パケットがパケットバッファの境界にまたがる場合（例えば、長い値を指定した SET application_name）に TLS 接続が停滞する問題を修正しました。(#1531 )
  • 1 つのバッチが Sync を挟まずに Parse メッセージと Close メッセージを混ぜる場合に、プリペアドステートメントの応答が誤った順序で送信される問題を修正しました。(#1555 )
  • track_extra_parameters にリストされているパラメータのうちサーバーが報告しないものが、クライアントがスタートアップパケットで設定した場合に不正な動作を引き起こす問題を修正しました。(#1576 )
  • サーバーがログインパケットを複数の TCP パケットに分割する場合（例えば、PgBouncer と PostgreSQL の間にもう 1 つプロキシがある場合）にログインに失敗する問題を修正しました。(#1446 )
  • 実行中のクエリがない場合に query_timeout が接続を閉じる問題を修正しました。(#1395 )
  • すぐに利用可能なサーバーが存在しない場合に、NegotiateProtocolVersion メッセージを重複して送信する問題を修正しました。(#1460 )
  • SHOW USERS の pool_size 列が、設定されていないユーザーに対して値を表示する問題を修正しました。(#1489 )
  • ENABLE 管理コマンドのエラーメッセージを修正しました。(#1308 )
  • struct asn1_string_st を不透明にする将来の OpenSSL バージョンに対するコンパイルを修正しました。(#1440 )
  • スタック上の機密性の高い暗号データの消去が、コンパイラの最適化によって除去されないようにしました。(#1508 )
  • Windows で clang を使用した pgbevent.dll のリンクを修正しました。(#1571 )
  • リリース tarball 内のルートレベルのファイルのパスを修正しました。これらは pgbouncer-X.Y.Z/configure ではなく pgbouncer-X.Y.Z/./configure として格納されていました。(#1549 )
  • 設定から track_extra_parameters を読み込む際のメモリリークを修正しました。(#1510 )
  • プロトコル拡張パラメータ（_pq_. プレフィックス）を含むスタートアップパケットごとのメモリリークを修正しました。これは、認証されていないクライアントによって引き起こすことができました。(#1540 )

PgBouncer 1.25.x

2026-05-08 - PgBouncer 1.25.2 - 「不確実性に満ちたタイトル争いに、新鮮な一撃が加わる」

• セキュリティ

  • CVE-2026-6664 の修正：1.25.2 より前の PgBouncer には、ネットワークパケット解析コードに整数オーバーフローがあり、境界チェックを回避してクラッシュを引き起こす可能性がありました。認証されていないリモート攻撃者は、不正な SCRAM 認証パケットを送信することで PgBouncer をクラッシュさせることができました。
  • CVE-2026-6665 の修正：1.25.2 より前の PgBouncer の SCRAM コードは、SCRAM client-final-message の内容を構築する際に strlcat() の戻り値を正しくチェックしていませんでした。悪意あるバックエンドが長い nonce を含む SCRAM server-final-message を送信すると、スタックオーバーフローを引き起こす可能性がありました。
  • CVE-2026-6666 の修正：1.25.2 より前の PgBouncer では、サーバーが SQLSTATE フィールドを含まないエラー応答を送信した場合に、NULL ポインタ参照によるクラッシュが発生する可能性がありました。
  • CVE-2026-6667 の修正：1.25.2 より前の PgBouncer では、KILL_CLIENT 管理コマンドに対する適切な権限チェックが行われていませんでした。管理コンソール（コンソール自体へのアクセスにも認可が必要です）にアクセスできるすべてのユーザーがこのコマンドを実行できました。このコマンドは、admin_users パラメータにリストされたユーザーにのみ許可されるべきでした。

• 修正

  • default_pool_size パラメータのドキュメントを明確にしました。
  • client_tls13_ciphers および server_tls13_ciphers のドキュメントを修正しました。

2025-12-03 - PgBouncer 1.25.1 - 「クリスマス前に多数のバグを修正」

• セキュリティ

  • CVE-2025-12819 の修正：このリリース以前は、認証中に悪意ある search_path パラメータを StartupMessage で提供することで、未認証の攻撃者が任意の SQL を実行できる可能性がありました。次のすべての設定を有するシステムは脆弱です：

    1. track_extra_parameters には search_path が含まれます（非デフォルトの設定で、おそらく Citus または PostgreSQL 18 を使用する設定でのみ構成されています）
    2. auth_user が空でない文字列に設定されている（デフォルト以外の設定）
    3. auth_query は完全修飾オブジェクト名を指定せずに設定されています（デフォルト設定、< 演算子はスキーマ修飾されていない）

• 修正

  • 1.25.0 で導入された、サーバーへの再接続後に一時的な SCRAM 認証で発生するエラーを修正しました (#1432 )
  • SIMD 対応なしの特殊アーキテクチャ向けに欠落している typedef を追加しました（#1414 、1.25.0 で導入）
  • クライアントがデータを送信する前に接続を閉じた場合のノイズとなる警告ログを削除する（#1420 、1.25.0 で導入）
  • NULL ポインタ参照の可能性を防止します（#1423 、1.25.0 で導入）
  • 1.25.0 で導入された潜在的なメモリリークを修正しました (#1422 )
  • SCRAM のサーバーメッセージ解析を修正しました（#1431 、1.25.0 で導入）

2025-11-09 - PgBouncer 1.25.0 - 「LDAPサポート付きのバージョン」

• 機能
  • LDAP 認証を追加しました！HBA ファイルまたは auth_ldap_options を使用して設定できます。(#731 )
  • クライアント側の直接TLS接続をサポートしました。これにより、PostgreSQL 17で導入されたより高速なTLS接続セットアップがクライアントで利用可能になります。PgBouncerは現在、このより高速な接続セットアップを使用してPostgreSQLサーバーに接続することはできません。(#1359 )
  • クライアント接続のアイドル状態を SHOW CLIENTS に追加します。 (#1191 )
  • transaction_timeout の設定を、グローバルおよびユーザー単位で追加します。(#1242 )
  • 5 秒以上接続を受け取らずにキューに積まれた場合、クライアントに NOTICE メッセージを送信します。この期間は query_wait_notify を使用して変更または無効化できます。(#1264 )
  • 認証の速度を向上させるためにセキュリティを犠牲にすることができるよう、scram_iterations 設定を追加しました (#1339 )
  • TLSv1.3 の暗号スイートを有効にするために、client_tls13_ciphers および server_tls13_ciphers を指定します。(#1352 )
• 変更点
  • 一時的な SCRAM 認証のパフォーマンスを大幅に向上。(#1338 )
  • KILL をデータベース指定なしで実行できるようにしました。この場合、すべてのデータベースに対して KILL を実行します。(#1317 )
  • ヘルスチェッククエリは、SELECT 1ではなく空のクエリを送信するようにデフォルトで設定されています。 (#1233 )
  • PAMキューが満杯になったことを警告としてログ出力する。これにより、この原因で遅延が発生しているクエリの原因を特定しやすくなる。(#1297 )
  • RELOAD コマンドは、再読み込み中に発生したエラーを報告するようになりました。(#1231 )
  • シャットダウン中に管理者接続用に PgBouncer の UNIX ソケットへのアクセスを有効化します。これにより、オペレーターが PgBouncer プロセスがシャットダウンしない原因を確認しやすくなり、スタックした接続に対して手動で KILL_CLIENT を実行できるようになります。(#1305 )
  • mkauth.py を、廃止された第三フィールドを追加しないように変更しました (#1365 )
  • FATAL メッセージを disconnect_client および disconnect_server 関数で改善しました。 (#1382 )
  • 非推奨となった OpenSSL 関数 EVP_PKEY_get0_EC_KEY の使用を停止しました。この関数は特定の FIPS 実装で問題を引き起こす可能性がありました。(#1384 )
• 修正内容
  • 長さ 1024 文字以上のパスワードを含むクラッシュを修正しました。(#1215 )
  • 複数ホスト接続を server_tls_sslmode=verify-full を使用する際に修正しました。 (#1303 )
  • キャンセル要求を転送する際の稀な FATAL エラーを修正しました。(#1383 )
  • パラメータの並べ替えを SHOW CONFIG で修正しました。(#1403 )
  • スタートアップパケットの解析を強化します。(#1407 )

PgBouncer 1.24.x

2025-04-16 - PgBouncer 1.24.1 - “CVE-2025-2291 VALID UNTIL yesterday”

• セキュリティ

  • CVE-2025-2291 の修正：以前、PgBouncer は auth_query を使用してパスワードハッシュを照会する際に、ユーザーのパスワードの VALID UNTIL を考慮していませんでした。したがって、Postgres の前に透明なプロキシとして PgBouncer を使用している場合、すでに有効期限が切れたパスワードが許可される可能性がありました。この問題を解決するため、デフォルトの auth_query およびドキュメント内のカスタム auth_query 関数の例が、VALID UNTIL を考慮するように変更されました。カスタム auth_query を使用している場合は、それに合わせて更新してください。デフォルトの auth_query を使用している場合、PgBouncer 1.24.1 にアップグレードするか、以前のバージョンの PgBouncer で設定を変更して新しいデフォルトの auth_query を使用できます。

• 修正

  • HBA ファイル内の pam 認証サポートを元に戻すことで、PAM サポートを修正しました。(#1291 ) (1.24.0 で導入されたバグ)
  • ユーザ接続数を減算する際のバグを修正しました。この修正は GitHub のタグ 1.24.0 に含まれていましたが、リリース用の tarball にはこの修正が含まれていませんでした。 (#1238 ) (1.24.0 で導入されたバグ)
  • test_load_balance_hosts.py をリリース tarball に追加しました。(#1282 )
  • テストの問題を修正し、Debian パッケージャーがテストを実行できるようにします。(#1266 , #1250 )

• ドキュメント

  • auth_query で安全な search_path を設定する例を更新しました。(#1245 )

2025-01-10 - PgBouncer 1.24.0 - “New year, new bouncer”

• 機能

  • systemd 用に Type=notify-reload をサポート。この機能には systemd バージョン 253 以降が必要です。(#1148 )
  • 管理コンソールに KILL_CLIENT コマンドを追加します。これにより、クライアント接続を強制的に終了できます。(#1147 )
  • max_user_client_connections 設定を、グローバルおよびユーザー単位で追加します。(#1137 )
  • max_db_client_connections 設定を、グローバルレベルおよびデータベースレベルで追加します。(#1138 )
  • current_client_connectionsカウンタをSHOW USERSおよびSHOW DATABASESの出力に追加します。(#1137 , #1138 )
  • ホスト間のロードバランシングを行わないことをサポートするための load_balance_hosts パラメータを追加します。(#736 )
  • プリペアドステートメントの使用カウンタを SHOW STATS で公開します。(#1192 )
  • client_idle_timeout 設定を追加します。(#1189 )
  • ユーザーレベルで query_timeout および reserve_pool_size を追加します。 (#1180 , #1228 )
  • HBA ファイルで pam 認証サポートを有効化します。(#326 )

• 変更

  • TLS 設定が変更されていない場合、RELOAD で接続を切断して作り直さないようにしました。以前は、TLS 接続がある場合、RELOAD によってすべての接続が作り直され、一時的ながら深刻なパフォーマンス低下を引き起こす可能性がありました。現在は、TLS 設定が実際に変更された場合にのみ、接続を作り直します。(#1157 )
  • プリペアドステートメントのサポートをデフォルトで有効化し、max_prepared_statements のデフォルト値は 200 に設定されました。このデフォルト値の変更は、実際にプリペアドステートメントを使用するクライアントにのみ影響します。プリペアドステートメントを使用する場合は、ドキュメント でプリペアドステートメントサポートの制限事項について確認することを推奨します (#1144 )
  • ソケット/クライアント/サーバーは、管理者出力で一意の ID で識別できるようになりました。以前はポインタで識別されていましたが、切断後に新しいクライアントがそのポインタを再利用することがよくありました。(#1172 )
  • pidfile が空の場合のエラーを明確にしました。(#1195 )
  • クライアントに server_login_retry の障害発生時に元のエラーを返します。(#1152 )
  • エラーが auth_query から発生した場合、元のサーバーのエラーをログに記録します。 (#1187 )
  • default_pool_size を 0 に設定すると、サイズ制限なしになります。(#1227 )
  • データベース用の reserve_pool 設定の名前を reserve_pool_size に変更します。以前の名前は新しい名前の別名として引き続き使用可能です。(#1232 )

• 修正

  • メモリ不足（OOM）エラーを含む、まれなエラー状況をより適切に処理するように改善しました。これにより、以前はクラッシュやメモリリークを引き起こしていた状況が軽減されました。(#1108 , #1101 , #1099 , #1169 , #1202 )
  • サンプル構成ファイルにおける server_tls_sslmode のデフォルト値を修正。(#1133 )
  • ドキュメントから無効なエイリアスについての記述を削除しました。(server_tls_protocols)#1155
  • auth_query とレプリケーション接続を併用する際に発生するバグを修正しました。このバグにより、このような設定で接続エラーが発生していました。(#1166 )
  • PgBouncer がサーバー設定を構成している間、クライアントのキャンセル要求を無視します。 (#298 )

PgBouncer 1.23.x

2024-08-02 - PgBouncer 1.23.1 - 「すべてが整然と戻された」

• 修正
  • PgBouncer が設定を再読み込みした後に発生する可能性のあるセグメンテーションフォールトを修正しました。(#1105 ) (1.23.0 で導入されたバグ)
  • 既知の put_in_order のクラッシュをすべて修正しました。(#1120 ) (1.23.0 で新たなクラッシュが導入されました)
  • テストに必要なファイルをリリース tarball に追加しました。 (#1124 ) (これらのファイルは 1.23.0 で導入されました)

2024-07-03 - PgBouncer 1.23.0 - “Into the new beginnings”

• 機能

  • ローリング再起動のサポートを追加しました。SIGTERM はもはや PgBouncer プロセスの即時シャットダウンを引き起こしなくなりました。代わりに「スーパー安全シャットダウン」を実行します。すべてのクライアントが切断されるのを待ってからシャットダウンを行います。新しい SIGTERM の振る舞いにより、ロードバランサーの背後にある複数の PgBouncer プロセスのローリング再起動、または so_reuseport で同じポートをリッスンしている場合の再起動が可能になります。これは マイナーな破壊的変更 です。Dockerfile や Systemd サービスファイルで旧来の SIGTERM の振る舞いに依存していた場合は、今後は SIGQUIT を使用する必要があります。(#902 )
  • certおよびpeer認証方法に対するユーザー名マップのサポートを追加しました。 この機能により、接続を開始するユーザーがデータベースユーザーでなくてもよい柔軟性が得られます。 PgBouncerのユーザー名マップサポートは、ドキュメントに記載された例外を除き、PostgreSQLとほぼ同じ動作をします。(#996 )
  • PgBouncer を介したレプリケーション接続のサポートを追加しました。(#876 )

• 変更

  • SHOW USERS の出力の接続一覧を改善しました。(#1040 )
  • ユーザーごとの pool_size 設定を許可します。(#1049 )
  • データベースごとに server_lifetime 設定を許可する。(#1057 )
  • SHOW USERS の出力で動的に作成されたユーザーを一覧表示する機能を追加しました。(#1052 )
  • HBA 設定で all アドレス型のサポートを追加しました。(#1078 )
  • systemd を使用する際の自動再起動をサポートする。(#1080 )
  • c-ares の最低バージョン要件を 1.9.0 に引き上げる (#1076 )

• 修正

  • 大容量および部分的なスタートアップパケットの処理に関する問題を修正しました。(#1058 )
  • 起動パラメータの options に --config=value 形式のサポートを追加します。(#1064 )
  • avg_wait_timeのメトリクス計算を修正しました。(#727 )
  • クライアントとの間で PostgreSQL プロトコルバージョンをネゴシエーションするサポートを追加しました。(#1007 )
  • auth_query の保留中リクエストを追加しました。(#1034 )
  • ドキュメントおよびCIの改善を複数実施。

PgBouncer 1.22.x

2024-03-04 - PgBouncer 1.22.1 - 「バンガロールでは夏だ」

• 修正
  • クライアントが COPY FROM STDIN クエリを使用することによって引き起こされる問題を修正します。このようなクエリはメモリリーク、パフォーマンスの低下、およびプリペアドステートメントの不具合を引き起こす可能性があります。(#1025 ) (1.21.0 で導入されたバグ)
  • リリース用tarボールに欠落しているテストを追加しました (#1026 ) (欠落していたテストは 1.19.0 および 1.21.0 で導入されました)

2024-01-31 - PgBouncer 1.22.0 - “DEALLOCATE ALL”

• 機能

  • max_prepared_statements が非ゼロ値に設定されている場合に DEALLOCATE ALL および DISCARD ALL をサポートしました（通常の DEALLOCATE は依然として非対応）(#972 )
  • データベースごとに auth_query の設定をサポートしています (#979 )

• 変更

  • 推奨される systemd ユニットファイル内の設定を改善しました (#983 )
  • 失敗を速やかに処理するロジックを、データベースへの接続がすべて失われていて、新たに接続できなくなった状況をすべて処理するように修正しました (#998 )
  • 複数のドキュメント改善

• 修正

  • トランザクションごとに PG14+ が SET DateStyle='ISO' を送信する問題を修正しました (#879 )
  • 空の application_name の処理を修正しました (#999 )
  • Windows で OpenSSL 3.2.0 を使用したビルドを修正しました (#1009 )

PgBouncer 1.21.x

2023-10-16 - PgBouncer 1.21.0 - 「プリペアドステートメント対応版」

• 機能

  • プロトコルレベルの名前付きプリペアドステートメントをサポートしました！これは PgBouncer で最も要望の多かった機能の一つです。プリペアドステートメントを PgBouncer と併用することで、システムの CPU 負荷を大幅に削減できます（PgBouncer 側および PostgreSQL 側の両方で）。合成ベンチマークでは、ワークロードによってはクエリスループットを 15% から 250% まで向上させることが確認されています。この新機能の恩恵を受けるには、新しい max_prepared_statements 設定を 0 以外の値に変更する必要があります（正確な値はワークロードによりますが、100 が妥当な値である可能性があります）。この機能の動作方法、制限事項、および値のチューニング方法については、max_prepared_statements のドキュメントを参照してください。設定後は、クライアントライブラリが実際にプリペアドステートメントを使用していることを確認する必要があります。その方法は各クライアントごとに異なりますので、使用しているクライアントのドキュメントを確認してください。この機能はリリース前に十分なテストを実施していますが、機能の複雑さからパフォーマンス上の問題やバグが存在する可能性は十分にあります。そのような問題を発見した場合は、報告してください。(#845 )

• 変更

  • OpenSSL の設定のセキュリティを向上させました。従来のデフォルト値は非常に古く、不適切でした。 このリリースでは、デフォルト値を、PgBouncer を実行しているシステムの OpenSSL のデフォルト値と同一にしました。(#948 & libusual/#41 )
  • PgBouncer は、可能な限り OpenSSL を使用して MD5 ハッシュを計算するようになりました。これは PgBouncer を FIPS 準拠の方法で使用するために必要です。(#949 )
  • クライアントが接続されていなくても、強制ユーザーを設定したプールに対しては min_pool_size を維持する (#947 )
  • PgBouncer がキャンセルトークンに peer_id をエンコードする方法が変更されたため、バージョン 1.21.0 の境界をまたぐ異なる PgBouncer バージョン間でのピアリングは、すべてのバージョンが同じ側にない限り動作しません。(#945 )

• 修正

  • 1.18.0 で導入されたバグにより、エラーメッセージ “FATAL in function client_proto(): bad client state: 6/7” が発生する問題を修正しました (#928 )
  • 1.18.0 で導入されたバグにより、エラーメッセージ “FATAL in function server_proto(): server in bad state: 11” が発生する問題を修正しました (#927 )
  • キャンセル送信のログレベルを低減する (#903 )
  • peers のログプレフィックスを slog で修正 (#922 )
  • ドキュメントのタイポを修正しました (#932 )
  • 静的解析器が指摘したエラーを修正しました (#943 )
  • ログイン中に一時的な FATAL エラーが発生しても、待機中のすべてのクライアントを終了しないようにする (#946 )
  • auth_dbname のデータベースが明示的に設定されていない場合、自動データベースを使用する。 (#921 )

• クリーンアップ

  • udns のサポートを削除しました (#938 )

PgBouncer 1.20.x

2023-08-09 - PgBouncer 1.20.1 - 「オプションの設定」

• 修正
  • リグレッションを修正しました。options を ignore_startup_parameters 内に配置した場合、options スタートアップパラメータ内の未知のパラメータが無視されなくなっていました（リグレッションは 1.20.0 で導入）。(#908 )
  • ドキュメント内の誤ったタイプミスを修正しました (#917 )

2023-07-20 - PgBouncer 1.20.0 - “A funny name goes here”

• 非推奨事項

  • オンライン再起動オプションはもはや非推奨とされています。近年はほとんど開発が行われていません。この機能には複数の既知の問題があり、新しく追加された機能の多くはこれをサポートしていません。現在、オンライン再起動を行う推奨方法は、so_reuseport および peers 機能を使用することです。これにより、同じポート上で複数の異なる PgBouncer プロセスを実行できます。その後、これらのプロセスを1つずつ再起動することで、常に目的のポートで PgBouncer プロセスがリスニングしていることを保証できます。(#894 )

• 機能

  • トランザクションプーリングモードでより多くのパラメータを追跡できるようにする track_extra_parameters を導入しました。以前は PgBouncer は application_name、DateStyle、TimeZone および standard_conforming_strings のみを追跡していました。現在はデフォルトで IntervalStyle も追跡するようになっています。また、track_extra_parameters を変更することで、さらに多くの設定を追跡できますが、PostgreSQL がクライアントに報告するもの に限られます。Citus 12.0+ を使用している場合、Citus が PostgreSQL が search_path をクライアントに報告するよう保証します。したがって、Citus を使用する場合は search_path を track_extra_parameters 設定に追加できます。(#867 )
  • 認証フェーズで SQLSTATE を転送する。これにより、データベースが存在しないことを検出可能となり、Npgsql（PostgreSQL の .NET データプロバイダ）で利用される。(#814 )
  • デフォルト server_tls_sslmode を prefer に変更します。 (#866 )
  • options スタートアップパラメータをサポートしました。これにより、psql および libpq が認識する PGOPTIONS 環境変数 を使用できるようになります。この変数を使用することで、起動時に任意の PostgreSQL パラメータを設定できます。これは track_extra_parameters を通じて PgBouncer が追跡する PostgreSQL パラメータに限られます。(#878 )

• 修正

  • pgbouncer が auth_dbname として使用された場合にクラッシュしないようにしました。まだサポートされていませんが、クラッシュする代わりに明確なエラーが表示されるようになりました。(#817 )
  • peer_cache の名前を SHOW MEM で修正しました。以前は db_cache として正しく表示されていませんでした。(#864 )
  • ログ内のソース/宛先の混同を修正しました。PgBouncer は宛先IPを意図していたのに、ソースIPをログに記録していました。(#880 )
  • UNIX ソケット経由の管理者接続ログは、log_connections が 1 に設定されている場合にのみ出力する。 (#883 )

PgBouncer 1.19.x

2023-05-31 - PgBouncer 1.19.1 - “Sunny Spring”

これは最近導入されたバグを修正するマイナーリリースです：

• 修正
  • “FATAL in function disconnect_client(): bad client state: 0” エラーを修正しました。(#846 ) (1.18.0 で導入されたバグ)
  • “FATAL in function server_proto(): server in bad state: 14” エラーを修正しました。(#849 ) (1.18.0 で導入されたバグ)
  • Python によるテストの実行に必要なファイルをリリース tarball に追加しました (#852 ) (1.19.0 で導入された新しいテスト)

2023-05-04 - PgBouncer 1.19.0 - 「昔ながらの、人間が手作業で生成するタイプ」

• 機能

  • に auth_dbname オプションを追加し、auth_query を実行する対象のデータベースを指定します。(#764 )
  • SHOW STATE コマンドを追加し、PgBouncer がアクティブ、一時停止（paused）、サスペンド（suspended）のいずれの状態かを表示します。(#528 )
  • PgBouncer プロセス間のピアリングをサポートしました。これにより、複数の異なる PgBouncer プロセスが単一のロードバランサーの背後にある場合でも、キャンセル要求が正常に動作し続けるように設定できるようになります。(#666 )
  • 専用の cancel_wait_timeout 設定を追加し、キャンセル要求の転送を放棄するまでの時間を決定します。デフォルトは 10 秒です。(#833 )
  • 新しいテストフレームワーク (#792 )

• 修正

  • TLSハンドシェイクの失敗時に可能性のあるメモリリークを修正しました。(#796 )
  • Windows でのサポートされていないコマンドラインオプションに対して、より正確なエラーメッセージを表示する。(#620 )
  • サーバーが BEING_CANCELED 状態にあるときに disconnect_server を呼び出す問題を修正しました。 (#815 ) (1.18.0 で導入)
  • SIGTERM を受信しても非ゼロのステータスで終了しないようになりました。(#834 )
  • 起動時に unix_socket_dir でソケットの作成に失敗した場合は、強制的に終了する。 (#830 )
  • 起動時に listen_addr のアドレスのいずれもリスンできなかった場合、強制的に失敗する。 (#838 )
  • sbuf_connect が失敗したときに、より詳細な情報を持つ警告メッセージを出力する。特に Unix ソケットの作成に失敗した際に有用である。(#837 )

• クリーンアップ

  • パフォーマンス向上のための各種 CI の更新
  • AppVeyor を削除

PgBouncer 1.18.x

2022-12-12 - PgBouncer 1.18.0 - 「実に明白なこと」

• 機能

  • application_name を SHOW CLIENTS/SERVERS/SOCKETS に追加 出力 (#449 )
  • キャンセル要求に関する情報を SHOW CLIENTS/SERVERS/POOLS 出力に追加 (#782 )

• 修正

  • 宛先ソケットが閉じられている場合、sbuf_send_pending 操作を失敗させる (#652 )
  • いくつかの可能性のあるクラッシュを修正 (#700 、 #730 )
  • コンマ区切りホストリスト機能におけるオーバーフローバグの修正により、 接続がUnixソケットに再ルーティングされる問題が解消されました (#747 )
  • min_pool_size を達成するために接続をエビクトしないようになりました (#648 )
  • PostgreSQL 15 での SHOW HELP の修正 (#769 )
  • クライアントのクエリキャンセル処理におけるレースコンディションを修正しました。 あるクライアントのクエリキャンセル要求が、別のクライアントのクエリをキャンセルする可能性がありました。 これは、PgBouncer がクエリのキャンセルを意図していたクライアントのクエリがすでに自身で完了していた場合に発生する可能性がありました。 (#717 )

• クリーンアップ

  • さまざまな CI の更新

PgBouncer 1.17.x

2022-03-23 - PgBouncer 1.17.0 - 「一線が引かれた」

• 機能

  • データベース定義では、コンマ区切りのホストリストを指定できます。 ホストはラウンドロビン方式で接続されます。
  • 存在しないデータベースに接続する場合、エラー（“no such database”）が認証後に報告されるようになりました。これにより、認証されていないクライアントが存在するデータベースを調べるのを防ぎます。（これはバージョン 1.15.0 でユーザーが存在しない場合に認証後にエラーを報告する変更と同様です。）
  • ログイン前にクライアントにサーバー切断エラーを送信しないでください。 これは、ログインしていないクライアントに、設定情報など公開されていない情報を漏らす可能性があります。
  • パスワード長を再度最大値に増加します。明らかに、前回の増加では長期間にわたって十分ではなかったようです。
  • 自動的な auth_file 再読み込みを削除しました。auth_file は設定ファイルの再読み込み時にのみ再読み込みされるようになり、変更された直後に自動的に再読み込みされることはなくなりました。
  • Windows ビルドには、バージョン情報リソースファイルが含まれるようになりました。
  • CI で作成された Windows ビルドは静的リンクされるようになったため、依存関係なしで直接使用できます。

• 修正

  • OpenSSL 3 のサポートが修正されました。以前のリリースではクラッシュしていました。
  • 接続時に迅速な失敗を適用しない。これは、認証前にサーバーのエラーを報告しないという前述の変更の一部である。また、SCRAM パススルー認証における特定の状況を修正する。この状況では、クライアント側の認証交信を許可して、再認証によりサーバー側の接続を修正できるようにする必要がある。迅速な失敗メカニズムは認証直後には依然として適用されるため、ほとんどの状況では実際の観察される動作は同じになる。
  • サンプル pgbouncer.ini における auth_type を md5 に変更し、組み込みのデフォルトと一致させます。このファイルをデフォルトの設定ファイルとして展開する場合があるため、変更後の設定がご自身の環境に適しているか確認してください。
  • アサート有効ビルドでの終了時クラッシュを修正。
  • tcp_defer_accept のドキュメントおよび動作を改善しました。 デフォルト値についてのドキュメントは誤りがあり、誤解を招く内容でした。 一部のケースでは、「show config」で誤った値が表示されていました。 また、設定はされているがサポートされていない場合、無視するのではなくエラーを発生させるようにしました。 これは、他のプラットフォーム固有のソケットオプションと同様の処理です。
  • Windows での c-ares によるビルドを修正。Windows では c-ares >=1.18.0 が必須になりました。

• クリーンアップ

  • Autoconf 2.70 以降の大部分の非推奨警告が削除されました。古い Autoconf のバージョンも引き続きサポートされています。
  • Cirrus CI の利用が、より多くのプラットフォームに拡張されました。
  • Travis CI のサポートは削除されました。
  • デフォルトのルートCAファイルを検索する場所を更新し、Fedora/RHEL/CentOSなど、より多くのプラットフォームをカバーする。
  • Python スクリプトはすべて、デフォルトで python3 を使用するようになりました。Python 2 互換性はもはや維持されません。
  • テストスクリプトは、非推奨となった which の代わりに command -v を使用しています。
  • いくつかのエラーメッセージを再構成し、それらがどのコマンドや設定項目に関連しているかが明確になるようにしました。
  • テストスクリプトはもはや GNU sed を必要としなくなりました。
  • make check は Windows でも動作します（ただし SSL テストスイートはまだ対応していません）。
  • 管理コンソールがシンプルなクエリプロトコルのみをサポートすることをドキュメント化し、この点に関するより良いエラーメッセージを提供するようになりました。

PgBouncer 1.16.x

2021-11-11 - PgBouncer 1.16.1 - 「静かさの効率性に対する深さのテスト」

これはセキュリティ修正を含むマイナーリリースです。

• PgBouncer をサーバーとして動作させ、SSL または GSS 暗号化ハンドシェイク後に不要なデータを拒否する。

中間者攻撃者がTCP接続にデータを挿入できる場合、暗号化保護されたデータベースセッションの開始部分に平文データを注入できる可能性があります。この攻撃は、PgBouncerが認証データを要求しない設定の場合に、サーバーに偽のSQLコマンドを送信する目的で悪用される可能性があります。（ただし、SSL 証明書認証に依存する PgBouncer の設定では、認証データを要求しない可能性が十分にあります。）（CVE-2021-3935）

2021-08-09 - PgBouncer 1.16.0 - 「ジャガーを撃退」

• 機能

  • TLS 設定のホットリロードをサポートします。設定ファイルを再読み込みすると、変更された TLS 設定が自動的に有効になります。
  • 抽象的な Unix ドメインソケットをサポート。 Unix ドメインソケットのパスの前に @ を付けることで、抽象名前空間内のソケットを使用できます。 これは PostgreSQL 14 の対応機能と一致します。
  • パスワードとユーザー名の最大長はそれぞれ 996 および 128 に増加されました。さまざまなクラウドサービスでこの要件が求められます。
  • データベースごとに最小プールサイズを設定できるようになりました。これは通常のプールサイズおよび予約プールサイズと同様です。
  • 保留中のクエリキャンセルの数は SHOW POOLS に表示されます。

• 修正

  • 設定パースでは、多くの場所でより厳密なエラー処理が導入されました。以前はエラーをログに記録して続行していた場所でも、設定エラーは現在、起動失敗を引き起こすようになっています。これは常にそうすべきだったはずですが、一部のコードでは正しく処理されていませんでした。一部のユーザーは、これまでずっと不正な設定を使用していたことに気づき、もはや動作しなくなるかもしれません。
  • クエリのキャンセル処理が修正されました。一部の状況下では、キャンセル要求が長時間スタックするように見えました。これにより、もはや発生しなくなります。実際、キャンセル要求はプールサイズの2倍まで超過可能となり、スタックする心配はほとんどありません。 (#542 , #543 )
  • HBA を介した md5 と scram の混在使用が修正されました。
  • Windows での c-ares を使用したビルドが修正されました。
  • “FIXME: query end, but query_start == 0” メッセージは解消されました。発生原因が判明し、これ以上表示されないはずです。(#565 )
  • default_pool_size、min_pool_size、reserve_pool_size の再読み込みを修正しました。これらの設定の再読み込みは以前は機能していませんでした。

• クリーンアップ

  • Cirrus CI が Travis CI の代わりに 使用 されるようになりました。
  • 通常通り、多数のテストが追加されています。
  • 「unclean server」のログメッセージを少し明確にしました。現在は「client disconnect while server was not ready」（サーバーが準備できていない間にクライアントが切断）または「client disconnect before everything was sent to the server」（すべてのデータがサーバーに送られる前にクライアントが切断）と表示されます。前者は、サーバーでトランザクションブロックが開いている状態でクライアント接続が閉じられた場合に発生し、一部のユーザーを混乱させていました。
  • 「pgbouncer」をデータベース名として使用できなくなりました。この名前は管理コンソール用に予約されており、通常のデータベース名として使用しても正しく動作していませんでした。これにより、明示的に禁止されています。
  • 接続が閉じられる前にクライアントに送信されるエラーは、もはや単に ERROR ではなく FATAL としてラベル付けされるようになりました。これにより、一部のクライアントが以前は混乱していた問題が解消されました。 (#564 )
  • GCC 11 でのコンパイラ警告を修正しました。 (#623 )

PgBouncer 1.15.x

2020-11-19 - PgBouncer 1.15.0 - “Ich hab noch einen Koffer in Berlin”

• 機能

  • 認証失敗の報告を改善しました。認証失敗のメッセージはクライアントに送信される際、失敗したことを示すのみで、詳細は含まれません。詳細は PgBouncer のログで確認できます。また、要求されたユーザーが存在しない場合でも、認証処理は終了まで実行され、同じ汎用的な失敗メッセージになります。これにより、クライアントが PgBouncer インスタンスに対してユーザー名や認証関連の情報を探るのを防ぎます。これは PostgreSQL の動作と同様です。
  • クライアントが即座に切断された場合、何もログに出力しない。モニタリングシステムがTCP/IP接続を開くだけで、データを送信せずに切断する場合にログの雑多な出力を防ぐためである。
  • systemd ジャーナルが使用されている場合は、ログ出力にそれを利用します。標準エラー出力が systemd ジャーナルに送信されることが検出された場合、ログ出力に systemd のネイティブ関数を使用します。これにより、タイムスタンプや PID の重複出力が回避され、ログが若干きれいになります。また、ログに重大度などのメタデータが追加されるため、ジャーナルが syslog に転送された場合でも、メッセージに有用なメタデータが付与されます。
  • テストスイートの一部は Windows でも実行できるようになりました。
  • SHOW CONFIG は設定のデフォルト値も表示するようになりました。

• 修正

  • FreeBSD で so_reuseport オプションを修正しました。PgBouncer 1.12.0 の元のコードは FreeBSD では実際に動作していませんでした。 (#504 )
  • 古い systemd バージョンを搭載したシステムでのコンパイルを修復しました。これは 1.14.0 で壊れていました。 (#505 )
  • Windows用バイナリzipパッケージをビルドするmakefileターゲットを修復しました。
  • 長いコマンドラインオプションも Windows で動作するようになりました。
  • auth_user 設定の動作を修正しました。従来の動作は、設定ファイル内の順序に依存していたため、混乱しやすく脆弱でした。これ以上はそのような状態にはなりません。(#391 , #393 )

• クリーンアップ

  • テストの安定性と移植性を向上させます。
  • Autoconf 関連のコードを現代化する。
  • OpenSSL 3.0.0 からの非推奨コンパイラ警告を無効化します。

PgBouncer 1.14.x

2020-06-11 - PgBouncer 1.14.0 - “La ritrovata magia”

• 機能

  • SCRAM 認証のパススルーを追加します。これにより、PgBouncer 内で userlist.txt または auth_query から取得した暗号化された SCRAM シークレットを使用してサーバーにログインできます。
  • systemd のソケット活性化をサポートしました。これは、/var/run/postgresql へのアクセスが制限されているシステムで、systemd が Unix ドメインソケットの作成を担当する場合に特に有用です。
  • Windows で Unix ドメインソケットのサポートを追加。

• クリーンアップ

  • テストまたはデプロイ用に、代替の小さな設定ファイルを追加します。 pgbouncer-minimal.ini

PgBouncer 1.13.x

2020-04-27 - PgBouncer 1.13.0 - “My favourite game”

• 機能

  • 設定キーワード tcp_user_timeout を追加し、対応するソケットオプションを設定します。
  • client_tls_protocols および server_tls_protocols のデフォルトが secure となり、TLS 1.2 および TLS 1.3 のみが有効になります。古いバージョンは引き続きサポートされていますが、デフォルトでは有効になっていません。
  • systemd サービス通知をサポートする。現在のところ、これにより Type=notify サービスユニットの使用が可能である。今後、より深い統合が計画されている。

• 修正

  • 複数行のログメッセージを修正 (libusual #24 )
  • auth_query から返される null ユーザ名を適切に処理する (#340 )

• クリーンアップ

  • debian にある Debian パッケージファイルは削除されました。 https://apt.postgresql.org/ . からのパッケージを使用することを推奨します。
  • テストスイートにおける多数の修正と改善
  • テストはもはやデフォルトで sudo を使用しようとしません。この機能は、環境変数 USE_SUDO を設定することで明示的に有効化できます。
  • libevent API の使用が、バージョン 2 形式のインターフェースを採用し、バージョン 1 で非推奨となったインターフェースの使用をやめました。

PgBouncer 1.12.x

2019-10-17 - PgBouncer 1.12.0 - 「学び、より良くなること」

このリリースでは、多数の軽微な機能強化および修正が含まれています。

• 機能

  • SO_REUSEPORT ソケットオプションを有効にする設定を追加します。一部のオペレーティングシステムでは、同じホスト上で同じポートをリッスンする複数の PgBouncer インスタンスを実行可能となり、カーネルが接続を自動的に分散します。
  • OS とは別個の resolv.conf ファイルを使用する設定を追加します。これにより、カスタムの DNS サーバーおよび他の DNS オプションを設定できます。
  • SHOW VERSION の出力を通常の結果行として送信し、NOTICE メッセージとして送信しない。これにより、出力の利用が容易になり、他の SHOW コマンドと一貫性が保たれる。

• 修正

  • 統計カラムを numeric として送信し、bigint として送信するのを回避します。これにより、bigint の範囲を超える値でクライアントライブラリが失敗するのを防ぎます。(#360 , #401 )
  • PAM ユーザーがパスワードを失う問題を修正しました。 (#285 )
  • SCRAM チャネルバインディングを有効にしたクライアントを受け入れるようになりました。以前は、チャネルバインディングをサポートするクライアント（つまり PostgreSQL 11 以降）が、特定の状況下で PgBouncer への接続に失敗していました（PgBouncer はチャネルバインディングをサポートしていません。この変更は、チャネルバインディングを提供するクライアントのサポートを修正するものです）。
  • musl-libc の最新バージョン（Alpine Linux で使用）とのコンパイルを修正。

• クリーンアップ

  • make check ターゲットを追加しました。これにより、1 つのコマンドからすべてのテストを実行できるようになります。
  • PostgreSQL wiki への参照を削除しました。すべての情報は現在、PgBouncer のドキュメントまたはウェブサイトにあります。
  • Libevent 1.x のサポートを削除しました。Libevent 2.x が必須です。Libevent の検出は現在 pkg-config を使用して行われます。
  • macOS および Windows でのコンパイラ警告を修正しました。これらのプラットフォームでのビルドは、現在警告なしで行えます。
  • LLVM scan-build からの警告を修正。

PgBouncer 1.11.x

2019-08-27 - PgBouncer 1.11.0 - “Instinct for Greatness”

• 機能
  • クライアントおよびサーバーに対する SCRAM 認証のサポートを追加しました。新しい認証タイプ scram-sha-256 が追加されました。
  • 保存されたパスワードが md5 の場合の auth_type=password を、PostgreSQL サーバーと同様に処理するようになりました。(#129 )
  • log_stats を追加して、統計情報をログに出力しないようにします。 (#287 )
  • ログタイムスタンプにタイムゾーンを追加します。
  • ログプレフィックスにPIDを[カッコ]で囲んで出力する。
• 修正内容
  • OpenSSL の configure テストを、-Werror と互換性がある新しい OpenSSL で実行する際に修正します。
  • auth_user における待機時間の計算を修正しました。これにより、待機時間がクラッシュするか、不正な値が報告される問題が解消されました。(#393 )
  • PostgreSQL 12 で追加された GSSENCRequest パケットを処理するようにしました。現在は何も行いませんが、「bad packet header」（不正なパケットヘッダー）という紛らわしいエラーメッセージを回避できます。
• クリーンアップ
  • テストスイートの多数の改善と、いくつかの新規テスト
  • Windows でのコンパイラ警告を複数修正。
  • [users] セクションのドキュメントを拡張し、例の設定ファイルに追加する。 (#330 )

PgBouncer 1.10.x

2019-07-01 - PgBouncer 1.10.0 - “Afraid of the World”

• 機能
  • TLS 1.3 の有効化および無効化をサポートする。 (TLS 1.3 はすでに OpenSSL ライブラリに依存してサポートされていたが、今や TLS プロトコルバージョンを選択する設定項目もこれに対応している。)
• 修正
  • TLS 1.3 のサポートを修正しました。これは OpenSSL 1.1.1 および 1.1.1a で破損していました（それ以前や以降では問題ありません）。
  • SHOW FDS での稀なクラッシュを修正しました (#311 )。
  • 多数のキャンセル要求が到着した場合、長時間の停止が発生する可能性を修正しました (#329 ).
  • PostgreSQL の再読み込み後に「unexpected response from login query」（ログインクエリからの予期しない応答）エラーが発生するのを回避します。 (#220 ).
  • idle_transaction_timeoutの計算を修正 (#125 )。 このバグにより、特定の状況で過剰なタイムアウトが発生していました。
• クリーンアップ
  • さまざまなログおよびエラーメッセージをより明確にします。
  • Coverity で発見された問題を修正しました（実際の運用において重大な影響を及ぼすものはありませんでした）。
  • すべてのテストスクリプトの改善とドキュメント化を実施する。
  • ドキュメントに追加の SHOW コマンドを追加する。
  • ドキュメントを rst から Markdown に変換する。
  • ソースツリー内の Python スクリプトはすべて Python 3 と互換性があります。

PgBouncer 1.9.x

2018-08-13 - PgBouncer 1.9.0 - “Chaos Survival”

• 機能
  • RECONNECT コマンド
  • WAIT_CLOSE コマンド
  • 即時切断 - セッションプールモードで、サーバーが “close_needed”（再接続）モードにある場合、直ちに接続を切断します。
  • SHOW SERVERS に close_needed 列を追加
• 修正
  • parse_filename における二重解放を回避
  • parse_line での NULL ポインタ参照を回避
• クリーンアップ
  • ポート mkauth.py を Python 3 に移行する
  • シグナルのドキュメントを改善
  • クイックスタートドキュメントの改善
  • SET コマンドをドキュメント化
  • 必須ソフトウェアのリストを修正
  • -Wimplicit-fallthrough 警告を修正
  • 各種 SHOW フィールドのドキュメントを追加
  • 再読み込みおよびDNS変更時の再接続動作の説明
  • KILL の実行後には RESUME が必要であることをドキュメント化
  • server_lifetime に関するドキュメントを明確化
  • メッセージおよびドキュメント内のスペルミスと大文字小文字の修正
  • テストでの psql 実行を修正
  • その他のテスト環境設定の改善

PgBouncer 1.8.x

2017-12-20 - PgBouncer 1.8.1 - “Ground-and-pound Mentality”

• 修正
  • ディストリビューションの tar パッケージに include/pam.h を含めるようにした。これにより、1.8 バージョンの tar パッケージがまったくビルドできなくなっていた。

2017-12-19 - PgBouncer 1.8 - “Confident at the Helm”

• 機能
  • PAM 認証をサポートします。 (有効にするには --with-pam を使用してください。)
  • SHOW DATABASES の出力に paused および disabled フィールドを追加します。
  • SHOW POOLS 出力に maxwait_us フィールドを追加します。
  • wait および wait_us フィールドを SHOW コマンドの出力に追加します。
  • 新しいコマンド SHOW STATS_TOTALS と SHOW STATS_AVERAGES を追加します。
  • SHOW STATS でクエリとトランザクションを個別に追跡します。total_requests、avg_req、および avg_query フィールドは、新しいフィールドに置き換えられました。
  • SHOW STATS に wait_time を追加します。
• 修正内容
  • libusual が OpenSSL 1.1 をサポートするようになりました。
  • Unix ソケット上で TLS を使用しようとしないでください。
  • pg_hba.conf を解析する際は、誤った行があってもファイル全体を拒否せず、解析を継続してください。 (#118 )
  • その他の HBA パースの修正。
  • クエリのキャンセル時に競合状態を修正。 (#141 )
• 整備作業
  • auth_user 設定は、データベースごとの設定に加えて、グローバルに指定することも可能になりました。 (#142 )
  • 管理コンソールのクライアントおよびサーバーのエンコーディングを UTF8 に設定します。

PgBouncer 1.7.x

2016-02-26 - PgBouncer 1.7.2 - “Finally Airborne”

• 修正
  • 古い pidfile の削除時にクラッシュする問題を修正。この問題は 1.7.1 で導入された。
  • クリーンアップを無効化 — テイクオーバーを壊し、本番負荷では有用でないため。問題は 1.7.1 で導入。
  • テイクオーバー後は、pidfile が消えるまで待ってから起動します。 メモリクリーンアップによる遅延シャットダウンが、既存のレースを露呈しました。 (#113 )
• クリーンアップ
  • ビルド時に DBGVER の処理を削除して再現性を確保する。 (#112 )
  • Antimake: $(wildcard) から取得したファイルリストを並べ替える。新しい gmake ではもはや並べ替えを行わない。 (#111 )
  • ログに libssl のバージョンを表示します。
  • deb: 完全なハードニングを有効化します。

2016-02-18 - PgBouncer 1.7.1 - 「5人の友人に転送しないと……」

警告： バージョン 1.7 以降、データベースがトランザクションプーリングモードにある場合、server_reset_query は実行されません。この点は 1.7 のリリース通知で十分に強調されていなかったようです。アプリケーションでこの動作に依存している場合、以前の動作を復元するには server_reset_query_always を使用してください。

このリリースの主な作業は、TLS関連のメモリリークを追跡することでしたが、実際にはリークは存在しません。代わりに、Debian/wheezy に組み込まれた libssl には、接続あたり600kのオーバーヘッドがあり（リークはしない）、期待される20〜30kよりも大幅に高いです。TLSを使用する際は、この点に注意が必要です。

• 修正
  • TLS：sslmode の “disabled” を “disable” に名称変更。PostgreSQL が使用している名称に合わせる。
  • TLS: client_tls_sslmode=verify-ca/-full はクライアント証明書のない接続を拒否するようになりました。 (#104 )
  • TLS: client_tls_sslmode=allow/require クライアント証明書の検証を実行する 送信された場合。以前は検証設定が無効だったため、クライアント証明書を用いた接続が失敗していた。 (#105 )
  • データベースを解放する際のメモリリークを修正。
  • tls_handshake() における潜在的なメモリリークを修正。
  • EOF処理を tls_handshake() で修正。
  • memset のサイズが小さすぎる問題を asn1_time_parse 互換性用に修正。
  • TLS 以外の (--without-openssl) ビルドを修正。 (#101 )
  • Windowsビルドに関するさまざまな問題を修正しました。 (#100 )
• 整備作業
  • TLS: 不活性な接続のメモリ使用量を削減するには SSL_MODE_RELEASE_BUFFERS を使用してください。
  • 終了時に割り当てられたメモリをクリーンアップします。メモリリークチェッカーの実行を支援します。
  • server_reset_queryのドキュメントを改善します。 (#110 )
  • TLS オプションをサンプル構成ファイルに追加します。

2015-12-18 - PgBouncer 1.7 - 「復活後に色が変化する」

• 機能
  • TLS 接続をサポートします。バックエンド実装として OpenSSL/LibreSSL が使用されます。
  • TLS クライアント証明書による認証をサポートします。
  • Unix ソケットでの “peer” 認証をサポートします。
  • PostgreSQL と同様に、ホストベースのアクセス制御ファイルをサポートしています。 pg_hba.conf これにより、ネットワーク接続に対する TLS 設定や、ローカル接続に対する “peer” 認証を構成できます。
• クリーンアップ
  • query_wait_timeout のデフォルト値を 120s に設定します。現在のデフォルト値（0）はキューイングを無限に許可するため、実用性がありません。つまり、クライアントが未処理のクエリを保持している状態でサーバー接続に割り当てられていない場合、クライアント接続は切断されます。
  • server_reset_query_always をデフォルトで無効化します。現在、reset クエリはセッションモードにあるプールでのみ使用されます。
  • pkt_buf を 4096 バイトに増加します。TLS との組み合わせでパフォーマンスが向上します。 動作はおそらく負荷に依存しますが、v1.2 以降ではパケットバッファが接続から分離され、プールから遅延して使用されるため、安全に実行できます。
  • パイプライン化されたコマンドの数が、ReadyForQueryパケットの受信を期待している状態をサポートします。 これにより、サーバーが早めに解放されるのを防ぎます。 修正対象：#52 。
  • sbuf_loopcnt のロジックを改善しました。ソケットにイベントがなくても、ソケットの再処理が保証されます。TLS では独自のバッファリングがあるため、この改善が必要です。
  • システムテストを、最新のBSDおよびMacOSで動作するように調整。 (Eric Radman)
  • crypt 認証を削除してください。この認証方式は古く、PostgreSQL 8.4 以降ではサポートされていません。
  • –with-cares の設定オプション（引数なし）を修正 引数なしの設定で動作が不正だったため。

PgBouncer 1.6.x

2015-09-03 - PgBouncer 1.6.1 - “Studio Audience Approves”

• 機能

  • 新しい設定: server_reset_query_always。設定すると、 セッション以外のプールでの server_reset_query の使用を無効化します。 PgBouncer ではプールごとの pool_mode を導入しましたが、 セッションプールとトランザクションプールは同じリセットクエリを使用すべきではありません。 実際、トランザクションプールはリセットクエリを使用すべきではありません。

    1.6.x で設定されていますが、1.7 で無効になります。

• 修正

  • [セキュリティ] auth_user の無効な割当を削除。(#69) auth_user が設定されており、クライアントが存在しないユーザー名を要求した場合、 クライアントは auth_user としてログインする。これは好ましくない。

    CVE-2015-6817

  • handle_auth_response で NoticeResponse をスキップするようにしました。そうしないと、サーバー側の詳細なログレベルがログイン失敗を引き起こします。

  • 管理コンソール: auth_type=any の場合に auth_user を設定するようにしました。そうしないと、ログ出力がクラッシュする可能性があります（#67）。

  • OpenBSD、Solaris、OSX での各種ポータビリティ修正。

2015-08-01 - PgBouncer 1.6 - 「未来のゾンビ」

• 機能

  • ユーザーのパスワードハッシュを PostgreSQL データベースから読み込みます。 新しいパラメータ:

    auth_user データベースに接続し、ユーザー情報を取得するために使用するユーザー。 データベースごとに設定することもできます。

    auth_query auth_user の権限で実行する SQL クエリ。 デフォルト： “SELECT usename, passwd FROM pg_shadow WHERE usename=$1”

    (Cody Cutrer)

  • プールモードは、データベースごとおよびユーザーごとに設定できます。 (Cody Cutrer)

  • データベースおよびユーザーごとの接続制限：max_db_connections および max_user_connections。

  • 新規接続を防止するための DISABLE/ENABLE コマンドを追加します。 (William Grant)

  • 新しいDNSバックエンド: c-ares。すべての有用な機能をサポートする唯一のDNSバックエンドです: /etc/hostsのリフレッシュ、SOA照会、大容量の応答（TCP/EDNS+UDP経由）、IPv6。現在は推奨されるバックエンドであり、将来的には唯一のバックエンドになる可能性が高く、不十分なライブラリの多数をサポートする意義がないためです。

    SNAFU: c-ares バージョン 1.10 以下では、IPv6 を有効にした状態で CNAME サポートが破損するバグがあります。（既に上流で修正済み。） 一時的な対策として、c-ares 1.10 以下では IPv4 のみを使用します。したがって、PgBouncer は c-ares >1.10（まだリリースされていない）が公開されてからしばらく経った後にのみ、他のバックエンドを廃止します。

  • SHOW CLIENTS/SERVERS で remote_pid を表示します。Unix ソケット経由で接続するクライアント、および TCP と Unix ソケットのいずれかで接続するサーバーで利用可能です。TCP サーバーの場合、PID はキャンセルキーから取得されます。

  • 負の DNS キャッシュを制御するための別々の設定パラメータ（dns_nxdomain_ttl）を追加。 (Cody Cutrer)

  • クライアントのホストIPアドレスとポートを application_name に追加します。 これは設定パラメータ application_name_add_host によって有効化され、デフォルトでは ‘off’ です。 (Andrew Dunstan)

  • 設定ファイルには、設定を複数のファイルに分割できるようにする ‘%include FILENAME’ 指令があります。 (Andrew Dunstan)

• クリーンアップ

  • log: IPv6 アドレスを [] で囲む
  • log: サーバーへの接続時、ローカルIPアドレスとポートを表示
  • win32: 長い引数には GNU スタイルを使用: –foo
  • ホスト名に数値を許可し、常に inet_pton でパースを試行する
  • deallocate_all() の修正についての FAQ
  • 例の設定ファイルに誤ったキーワードを修正 (Magnus Hagander)
  • 認証ファイルにコメント（’;’ を用いて）を許可する。 (Guillaume Aubert)
  • ログメッセージおよびコメント内のスペルミスを修正します。 (Dmitriy Olshevskiy)

• 修正

  • メンテナンス中に新しい接続の起動を修正 (Cody Cutrer)
  • 起動時に認証ファイルを2回読み込まない。 (Cody Cutrer)
  • 自動DBの適切な無効化
  • ipv6: リスンソケットに IPV6_V6ONLY を設定します。
  • win32: リスンソケットに SO_REUSEADDR を設定しないでください。
  • IPv6 アドレスの memcpy 修正
  • 待機中のクライアントのキャンセルを修正。 (Mathieu Fenniak)
  • 小さなバグ修正、calloc の結果を確認する必要があります (Heikki Linnakangas)
  • PID ファイルの末尾に改行を追加する (Peter Eisentraut)
  • PAUSE が実行された場合、新しいサーバー接続を許可しない。 (Petr Jelinek)
  • ログイン時にヘッダーが遅延する場合の「bad packet」を修正。 (Michal Trojnara, Marko Kreen)
  • Coverity で検出されたエラーを修正。 (Euler Taveira)
  • サーバー数が min_pool を下回った場合、server_idle_timeout を無効にする (#60) (Marko Kreen)

PgBouncer 1.5.x

2015-04-09 - PgBouncer 1.5.5 - “Play Dead To Win”

• 修正
  • リモートクラッシュを修正 - 無効なパケット順序により NULL ポインタの参照が発生する問題を解消。悪用可能ではなく、DoS にのみ影響。

2012-11-28 - PgBouncer 1.5.4 - 「リークなし、訓練成功」

• 修正
  • DNS：getaddrinfo_a() バックエンドにおけるメモリリークを修正。
  • DNS：udns バックエンドにおけるメモリリークを修正。
  • DNS：統計の計算を修正。
  • DNS：getaddrinfo_a() におけるエラーメッセージの処理を改善。
  • Win32 のコンパイルを修正。
  • コンパイラの依存関係サポートチェックを configure で修正。
  • ドキュメントの修正をいくつか実施。

2012-09-12 - PgBouncer 1.5.3 - “Quantum Toaster”

• 重大な修正

  • データベース名が長すぎるとクラッシュする可能性があり、自動データベース作成が有効な場合、リモートからトリガーされることがあります。

    • 元のチェックは、すべての名前が設定ファイルから来ると想定していたため fatal() を使用しても問題ありませんでしたが、autodbs が有効な場合（[databases] セクションの ‘*’ による）、データベース名はネットワークから来る可能性があり、リモートシャットダウンを可能にしていました。

    CVE-2012-4575

• マイナー機能

  • max_packet_size - クライアントとサーバー間で許可される最大パケットサイズを調整する設定パラメータ。 デフォルト値は (2G-1) と同一ですが、現在はこれを小さく設定できます。
  • パケットヘッダーが解析できない場合、ログおよびエラーメッセージに16進数で表示する。

• 修正

  • AntiMake：パス名の操作に $(relpath) および $(abspath) を使用していたが、ソースツリーのパスにシンボリックリンクが含まれる場合にビルドが失敗していた。コードは現在、平文の文字列のみを扱うように変更された。
  • 管理コンソール: SET コマンドで空文字列の値を設定できるようになりました。
  • config.txt：タイムアウトは浮動小数点数で設定可能であることを示す。 これは 1.4 で導入された、あまり知られていない機能である。

2012-05-29 - PgBouncer 1.5.2 - 「噛まずに、ただ飲み込む」

• 修正
  • 誤って、reserve_pool_timeout がマイクロ秒単位で扱われていたため、プールが満杯になった際に即座に予約プールが有効化されていました。現在は意図した通り、秒単位で扱うように修正しました。 (Noticed by Keyur Govande)

2012-04-17 - PgBouncer 1.5.1 - “Abort, Retry, Ignore?”

• 機能
  • UNIXソケットの権限を調整するためのパラメータ: unix_socket_mode=0777, unix_socket_group=’’.
• 修正事項
  • サーバー側変数に空文字列を許可する — これは “application_name” が正しく動作するために必要であり、サーバー側のデフォルト値を持たない唯一のパラメーターだからである。
  • 接続文字列が変更された場合、サーバーのパラメーターの再読み込みが必要です。 以前は PgBouncer は古いパラメーターで続行していましたが、Postgres のアップグレード時にはこれにより障害が発生します。
  • autodb の接続文字列が変更された場合、古い接続を切断します。
  • cf_setint: 整数設定パラメータの解析に atoi() の代わりに strtol() を使用します。これにより16進数、8進数のサポートおよびより良いエラー検出が可能になります。
  • sigqueue() を使用して union sigval の存在を検出 - HPUX でのコンパイルを修正。
  • Makefile から ‘git’ コマンドを削除し、プレーンなtarボールビルド時に発生するランダムなエラーを回避する。
  • stats_period パラメータ。このパラメータは、統計出力の周期を調整します。
  • Asciidoc 8.4 以上を必要とします。以前のバージョンとの互換性は失われているようです。
  • close() からの EINTR に対する再試行をやめます。

2012-01-05 - PgBouncer 1.5 - 「2007 年から満足したクライアントを跳ね返し続ける」

1 つの DNS 名に 8 個を超える IP アドレスを関連付ける場合、EDNS0 プロトコルで照会する必要があります。 この機能をサポートするのは getaddrinfo_a()/getaddrinfo() と UDNS バックエンドだけで、libevent 1.x/2.x はサポートしません。 libc で有効にするには、/etc/resolv.conf に ‘options edns0’ を追加してください。

GNU Make 3.81 以上が必要です。

• 機能
  • DNS の応答変更を検出し、最新の応答に存在しない IP アドレスへの接続を無効化します。 (Petr Jelinek)
  • DNS ゾーンシリアルに基づくホスト名の無効化。オプション dns_zone_check_period が設定されている場合、すべての DNS ゾーンに対して SOA を照会し、シリアルが変更された時点ですべてのホスト名を照会します。これは、接続の無効化を確定的に実行するため必要です。なぜなら、照会が行われない状態では、照会時の無効化は無意味だからです。新しい UDNS バックエンドでのみ動作します。
  • DNS キャッシュを確認するための新しい SHOW DNS_HOSTS および SHOW DNS_ZONES コマンドを追加。
  • 新しいパラメータ: min_pool_size - ロードがなければ接続をすべて切断しないようにする (Filip Rembiałkowski)
  • idle_in_transaction_timeout - トランザクションが長時間アイドル状態になると終了する。 デフォルトでは設定されない。
  • DNS ルックアップ用に libudns バックエンドを追加。evdns よりも機能が豊富。 –with-udns を使用して有効化してください。現時点では IPv6 に対応していません。
  • KILL コマンドは、特定のデータベースのすべての接続を即座に終了します。 (Michael Tharp)
  • Antimake ビルドシステムに移行して、より見やすい Makefile を得る。 今後は GNU Make 3.81 以上が必要です。
• 修正
  • DNS は IPv6 ホスト名に対応しています。
  • サーバーから NOTIFY が到着しても接続状態を変更しない。
  • さまざまなドキュメントの修正。 (Dan McGee)
  • 管理コンソールで "" を使った識別子の引用をサポートしました。当初はデータベース名を引数に取るコマンドがなかったため、引用は不要でした。
  • 管理コンソール：単語の正規表現の先頭に数字を許可する。厳密なパーサーを使用しようとすると、ここでは複雑になりすぎる。
  • 自動データベースが一時停止されている場合、期限を切らないでください。 (Michael Tharp)
  • PAUSE を実行する際に必要に応じて自動でデータベースを作成します。 (Michael Tharp)
  • RESUME コマンドによって発行される誤ったログメッセージを修正。 (Peter Eisentraut)
  • データベース接続文字列に user= があり password= がない場合、パスワードは userlist から取得されます。
  • テイクオーバーコードで ‘*’ を正しく解析。
  • autogen.sh: 古い autoconf/automake と互換性を持つ。
  • Win32 で mingw/msvc ランタイムの basename() が不正なため、サービス実行時にクラッシュする問題を修正。現在は常に互換性のある basename() が使用される。

PgBouncer 1.4.x

2011-06-16 - PgBouncer 1.4.2 - “先制アルゴリズム”

影響を受ける OS: *BSD、Solaris、Win32。

• ポータビリティ修正
  • リンカーに CFLAGS を渡します。pthread ベースの getaddrinfo_a() フォールバックを使用する場合に必要です。
  • lib/find_modules.sh: split() を index()+substr() に置き換えます。 これにより、古い AWK でも動作するようになります。
  • <usual/endian.h>：システムの htoX/Xtoh 定義を無視します。マクロは部分的に定義されている可能性があります。
  • <usual/signal.h>：compat sigval と compat sigevent を分離する
  • <usual/socket.h>：iovec を取得するには <sys/uio.h> を含めてください。
  • <usual/time.h>：win32 での関数の自動検出を改善
  • <usual/base_win32.h>：重複する sigval/sigevent の宣言を削除

2011-04-01 - PgBouncer 1.4.1 - 「すべては演技だった」

• 機能

  • IPv6 アドレスのリスニング/接続をサポートします。 (Hannu Krosing)
  • ’listen_addr’ に複数のリッスンアドレスを指定可能。それぞれに対して getaddrinfo() が呼び出されるため、名前も使用できます。
  • 管理コンソール: クライアントに ‘server_version’ を送信して PgBouncer のバージョンを通知します。

• 重要な修正

  • glibc < 2.9 では getaddrinfo_a() を無効化する。古いバージョンでクラッシュするため。

    影響を受ける主要な OS 一覧: RHEL/CentOS 5.x (glibc 2.5)、Ubuntu 8.04 (glibc 2.7)。 また、Debian/lenny (glibc 2.7) も影響を受けるが、getaddrinfo_a() はクラッシュしない。 ただし、その状態を検出する適切な方法が存在しない。

    このような OS では libevent 2.x を使用してください。fallback の getaddrinfo_a() は本番システム向けではありません。DNS バックエンドの選択方法については、README の「DNS ルックアップサポート」セクションを参照してください。

    (Hubert Depesz Lubaczewski, Dominique Hermsdorff, David Sommerseth)

  • libevent 2.x を使用する場合、–enable-evdns をデフォルトで有効にします。

  • デフォルトで tcp_keepalive を有効にします。これは Postgres も同様に実行しているためです。 (Hubert Depesz Lubaczewski)

  • Postgres との互換性を保つため、server_reset_query のデフォルトを DISCARD ALL に設定しました。

  • win32: NULL の Unix ソケットアドレスで発生するクラッシュを修正。 (Hiroshi Saito)

  • autodb のクリーンアップを修正：古いクリーンアップコードはデータベースとプールを混同していた。 空のプールが見つかった瞬間、データベースが「アイドル」とマークされ、 後にアクティブなユーザーがいるデータベースを終了する可能性があった。

    Reported-By: Hubert Depesz Lubaczewski

• 修正

  • getaddrinfo_a() を非ブロッキングにするために、並列にリクエストを処理する単一のスレッドを使用して、アドレス解決を行う。
  • compat getaddrinfo_a が使用される場合に pthread コンパイルを有効にしました。
  • release_server がライフタイム切断時に ->last_lifetime_disconnect の設定を失った。 (Emmanuel Courreges)
  • win32: DOS形式の改行コードに対応した認証ファイルの修正 — load_file() はファイルの短縮を考慮していなかった。 (Rich Schaaf)
  • <usual/endian.h>：enc/dec 関数の autoconf 検出を追加 BSD での競合を回避するため。 (James Pye)
  • 設定ファイルが存在しない場合にクラッシュしない。 (Lou Picciano)
  • ログレベルがノイズのとき、DNS ルックアップの失敗でクラッシュしないようにする (-v -v)。 (Hubert Depesz Lubaczewski, Dominique Hermsdorff)
  • find_modules.sh では、$(cmd) の代わりにバッククォートを使用して、よりポータブルにする。 (Lou Picciano)
  • find_modules.sh では、互換性を高めるために ‘sed’ の代わりに ‘awk’ を使用してください。 (Giorgio Valoti)
  • 起動時に非同期DNSバックエンドの情報をアクティブログに出力します。
  • –disable-evdns が ‘yes’ ではなく ’no’ を意味するように修正。
  • ドキュメントに -R が unix_socket_dir を必要とする点を記載してください。
  • server_reset_query を faq.txt で説明します。
  • スラブアロケータで失われていた memset を復元
  • libusual におけるいくつかの小さなポータビリティ修正。

2011-01-11 - PgBouncer 1.4 - “Gore Code”

• 機能

  • 非同期 DNS ルックアップ — リロード時にホスト名を解決する代わりに、設定可能なキャッシュとともに接続時に解決するようになりました。 (参照: dns_max_ttl パラメータ。)

    デフォルトでは、バックエンドとして getaddrinfo_a() (glibc) を使用します。存在しない場合、getaddrinfo_a() はブロッキング(!) な getaddrinfo() を使ってエミュレートされます。

    –enable-evdns を configure に指定すると、libevent の evdns がバックエンドとして使用されます。デフォルトでは使用されません。これは libevent 1.3/1.4 にバグのある実装が含まれているためです。libevent 2.0 の evdns だけが問題ないとされています。

  • 新しい設定変数: syslog_ident は、syslog の名前を調整するために使用します。

  • application_name 起動パラメータに対する適切なサポート。

  • コマンドラインの長オプション (Guillaume Lelarge)

  • Solaris 互換性の修正 (Hubert Depesz Lubaczewski)

  • 新しい設定変数: disable_pqexec。非常に厳格な環境では、この設定で Simple Query Protocol を無効化できます。これには、Extended Query Protocol のみを使用するアプリケーションが必要です。

  • Postgres互換性: スタートアップパケット内のデータベース名が空の場合、ユーザー名をデータベース名として使用する。

• 修正

  • DateStyle および TimeZone サーバー設定パラメーターは、正確な大文字・小文字を使用する必要があります。
  • 管理コンソール：datetime、timezone、stdstr のサーバーパラメータをクライアントに送信。

• 内部のクリーンアップ

  • 低レベルなユーティリティ関数には libusual ライブラリを使用します。
  • サーバー パラメータの固定長制限を削除します。

PgBouncer 1.3.x

2010-09-09 - PgBouncer 1.3.4 - “Bouncer is always right”

• 修正
  • 接続時に迅速な失敗ロジックを適用します。サーバーが障害状態の場合、クライアントは接続時にエラーを受け取ります。
  • 自動生成されたデータベースに、再読み込み時のチェック用タグを付けないようにしました。設定ファイルに存在しないため、タグが付いたままだと強制終了されてしまうためです。
  • application_name パラメータをデフォルトで無視します。これにより、Postgres 9.0 のすべてのユーザーが、それを ignore_startup_parameters= に自分で追加する必要がなくなります。
  • pg_auth の引用を正しく修正しました。 ‘' はその場で使用されていません。
  • 管理コンソールでのエラー報告を改善し、ユーザーに受信したクエリを表示します。
  • 対応 OS（OpenBSD）では、tv_sec が time_t でない場合があります。
  • gcc 4.5 での警告を多すぎないようにする。

2010-05-10 - PgBouncer 1.3.3 - “NSFW”

• 改善
  • listen(2) の引数を設定可能にする: listen_backlog。これは、システムの最大許容値が設定可能な OS で有用です。
  • ログイン失敗の原因となったユーザー名やデータベース名を明示するように、切断メッセージを改善します。
• 修正内容
  • 高速失敗（fast-fail）時の再起動ロジックを再構成しました。以前のロジックは、恒久的に壊れたデータベースやユーザーの場合、ログインしたいクライアントがいなくても再試行しようとするため厄介でした。
  • ログ出力関数が元の errno を保持するようにしました。そうしないと、高いログレベルやロギングの問題時に pgbouncer が奇妙な動作をする可能性があります。
  • 起動関連のバッファサイズを増やして、EDB のノイズの多い起動を処理する。
  • V2 プロトコルの起動リクエストを検出し、切断の明確な理由を提示する。

2010-03-15 - PgBouncer 1.3.2 - “Boomerang Bullet”

• 修正

  • 新しい設定変数 ‘query_wait_timeout’。クライアントがこの秒数以内にサーバー接続を取得できない場合、クライアントは終了されます。

  • クライアント接続プールにサーバー接続が存在せず、直前の接続が失敗した場合、クライアント接続を保留せず、直ちにエラーを送信する。

    これにより、前の修正と併せて、データベースが停止した場合の不要な停止を回避できます。

  • libevent の状態を sbuf.c で追跡して、二重の event_del() を回避します。 通常は安全ですが、100% 効果があるとは限りません。 今後は常に event_del() が呼び出されたかどうかを明確に把握できるようになります。

  • SUSPEND 中はメンテナンスを無効化しました。そうしないと、短いタイムアウトの設定では、古い PgBouncer が接続を送り渡した後にいくつかの接続を閉じてしまう可能性がありました。

  • クライアントがウェルカムパケットを待っている間（最初のサーバー接続時）に client_login_timeout を適用する。そうでなければ、query_timeout が設定されていない限り、無限に待機し続ける可能性がある。

  • win32: -U/-P オプションを -regservice に追加し、ユーザーがサービスの実行に使用するアカウントを選択できるようにします。従来のローカルサービスとローカルシステムの自動選択は信頼性が低かったためです。

  • console：テキスト列の末尾から \0 を削除します。C クライアントでは問題なかったため、気づきにくかったためです。

  • ドキュメントの改善。 (Greg Sabino Mullane)

  • ログメッセージのログイン関連の記述を明確化しました。

  • プーラーが送信したエラー（通常は切断時）のログレベルを INFO から WARNING に変更し、問題を示すことを明示します。

  • query_timeout のログメッセージを「query timeout」に変更します。

2009-07-06 - PgBouncer 1.3.1 - 「NSA監視要件を完全に準拠」

• 修正
  • sbuf_loopcnt の問題を修正しました。接続がフリーズする原因となる場合があります。 クエリまたは結果の長さが (pktlen * sbuf_loopcnt) [デフォルトで 10k] の倍数に近い場合、存在しないデータを待機し続ける可能性があります。
  • データベースの再構成を即時に行います。現在、SIGHUP 後に古い接続が再利用される可能性があります。
  • SHOW DATABASES のカラム追加により破損していた問題を修正。
  • 管理コンソールへのアクセスは、「auth_type=any」の場合、ユーザー名がドロップされたため無効化されました。 修正：「auth_type=any」の場合、任意のユーザーが管理者として管理コンソールにアクセスできるようにします。
  • 不具合のある CUSTOM_ALIGN マクロを修正。幸いにも、OS が ALIGN マクロを定義している場合、このマクロは使用されないため、実際の環境では問題が発生していなかったと思われる。
  • win32: 設定解析時にホスト名解決が必要なため、WSAStartup() をデーモンモード時のみではなく常に呼び出すようにしました。
  • win32: サービスのコマンドラインで、パスにスペースを含む場合に備えて設定ファイル名を引用符で囲みます。実行可能ファイルのパスについては、win32 の仕様上、引用符の必要性がありません。
  • SHOW HELP テキストに STATS を追加。
  • doc/usage.txt: 管理コンソールの結果における時間単位はミリ秒ではなくマイクロ秒です。

2009-02-18 - PgBouncer 1.3 - “New Ki-Smash Finishing Move”

• 機能

  • IANA は PgBouncer の公式ポートとしてポート 6432 を割り当てました。 したがって、デフォルトのポート番号は 6432 に変更されました。 既存の個別ユーザーは変更する必要はありませんが、 PgBouncer のパッケージを配布する場合は、パッケージのデフォルトを公式ポートに変更してください。

  • による動的データベース作成 (David Galoyan)

    これで、データベース名 “*” を定義できます。定義された場合、未定義のデータベースすべてに対してその接続文字列が使用されます。主にテスト／開発環境で有用です。

  • Windows でのサポート (斎藤浩史)

    PgBouncer は現在、Windows 2000 以降で動作します。コマンドラインの使用方法は従来と同様ですが、デーモンとして実行できず、オンライン再起動もできません。サービスとして実行するには、設定ファイルに service_name パラメータを定義します。その後、以下の手順を実行します。

    > pgbouncer.exe config.ini -regservice
    > net start SERVICE_NAME
    

    停止と登録解除は以下の手順で行います。

    > net stop SERVICE_NAME
    > pgbouncer.exe config.ini -unregservice
    

    Windows イベントログを使用するには、事前にイベント DLL を登録する必要があります。

    > regsvr32 pgbevent.dll
    

    その後、設定ファイルで syslog = 1 を設定できます。

• マイナー機能

  • 設定ファイル内のデータベース名は、標準SQLの識別子クォートを使用して引用できるようになり、データベース名に非標準文字を含められるようになりました。

  • 新しい設定項目: ‘reserve_pool_size’ および ‘reserve_pool_timeout’。 クライアントが ‘reserve_pool_timeout’ 秒以上待機している場合、‘reserve_pool_size’ はプールに追加可能な接続数を指定します。また、‘reserve_pool’ 接続変数でプールごとに設定することもできます。

  • ソケット1つで費やされる時間を制限するための新しい設定 ‘sbuf_loopcnt’。

    一部の状況（例：SMP サーバー、ローカル Postgres、高速ネットワーク）では、pgbouncer は recv()->send() ループをブロッキングせずに多数回実行できます。しかし、これは他の接続が長時間スタックする原因になります。処理の公平性を高めるため、1 つのソケットに対して recv()->send() を実行する回数を制限します。回数制限に達した場合、他のソケットの処理に進みます。そのソケットの処理は次のイベントループで再開されます。

    Alexander Schöcke による報告とテストに感謝します。

  • crypt() 認証は現在オプションになりました。これは Postgres から削除されたためです。 OS で提供されていなくても、pgbouncer は問題なく動作します。

  • ログタイムスタンプにミリ秒を追加します。

  • 旧来的な MD5 実装を、よりコンパクトな実装に置き換えます。

  • ISC ライセンスを FSF の説明で更新。

• 修正

  • event_del() が失敗を報告した場合、ただクリーンアップを続行してください。 以前は、失敗が ENOMEM によるものだった場合に pgbouncer が再試行していました。 しかし、これにより無限ループによるログの洪水が発生していたため、 libevent がこれを好まないようです。

    なぜ event_del() が最初の呼び出しで失敗を報告するのかは、依然として謎です。

  • –enable-debug はもはやバイナリからデバッグ情報を削除するかどうかを切り替えるだけです。 これ以上 -fomit-frame-pointer に影響を与えることはなく、危険なためです。

  • include の順序を修正し、そうでなければシステムの include が内部のものより前に来る場合があります。これは新しい md5.h include ファイルで問題となりました。

  • COPYRIGHT ファイルを .tgz に含める…

PgBouncer 1.2.x

2008-08-08 - PgBouncer 1.2.3 - “Carefully Selected Bytes”

• 修正
  • BSD 用に動作しなかった SO_ACCEPTFILTER コードを無効化します。
  • 例として etc/userlist.txt を tgz に含める。
  • 再帰には ‘make’ の代わりに ‘$(MAKE)’ を使用 (Jørgen Austvik)
  • glibc が無意味になるため、_GNU_SOURCE を定義してください。
  • libevent 1.1 のリンクテストを通過させ、後に「1.3b+ needed」（1.3b 以降が必要）というメッセージを報告できるようにしました。
  • 古い pidfile を検出し、削除する。

Devrim GÜNDÜZ と Bjoern Metzdorf による問題報告とテストに感謝します。

2008-08-06 - PgBouncer 1.2.2 - 「バーフバッグ付属」

• 修正
  • ‘drop_on_error’ を削除してください。これは誤ったアイデアでした。PostgreSQL の破損したプランキャッシュ動作を回避するための暫定対策として追加されたものですが、通常のケースで一部のクエリが常にエラーを返す場合に、損害を引き起こす可能性があります。

2008-08-04 - PgBouncer 1.2.1 - “Waterproof”

• 機能
  • 新しいパラメータ ‘drop_on_error’ — サーバーがエラーを発生させた場合、接続は再利用されず、クライアントが処理を終了した後に破棄されます。これはプランキャッシュを更新するために必要です。自動更新は 8.3 でも動作しません。デフォルトは 1 です。
• 修正事項
  • SHOW SOCKETS/CLIENTS/SERVERS: ソケットにバッファがない場合にクラッシュしない。
  • SUSPEND で suspend_timeout が発動した場合の無限ループを修正。
• 軽微な整備
  • struct iovec に <sys/uio.h> を使用してください。
  • RESUME/SIGUSR2 で（SIGINT による）シャットダウンを取り消すようにしました。そうしないと、次の PAUSE 時に発動してしまいます。
  • 管理コンソール操作がキャンセルされた場合の適切なログメッセージ。

2008-07-29 - PgBouncer 1.2 - “Ordinary Magic Flute”

PgBouncer 1.2 では、libevent バージョン 1.3b 以降が必要です。 古い libevent バージョンでは、新しい再起動コードでクラッシュします。

• 機能

  • コマンドラインオプション (-u) および設定パラメータ (user=) を、起動時にユーザー切り替えをサポートするためのものとして導入しました。また、現在、pgbouncer は root として実行されることを拒否します。

    (Jacob Coby)

  • より詳細な使用説明テキスト (-h)。 (Jacob Coby)

  • 新しいデータベースオプション：接続開始前に新しい接続でクエリを実行できるようにする connect_query。

    (Teodor Sigaev)

  • 新しい設定変数 ‘ignore_startup_parameters’ を導入し、起動パケット内の追加パラメータを許可または無視できるようにしました。デフォルトでは ‘database’ と ‘user’ のみが許可され、それ以外のパラメータはエラーを発生させます。これは、過剰に積極的な JDBC が起動パケット内で ’extra_float_digits=2’ を無条件に設定しようとする場合に耐えられるようにするためです。

  • syslog へのログ出力: syslog=0/1 および syslog_facility=daemon/user/local0 の新パラメータ。

  • より安全なオンライン再起動 (-R)

    • fork の前で FD の読み込みを移動し、管理コンソールにログ出力できるようにし、^C で中断できるようにする

    • fork後にSHUTDOWNを保持し、^Cが安全になるようにする

    • 誰かがリッスンしているかどうかを確認するため、Unix ソケットへの connect() が試行されます。 これにより、-R は、以前のプロセスが実行されていなくても使用可能になります。 以前のプロセスが存在する場合でも、-R が使用されない限り、起動は失敗します。

  • 新しい管理コンソールコマンド：

    • SHOW TOTALS は、ログに出力される統計の要約に加えてメモリ使用量を表示します。

    • SHOW ACTIVE_SOCKETS は、ソケットを表示するものと同様ですが、アクティブなソケットのみをフィルタリングして表示します。

• 目に見えにくい機能

  • suspend_timeout - スタックした接続と長時間のログインを切断します。再起動時の追加の安全性を提供します。

  • リモートデータベースがログイン時にエラーを発生させた場合、クライアントに通知する。

  • 設定からデータベースを削除して再読み込みすると、すべての接続が切断され、データベースが削除されます。

  • 管理コンソールの SHOW/SET コマンドで、PostgreSQL に似た動作を実現するため、仮のパラメータを設定します。 これは psycopg が管理コンソールに接続できるようにするため必要でした。 (client_encoding/default_transaction_isolation/datestyle/timezone)

  • server_lifetime=0 を設定すると、最初の使用後すぐにサーバー接続を切断します。以前は「0」を設定すると PgBouncer がサーバーの年齢を無視していました。この動作は非文書化されていたため、依存しているユーザーは存在しないはずです。

  • 内部の改善事項：

    • パケットバッファは遅延割り当てされ、再利用されます。これによりメモリ使用量が大幅に削減されます。また、多数の接続で大きな pktbuf を使用することも現実的になります。

    • OOM状況でも正常に動作するよう、多数のエラー処理の改善が行われました。

    • メモリ管理にスラブ割り当てを使用します。

    • 多数のコードクリーンアップ。

• 修正

  • イベントループごとに1回だけ accept() が実行される仕様により、接続試行の数が多い場合に接続バックログが発生する可能性がありました。現在はリスニングソケットを常に完全にドレインするようにしたため、この問題が解消されます。
  • connect からの EINTR を処理する。
  • configure.ac を autoconf 2.59 と互換性を持たせる。
  • Solaris互換性の修正 (Magne Maehre)

PgBouncer 1.1.x

2007-12-10 - PgBouncer 1.1.2 - “The Hammer”

• 機能
  • server_lifetime による切断は、(server_lifetime / pool_size) 秒ごとに分離されるようになりました。これにより、pgbouncer が再接続の洪水を引き起こすのを回避できます。
• 修正
  • オンラインアップグレード 1.0 → 1.1 の問題：
    • 1.0 ではサーバーのパラメーターを追跡しないため、それらは NULL のままになりますが、1.1 ではこれを想定しておらず、クラッシュしました。
    • サーバーのパラメータが不明な場合でも、クライアントのパラメータが設定されているなら、エラーを出力する代わりにそれらに対して SET を実行する。
  • INFO レベルで誤って残された一時的なデバッグ出力を削除し、ログが汚染されないようにする。
  • debian/changelog の修正を元に戻す。
• 整理作業。
  • バッファのアライメントを改善するために、構造体 SBuf のフィールドの順序を再配置する。

2007-10-26 - PgBouncer 1.1.1 - “Breakdancing Bee”

• 修正
  • サーバーのパラメーター・キャッシュが初期化されないまま残る場合があり、これにより不要な SET が発生しました。これは 8.1 では standard_conforming_strings を変更できないため問題を引き起こしました。 （報告およびテストの協力にディミトリ・フォンタインに感謝します。）
  • ドキュメントの修正。
  • doc/fixman.py を .tgz に含める。

2007-10-09 - PgBouncer 1.1 - “Mad-Hat Toolbox”

• 機能

  • 次のサーバー設定パラメーターを追跡してください：

    client_encoding  datestyle, timezone, standard_conforming_strings
    

  • データベース接続文字列の拡張機能：

    • host= でホスト名を受け付けます。
    • host= でカスタム Unix ソケットの場所を受け付ける
    • クォートされた値を許可: password=’ asd’‘foo’

  • 新しい設定変数: server_reset_query。接続の解放直後に送信されます

  • 新しい設定変数: サーバーの接続割り当て方式を LIFO と RR の間で切り替えるための server_round_robin。

  • アイドル状態の接続に送信されたキャンセルパケットは、接続を切断しなくなりました。

  • psql からの ^C によるキャンセルが SUSPEND / PAUSE でも機能するようになりました。

  • 起動時に FD 制限を出力する。

  • 一時停止時に、できるだけ早くパケット境界に到達するように試みます。

  • データベースパラメータに ’timezone’ を追加します。

  • 長寿命のログファイルディスクリプタを使用。SIGHUP / RELOAD で再オープンする。

  • SHOW SERVERS/CLIENTS/SOCKETS で表示されるローカル接続エンドポイントの情報。

• コードの整理

  • デバッグログメッセージにソケット情報が含まれます。
  • マジックナンバーの削除とエラーメッセージの整理。 (David Fetter)
  • 現在のパケット情報用のラッパー構造体です。複雑さを大幅に削減します。

• 修正

  • パケットヘッダーの無効な値をより正確に検出する。
  • auth_file の変更チェックが不具合だったため、pgbouncer が頻繁に再読み込みを行っていました。

PgBouncer 1.0.x

2007-06-18 - PgBouncer 1.0.8 - “Undead Shovel Jutsu”

• 修正
  • キャンセルパケット処理でのクラッシュを修正。(^C による psql からの中断)
• 機能
  • PAUSE と RESUME が動作するようになりました。
  • 管理コンソールコマンドの解析のクリーンアップ。
  • コストの高い in-list アサートチェックを無効化しました。

2007-04-19 - PgBouncer 1.0.7 - “With Vitamin A-Z”

• 修正
  • 複数のエラー／通知パケットを送信する際、パケット間で send() がブロックするとアサーションが発生する問題を、flush ロジックを完全に削除して修正しました。pgbouncer は明示的なバッファリングを行わないため、flush は不要です。これは、MSG_MORE でバッファリングをカーネル側に任せていた時代の名残です。
  • また、送信がブロック解除されたときに recv() のロジックを呼び出さないようにしてください。
  • admin_users および stats_users の検索コードで部分一致が正しく処理されない問題を修正。
  • UNIX ソケットのピア UID を取得する方法を標準化し、getpeereid() を使用する。

2007-04-12 - PgBouncer 1.0.6 - “Daily Dose”

• 修正
  • 「テイクオーバー中のメンテナンス無効化」の修正が、メンテナンス全体を無効化してしまう可能性がありました。修正しました。
  • FreeBSD のコンパイル修正。FreeBSD では <sys/ucred.h> に <sys/param.h> が必要です。 Robert Gogolok による報告に感謝します。

2007-04-11 - PgBouncer 1.0.5 - 「今日はこれで十分」

• 修正
  • オンライン再起動のバグを修正：
    • アイドル状態のサーバーに ->ready を設定。
    • use_client_socket() から不要なコードを削除します
    • テイクオーバー中にメンテナンスを無効化。

2007-04-11 - PgBouncer 1.0.4 - 「最後の ’last’ バグ」

• 修正
  • アイドル状態のサーバーが「dirty」とタグ付けされたための通知。 release_server() はこれを想定していなかった。 これを修正するには、それらを破棄してください。

2007-04-11 - PgBouncer 1.0.3 - “Fearless Fork”

• 修正

  • ログインパスにエラー処理が不足していたため、接続が終了した際にアサーションが発生する可能性がありました。
  • アサートを sbuf.c でクリーンアップし、問題を早期に検出する。
  • Assert() がトリガーされたときにコアを生成する。

• 新機能

  • 新しい設定変数: log_connections、log_disconnections、log_pooler_errors は、ログ出力を有効または無効にするために使用します。
  • 設定変数: client_login_timeout ログインフェーズで、SUSPEND ひいてはオンライン再起動を停滞させる可能性のある無応答の接続を切断します。

2007-03-28 - PgBouncer 1.0.2 - “Supersonic Spoon”

• 修正
  • libevent は、同じループ内で削除されたイベントを報告する可能性があります。 1 つのループ内でソケットの再利用を回避してください。
  • release_server() は、disconnect_client() から呼び出された際に、パケットが実際に送信されたかどうかを確認していなかった。

2007-03-15 - PgBouncer 1.0.1 - “Alien technology”

• 修正

  • キャッシュ済みとキャッシュ未使用の時刻の混在、および unsigned usec_t の型定義の使用により、誤った query_timeout エラーが発生していた。
  • 送信待機からソケットが起床した後も、依然としてストールする稀なケースを修正。
  • サーバー接続のより公正なキューイング。以前は、新しいクエリが古いクエリより先にサーバー接続を取得することができた。
  • サーバーの解放を、すべてのデータが確実に送信された後に遅らせる。

• 機能

  • SHOW SOCKETS コマンドで、状態に関する詳細情報を取得できます。
  • 接続の追跡を支援するため、ログに PgSocket ポインタを出力します。
  • 管理コンソールで、SHOW の代わりに SELECT を許可します。
  • さまざまなコードの整備。

2007-03-13 - PgBouncer 1.0 - “Tuunitud bemm”

• 初の公開リリース。

7 - コミュニティ

チュートリアル

• Postgres Plus Standard Server 用に PgBouncer を設定する方法

  PgBouncer の概念についての良い概要。

• バウンシングの意味とは何か？

  プーリングモードの違いについて説明します。

サポート

• プロジェクトページ （GitHub）

• イシュートラッカー （GitHub）

• PgBouncer セクション （Stack Overflow）

• チャットルーム （Gitter）

• コミュニティディスカッション （GitHub）

8 - よくある質問

PgBouncer への接続方法

PgBouncer は Postgres サーバーとして動作するため、クライアントを PgBouncer のポートに向けるだけで接続できます。

複数のサーバー間でクエリを負荷分散するには？

PgBouncer は、データベース接続文字列でのコンマ区切りのホストリストをサポートしています。load_balance_hosts=round-robin を指定すると、新しいサーバー接続はそのリストを巡回して作成されます。例：

[databases]
app = host=pg1,pg2 port=5432 dbname=app load_balance_hosts=round-robin

外部ツールを使用することもできます：

1. DNS ラウンドロビン。1 つの DNS 名の背後にある複数の IP アドレスを使用します。PgBouncer は新しい接続が開始されるたびに DNS を照会しません。代わりに、すべての IP をキャッシュし、内部でラウンドロビンを行います。注意：1 つの名前の背後に 8 つを超える IP がある場合、DNS バックエンドは EDNS0 プロトコルをサポートしている必要があります。詳細については DNS ルックアップサポート を参照してください。

2. TCP 接続のロードバランサーを使用してください。LVS または HAProxy が適した選択肢のようです。PgBouncer 側では、server_lifetime を小さく設定し、あわせて server_round_robin を有効にするのが良いでしょう。デフォルトでは、アイドル状態の接続は LIFO アルゴリズムで再利用されますが、負荷分散が必要な状況ではこの動作がうまく機能しない可能性があります。

フェイルオーバーの方法

コンマ区切りのホストリストと load_balance_hosts=disable を使用すると、PgBouncer は接続試行が失敗するまで同じホストを使い続け、その後次のホストを試します。これはプライマリー／レプリカのロール検出は行いません。データベースのトポロジー変更に追従するフェイルオーバーには、外部ツールを使用してください：

1. DNS の再構成：DNS 名の背後にある IP アドレスが再構成された場合、PgBouncer は新しいサーバーに再接続します。この動作は、次の 2 つの設定パラメーターで調整できます。dns_max_ttl は 1 つのホスト名の生存期間を調整し、dns_zone_check_period は変更がないかどうかを確認するためにゾーン SOA を照会する頻度を調整します。ゾーンの SOA レコードが変更された場合、PgBouncer はそのゾーン下のすべてのホスト名を再照会します。

2. 設定に新しいホストを書き込み、PgBouncer に再読み込みさせます。 SIGHUP を送信するか、管理コンソールで RELOAD コマンドを使用してください。PgBouncer はホスト設定の変更を検出し、新しいサーバーに再接続します。

3. RECONNECT コマンドを使用してください。これは、上記の 2 つのオプションのいずれも適用できない状況で使用するものです。たとえば、前述の HAProxy を使って PgBouncer から下流への接続をルーティングする場合などです。RECONNECT は、単にすべてのサーバー接続を開き直すだけです。したがって、他のコンポーネントが接続ルーティング情報を変更した後に実行してください。

セッションプーリングとプリペアドステートメントをどのように使用するか？

セッションプーリングモードでは、リセットクエリが古いプリペアドステートメントをクリアする必要があります。これは server_reset_query = DISCARD ALL; または少なくとも DEALLOCATE ALL; を使用することで達成できます。

トランザクションプーリングとプリペアドステートメントをどのように使用するか？

バージョン 1.21.0 以降、PgBouncer はトランザクションプーリングモードでプリペアドステートメントを追跡し、リンクされたサーバー接続上でオンザフライで準備されるように保証できます。この機能を有効にするには、max_prepared_statements をゼロ以外の値に設定する必要があります（デフォルトは 200 です）。詳細については、max_prepared_statements のドキュメントを参照してください。

PHP/PDO を使用する場合、バージョンによっては PgBouncer のプリペアドステートメントサポートと互換性がありません (#991 )。PHP/PDO は PHP 8.4+ かつ libpq 17 を使用している場合にのみ互換性があります。したがって、古いバージョンを使用する環境では、アップグレードを推奨するか、クライアント側でプリペアドステートメントを無効にする必要があります。

JDBC でのプリペアドステートメントの無効化

JDBC で行う正しい方法は、接続文字列に prepareThreshold=0 パラメータを追加することです。

PHP/PDO でのプリペアドステートメントの無効化

サーバー側のプリペアドステートメントの使用を無効にするには、PDO 属性 PDO::ATTR_EMULATE_PREPARES を true に設定する必要があります。接続時に行います：

$db = new PDO("dsn", "user", "pass", array(PDO::ATTR_EMULATE_PREPARES => true));

またはそれ以降：

$db->setAttribute(PDO::ATTR_EMULATE_PREPARES, true);

接続を落とさずに PgBouncer をアップグレードする方法

SHUTDOWN WAIT_FOR_CLIENTS のドキュメントのセクション に記載された手順に従って、ローリング再起動を行うことができます。

クライアントがどのサーバー接続にあるかを確認するにはどうすればよいですか？

管理コンソール上で SHOW CLIENTS および SHOW SERVERS コマンドを使用します。

1. クライアント接続をサーバー接続にマッピングするには、ptr と link を使用してください。

2. クライアント接続の addr および port を使用して、クライアントからの TCP 接続を識別します。

3. サーバーへの TCP 接続を識別するために、local_addr および local_port を使用します。

PgBouncer は Web サーバーかデータベースサーバーにインストールすべきか？

状況によります。

Web サーバーに PgBouncer をインストールするのは、短命な接続が使用される場合に適しています。この場合、接続のセットアップ遅延が最小化されます（TCP では接続が利用可能になるまで数回のパケット往復が必要です）。データベースサーバーに PgBouncer をインストールするのは、複数の異なるホスト（例：Web サーバー）が接続する場合に適しています。この場合、それらの接続をまとめて最適化できます。

Web サーバーおよびデータベースサーバーの両方に PgBouncer をインストールすることも可能です。その一方で、各 PgBouncer のホップがクエリごとにわずかな遅延を追加するという欠点があります。

最終的には、パフォーマンス要件に最も適したモデルをテストして選定する必要があります。また、Web サーバーとデータベースサーバーのどちらかがダウンした際に、PgBouncer のインストールがアプリケーションのフェイルオーバーにどのような影響を与えるかについても検討する必要があります。