PgBouncer 1.25.2 ドキュメント

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

1 - 機能

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

  セッションプーリング

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

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

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

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

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

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

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

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

• クライアント接続を切断せずにオンラインで再起動またはアップグレードできます。

プーリングモードの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 でサポートされています）。

オンライン再起動 (-R) を有効にするには、Unix ソケットを設定し、ファイルシステム名前空間内に配置する必要があります。

デフォルト： /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

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

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

• プールに対応する [database] セクションのエントリで、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 のデータベースを対象とし、出力接続先の 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 はクライアントごとに client_encoding、datestyle、timezone、standard_conforming_strings、application_name のパラメータを追跡します。他のパラメータを追跡可能にするには、ここに指定できます。これにより、PgBouncer はそれらのパラメータをクライアント変数キャッシュに保持し、クライアントがアクティブになるとサーバーに復元することを認識します。

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

注意： 多くのパラメータはこの方法では追跡できません。追跡できるのは、Postgres がクライアントに報告するパラメータのみです。Postgres には クライアントに報告するパラメータの公式リスト があります。ただし、Postgres 拡張機能はこのリストを変更できます。拡張機能は独自にパラメータを追加して報告することができ、また、Postgres が報告していない既存のパラメータを報告し始めることがあります。特に、Citus 12.0 以降では search_path の報告が行われるようになります。

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

デフォルト： IntervalStyle

ignore_startup_parameters

デフォルトでは、PgBouncer は起動パケット内で追跡できるパラメータのみを許可します：client_encoding、datestyle、timezone および standard_conforming_strings。それ以外のパラメータはエラーを発生させます。他のパラメータを許可するには、ここに指定することで、PgBouncer が管理者がそれらを処理していることを認識し、無視できるようにします。

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

Postgres プロトコルでは、パラメータ設定を、起動パケット内のパラメータとして直接指定するか、options 起動パケット 内に含める方法で指定できます。これらの両方の方法で指定されたパラメータは、ignore_startup_parameters でサポートされています。また、options を track_extra_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 メソッドと同様だが、指定されたユーザー名は無視される。すべてのデータベースが特定のユーザーとしてログインするように設定されている必要がある。また、管理コンソールデータベースでは、任意のユーザーが admin としてログインできる。
• 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 関数を呼び出すスーパーユーザー以外のユーザーを使用することを推奨します。

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

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

auth_dbname

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

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 の場合、この設定は無視され、管理者として任意のユーザー名が許可されます。

デフォルト： 空

stats_users

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

デフォルト： 空

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

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

クライアントが接続したが、この時間内にログインできなかった場合、接続は切断されます。主に、SUSPEND を停止させないためのオンライン再起動を防ぐために必要です。[秒]

デフォルト： 60.0

autodb_idle_timeout

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

デフォルト： 3600.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

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: FIXME: サーバーがプレーン接続を拒否した場合は、TLSを試してみてください。
• 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 以下の場合は client_tls_ciphers を参照してください。

デフォルト： <empty>

危険なタイムアウト

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

query_timeout

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

デフォルト： 0.0（無効）

query_wait_timeout

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

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

デフォルト： 120.0

cancel_wait_timeout

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

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

デフォルト： 10.0

client_idle_timeout

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

デフォルト： 0.0（無効）

idle_transaction_timeout

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

デフォルト： 0.0（無効）

transaction_timeout

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

デフォルト： 0.0（無効）

suspend_timeout

SUSPEND または再起動中のバッファフラッシュを待つ時間（-R）。フラッシュが成功しなければ接続は切断されます。[秒]

デフォルト： 10

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

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 は管理コンソール用に予約されており、ここではキーとして使用できません。

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

* = 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 が使用されます。

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

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

reserve_pool_size

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

connect_query

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

pool_mode

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

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 はユーザーが存在するかのように振る舞い、クライアントに「ユーザーが存在しません」というメッセージを返さない一方で、提供されたパスワードを受け入れることもありません。

pool_size

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

reserve_pool_size

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

pool_mode

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

max_user_connections

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

query_timeout

ユーザークエリの実行可能時間の最大秒数を設定します。このタイムアウトを設定すると、上記で説明したサーバーレベルの query_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)

ユーザー admin はパスワード 1234 を持ち、ハッシュ化されたパスワードは 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][-R][-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 に接続できます。このとき、pgbouncer は実際に接続先のサーバーに接続するか、既存の接続を再利用します。

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

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

セッションプーリング

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

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

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

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

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

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

クイックスタート

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

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|FDS|POOLS|CLIENTS|SERVERS|SOCKETS|LISTS|VERSION|...]
      SET key = arg
      RELOAD
      PAUSE
      SUSPEND
      RESUME
      SHUTDOWN
      [...]
   

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

    pgbouncer=# RELOAD;
   

コマンドラインスイッチ

-d、--daemon

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

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

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

-R, --reboot

非推奨: このオプションの代わりに、so_reuseport を使用して複数の pgbouncer プロセスが同じポートをリッスンするローリング再起動を使用してください オンライン再起動を実行します。これは実行中のプロセスに接続し、開いているソケットを読み込み、それらを使用することを意味します。アクティブなプロセスが存在しない場合は、通常通り起動します。 注意： OS が Unix ソケットをサポートしている場合にのみ動作し、unix_socket_dir が設定で無効になっていない必要があります。Windows では動作しません。TLS 接続では動作せず、接続が切断されます。

-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 を参照。

avg_xact_count

直近の統計期間における平均トランザクション数（秒単位）。

avg_query_count

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

avg_server_assignment_count

1 秒あたりのサーバーのクライアントへの割り当て回数の平均値（直近の統計期間内）。

avg_recv

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

avg_sent

クライアントへの平均送信バイト数/秒。

avg_xact_time

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

avg_query_time

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

avg_wait_time

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

avg_client_parse_count

クライアントが作成した準備済みステートメントの平均数。名前付き準備ステートメント追跡モードでのみ有効です。詳細は max_prepared_statements を参照してください。

avg_server_parse_count

サーバーで pgbouncer が作成した準備済みステートメントの平均数。名前付き準備ステートメント追跡モードでのみ有効であり、max_prepared_statements を参照してください。

avg_bind_count

クライアントが pgbouncer を介して PostgreSQL に転送する準備完了したプリペアドステートメントの平均数。名前付きプリペアドステートメント追跡モードでのみ有効。詳細は max_prepared_statements を参照。

SHOW STATS_TOTALS

SHOW STATS のうち、合計値（total_）を示すサブセット。

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

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

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 エントリが作成されます。

database

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

cl_active_cancel_req

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

cl_waiting_cancel_req

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

sv_active_cancel

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

sv_login

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

SHOW LISTS

次の内部情報を列（行ではなく）で表示します：

databases

データベース数。

users

ユーザー数。

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。設定されていない場合は NULL。

reserve_pool_size

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

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

この PgBouncer インスタンスで許可されるクライアント接続の最大数。各データベースごとに 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 FDS

内部コマンド - 使用中のファイル記述子の一覧と、それらに紐付く内部状態を表示します。

接続ユーザー名が “pgbouncer” で、Unix ソケット経由で接続し、実行中のプロセスと同じ UID を持つ場合、実際の FD が接続経由で渡されます。 この仕組みはオンライン再起動に使用されます。 注意：Windows では動作しません。

このコマンドは内部イベントループをブロックするため、PgBouncer を使用中に使用してはなりません。

fd

ファイルディスクリプタの数値値。

task

pooler、client、または server のいずれか。

user

接続に使用される FD を利用するユーザー。

database

接続に使用される FD におけるデータベース。

addr

接続に使用される IP アドレス。Unix ソケットが使用されている場合は unix となる。

port

接続に使用される FD で利用されるポート。

cancel

この接続のキャンセルキー。

link

に対応するサーバー/クライアントの fd。アイドルの場合は NULL。

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 の状態設定を表示します。現在の状態は、有効、一時停止、一時停止中です。

プロセス制御コマンド

PAUSE [db]

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

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

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

DISABLE db

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

ENABLE db

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

RECONNECT [db]

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

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

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

KILL [db]

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

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

KILL_CLIENT id

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

例のコマンドは、KILL_CLIENT 1234 のように表示されます。

SUSPEND

すべてのソケットバッファがフラッシュされ、PgBouncer はそれらでのデータ受信を停止します。 コマンドは、すべてのバッファが空になるまで戻りません。 PgBouncer のオンライン再起動時に使用します。

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

RESUME [db]

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

SHUTDOWN

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

SHUTDOWN WAIT_FOR_SERVERS

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

SHUTDOWN WAIT_FOR_CLIENTS

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

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

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 のドキュメントより：

epoll、kqueue、devpoll、poll または select のサポートを無効にするには、環境変数 EVENT_NOEPOLL を設定します。

それぞれ 、EVENT_NODEVPOLL、EVENT_NOPOLL または EVENT_NOSELECT を設定することで可能です。

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

関連項目

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

https://www.pgbouncer.org/

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

Building

PgBouncer はコンパイルするためのいくつかの要素に依存しています：

• GNU Make 3.81+
• Libevent 2.0+
• pkg-config
• OpenSSL 1.0.1+（TLS 機能用）
• (オプション) c-ares は Libevent の evdns の代替として利用可能
• (オプション) LDAP ライブラリ
• (オプション) PAM ライブラリ

依存関係をインストールしたら、次のように実行します：

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

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

DNS ルックアップサポート

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

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

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

デフォルトでは、c-ares が利用可能であればそれを使用します。configure --with-cares を指定することで c-ares の使用を強制し、--without-cares を指定することで無効化できます。c-ares を使用しない（見つからないか無効化されている）場合、Libevent が使用されます。Libevent の evdns の使用を無効にするには --disable-evdns を指定し、libc に基づく実装にフォールバックします。

PAM 認証

PAM 認証を有効にするには、./configure にフラグ --with-pam を設定します（デフォルト値は no）。PAM サポートでコンパイルされた場合、ユーザーを PAM で検証するための新しいグローバル認証タイプ pam が利用可能になります。

LDAP 認証

LDAP 認証を有効にするには、./configure にフラグ --with-ldap を設定します（デフォルト値は no）。LDAP サポート付きでコンパイルされた場合、ユーザーを LDAP を使って検証するための新しいグローバル認証タイプ ldap が利用可能になります。

systemd 統合

systemd 統合を有効にするには、configure オプションを使用してください。これにより、--with-systemd を使用できるほか、systemd 253 以降では Type=notify（または Type=notify-reload）も利用可能です。ソケット活性化も可能です。例については etc/pgbouncer.service および etc/pgbouncer.socket を参照してください。

Git からビルドする

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

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

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

追加で必要なパッケージ: autoconf, automake, libtool, pandoc

テスト

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

Windows 上でのビルド

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

MinGW でビルドするには、通常通り以下を実行します：

$ ./configure
$ make

Unix からクロスコンパイルする場合:

$ ./configure --host=i586-mingw32msvc

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

Windows 上での実行

コマンドラインから実行する場合は通常通りですが、-d（デーモン化）、-R（再起動）、-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 - Source Releases Download

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.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 クライアント最終メッセージの内容を構築する際に strlcat() の戻り値を正しくチェックしていなかった。悪意あるバックエンドが長い nonce を含む SCRAM サーバー最終メッセージを送信すると、スタックオーバーフローを引き起こす可能性がある。
  • CVE-2026-6666 の修正：1.25.2 以前の PgBouncer では、サーバーが SQLSTATE フィールドを含まないエラー応答を送信した場合、ヌルポインタ参照の可能性があり、クラッシュを引き起こすおそれがあります。
  • 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 を使用できます。

• 修正

  • PAM 認証を修正するために、HBA ファイル内の 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 )

• 変更

  • RELOAD の際、TLS 設定が変更されていない場合は接続を再利用しない。以前は TLS 接続がある場合、すべての接続が RELOAD で再利用され、一時的に深刻なパフォーマンス低下を引き起こしていた。現在は TLS 設定が実際に変更された場合にのみ、この再利用が行われる。(#1157 )
  • プリペアドステートメントのサポートをデフォルトで有効化し、max_prepared_statements のデフォルト値は now 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 )
  • クライアントとの間でポストグレSQLプロトコルバージョンのネゴシエーションをサポートする。(#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 - 「オプションの設定」

• 修正
  • 1.20.0 で導入されたバグ修正の再現を修正しました。options を ignore_startup_parameters 内に配置した場合、options スタートアップパラメータ内に含まれる未知のパラメータを無視しなくなる問題を解消しました。(#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 パラメータをサポートしました。これにより、PGOPTIONS 環境変数を用いることが可能になります。psql および libpq が認識しているもの 。この変数を使用することで、起動時に任意の 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

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

• 修正
  • 修正: 関数 disconnect_client() で FATAL が発生: クライアントの状態が無効: 0 (#846 ) (1.18.0 で導入されたバグ)
  • 修正: 関数 server_proto() で FATAL: サーバーが異常状態: 14 (#849 ) (1.18.0 で導入されたバグ)
  • Python によるテストを実行するのに必要なファイルをリリース用ターボールに追加しました (#852 ) (1.19.0 で導入された新しいテスト)

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

• 機能

  • に auth_dbname オプションを追加し、auth_query を実行する対象のデータベースを指定します。(#764 )
  • SHOW STATE コマンドを追加し、PgBouncer がアクティブ、一時停止中、または一時停止状態かどうかを表示します。(#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 ビルドには、バージョン情報リソースファイルが含まれるようになりました。
  • Windows で CI によって作成されたビルドはもはや静的リンクされているため、依存関係を必要とせずに直接使用できます。

• 修正

  • 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_start == 0」メッセージは解消されました。発生原因が判明し、これ以上表示されないはずです。(#565 )
  • 再読み込みを修正しました。default_pool_size、min_pool_size、および res_pool_size を再読み込みしても、以前は機能していませんでした。

• クリーンアップ

  • Cirrus CI は now 使用 され 代わりに Travis CI が使用されません。
  • 通常通り、多数のテストが追加されています。
  • 「unclean 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 ジャーナルに送信されることが検出された場合、ログ出力に systemd のネイティブ関数を使用します。これにより、タイムスタンプや PID の重複出力が回避され、ログが若干きれいになります。また、ログに重大度などのメタデータが追加されるため、ジャーナルが syslog に転送された場合でも、メッセージに有用なメタデータが付与されます。
  • テストスイートの一部は now Windows で実行できるようになりました。
  • SHOW CONFIG は設定のデフォルト値も表示するようになりました。

• 修正

  • FreeBSD で so_reuseport オプションを修正しました。PgBouncer 1.12.0 の元のコードは FreeBSD では実際に動作していませんでした。 (#504 )
  • 1.14.0 で破損した、古い systemd バージョンを搭載したシステムでのコンパイルを修復しました。 (#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 は now default to 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 への参照を削除しました。すべての情報は now 、PgBouncer のドキュメントまたはウェブサイトにあります。
  • Libevent 1.x のサポートを削除しました。Libevent 2.x が必須です。Libevent の検出は now pkg-config を使用して行われます。
  • macOS および Windows でのコンパイラ警告を修正しました。これらのプラットフォームでのビルドは now 警告が発生しなくなりました。
  • 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 )
  • GSSENCRequest パケットの処理。PostgreSQL 12 で追加。現在は何も実行しないが、「不正なパケットヘッダー」という誤ったエラーメッセージを避けるために存在する。
• クリーンアップ
  • テストスイートの多数の改善と、いくつかの新規テスト
  • 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 の再読み込み後に「ログインクエリからの予期しない応答」を回避する (#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 に移行する
  • シグナルのドキュメントを改善
  • クイックスタートドキュメントの改善
  • Document SET コマンド
  • 必須ソフトウェアのリスト
  • 警告を修正-Wimplicit-fallthrough
  • 各種 SHOW フィールドのドキュメントを追加
  • 再読み込みおよびDNS変更時の再接続動作の説明
  • KILL が実行された後は RESUME が必要なドキュメント
  • サーバーのライフタイムに関するドキュメントを明確化
  • メッセージおよびドキュメント内のスペルミスと大文字小文字の修正
  • テストでの 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 フィールドを追加します。
  • に maxwait_us フィールドを SHOW POOLS 出力に追加します。
  • wait および wait_us フィールドを SHOW コマンドの出力に追加します。
  • に新しいコマンド SHOW STATS_TOTALS と SHOW STATS_AVERAGES を追加します。
  • SHOW STATS でクエリとトランザクションを個別に追跡します。total_requests、avg_req、および avg_query フィールドは、新しいフィールドに置き換えられました。
  • に wait_time を SHOW STATS に追加します。
• 修正内容
  • 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 ハンドシェイク中のメモリリークを修正。
  • 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

  • 認証応答の処理中に NoticeResponse をスキップする。そうでなければ、サーバーでの詳細ログ出力がログイン失敗を引き起こす。

  • 管理コンソール: auth_type=any の場合、auth_user を指定してください。それ以外の場合、ログ出力がクラッシュする可能性があります（#67）。

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

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

• 機能

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

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

    auth_query 認証ユーザー下で実行する 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 でリモート 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)
  • Coverty で検出されたエラーを修正。 (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) を使用していたが、ソースツリーのパスにシンボリックリンクが含まれる場合にビルドが失敗していた。コードは現在、平文の文字列のみを扱うように変更された。
  • console: now 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 Rembialkowski)
  • 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 から取得されます。
  • takeover コードで ‘*’ を正しく解析する。
  • 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() を非ブロッキングにするために、並列にリクエストを処理する単一のスレッドを使用して、アドレス解決を行う。
  • pthread コンパイルを有効にしてください。compat getaddrinfo_a が使用される場合。
  • 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 サーバー設定パラメーターは、正確な大文字・小文字を使用する必要があります。
  • 管理コンソール：クライアントに日時、タイムゾーンおよび標準出力サーバー設定を送信します。

• 内部のクリーンアップ

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

PgBouncer 1.3.x

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

• 修正
  • 接続時に迅速な失敗ロジックを適用します。サーバーが障害状態の場合、クライアントは接続時にエラーを受け取ります。
  • 再読み込み時にチェックするため、自動生成されたデータベースにタグを付けないでください。それらは設定に存在しないため、殺されてしまいます。
  • アプリケーション名パラメータをデフォルトで無視します。これにより、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 で有用です。
  • ログイン失敗の原因となったユーザー名やデータベース名を明示するように、切断メッセージを改善します。
• 修正内容
  • クライアントがログインを試みない状態でも、再起動を繰り返すという従来の高速失敗再起動ロジックを変更しました。永続的に破損したデータベースやユーザーの場合、この動作は不快でした。
  • ログ出力関数が古い 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
    

    To stop and unregister:

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

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

    > regsrv32 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 Schocke による報告およびテストのおかげで。

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

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

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

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

• 修正

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

    Why event_del() report failure first time is still mystery.

  • –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’ の代わりに使用してください (Jorgen Austvik)
  • glibc が無意味になるため、_GNU_SOURCE を定義してください。
  • libevent 1.1 のリンクテストを通過させ、後に「1.3b+ が必要」を報告できるようにする
  • 古い pidfile を検出し、削除する。

Devrim GUNDUZ および 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> を使用してください。
  • 中断停止（SIGINT からの再開）を RESUME/SIGUSR2 で実行する場合、次回の 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 ソケットがリスニングしているか確認するために試行されます。 これにより、-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= で指定されたホスト名を受け入れます。
    • ホストにカスタム Unix ソケットの場所を許可する
    • クォートされた値を許可: password=’ asd’‘foo’

  • 新しい設定変数: server_reset_query は、リリース直後にすぐに送信されます

  • 新しい設定変数: サーバーの接続割り当て方式を LIFO と RR の間で切り替えるための server_round_robin。

  • でアイドル状態の接続に対して送信された Cancel パケットは、もはや接続を切断しなくなりました。

  • からの ^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 からの中断)
• 機能
  • 一時停止 ；再開 ；正常に動作しています。
  • 管理コンソールコマンドの解析のクリーンアップ。
  • 価格の高い in-list アサートチェックを無効化します。

2007-04-19 - PgBouncer 1.0.7 - “With Vitamin A-Z

• 修正
  • send() の間にエラー/通知パケットが発生し、アサートがトリガーされる。バッファリングのロジックを完全に削除することで修正する。pgbouncer は明示的にバッファを保持しないため、この処理は不要である。これは MSG_MORE でバッファリングをカーネルに押し出していた時代の残骸である。
  • また、送信がブロック解除されたときに recv() のロジックを呼び出さないようにしてください。
  • admin_users および stats_users の検索コードで部分一致が正しく処理されない問題を修正。
  • UNIX ソケットのピア UID を取得する方法を標準化し、getpeereid() を使用する。

2007-04-12 - PgBouncer 1.0.6 - “Daily Dose

• 修正
  • 「トーケイ中におけるメンテナンスの無効化」の修正により、メンテナンスが完全に無効化される可能性がある。修正する。
  • 用の FreeBSD へのコンパイル修正、<sys/ucred.h> は <sys/param.h> が必要です。 Robert Gogolok による報告に感謝します。

2007-04-11 - PgBouncer 1.0.5 - 「今日はこれで十分」

• 修正
  • オンライン再起動のバグを修正：
    • Set -> サーバーのアイドル状態を待機可能にします。
    • 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 セクション at Stack Overflow

• GitHub でのコミュニティディスカッション

8 - よくある質問

PgBouncer への接続方法

PgBouncer は Postgres サーバーとして動作するため、クライアントを PgBouncer のポートに接続するだけでよい。

複数のサーバー間でクエリを負荷分散するには？

PgBouncer には内部的なマルチホスト構成がありません。 外部ツールを介して実現可能です：

1. DNS ラウンドロビン。1 つのドメイン名の背後にある複数の IP アドレスを使用します。PgBouncer は新しい接続を確立するたびに DNS を照会しません。代わりに、すべての IP アドレスをキャッシュし、内部でラウンドロビンを行います。注意：1 つの名前に 8 つ以上の IP アドレスが関連付けられている場合、DNS バックエンドは EDNS0 プロトコルをサポートしている必要があります。詳細については README を参照してください。

2. TCP接続のロードバランサーを使用してください。LVS または HAProxy が適した選択肢のようです。PgBouncer側では、server_lifetime を小さく設定し、server_round_robin を有効にするのが良いでしょう。デフォルトでは、アイドル状態の接続はLIFOアルゴリズムで再利用されますが、ロードバランシングが必要な状況では、この動作が十分に機能しない可能性があります。

フェイルオーバーの方法

PgBouncer には内部的なフェイルオーバーホストの設定や検出機能がありません。 外部ツールを用いることで可能になります：

1. DNS の再構成：DNS 名の背後にある IP アドレスが再構成された場合、PgBouncer は新しいサーバーに再接続します。この動作は、次の 2 つの設定パラメーターで調整できます。dns_max_ttl はホスト名の有効期間を、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 をゼロ以外の値に設定する必要があります。詳細については、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 のホップがクエリごとにわずかな遅延を追加するという欠点があります。

最終的には、パフォーマンス要件に最も適したモデルをテストして選定する必要があります。また、ウェブサーバーまたはデータベースサーバーの障害発生時に PgBouncer を導入することでアプリケーションのフェイルオーバーにどのような影響を与えるかを検討する必要があります。