# 設定: pgbouncer.ini

> PgBouncer 設定ファイル (pgbouncer.ini) リファレンス

---

LLMSインデックス: [llms.txt](/ja/llms.txt)

---

--------

## 説明 {#description}

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

--------

## 汎用設定 {#generic-settings}

### logfile {#logfile}

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

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

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

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

### pidfile {#pidfile}

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

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

### listen_addr {#listen_addr}

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

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

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

### listen_port {#listen_port}

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

デフォルト： 6432

### unix_socket_dir {#unix_socket_dir}

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

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

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

### unix_socket_mode {#unix_socket_mode}

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

デフォルト： 0777

### unix_socket_group {#unix_socket_group}

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

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

### user {#user}

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

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

### pool_mode {#pool_mode}

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

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

### max_client_conn {#max_client_conn}

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

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

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

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

```text
max_client_conn + (max pool_size * total databases)
```

理論上の最大値は、誰かが意図的に特殊な負荷を設計しない限り、達成されることはない。それでも、ファイル記述子の数を安全に高い値に設定すべきである。

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

デフォルト： 100

### default_pool_size {#default_pool_size}

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

デフォルト： 20

### min_pool_size {#min_pool_size}

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

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

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

デフォルト： 0（無効）

### reserve_pool_size {#reserve_pool_size}

プールに許可する追加接続数（`reserve_pool_timeout` を参照）。0 は無効化を意味する。

デフォルト： 0（無効）

### reserve_pool_timeout {#reserve_pool_timeout}

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

デフォルト： 5.0

### max_db_connections {#max_db_connections}

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

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

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

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

### max_db_client_connections {#max_db_client_connections}

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

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

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

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

### max_user_connections {#max_user_connections}

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

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

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

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

### max_user_client_connections {#max_user_client_connections}

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

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

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

### server_round_robin {#server_round_robin}

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

デフォルト： 0

### track_extra_parameters {#track_extra_parameters}

デフォルトでは、PgBouncer はクライアントごとに `client_encoding`、`datestyle`、`timezone`、`standard_conforming_strings`、`application_name` のパラメータを追跡します。他のパラメータを追跡可能にするには、ここに指定できます。これにより、PgBouncer はそれらのパラメータをクライアント変数キャッシュに保持し、クライアントがアクティブになるとサーバーに復元することを認識します。

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

注意： 多くのパラメータはこの方法では追跡できません。追跡できるのは、Postgres がクライアントに報告するパラメータのみです。Postgres には [クライアントに報告するパラメータの公式リスト](https://www.postgresql.org/docs/15/protocol-flow.html#PROTOCOL-ASYNC)があります。ただし、Postgres 拡張機能はこのリストを変更できます。拡張機能は独自にパラメータを追加して報告することができ、また、Postgres が報告していない既存のパラメータを報告し始めることがあります。特に、Citus 12.0 以降では `search_path` の報告が行われるようになります。

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

デフォルト： IntervalStyle

### ignore_startup_parameters {#ignore_startup_parameters}

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

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

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

[options-startup]: https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-OPTIONS

デフォルト： 空

### peer_id {#peer_id}

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

デフォルト： 0

### disable_pqexec {#disable_pqexec}

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

デフォルト： 0

### application_name_add_host {#application_name_add_host}

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

デフォルト： 0

### conffile {#conffile}

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

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

### service_name {#service_name}

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

デフォルト： `pgbouncer`

### job_name {#job_name}

`service_name` への別名。

### stats_period {#stats_period}

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

デフォルト： 60

### max_prepared_statements {#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 はこれらのプリペアドステートメントを処理するために、最大で次の量のメモリが必要です：

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

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

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

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

```text
ERROR:  cached plan must not change result type
```

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

デフォルト： 200

### scram_iterations {#scram_iterations}

SCRAM-SHA-256 を使用してパスワードを暗号化する際に実行する計算反復回数です。反復回数を増やすことで、保存されたパスワードに対するブルートフォース攻撃に対する保護が強化されますが、認証が遅くなります。

デフォルト： 4096

--------

## 認証設定 {#authentication-settings}

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

### auth_type {#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_hba_file}

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

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

### auth_ident_file {#auth_ident_file}

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

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

### auth_file {#auth_file}

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

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

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

### 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 {#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 {#auth_dbname}

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

### auth_ldap_options {#auth_ldap_options}

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

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

--------

## ログ設定 {#log-settings}

### syslog {#syslog}

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

デフォルト： 0

### syslog_ident {#syslog_ident}

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

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

### syslog_facility {#syslog_facility}

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

デフォルト： `daemon`

### log_connections {#log_connections}

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

デフォルト： 1

### log_disconnections {#log_disconnections}

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

デフォルト： 1

### log_pooler_errors {#log_pooler_errors}

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

デフォルト： 1

### log_stats {#log_stats}

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

デフォルト： 1

### verbose {#verbose}

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

デフォルト： 0

--------

## 管理コンソールのアクセス制御 {#console-access-control}

### admin_users {#admin_users}

コンソール上ですべてのコマンドを実行できるように許可されるデータベースユーザーのカンマ区切りリスト。`auth_type` が `any` の場合、この設定は無視され、管理者として任意のユーザー名が許可されます。

デフォルト： 空

### stats_users {#stats_users}

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

デフォルト： 空

--------

## 接続の健全性チェック、タイムアウト {#connection-sanity-checks-timeouts}

### server_reset_query {#server_reset_query}

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

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

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

デフォルト： `DISCARD ALL`

### server_reset_query_always {#server_reset_query_always}

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

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

デフォルト： 0

### server_check_delay {#server_check_delay}

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

デフォルト： 30.0

### server_check_query {#server_check_query}

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

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

`<empty>` が有効な場合、健全性チェックとして空のクエリを送信する。

デフォルト： `<empty>`

### server_fast_close {#server_fast_close}

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

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

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

デフォルト： 0

### server_lifetime {#server_lifetime}

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

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

デフォルト： 3600.0

### server_idle_timeout {#server_idle_timeout}

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

デフォルト： 600.0

### server_connect_timeout {#server_connect_timeout}

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

デフォルト： 15.0

### server_login_retry {#server_login_retry}

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

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

デフォルト： 15.0

### client_login_timeout {#client_login_timeout}

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

デフォルト： 60.0

### autodb_idle_timeout {#autodb_idle_timeout}

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

デフォルト： 3600.0

### dns_max_ttl {#dns_max_ttl}

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

デフォルト： 15.0

### dns_nxdomain_ttl {#dns_nxdomain_ttl}

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

デフォルト： 15.0

### dns_zone_check_period {#dns_zone_check_period}

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

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

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

デフォルト： 0.0（無効）

### resolv_conf {#resolv_conf}

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

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

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

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

### query_wait_notify {#query_wait_notify}

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

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

デフォルト： 5

--------

## TLS 設定 {#tls-settings}

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

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

### client_tls_sslmode {#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 {#client_tls_key_file}

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

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

### client_tls_cert_file {#client_tls_cert_file}

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

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

### client_tls_ca_file {#client_tls_ca_file}

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

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

### client_tls_protocols {#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 {#client_tls_ciphers}

許可される TLS キャプチャ、OpenSSL の構文を使用。ショートカット：

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

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

デフォルト： `default`

### client_tls13_ciphers {#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 {#client_tls_ecdhcurve}

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

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

デフォルト： `auto`

### client_tls_dheparams {#client_tls_dheparams}

DHE キー交換タイプ。

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

デフォルト： `auto`

### server_tls_sslmode {#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 {#server_tls_ca_file}

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

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

### server_tls_key_file {#server_tls_key_file}

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

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

### server_tls_cert_file {#server_tls_cert_file}

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

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

### server_tls_protocols {#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 {#server_tls_ciphers}

許可される TLS キャプチャ、OpenSSL の構文を使用。ショートカット：

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

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

デフォルト： `default`

### server_tls13_ciphers {#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>`

--------

## 危険なタイムアウト {#dangerous-timeouts}

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

### query_timeout {#query_timeout}

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

デフォルト： 0.0（無効）

### query_wait_timeout {#query_wait_timeout}

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

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

デフォルト： 120.0

### cancel_wait_timeout {#cancel_wait_timeout}

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

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

デフォルト： 10.0

### client_idle_timeout {#client_idle_timeout}

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

デフォルト： 0.0（無効）

### idle_transaction_timeout {#idle_transaction_timeout}

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

デフォルト： 0.0（無効）

### transaction_timeout {#transaction_timeout}

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

デフォルト： 0.0（無効）

### suspend_timeout {#suspend_timeout}

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

デフォルト： 10

--------

## 低レベルのネットワーク設定 {#low-level-network-settings}

### pkt_buf {#pkt_buf}

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

デフォルト： 4096

### max_packet_size {#max_packet_size}

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

デフォルト： 2147483647

### listen_backlog {#listen_backlog}

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

デフォルト： 128

### sbuf_loopcnt {#sbuf_loopcnt}

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

デフォルト： 5

### so_reuseport {#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}

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

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

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

### tcp_socket_buffer {#tcp_socket_buffer}

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

### tcp_keepalive {#tcp_keepalive}

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

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

デフォルト： 1

### tcp_keepcnt {#tcp_keepcnt}

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

### tcp_keepidle {#tcp_keepidle}

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

### tcp_keepintvl {#tcp_keepintvl}

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

### tcp_user_timeout {#tcp_user_timeout}

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

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

デフォルト： 0

--------

## [databases] {#section-databases}

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

```ini
dbname = connection string
```

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

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

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

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

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

```ini
* = host=foo
```

その後、データベース `bar` を指定して PgBouncer に接続すると、実際にはエントリが存在するかのように振る舞います。

```ini
bar = host=foo dbname=bar
```

存在する（`dbname` のデフォルトがクライアント側のデータベース名であるため、それを活用している；以下を参照）。

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

### dbname {#dbname}

宛先データベース名。

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

### host {#host}

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

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

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

例:

```text
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 {#port}

デフォルト： 5432

### user {#user-1}

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

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

### password {#password}

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

### auth_user {#auth_user-1}

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

### auth_query {#auth_query-1}

グローバルな `auth_query` 設定の上書き。指定された場合に有効。SQL文全体はシングルクォートで囲む必要がある。

### auth_dbname {#auth_dbname-1}

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

### pool_size {#pool_size}

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

### min_pool_size {#min_pool_size-1}

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

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

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

### reserve_pool_size {#reserve_pool_size-1}

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

### connect_query {#connect_query}

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

### pool_mode {#pool_mode-1}

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

### load_balance_hosts {#load_balance_hosts}

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

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

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

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

デフォルト： `round-robin`

### max_db_connections {#max_db_connections-1}

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

### max_db_client_connections {#max_db_client_connections-1}

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

### server_lifetime {#server_lifetime-1}

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

### client_encoding {#client_encoding}

クライアントからサーバーに `client_encoding` を要求します。

### datestyle {#datestyle}

特定の `datestyle` をサーバーから取得します。

### timezone {#timezone}

特定の `timezone` をサーバーから取得します。

--------

## セクション [users] {#section-users}

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

```ini
user1 = settings
```

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

```ini
user1 = pool_mode=session
```

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

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

### pool_size {#pool_size-1}

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

### reserve_pool_size {#reserve_pool_size-2}

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

### pool_mode {#pool_mode-2}

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

### max_user_connections {#max_user_connections-1}

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

### query_timeout {#query_timeout-1}

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

### idle_transaction_timeout {#idle_transaction_timeout-1}

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

### transaction_timeout {#transaction_timeout-1}

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

### client_idle_timeout {#client_idle_timeout-1}

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

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

### max_user_client_connections {#max_user_client_connections-1}

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

--------

## セクション [peers] {#section-peers}

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

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

[cancel-problem-video]: https://www.youtube.com/watch?v=X-nCHcZ6vQU

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

```ini
peer_id = connection string
```

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

```ini
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 {#host-1}

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

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

例:

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

### port {#port-1}

デフォルト： 6432

### pool_size {#pool_size-2}

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

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

--------

## Include ディレクティブ {#include-directive}

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

```ini
%include filename
```

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

--------

## 認証ファイル形式 {#authentication-file-format}

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

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

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

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

```text
"md5" + md5(password + username)
```

ユーザー `admin` はパスワード `1234` を持ち、ハッシュ化されたパスワードは MD5 により生成され、結果として `md545f2603610af569b6155c45067268c6b` になります。

PostgreSQL SCRAM シークレット形式:

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

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

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

### 制限事項 {#limitations}

パスワードが平文で保存されている場合、バックエンドサーバーで使用される任意のパスワードベースの認証に使用できます。平文、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` の代わりに使用することもできます。

### マネージドサーバーに関する注意事項 {#note-on-managed-servers}

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

一部のクラウドプロバイダ（例：AWS RDS）では、パスワードを取得するためにPostgreSQLのセンシティブなシステムテーブルへのアクセスが禁止されています。最も特権的なユーザー（例：`rds_superuser` のメンバー）に対しても、`select * from pg_authid` は `ERROR: permission denied for table pg_authid` を返します。これは既知の動作です（[blog](https://aws.amazon.com/blogs/database/best-practices-for-migrating-postgresql-databases-to-amazon-rds-and-amazon-aurora/)）。

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

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

```bash
$ 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-file-format}

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-map-file-format}

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`、正規表現。

--------

## 例 {#examples}

小さな例での設定:

```ini
[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
```

データベースの例:

```ini
[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` 用のセキュアな関数の例：

```sql
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 プロセスの設定例。最初のプロセスの設定：

```ini
[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 番目のプロセスの設定:

```ini
[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
```

--------

## 関連項目 {#see-also}

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

<https://www.pgbouncer.org/>

---

逆リンク:

- [変更履歴](/ja/docs/pgbouncer/changelog/)
- [FAQ](/ja/docs/pgbouncer/faq/)
- [機能](/ja/docs/pgbouncer/features/)
- [使用法](/ja/docs/pgbouncer/usage/)