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

Описание

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

Общие параметры

logfile

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

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

Обратите внимание: сам по себе параметр logfile не отключает ведение журнала в stderr. Для этого используйте параметр командной строки -q или -d.

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

pidfile

Задаёт файл PID. Без pidfile демонизация (-d) запрещена.

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

listen_addr

Задаёт список адресов через запятую для прослушивания соединений TCP. Можно также указать *, что означает «прослушивать все адреса». Если параметр не задан, принимаются только соединения через Unix-сокет.

Адреса можно задавать численно (IPv4/IPv6) или по имени.

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

listen_port

Порт для прослушивания. Применяется к TCP и Unix-сокетам.

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

unix_socket_dir

Задаёт местоположение Unix-сокетов как для прослушивающего сокета, так и для серверных соединений. Пустая строка отключает Unix-сокеты. Значение, начинающееся с @, предписывает создать Unix-сокет в абстрактном пространстве имён; сейчас это поддерживается в Linux и Windows.

Для перезапуска без остановки обслуживания (-R) обязательно настроить Unix-сокет в пространстве имён файловой системы.

По умолчанию: /tmp (пусто в Windows)

unix_socket_mode

Режим файловой системы для Unix-сокета. Игнорируется для сокетов в абстрактном пространстве имён. Не поддерживается в Windows.

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

unix_socket_group

Имя группы для Unix-сокета. Игнорируется для сокетов в абстрактном пространстве имён. Не поддерживается в Windows.

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

user

Если задан, указывает пользователя Unix, на которого следует переключиться после запуска. Работает, только если PgBouncer запущен от root или уже работает от указанного пользователя. Не поддерживается в Windows.

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

pool_mode

Задаёт момент, когда серверное соединение можно повторно использовать для других клиентов.

• session: сервер возвращается в пул после отключения клиента. Значение по умолчанию.
• transaction: сервер возвращается в пул после завершения транзакции.
• statement: сервер возвращается в пул после завершения запроса. В этом режиме запрещены транзакции из нескольких операторов.

max_client_conn

Максимальное разрешённое число клиентских соединений.

При увеличении этого параметра может потребоваться увеличить ограничения файловых дескрипторов операционной системы. Возможное число используемых дескрипторов превышает max_client_conn. Если каждый пользователь подключается к серверу под собственным именем, теоретический максимум равен:

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

Если пользователь базы данных указан в строке соединения и все пользователи подключаются под одним именем, теоретический максимум равен:

max_client_conn + (max pool_size * total databases)

Теоретический максимум не должен достигаться без намеренно созданной специальной нагрузки. Тем не менее число файловых дескрипторов следует задать с безопасным запасом.

Сведения о ulimit приведены на странице man используемой оболочки. Примечание: ulimit неприменим в Windows.

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

default_pool_size

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

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

min_pool_size

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

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

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

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

reserve_pool_size

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

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

reserve_pool_timeout

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

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

max_db_connections

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

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

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

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

max_db_client_connections

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

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

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

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

max_user_connections

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

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

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

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

max_user_client_connections

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

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

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

server_round_robin

По умолчанию PgBouncer повторно использует серверные соединения по принципу LIFO (последним пришёл — первым вышел), поэтому основная нагрузка приходится на несколько соединений. Это обеспечивает лучшую производительность, если базу данных обслуживает один сервер. Но если за адресом базы работает циклическая система — TCP, DNS или список узлов, — PgBouncer также лучше использовать соединения циклически для равномерной нагрузки.

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

track_extra_parameters

По умолчанию PgBouncer отслеживает для каждого клиента параметры client_encoding, datestyle, timezone, standard_conforming_strings и application_name. Здесь можно указать дополнительные параметры, чтобы PgBouncer сохранял их в кэше переменных клиента и восстанавливал на сервере при каждом переходе клиента в активное состояние.

Для нескольких значений используйте список через запятую, например default_transaction_read_only, IntervalStyle.

Примечание: большинство параметров нельзя отслеживать таким способом. Можно отслеживать только параметры, которые Postgres сообщает клиенту. У Postgres есть официальный список сообщаемых клиенту параметров . Расширения Postgres могут менять этот список: добавлять собственные сообщаемые параметры или включать передачу существующих параметров, которые сам Postgres не сообщает. В частности, Citus 12.0+ заставляет Postgres также сообщать search_path.

Протокол Postgres позволяет задавать параметры непосредственно в пакете запуска или внутри options пакета запуска . track_extra_parameters поддерживает оба способа. Однако включить в track_extra_parameters сам options нельзя — только содержащиеся в options параметры.

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

ignore_startup_parameters

По умолчанию PgBouncer разрешает в пакетах запуска только параметры, которые может отслеживать: client_encoding, datestyle, timezone и standard_conforming_strings. Все остальные параметры вызывают ошибку. Здесь можно разрешить дополнительные параметры, сообщив PgBouncer, что администратор обрабатывает их самостоятельно и их можно игнорировать.

Для нескольких значений используйте список через запятую, например options,extra_float_digits.

Протокол Postgres позволяет задавать параметры непосредственно в пакете запуска или внутри options пакета запуска . ignore_startup_parameters поддерживает оба способа. Можно даже включить сам options в track_extra_parameters, в результате чего все неизвестные параметры внутри options будут игнорироваться.

По умолчанию: пусто

peer_id

Идентификатор однорангового узла, используемый для распознавания этого процесса PgBouncer в группе связанных процессов PgBouncer. Значение peer_id должно быть уникальным в группе. При значении 0 одноранговое взаимодействие PgBouncer отключено. Подробнее см. документацию секции [peers]. Максимальное значение peer_id — 16383.

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

disable_pqexec

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

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

application_name_add_host

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

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

conffile

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

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

service_name

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

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

job_name

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

stats_period

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

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

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 требуется не более следующего объёма памяти для обработки подготовленных операторов:

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

Отслеживание подготовленных операторов увеличивает не только расход памяти, но и загрузку CPU, поскольку PgBouncer анализирует и переписывает запросы. Чтобы использовать для обработки несколько ядер, несколько экземпляров PgBouncer могут прослушивать один порт; подробности приведены в документации параметра so_reuseport .

Подготовленные операторы также повышают производительность. Как и при прямом подключении к PostgreSQL, подготовка многократно выполняемого запроса уменьшает общий объём разбора и планирования. Способ отслеживания в PgBouncer особенно полезен, когда несколько клиентов подготавливают одинаковые запросы: клиентские соединения автоматически повторно используют оператор в серверном соединении, даже если его подготовил другой клиент. Например, при pool_size 20 и 100 клиентах, подготавливающих один и тот же запрос, на сервере PostgreSQL запрос будет подготовлен и разобран только 20 раз.

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

ERROR:  cached plan must not change result type

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

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

scram_iterations

Число вычислительных итераций при шифровании пароля с помощью SCRAM-SHA-256. Большее число итераций лучше защищает хранимые пароли от перебора, но замедляет аутентификацию.

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

Параметры аутентификации

PgBouncer самостоятельно аутентифицирует клиентов и ведёт собственную базу пользователей. Эти параметры управляют аутентификацией.

auth_type

Способ аутентификации пользователей.

• cert: клиент обязан подключаться по TLS с действительным клиентским сертификатом. Имя пользователя берётся из поля CommonName сертификата.
• md5: проверка пароля на основе MD5. Это метод аутентификации по умолчанию. auth_file может содержать зашифрованные MD5 и открытые пароли. Если настроен md5, а у пользователя есть секрет SCRAM, автоматически применяется аутентификация SCRAM.
• scram-sha-256: проверка пароля с SCRAM-SHA-256. auth_file должен содержать секреты SCRAM или открытые пароли.
• plain: открытый пароль передаётся по сети. Устарел.
• trust: аутентификация не выполняется, но имя пользователя всё равно должно существовать в auth_file.
• any: аналог trust, но указанное имя пользователя игнорируется. Все базы данных должны быть настроены для входа от конкретного пользователя. Кроме того, консольная база разрешает любому пользователю вход как администратору.
• 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

Файл конфигурации HBA, используемый при auth_type со значением hba. Подробности см. ниже в разделе Формат файла HBA .

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

auth_ident_file

Файл сопоставления идентификаторов, используемый при auth_type со значением hba и заданном сопоставлении пользователей. Подробности см. ниже в разделе Формат файла сопоставления ident .

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

auth_file

Имя файла, из которого загружаются имена пользователей и пароли. Подробности см. ниже в разделе Формат файла аутентификации .

Для большинства типов аутентификации необходимо задать auth_file или auth_user, иначе пользователи не будут определены.

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

auth_user

Если задан auth_user, любой отсутствующий в auth_file пользователь будет запрошен из pg_authid базы данных запросом auth_query от имени auth_user. Пароль auth_user берётся из auth_file. Если для auth_user пароль не нужен, его можно не определять в auth_file.

Для прямого доступа к pg_authid нужны права администратора. Предпочтительнее использовать непривилегированного пользователя, вызывающего функцию SECURITY DEFINER.

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

auth_query

Запрос для загрузки пароля пользователя из базы данных.

Для прямого доступа к pg_authid нужны права администратора. Предпочтительнее использовать непривилегированного пользователя, вызывающего функцию SECURITY DEFINER.

Обратите внимание: запрос выполняется внутри целевой базы данных. Если используется функция, её необходимо установить в каждой базе.

По умолчанию: SELECT rolname, CASE WHEN rolvaliduntil < now() THEN NULL ELSE rolpassword END FROM pg_authid WHERE rolname=$1 AND rolcanlogin

auth_dbname

Имя базы данных из секции [database], используемой для аутентификации. Параметр может быть глобальным или переопределяться в строке соединения.

auth_ldap_options

Параметры соединения LDAP при auth_type со значением ldap. Не используются, если аутентификация настроена через auth_hba_file. Пример:

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

Параметры ведения журнала

syslog

Включает или отключает syslog. В Windows вместо него используется журнал событий.

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

syslog_ident

Имя, под которым журналы отправляются в syslog.

По умолчанию: pgbouncer (имя программы)

syslog_facility

Facility для отправки журналов в syslog. Возможные значения: auth, authpriv, daemon, user, local0-7.

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

log_connections

Записывать успешные входы в журнал.

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

log_disconnections

Записывать отключения и их причины в журнал.

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

log_pooler_errors

Записывать сообщения об ошибках, отправляемые пулом клиентам.

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

log_stats

Записывать агрегированную статистику в журнал каждые stats_period. Параметр можно отключить, если внешние средства мониторинга получают те же данные из команд SHOW.

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

verbose

Увеличить подробность. Соответствует ключу командной строки -v. Например, -v -v равнозначно verbose=2. Сейчас максимальный поддерживаемый уровень — 3.

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

Управление доступом к консоли

admin_users

Список пользователей базы данных через запятую, которым разрешено подключаться и выполнять все команды в консоли. Игнорируется при auth_type со значением any: в этом случае любое имя пользователя допускается как администратор.

По умолчанию: пусто

stats_users

Список пользователей базы данных через запятую, которым разрешено подключаться и выполнять в консоли запросы только для чтения, то есть все команды SHOW, кроме SHOW FDS.

По умолчанию: пусто

Проверки соединений и тайм-ауты

server_reset_query

Запрос, отправляемый серверу при освобождении соединения до его передачи другим клиентам. В этот момент активной транзакции нет, поэтому значение не должно содержать ABORT или ROLLBACK.

Запрос должен очищать все изменения сеанса базы данных, чтобы следующий клиент получил соединение в однозначно определённом состоянии. По умолчанию используется DISCARD ALL, который очищает всё, но не оставляет следующему клиенту заранее кэшированного состояния. Если сохранение части состояния не нарушает работу приложения, можно использовать более лёгкий вариант, например DEALLOCATE ALL для удаления только подготовленных операторов.

В транзакционном режиме пула server_reset_query не используется, поскольку клиенты не должны применять сеансовые возможности: каждая транзакция попадает в другое соединение и получает другое состояние сеанса.

По умолчанию: DISCARD ALL

server_reset_query_always

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

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

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

server_check_delay

Сколько времени сохранять освобождённые соединения для немедленного повторного использования без выполнения server_check_query. При 0 проверка выполняется всегда.

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

server_check_query

Простой ничего не изменяющий запрос для проверки работоспособности серверного соединения.

Пустая строка отключает проверку.

Значение <empty> отправляет пустой запрос для проверки.

По умолчанию: <empty>

server_fast_close

В сеансовом режиме пула отключать сервер в состоянии “close_needed” немедленно или после завершения текущей транзакции, не дожидаясь конца сеанса. Состояние задаётся командой RECONNECT, командой RELOAD, изменяющей параметры соединения, или изменением DNS. В режиме на уровне операторов и транзакционном режиме параметр не действует, поскольку там это поведение используется по умолчанию.

Если из-за этого параметра серверное соединение закрывается до окончания клиентского сеанса, клиентское соединение также закрывается. Так клиент обязательно обнаружит прерывание сеанса.

Параметр ускоряет применение изменений конфигурации соединений при сеансовом режиме пула и долгих сеансах. Недостаток: изменение конфигурации может прервать клиентские сеансы, поэтому приложениям нужна логика переподключения и восстановления состояния. Транзакции не теряются, поскольку прерываются только неактивные сеансы, а не выполняющиеся транзакции.

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

server_lifetime

Пул закрывает неиспользуемое серверное соединение, которое сейчас не связано ни с одним клиентом и существует дольше указанного времени. Значение 0 означает, что соединение используется один раз, а затем закрывается. [seconds]

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

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

server_idle_timeout

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

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

server_connect_timeout

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

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

server_login_retry

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

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

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

client_login_timeout

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

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

autodb_idle_timeout

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

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

dns_max_ttl

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

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

dns_nxdomain_ttl

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

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

dns_zone_check_period

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

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

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

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

resolv_conf

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

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

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

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

query_wait_notify

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

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

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

Параметры TLS

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

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

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

Закрытый ключ, с которым PgBouncer принимает клиентские соединения.

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

client_tls_cert_file

Сертификат для закрытого ключа. Клиенты могут его проверить.

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

client_tls_ca_file

Файл корневого сертификата для проверки клиентских сертификатов.

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

client_tls_protocols

Разрешённые версии протокола TLS. Допустимые значения: tlsv1.0, tlsv1.1, tlsv1.2, tlsv1.3. Сокращения: all (tlsv1.0,tlsv1.1,tlsv1.2,tlsv1.3), secure (tlsv1.2,tlsv1.3).

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

client_tls_ciphers

Разрешённые шифры TLS в синтаксисе OpenSSL. Сокращения:

• default/secure/fast/normal (все используют общесистемные значения OpenSSL по умолчанию)
• all (включает все шифры; не рекомендуется)

Влияет только на соединения с TLS версии 1.2 и ниже. Для версии 1.3 см. ниже client_tls13_ciphers.

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

client_tls13_ciphers

Разрешённые шифры TLS v1.3. При пустом значении используется client_tls_ciphers. Допустимые значения:

• TLS_AES_256_GCM_SHA384
• TLS_CHACHA20_POLY1305_SHA256
• TLS_AES_128_GCM_SHA256
• TLS_AES_128_CCM_8_SHA256
• TLS_AES_128_CCM_SHA256

Влияет только на соединения с TLS версии 1.3 и выше. Для версии 1.2 и ниже см. client_tls_ciphers.

По умолчанию: <empty>

client_tls_ecdhcurve

Имя эллиптической кривой для обмена ключами ECDH.

Допустимые значения: none (DH отключён), auto (256-bit ECDH), имя кривой.

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

client_tls_dheparams

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

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

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

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

Файл корневого сертификата для проверки сертификатов сервера PostgreSQL.

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

server_tls_key_file

Закрытый ключ для аутентификации PgBouncer на сервере PostgreSQL.

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

server_tls_cert_file

Сертификат для закрытого ключа. Сервер PostgreSQL может его проверить.

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

server_tls_protocols

Разрешённые версии протокола TLS. Допустимые значения: tlsv1.0, tlsv1.1, tlsv1.2, tlsv1.3. Сокращения: all (tlsv1.0,tlsv1.1,tlsv1.2,tlsv1.3), secure (tlsv1.2,tlsv1.3), legacy (all).

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

server_tls_ciphers

Разрешённые шифры TLS в синтаксисе OpenSSL. Сокращения:

• default/secure/fast/normal (все используют общесистемные значения OpenSSL по умолчанию)
• all (включает все шифры; не рекомендуется)

Влияет только на соединения с TLS версии 1.2 и ниже. Для версии 1.3 см. ниже server_tls13_ciphers.

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

server_tls13_ciphers

Разрешённые шифры TLS v1.3. При пустом значении используется server_tls_ciphers. Допустимые значения:

• TLS_AES_256_GCM_SHA384
• TLS_CHACHA20_POLY1305_SHA256
• TLS_AES_128_GCM_SHA256
• TLS_AES_128_CCM_8_SHA256
• TLS_AES_128_CCM_SHA256

Влияет только на соединения с TLS версии 1.3 и выше. Для версии 1.2 и ниже см. client_tls_ciphers.

По умолчанию: <empty>

Опасные тайм-ауты

Настройка следующих тайм-аутов может вызвать неожиданные ошибки.

query_timeout

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

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

query_wait_timeout

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

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

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

cancel_wait_timeout

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

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

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

client_idle_timeout

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

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

idle_transaction_timeout

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

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

transaction_timeout

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

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

suspend_timeout

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

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

Низкоуровневые сетевые параметры

pkt_buf

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

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

max_packet_size

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

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

listen_backlog

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

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

sbuf_loopcnt

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

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

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; подробности см. в man 7 tcp. Это логический параметр: 1 означает «включён». Фактическое значение при включении сейчас жёстко задано как 45 секунд.

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

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

tcp_socket_buffer

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

tcp_keepalive

Включает базовое постоянное соединение с параметрами операционной системы по умолчанию.

В Linux системные значения по умолчанию: tcp_keepidle=7200, tcp_keepintvl=75, tcp_keepcnt=9. В других операционных системах они, вероятно, похожи.

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

tcp_keepcnt

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

tcp_keepidle

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

tcp_keepintvl

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

tcp_user_timeout

Задаёт параметр сокета TCP_USER_TIMEOUT: максимальное время в миллисекундах, в течение которого переданные данные могут оставаться неподтверждёнными до принудительного закрытия соединения TCP. При 0 используется значение операционной системы по умолчанию.

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

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

Секция [databases]

Секция [databases] определяет имена баз данных, к которым могут подключаться клиенты PgBouncer, и назначения маршрутизации этих соединений. Секция содержит строки key=value вида:

dbname = connection string

Ключ считается именем базы данных, а значение — строкой соединения из описанных ниже пар key=value параметров соединения. Синтаксис похож на libpq, но сама libpq не используется, а набор доступных возможностей отличается. Пример:

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

Имя базы данных может без кавычек содержать символы _0-9A-Za-z. Имена с другими символами необходимо заключать в стандартные кавычки идентификаторов SQL: двойные кавычки, причём одна двойная кавычка записывается как "".

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

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

* = host=foo

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

bar = host=foo dbname=bar

При этом используется значение dbname по умолчанию — имя базы данных на стороне клиента; см. ниже.

Автоматически созданные записи баз данных удаляются, если остаются неактивными дольше времени, заданного autodb_idle_timeout.

dbname

Имя целевой базы данных.

По умолчанию: совпадает с именем базы данных на стороне клиента

host

Имя узла или IP-адрес для подключения. Имена разрешаются при установлении соединения, результат кэшируется согласно dns_max_ttl. При изменении разрешения имени существующие серверные соединения автоматически закрываются после освобождения согласно режиму пула, а новые сразу используют новый результат. Если DNS возвращает несколько результатов, они перебираются циклически.

Если значение начинается с /, используется Unix-сокет в пространстве имён файловой системы. Если оно начинается с @, используется Unix-сокет в абстрактном пространстве имён.

Можно указать список имён узлов или адресов через запятую; соединения будут устанавливаться циклически. Если имена из списка сами разрешаются DNS в несколько адресов, две системы циклического перебора работают независимо. Это особенность реализации, которая может измениться. Все узлы списка должны быть доступны постоянно: механизмов пропуска недоступных узлов или выбора только доступных нет. В этом поведение отличается от списка узлов libpq. Параметр влияет только на выбор назначения новых соединений. Распределение клиентов по уже установленным серверным соединениям описывает server_round_robin.

Примеры:

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

По умолчанию: не задан, то есть используется Unix-сокет

port

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

user

Если задан user=, все соединения с целевой базой данных устанавливаются от указанного пользователя, поэтому для базы существует только один пул.

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

password

Если пароль здесь не указан, для заданного выше пользователя используется пароль из auth_file. Динамическое получение пароля, например через auth_query, сейчас не поддерживается.

auth_user

Переопределяет глобальный auth_user, если задан.

auth_query

Переопределяет глобальный auth_query, если задан. Весь оператор SQL необходимо заключить в одинарные кавычки.

auth_dbname

Переопределяет глобальный auth_dbname, если задан.

pool_size

Задаёт максимальный размер пулов для этой базы данных. Если не задан, используется default_pool_size.

min_pool_size

Задаёт минимальный размер пула для этой базы данных. Если не задан, используется глобальный min_pool_size.

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

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

reserve_pool_size

Задаёт дополнительные соединения для базы данных. Если не задан, используется глобальный reserve_pool_size. Для обратной совместимости reserve_pool является псевдонимом этого параметра.

connect_query

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

pool_mode

Задаёт режим пула для этой базы данных. Если не задан, используется pool_mode по умолчанию.

load_balance_hosts

Если в host задан список через запятую, load_balance_hosts определяет выбор записи для нового соединения.

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

• round-robin: новая попытка соединения выбирает следующую запись узла в списке.
• disable: новые соединения используют одну запись узла до ошибки, после чего выбирается следующая.

При нескольких узлах рекомендуется задать server_login_retry ниже значения по умолчанию для быстрых повторных попыток.

По умолчанию: round-robin

max_db_connections

Задаёт общий для базы данных максимум серверных соединений: суммарно все её пулы не будут иметь больше указанного числа соединений.

max_db_client_connections

Задаёт общий для базы данных максимум клиентских соединений. Следует использовать вместе с max_client_conn, чтобы ограничить число соединений, принимаемых PgBouncer.

server_lifetime

Задаёт server_lifetime для отдельной базы данных. Если не задан, используется значение server_lifetime всего экземпляра.

client_encoding

Запрашивает у сервера конкретное значение client_encoding.

datestyle

Запрашивает у сервера конкретное значение datestyle.

timezone

Запрашивает у сервера конкретное значение timezone.

Секция [users]

Эта секция содержит строки key=value вида:

user1 = settings

Ключ считается именем пользователя, а значение — списком пар key=value параметров конфигурации этого пользователя. Пример:

user1 = pool_mode=session

Здесь доступно лишь несколько параметров.

Обратите внимание: если настроен auth_file, пользователь определён в этой секции, но отсутствует в auth_file, PgBouncer попытается найти его пароль через auth_query, когда задан auth_user. Если auth_user не задан, PgBouncer будет считать пользователя существующим и не вернёт клиенту сообщение “no such user”, но и не примет никакой предоставленный пароль.

pool_size

Задаёт максимальный размер пулов для всех соединений этого пользователя. Если не задан, используется значение базы данных или default_pool_size.

reserve_pool_size

Задаёт число дополнительных соединений, разрешённых в пуле этого пользователя. Если не задан, используется конфигурация базы данных или глобальный reserve_pool_size.

pool_mode

Задаёт режим пула для всех соединений этого пользователя. Если не задан, используется значение базы данных или pool_mode по умолчанию.

max_user_connections

Задаёт максимум серверных соединений пользователя: суммарно все пулы этого пользователя не будут иметь больше указанного числа соединений.

query_timeout

Задаёт максимальное число секунд выполнения запроса пользователя. Если задан, этот тайм-аут переопределяет описанный выше серверный query_timeout.

idle_transaction_timeout

Задаёт максимальное число секунд, в течение которых пользователь может держать открытой неактивную транзакцию. Если задан, переопределяет описанный выше серверный idle_transaction_timeout.

transaction_timeout

Задаёт максимальное число секунд, в течение которых пользователь может держать транзакцию открытой. Если задан, переопределяет описанный выше серверный transaction_timeout.

client_idle_timeout

Задаёт максимальное время в секундах, в течение которого клиенту разрешено неактивное соединение с экземпляром PgBouncer. Если задан, переопределяет описанный выше серверный client_idle_timeout.

Обратите внимание: это потенциально опасный тайм-аут.

max_user_client_connections

Задаёт максимум клиентских соединений пользователя. Это пользовательский эквивалент параметра max_client_conn.

Секция [peers]

Секция [peers] определяет одноранговые узлы, которым PgBouncer может передавать запросы отмены, и маршруты этих запросов.

Процессы PgBouncer можно связать в одноранговую группу, задав peer_id и секцию [peers] в конфигурации каждого процесса. Тогда процессы смогут передавать запросы отмены тому процессу, где возник отменяемый запрос. Это необходимо, чтобы отмена работала, когда несколько процессов PgBouncer, возможно на разных серверах, находятся за одним балансировщиком TCP. Запрос отмены передаётся по другому соединению TCP, чем отменяемый запрос, поэтому балансировщик TCP может направить его не тому процессу. Одноранговое взаимодействие в конечном счёте доставляет запрос отмены нужному процессу. Подробнее см. запись доклада на конференции .

Секция содержит строки key=value вида:

peer_id = connection string

Ключ считается peer_id, а значение — строкой соединения из описанных ниже пар key=value параметров. Синтаксис похож на libpq, но сама libpq не используется, а набор доступных возможностей отличается. Пример:

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

Примечание 1: для однорангового взаимодействия peer_id каждого процесса PgBouncer должен быть уникален в группе, а секция [peers] должна содержать записи всех этих идентификаторов. Пример приведён в разделе примеров. Секция [peers] может, но не обязана содержать peer_id самого PgBouncer, которому принадлежит конфигурация. Такая запись игнорируется, но упрощает управление: одну и ту же секцию [peers] можно использовать в нескольких конфигурациях.

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

host

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

Если значение начинается с /, используется Unix-сокет в пространстве имён файловой системы. Если оно начинается с @, используется Unix-сокет в абстрактном пространстве имён.

Примеры:

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

port

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

pool_size

Задаёт максимальное число запросов отмены, одновременно передаваемых одноранговому узлу. Запросы отмены часто поступают всплесками, например когда обслуживающий сервер Postgres работает медленно или недоступен. Поэтому pool_size не должен быть настолько мал, чтобы не справляться со всплесками.

Если не задан, используется default_pool_size.

Директива включения

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

%include filename

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

Формат файла аутентификации

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

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

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

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

"md5" + md5(password + username)

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

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

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

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

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

Ограничения

Открытый пароль можно использовать с любым парольным методом аутентификации сервера бэкенда: 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.

Примечание об управляемых серверах

Если сервер бэкенда использует парольную аутентификацию SCRAM, PgBouncer не сможет пройти аутентификацию, не зная: a) открытого пароля пользователя или b) соответствующего секрета SCRAM.

Некоторые облачные провайдеры, например AWS RDS, запрещают доступ к конфиденциальным системным таблицам PostgreSQL для получения паролей. Даже у самого привилегированного пользователя, например участника rds_superuser, запрос select * from pg_authid возвращает ERROR: permission denied for table pg_authid. Это известное поведение (статья ).

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

Создайте секрет SCRAM для произвольного пароля инструментом, способным вывести секрет. Например, psql --echo-hidden с командой \password выводит секрет SCRAM в консоль перед отправкой серверу.

$ 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 задаётся параметром 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 задаётся параметром 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 и регулярные выражения.

Примеры

Небольшой пример конфигурации:

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

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

Примеры баз данных:

[databases]

; foodb over Unix socket
foodb =

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

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

Пример безопасной функции для auth_query:

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

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

[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

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

[databases]
postgres = host=localhost dbname=postgres

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

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

См. также

pgbouncer(1) — страница man с общими сведениями об использовании и командах консоли.

https://www.pgbouncer.org/