# Конфигурация: pgbouncer.ini

> Справочник по файлу конфигурации PgBouncer (pgbouncer.ini)

---

Индекс LLMS: [llms.txt](/ru/llms.txt)

---

--------

## Описание {#description}

Файл конфигурации имеет формат «ini». Имена секций заключаются между `[` и `]`.
Строки, начинающиеся с `;` или `#`, считаются комментариями и игнорируются.
Символы `;` и `#` не имеют специального значения в других позициях строки.

--------

## Общие параметры {#generic-settings}

### logfile {#logfile}

Задаёт файл журнала. Для демонизации (`-d`) обязательно задать этот параметр или `syslog`.

Файл журнала остаётся открытым, поэтому после ротации следует выполнить
`kill -HUP` или `RELOAD;` в консоли. В Windows службу необходимо остановить и запустить.

Обратите внимание: сам по себе параметр `logfile` не отключает ведение журнала
в stderr. Для этого используйте параметр командной строки `-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` приведены на странице man используемой оболочки. Примечание:
`ulimit` неприменим в Windows.

По умолчанию: 100

### default_pool_size {#default_pool_size}

Максимальное число серверных соединений на пару «пользователь — база данных».
Его можно переопределить параметром `pool_size` в конфигурации базы данных или
пользователя; это значение используется, если для базы или пользователя не
задан отдельный `pool_size`.

По умолчанию: 20

### min_pool_size {#min_pool_size}

Добавлять серверные соединения в пул, если их число ниже указанного. Это улучшает
поведение при резком возвращении обычной нагрузки после периода полной
неактивности. Фактически значение ограничено размером пула.

Применяется только к пулам, для которых выполняется хотя бы одно условие:

* в записи пула в секции `[database]` задан ключ `user` — принудительный пользователь;
* к пулу подключён хотя бы один клиент.

По умолчанию: 0 (отключено)

### reserve_pool_size {#reserve_pool_size}

Число дополнительных соединений, разрешённых для пула (см. `reserve_pool_timeout`). 0 отключает резервный пул.

По умолчанию: 0 (отключено)

### reserve_pool_timeout {#reserve_pool_timeout}

Если клиент не обслужен за это время, используются дополнительные соединения
из резервного пула. 0 отключает параметр. [seconds]

По умолчанию: 5.0

### max_db_connections {#max_db_connections}

Не разрешать для одной базы данных больше указанного числа серверных соединений
независимо от пользователя. Учитывается база данных PgBouncer, к которой
подключился клиент, а не база PostgreSQL исходящего соединения.

Параметр также можно задать для каждой базы данных в секции `[databases]`.

Обратите внимание: после достижения ограничения закрытие клиентского соединения
одного пула не позволит немедленно установить серверное соединение другого пула,
поскольку серверное соединение первого ещё открыто. Как только оно закроется
по тайм-ауту неактивности, для ожидающего пула сразу откроется новое соединение.

По умолчанию: 0 (без ограничений)

### max_db_client_connections {#max_db_client_connections}

Не разрешать для одной базы данных больше указанного числа клиентских соединений
с PgBouncer независимо от пользователя. Учитывается база данных PgBouncer, к
которой подключился клиент, а не база PostgreSQL исходящего соединения.

Следует задать число не меньше max_db_connections. Разность этих значений можно
рассматривать как число соединений с базой данных, способных находиться в очереди
в ожидании завершения активных соединений.

Параметр также можно задать для каждой базы данных в секции `[databases]`.

По умолчанию: 0 (без ограничений)

### max_user_connections {#max_user_connections}

Не разрешать одному пользователю больше указанного числа серверных соединений
независимо от базы данных. Учитывается связанный с пулом пользователь PgBouncer:
пользователь серверного соединения либо, если он не задан, пользователь клиента.

Параметр также можно задать для каждого пользователя в секции `[users]`.

Обратите внимание: после достижения ограничения закрытие клиентского соединения
одного пула не позволит немедленно установить серверное соединение другого пула,
поскольку серверное соединение первого ещё открыто. После его закрытия по
тайм-ауту неактивности для ожидающего пула сразу откроется новое соединение.

По умолчанию: 0 (без ограничений)

### max_user_client_connections {#max_user_client_connections}

Не разрешать одному пользователю больше указанного числа клиентских соединений
независимо от базы данных. Значение должно быть больше max_user_connections.
Разность max_user_client_connections и max_user_connections можно рассматривать
как максимальный размер очереди пользователя.

Параметр также можно задать для каждого пользователя в секции `[users]`.

По умолчанию: 0 (без ограничений)

### server_round_robin {#server_round_robin}

По умолчанию PgBouncer повторно использует серверные соединения по принципу
LIFO (последним пришёл — первым вышел), поэтому основная нагрузка приходится на
несколько соединений. Это обеспечивает лучшую производительность, если базу
данных обслуживает один сервер. Но если за адресом базы работает циклическая
система — 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+ заставляет Postgres также сообщать `search_path`.

Протокол Postgres позволяет задавать параметры непосредственно в пакете запуска
или внутри [`options` пакета запуска][options-startup]. `track_extra_parameters`
поддерживает оба способа. Однако включить в `track_extra_parameters` сам
`options` нельзя — только содержащиеся в `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 в группе связанных процессов PgBouncer. Значение `peer_id` должно быть
уникальным в группе. При значении 0 одноранговое взаимодействие PgBouncer
отключено. Подробнее см. документацию секции `[peers]`. Максимальное значение
`peer_id` — 16383.

По умолчанию: 0

### disable_pqexec {#disable_pqexec}

Отключить протокол Simple Query (PQexec). В отличие от Extended Query, Simple
Query допускает несколько запросов в одном пакете, что делает возможными
некоторые классы атак с внедрением SQL. Отключение может повысить безопасность,
но работать продолжат только клиенты, использующие исключительно Extended Query.

По умолчанию: 0

### application_name_add_host {#application_name_add_host}

Добавлять адрес и порт клиентского узла к имени приложения при установлении
соединения. Это помогает определить источник ошибочных запросов и других проблем.
Логика применяется только при запуске соединения. Если позднее `application_name`
изменяется командой `SET`, PgBouncer больше его не меняет.

По умолчанию: 0

### conffile {#conffile}

Показывает местоположение текущего файла конфигурации. После изменения PgBouncer
использует другой файл при следующем `RELOAD` / `SIGHUP`.

По умолчанию: файл из командной строки

### service_name {#service_name}

Используется при регистрации службы win32.

По умолчанию: `pgbouncer`

### job_name {#job_name}

Псевдоним для `service_name`.

### stats_period {#stats_period}

Задаёт частоту обновления средних значений в различных командах `SHOW` и записи
агрегированной статистики в журнал (но см. `log_stats`). [seconds]

По умолчанию: 60

### max_prepared_statements {#max_prepared_statements}

При ненулевом значении PgBouncer отслеживает команды протокольного уровня,
относящиеся к именованным подготовленным операторам, которые клиент отправляет
в транзакционном режиме пула и режиме на уровне операторов. PgBouncer гарантирует,
что любой подготовленный клиентом оператор доступен в обслуживающем серверном
соединении, даже если изначально он был подготовлен в другом соединении.

PgBouncer анализирует все запросы, отправленные клиентами как подготовленные
операторы, и присваивает каждой уникальной строке запроса внутреннее имя формата
`PGBOUNCER_{unique_id}`. Если одна строка подготавливается несколько раз, в том
числе разными клиентами, запросы используют общее внутреннее имя. На настоящем
сервере PostgreSQL PgBouncer подготавливает оператор только под внутренним, а не
клиентским именем. PgBouncer запоминает имя, присвоенное клиентом каждому
подготовленному оператору, и перед отправкой на сервер переписывает использующую
его команду, заменяя клиентское имя внутренним, например `my_prepared_statement`
на `PGBOUNCER_123`. Если требуемый клиенту оператор ещё не подготовлен на сервере,
например потому, что клиенту назначен другой сервер, PgBouncer прозрачно
подготавливает оператор перед выполнением.

Примечание: отслеживание и переписывание не работает для команд подготовленных
операторов уровня SQL, поэтому `PREPARE`, `EXECUTE` и `DEALLOCATE` передаются
Postgres без изменений. Исключение — `DEALLOCATE ALL` и `DISCARD ALL`: они
работают ожидаемым образом и удаляют подготовленные операторы, которые PgBouncer
отслеживал для отправившего команду клиента.

Значение параметра определяет число подготовленных операторов, сохраняемых
активными в кэше LRU одного серверного соединения. При значении 0 поддержка
подготовленных операторов в транзакционном режиме и режиме на уровне операторов
отключается. Для лучшей производительности следует задать значение больше числа
часто используемых приложением подготовленных операторов. Чем оно выше, тем
больше памяти занимает каждое соединение PgBouncer на сервере PostgreSQL,
поскольку в нём остаётся подготовлено больше запросов. Увеличивается и потребление
памяти самим PgBouncer, которому нужно отслеживать строки запросов.

Однако влияние на потребление памяти PgBouncer невелико:
- каждый уникальный запрос хранится один раз в глобальном кэше запросов;
- каждое клиентское соединение хранит буфер для переписывания пакетов. Его
  размер не превышает 4 размеров `pkt_buf`. Этот предел достигается редко —
  только если запросы подготовленных операторов в 2–4 раза больше `pkt_buf`.

Рассмотрим пример:
- имеется 1000 активных клиентов;
- клиенты подготавливают 200 уникальных запросов;
- средний размер запроса — 5kB;
- параметр `pkt_buf` имеет значение по умолчанию 4096 (4kB).

Тогда PgBouncer требуется не более следующего объёма памяти для обработки подготовленных операторов:

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

Отслеживание подготовленных операторов увеличивает не только расход памяти, но
и загрузку CPU, поскольку PgBouncer анализирует и переписывает запросы. Чтобы
использовать для обработки несколько ядер, несколько экземпляров 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`, но указанное имя пользователя игнорируется. Все базы данных должны быть настроены для входа от конкретного пользователя. Кроме того, консольная база разрешает любому пользователю вход как администратору.
- **`hba`**: фактический тип аутентификации загружается из `auth_hba_file`. Это позволяет применять разные методы для разных путей доступа: например, для соединений через Unix-сокет — `peer`, а для TCP обязательно использовать TLS.
- **`ldap`**: пользователи аутентифицируются на сервере LDAP, как в PostgreSQL (подробности см. <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}

Файл конфигурации HBA, используемый при `auth_type` со значением `hba`.
Подробности см. ниже в разделе [Формат файла HBA](#hba-file-format).

По умолчанию: не задан

### auth_ident_file {#auth_ident_file}

Файл сопоставления идентификаторов, используемый при `auth_type` со значением
`hba` и заданном сопоставлении пользователей. Подробности см. ниже в разделе
[Формат файла сопоставления ident](#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}

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 означает,
что соединение используется один раз, а затем закрывается. [seconds]

Параметр также можно задать для каждой базы данных в секции `[databases]`.

По умолчанию: 3600.0

### server_idle_timeout {#server_idle_timeout}

Серверное соединение закрывается после указанного числа секунд бездействия.
Значение 0 отключает тайм-аут. [seconds]

По умолчанию: 600.0

### server_connect_timeout {#server_connect_timeout}

Если соединение и вход не завершены за указанное время, соединение закрывается. [seconds]

По умолчанию: 15.0

### server_login_retry {#server_login_retry}

Если вход на сервер не удался из-за ошибки соединения или аутентификации, пул
ждёт указанное время до повторной попытки. В период ожидания новые клиенты,
пытающиеся подключиться к недоступному серверу, немедленно получат ошибку без
новой попытки соединения. [seconds]

Так клиенты не накапливаются в очереди в ожидании серверного соединения, когда
сервер не работает. Однако при кратковременном отказе, например во время
перезапуска или из-за ошибочной конфигурации, пул рассмотрит новое соединение
не раньше истечения этого времени. Плановыми событиями, такими как перезапуск,
обычно следует управлять командой `PAUSE`, чтобы избежать задержки.

По умолчанию: 15.0

### client_login_timeout {#client_login_timeout}

Если клиент подключился, но не успел войти за указанное время, он отключается.
Это главным образом предотвращает блокировку `SUSPEND` и, следовательно,
перезапуска без остановки обслуживания неработающими соединениями. [seconds]

По умолчанию: 60.0

### autodb_idle_timeout {#autodb_idle_timeout}

Автоматически созданные через `*` пулы баз данных освобождаются после указанного
числа секунд бездействия. При этом их статистика также забывается. [seconds]

По умолчанию: 3600.0

### dns_max_ttl {#dns_max_ttl}

Сколько времени можно кэшировать результаты поиска DNS. Фактический TTL DNS игнорируется. [seconds]

По умолчанию: 15.0

### dns_nxdomain_ttl {#dns_nxdomain_ttl}

Сколько времени можно кэшировать ошибки DNS и результаты поиска DNS для NXDOMAIN. [seconds]

По умолчанию: 15.0

### dns_zone_check_period {#dns_zone_check_period}

Период проверки изменения серийного номера зоны.

PgBouncer может получать зоны DNS из имён узлов — всё после первой точки — и
периодически проверять изменение серийного номера зоны. При изменении повторно
разрешаются все имена узлов зоны. Если меняется IP-адрес узла, его соединения
признаются недействительными.

Работает только с бэкендом c-ares (параметр `configure` `--with-cares`).

По умолчанию: 0.0 (disabled)

### resolv_conf {#resolv_conf}

Местоположение пользовательского файла `resolv.conf`. Он позволяет задавать
собственные серверы DNS и другие параметры разрешения имён независимо от
глобальной конфигурации операционной системы.

Требуется бэкенд evdns (>= 2.0.3) или c-ares (>= 1.15.0).

Файл разбирается библиотекой бэкенда DNS, а не PgBouncer. Допустимый синтаксис
и директивы описаны в документации библиотеки.

По умолчанию: пусто (используются значения операционной системы по умолчанию)

### query_wait_notify {#query_wait_notify}

Время нахождения клиента в очереди до отправки PgBouncer уведомления о постановке в очередь. [seconds]

Значение 0 отключает уведомление.

По умолчанию: 5

--------

## Параметры TLS {#tls-settings}

Если содержимое файла сертификата или ключа изменено без изменения имени файла
в конфигурации, после RELOAD новые соединения будут использовать новое содержимое.
Существующие соединения не закроются. Если по соображениям безопасности все
соединения должны как можно скорее перейти на новые файлы, после RELOAD
рекомендуется выполнить RECONNECT.

Изменение любого параметра TLS автоматически запускает RECONNECT по соображениям безопасности.

### client_tls_sslmode {#client_tls_sslmode}

Режим TLS для соединений от клиентов. По умолчанию TLS отключён. При включении
обязательно настроить `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-bit ECDH), имя кривой.

По умолчанию: `auto`

### client_tls_dheparams {#client_tls_dheparams}

Тип обмена ключами DHE.

Допустимые значения: `none` (DH отключён), `auto` (2048-bit DH), `legacy` (1024-bit DH).

По умолчанию: `auto`

### server_tls_sslmode {#server_tls_sslmode}

Режим TLS для соединений с серверами PostgreSQL. Режим по умолчанию — `prefer`.

- **`disable`**: обычный TCP. TLS даже не запрашивается у сервера.
- **`allow`**: FIXME: если сервер отклоняет обычное соединение, попробовать TLS?
- **`prefer`**: сначала у PostgreSQL всегда запрашивается соединение TLS. При отказе устанавливается обычное соединение 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`,
чтобы он срабатывал лишь при проблемах сети. [seconds]

По умолчанию: 0.0 (disabled)

### query_wait_timeout {#query_wait_timeout}

Максимальное разрешённое время ожидания выполнения запроса. Если за это время
запросу не назначен сервер, клиент отключается. 0 отключает тайм-аут; тогда
клиенты могут находиться в очереди неограниченно долго. [seconds]

Параметр не позволяет неотвечающим серверам захватывать соединения. Он также
помогает, когда сервер не работает или по какой-либо причине отклоняет соединения.

По умолчанию: 120.0

### cancel_wait_timeout {#cancel_wait_timeout}

Максимальное разрешённое время ожидания выполнения запроса отмены. Если за это
время запросу отмены не назначен сервер, клиент отключается. 0 отключает тайм-аут;
тогда запросы отмены могут находиться в очереди неограниченно долго. [seconds]

Параметр предотвращает зависание клиента, когда запрос отмены невозможно
передать из-за недоступности сервера.

По умолчанию: 10.0

### client_idle_timeout {#client_idle_timeout}

Клиентские соединения закрываются после указанного числа секунд бездействия.
Значение должно превышать клиентские параметры времени существования соединения;
параметр следует использовать только при проблемах сети. [seconds]

По умолчанию: 0.0 (disabled)

### idle_transaction_timeout {#idle_transaction_timeout}

Если клиент находится в состоянии "idle in transaction" дольше указанного
времени, он отключается. [seconds]

По умолчанию: 0.0 (disabled)

### transaction_timeout {#transaction_timeout}

Если клиент находится в состоянии "in transaction" дольше указанного времени,
он отключается. [seconds]

По умолчанию: 0.0 (disabled)

### suspend_timeout {#suspend_timeout}

Сколько ждать сброса буфера во время `SUSPEND` или перезапуска (`-R`). Если
сброс не удаётся, соединение разрывается. [seconds]

По умолчанию: 10

--------

## Низкоуровневые сетевые параметры {#low-level-network-settings}

### pkt_buf {#pkt_buf}

Размер внутреннего буфера пакетов. Влияет на размер отправляемых пакетов TCP и
общее потребление памяти. Фактические пакеты libpq могут быть больше, поэтому
задавать большое значение не требуется.

По умолчанию: 4096

### max_packet_size {#max_packet_size}

Максимальный размер пакета PostgreSQL, пропускаемого PgBouncer. Один пакет
содержит один запрос или одну строку набора результатов. Полный набор результатов
может быть больше.

По умолчанию: 2147483647

### listen_backlog {#listen_backlog}

Аргумент очереди для `listen(2)`. Определяет число новых попыток соединения без
ответа, сохраняемых в очереди. При заполнении очереди дальнейшие новые соединения
отбрасываются.

По умолчанию: 128

### sbuf_loopcnt {#sbuf_loopcnt}

Сколько раз обрабатывать данные одного соединения перед переходом дальше. Без
ограничения одно соединение с большим набором результатов может надолго
заблокировать PgBouncer. За один цикл обрабатывается объём данных `pkt_buf`.
0 означает отсутствие ограничения.

По умолчанию: 5

### so_reuseport {#so_reuseport}

Определяет, задавать ли параметр сокета `SO_REUSEPORT` для прослушивающих
сокетов TCP. В некоторых операционных системах это позволяет запускать на одном
узле несколько экземпляров PgBouncer, прослушивающих один порт, а ядро будет
автоматически распределять соединения. Так PgBouncer может использовать больше
ядер CPU. PgBouncer однопоточный и использует одно ядро CPU на экземпляр.

Подробное поведение зависит от ядра операционной системы. На момент написания
параметр даёт требуемый эффект в достаточно новых версиях Linux, DragonFlyBSD
и FreeBSD. В FreeBSD вместо него применяется параметр сокета `SO_REUSEPORT_LB`.
Некоторые другие системы поддерживают этот параметр сокета, но без нужного эффекта:
несколько процессов смогут привязаться к одному порту, однако соединения будет
получать только один. Подробности см. в документации `setsockopt()` вашей системы.

В системах без поддержки этого параметра сокета его включение приведёт к ошибке.

Каждому экземпляру PgBouncer на одном узле нужны разные значения как минимум
для `unix_socket_dir` и `pidfile`, а при использовании — и для `logfile`.
Кроме того, при включении параметра невозможно подключиться к конкретному
экземпляру PgBouncer по TCP/IP, что может повлиять на мониторинг и сбор метрик.

Чтобы запросы отмены продолжали работать, следует настроить одноранговое
взаимодействие между процессами PgBouncer. Подробности приведены в документации
параметра `peer_id` и секции конфигурации `peers`. В разделе примеров также есть
конфигурация с одноранговыми узлами и `so_reuseport`.

По умолчанию: 0

### tcp_defer_accept {#tcp_defer_accept}

Задаёт параметр сокета `TCP_DEFER_ACCEPT`; подробности см. в `man 7 tcp`. Это
логический параметр: 1 означает «включён». Фактическое значение при включении
сейчас жёстко задано как 45 секунд.

Сейчас поддерживается только в Linux.

По умолчанию: 1 в Linux, иначе 0

### tcp_socket_buffer {#tcp_socket_buffer}

По умолчанию: не задан

### tcp_keepalive {#tcp_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: двойные кавычки, причём одна двойная кавычка записывается как `""`.

Имя базы данных `pgbouncer` зарезервировано для административной консоли и не
может использоваться здесь как ключ.

`*` служит резервным определением базы данных: если точное имя отсутствует, его
значение используется как строка соединения запрошенной базы. Например, при
наличии следующей записи и отсутствии переопределяющих записей:

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

соединение с PgBouncer, указавшее базу `bar`, будет фактически вести себя так,
как если бы существовала запись:

```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=`, все соединения с целевой базой данных устанавливаются от
указанного пользователя, поэтому для базы существует только один пул.

Иначе PgBouncer входит в целевую базу от имени пользователя клиента, и для
каждого пользователя создаётся отдельный пул.

### 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` — принудительный пользователь;
* к пулу подключён хотя бы один клиент.

### 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`, PgBouncer попытается найти его пароль
через `auth_query`, когда задан `auth_user`. Если `auth_user` не задан, PgBouncer
будет считать пользователя существующим и не вернёт клиенту сообщение
"no such user", но и не примет никакой предоставленный пароль.

### 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 можно связать в одноранговую группу, задав `peer_id` и секцию
`[peers]` в конфигурации каждого процесса. Тогда процессы смогут передавать
запросы отмены тому процессу, где возник отменяемый запрос. Это необходимо,
чтобы отмена работала, когда несколько процессов 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: для однорангового взаимодействия `peer_id` каждого процесса
PgBouncer должен быть уникален в группе, а секция `[peers]` должна содержать
записи всех этих идентификаторов. Пример приведён в разделе примеров. Секция
`[peers]` **может**, но не обязана содержать `peer_id` самого PgBouncer, которому
принадлежит конфигурация. Такая запись игнорируется, но упрощает управление:
одну и ту же секцию `[peers]` можно использовать в нескольких конфигурациях.

Примечание 2: одноранговое взаимодействие разных версий поддерживается, пока
все узлы находятся по одну сторону границы v1.21.0. В v1.21.0 формат кодирования
токенов отмены был несовместимо изменён, поэтому они не совместимы с токенами
предыдущих версий.

### host {#host-1}

Имя узла или IP-адрес для подключения. Имена разрешаются при установлении
соединения, результат кэшируется согласно `dns_max_ttl`. Несколько результатов
DNS перебираются циклически. Однако обычно не рекомендуется использовать имя,
разрешающееся в несколько IP-адресов: запрос отмены всё ещё может попасть не на
тот узел, и его придётся передать повторно, что разрешено не более трёх раз.

Если значение начинается с `/`, используется 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-directive}

Файл конфигурации PgBouncer может содержать директивы включения, указывающие
другой файл для чтения и обработки. Так конфигурацию можно разделить на физически
отдельные части. Директива выглядит следующим образом:

```ini
%include filename
```

Если имя файла не является абсолютным путём, оно считается относительно текущего рабочего каталога.

--------

## Формат файла аутентификации {#authentication-file-format}

В этом разделе описан формат файла, указанного параметром `auth_file`. Это
текстовый файл следующего формата:

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

Должно присутствовать не менее 2 полей в двойных кавычках. Первое поле — имя
пользователя, второе — открытый пароль, хешированный MD5 пароль или секрет SCRAM.
Остаток строки PgBouncer игнорирует. Двойную кавычку внутри значения поля можно
экранировать двумя двойными кавычками.

Формат хешированного MD5 пароля PostgreSQL:

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

Таким образом, у пользователя `admin` с паролем `1234` хешированный MD5 пароль
будет равен `md545f2603610af569b6155c45067268c6b`.

Формат секрета SCRAM PostgreSQL:

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

Подробности приведены в документации PostgreSQL и RFC 5803.

Пароли и секреты в файле аутентификации служат двум целям. Во-первых, они
проверяют пароли входящих клиентских соединений, если настроен парольный метод
аутентификации. Во-вторых, они используются как пароли исходящих соединений с
сервером бэкенда, если тот требует парольную аутентификацию и пароль не задан
непосредственно в строке соединения базы данных.

### Ограничения {#limitations}

Открытый пароль можно использовать с любым парольным методом аутентификации
сервера бэкенда: plain text, MD5 или SCRAM (подробности см.
<https://www.postgresql.org/docs/current/auth-password.html>).

Хешированные MD5 пароли можно использовать, если сервер бэкенда применяет
аутентификацию MD5 или у конкретных пользователей хранятся хешированные MD5 пароли.

Секреты SCRAM можно использовать для входа на сервер только при одновременном
выполнении трёх условий: клиентская аутентификация также использует SCRAM,
определение базы данных PgBouncer не задаёт имя пользователя, а секреты SCRAM
в PgBouncer и на сервере PostgreSQL идентичны — совпадают соль и итерации, а не
только пароль. Это следует из свойства безопасности SCRAM: одного хранимого
секрета SCRAM недостаточно для получения учётных данных входа.

Файл аутентификации можно написать вручную или сгенерировать из другого списка
пользователей и паролей. Пример сценария создания файла из системной таблицы
`pg_authid` находится в `./etc/mkauth.py`. Чтобы не сопровождать отдельный файл,
вместо `auth_file` можно использовать `auth_query`.

### Примечание об управляемых серверах {#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`.
Это известное поведение ([статья](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` выводит секрет
SCRAM в консоль перед отправкой серверу.

```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 из QUERY и укажите его в `userlist.txt` PgBouncer.

Если использован другой инструмент, а не `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 и префиксы доменов.
* Поле метода аутентификации: поддерживаются методы `auth_type` PgBouncer, а также `peer` и `reject`, кроме `any` и `pam`, работающих только глобально.
* Параметр сопоставления имён пользователей (`map=`) поддерживается при `auth_type` со значением `cert` или `peer`.

--------

## Формат файла сопоставления ident {#ident-map-file-format}

Местоположение файла сопоставления ident задаётся параметром `auth_ident_file`.
Он загружается только при `auth_type` со значением `hba`.

Формат представляет собой упрощённый вариант файла сопоставления ident
PostgreSQL (см. <https://www.postgresql.org/docs/current/auth-username-maps.html>).

* Поддерживаются только строки вида `map-name system-username database-username`.
* Включение файла или каталога не поддерживается.
* Поле 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;
```

Примеры конфигураций для 2 одноранговых процессов PgBouncer, создающих
многоядерную установку PgBouncer с помощью `so_reuseport`. Конфигурация первого процесса:

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

Конфигурация второго процесса:

```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) — страница man с общими сведениями об использовании и командах консоли.

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

---

Обратные ссылки:

- [Журнал изменений](/ru/docs/pgbouncer/changelog/)
- [FAQ](/ru/docs/pgbouncer/faq/)
- [Возможности](/ru/docs/pgbouncer/features/)
- [Использование](/ru/docs/pgbouncer/usage/)