設定: pgbouncer.ini

PgBouncer 設定ファイル (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] セクションでユーザーごとに設定することもできます。

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

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

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

デフォルト： 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回までしか許可されません）。

例:

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