Перейти к основному содержимому

Конфигурирование (pgbouncer.ini)

Описание​

В документе приведено описание настроек и разделов конфигурационного файла PgBouncer.

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

Общие настройки​

logfile​

Указывает имя файла журнала. Для работы в фоновом режиме (-d) необходимо указать либо этот параметр, либо syslog.

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

Обратите внимание, что установка 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 в абстрактном пространстве имен.

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

По умолчанию: /tmp.

unix_socket_mode​

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

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

unix_socket_group​

Имя группы, используемое для сокетов Unix. Игнорируется для сокетов в абстрактном пространстве имен.

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

user​

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

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

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)

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

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

default_pool_size​

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

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

min_pool_size​

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

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

  • запись в разделе [database] для пула имеет значение, установленное для ключа пользователя (он же forced user);
  • к пулу подключен хотя бы один клиент.

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

reserve_pool_size​

Сколько дополнительных подключений разрешить к пулу (см. reserve_pool_timeout). 0 – отключает.

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

reserve_pool_timeout​

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

По умолчанию: 5.0 (секунды).

max_db_connections​

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

Этот параметр также можно задать для каждой базы данных в разделе [databases].

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

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

max_user_connections​

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

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

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

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

max_user_client_connections​

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

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

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

server_round_robin​

По умолчанию PgBouncer использует соединения с сервером по принципу LIFO (last-in, first-out), так что небольшая часть соединений получают наибольшую нагрузку. Это обеспечивает наилучшую производительность, если есть только один сервер, обслуживающий базу данных. Но если за адресом базы данных стоит система round-robin (TCP, DNS или список хостов), то будет лучше, если PgBouncer также будет использовать соединения по такому принципу, добиваясь равномерной нагрузки.

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

track_extra_parameters​

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

Если нужно указать несколько значений, используйте список, разделенный запятыми (например, default_transaction_readonly, IntervalStyle)

Примечание

Большинство параметров нельзя отследить таким образом. Единственные параметры, которые можно отследить, это те, о которых БД сообщает клиенту (у PostgreSQL есть официальный список параметров, о которых она сообщает клиенту https://www.postgresql.org/docs/15/protocol-flow.html#PROTOCOL-ASYNC). Расширения PostgreSQL могут изменять этот список, они могут сами добавлять параметры, которые могут начать сообщать параметры, о которых PostgreSQL не сообщает. Примечательно, что Citus 12.0+ заставляет PostgreSQL также сообщать search_path.

Протокол PostgreSQL позволяет указывать параметры как непосредственно в качестве параметра в стартовом пакете, так и внутри стартового пакета опций (https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-OPTIONS). Параметры, указанные обоими этими способами, поддерживаются track_extra_parameters. Однако в track_extra_parameters нельзя включить сам параметр options, только параметры, содержащиеся в options.

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

ignore_startup_parameters​

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

Если нужно указать несколько значений, используйте список, разделенный запятыми (например: options, extra_float_digits).

Протокол PostgreSQL позволяет указывать параметры как непосредственно в качестве параметра в стартовом пакете, так и внутри стартового пакета опций (https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-OPTIONS). Параметры, заданные обоими этими способами, поддерживаются ignore_startup_parameters. Можно даже включить сами параметры в track_extra_parameters, в результате чего все неизвестные параметры, содержащиеся внутри параметров, будут игнорироваться.

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

peer_id​

Идентификатор пира, используемый для идентификации данного процесса PgBouncer в группе процессов PgBouncer, которые пирируются вместе. Значение peer_id должно быть уникальным в группе пиринговых процессов PgBouncer. При значении 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.

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

job_name​

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

stats_period​

Устанавливает, как часто обновляются средние значения, отображаемые в различных командах SHOW, и как часто агрегированная статистика записывается в журнал (см. log_stats).

По умолчанию: 60 (в секундах).

max_prepared_statements​

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

PgBouncer внутренне изучает все запросы, отправляемые клиентами в виде подготовленного запроса, и присваивает каждой уникальной строке запроса внутреннее имя в формате PGBOUNCER_{unique_id}. Подготовленные запросы подготавливаются только с этим именем на соответствующем сервере PostgreSQL. PgBouncer отслеживает имя, которое клиент присвоил каждому подготовленному запросу. Он переписывает каждую команду, использующую подготовленный запрос, чтобы использовать соответствующее внутреннее имя (например, PGBOUNCER_123) перед передачей команды на сервер. Более того, если подготовленный запрос, который хочет использовать клиент, еще не подготовлен на сервере, он автоматически подготавливает его перед передачей команды, которую отправил клиент.

Примечание

Это отслеживание и переписывание команд подготовленного запроса не работает для команд подготовленного запроса на уровне SQL, таких как: PREPARE, EXECUTE, DEALLOCATE, DEALLOCATE ALL и DISCARD ALL. Выполнение команд DEALLOCATE ALL и DISCARD ALL особенно проблематично, поскольку эти команды, казалось бы, выполняются успешно, но они существенно изменяют состояние серверного соединения, причем PgBouncer этого не замечает. Что, в свою очередь, с большой вероятностью приведет к нарушению выполнения любых дальнейших подготовленных запросов на этом серверном соединении.

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

Однако влияние на использование памяти PgBouncer не так велико:

  • Каждый уникальный запрос хранится один раз в глобальном кеше запросов.
  • Каждое клиентское соединение хранит буфер, который используется для перезаписи пакетов. Его размер не более чем в 4 раза превышает размер pkt_buf. Однако этот предел часто не достигается, это происходит только тогда, когда запросы в подготовленных операциях в 2-4 раза превышают размер pkt_buf.

Если рассмотреть следующий сценарий в качестве примера:

  • Есть 1000 активных клиентов.
  • Клиенты готовят 200 уникальных запросов.
  • Средний размер запроса составляет 5 КБ.
  • Параметр pkt_buf установлен по умолчанию на 4096 (4 Кб).

Тогда PgBouncer потребуется не более следующего объема памяти для обработки этих подготовленных операторов: 200 x 5kB + 1000 x 4 x 4kB = ~17MB памяти.

Отслеживание подготовленных запросов связано не только с затратами памяти, но и с увеличением использования процессора, поскольку 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.

Настройки аутентификации​

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

auth_type​

Как аутентифицировать пользователей:

  • cert – клиент должен подключиться по TLS-соединению с действительным сертификатом клиента. Имя пользователя берется из поля CommonName сертификата.
  • md5 – использовать проверку паролей на основе MD5. Это метод аутентификации по умолчанию. auth_file может содержать как MD5-зашифрованные, так и обычные пароли. Если настроен md5, а у пользователя есть SCRAM-секрет, то вместо него автоматически используется SCRAM-аутентификация.
  • scram-sha-256 – использовать проверку паролей с помощью SCRAM-SHA-256. auth_file должен содержать секреты SCRAM или пароли в открытом виде.
  • plain – пароль передается в открытом виде. Утратил силу.
  • trust – аутентификация не выполняется. Имя пользователя должно по-прежнему существовать в auth_file.
  • any – аналогичен методу trust, но указанное имя пользователя игнорируется. Требуется, чтобы все базы данных были настроены на вход под определенным пользователем. Кроме того, консольная база данных позволяет любому пользователю входить в систему под именем admin.
  • hba – фактический тип аутентификации загружается из файла auth_hba_file. Это позволяет использовать различные методы аутентификации для разных путей доступа, например: соединения через Unix socket используют метод peer, соединения через TCP должны использовать TLS.
  • pam – для аутентификации пользователей используется PAM, auth_file игнорируется. Этот метод несовместим с базами данных, использующими параметр auth_user. Имя службы, передаваемое в PAM - pgbouncer. pam не поддерживается в файле конфигурации HBA.

auth_hba_file​

Файл конфигурации HBA для использования, когда в auth_type установлено в hba.

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

auth_ident_file​

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

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

auth_file​

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

Большинство типов аутентификации (смотрите выше) требуют, чтобы были заданы либо auth_file, либо auth_user; в противном случае пользователи не будут определены.

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

auth_user​

Если задан auth_user, то любой пользователь, не указанный в auth_file, будет запрашиваться через запрос auth_query из pg_authid в базе данных, используя 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] для использования в целях аутентификации. Этот параметр может быть как глобальным, так и переопределенным в строке подключения, если он указан.

Настройки журнала​

syslog​

Включение/выключение syslog.

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

syslog_ident​

Под каким именем отправлять журналы в syslog.

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

syslog_facility​

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

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

log_connections​

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

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

log_disconnections​

Вести журнал отключений с указанием причин.

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

log_pooler_errors​

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

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

log_stats​

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

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

verbose​

Повысить многословность. Аналогично переключателю -v в командной строке. Например, использование -v -v в командной строке равносильно verbose=2.

По умолчанию: 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 будет выполняться только в пулах, находящихся в режиме session-pooling. Соединения в режиме пула транзакций не должны нуждаться в запросе сброса.

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

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

server_check_delay​

Как долго держать освобожденные соединения доступными для немедленного повторного использования без выполнения server_check_query. Если 0, то проверка выполняется всегда.

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

server_check_query​

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

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

server_fast_close​

Отключить сервер в режиме объединения сессий сразу или после завершения текущей транзакции, если он находится в режиме close_need (установленном с помощью RECONNECT, RELOAD, изменяющего настройки соединения, или изменения DNS), вместо того чтобы ждать окончания сессии. В режиме пула операторов или транзакций это не влияет, так как там это поведение используется по умолчанию.

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

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

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

server_lifetime​

Пулер закроет неиспользуемое (не связанное в данный момент ни с одним клиентским соединением) серверное соединение, которое было подключено дольше, чем это значение. Установка значения 0 означает, что соединение будет использовано только один раз, а затем закрыто.

По умолчанию: 3600.0 (секунды).

server_idle_timeout​

Если соединение с сервером простаивает больше указанного количества секунд, оно будет закрыто. Если 0, то этот тайм-аут отключен.

По умолчанию: 600.0 (секунды).

server_connect_timeout​

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

По умолчанию: 15.0 (секунды).

server_login_retry​

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

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

По умолчанию: 15.0 (секунды).

client_login_timeout​

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

По умолчанию: 60.0 (секунды).

autodb_idle_timeout​

Если автоматически созданные (через «*») пулы баз данных не использовались в течение autodb_idle_timeout секунд, они освобождаются. Негативным аспектом этого является то, что их статистика также забывается.

По умолчанию: 3600.0 (секунды).

dns_max_ttl​

Продолжительность кеширования DNS-поисков. Фактическое значение DNS TTL игнорируется.

По умолчанию: 15.0 (секунды).

dns_nxdomain_ttl​

Как долго могут кешироваться ошибки DNS и поиск DNS NXDOMAIN.

По умолчанию: 15.0 (секунды).

dns_zone_check_period​

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

PgBouncer может собирать DNS-зоны из имен хостов (все после первой точки), а затем периодически проверять, не изменилась ли последовательность зон. Если он замечает изменения, все имена хостов в этой зоне просматриваются заново. Если IP-адрес какого-либо хоста изменится, его соединения будут аннулированы.

Работает только с бэкендом c-ares (опция конфигурации --with-cares).

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

resolv_conf​

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

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

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

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

Настройки TLS​

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

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

client_tls_sslmode​

По умолчанию TLS-соединения отключены. При включении необходимо также настроить client_tls_key_file и client_tls_cert_file, чтобы задать ключ и сертификат, которые PgBouncer использует для приема клиентских соединений. Наиболее распространенным форматом файла сертификата является pem.

Возможные значения:

  • disable — обычный TCP. Если клиент запрашивает TLS, игнорируется. Установлен по умолчанию;
  • allow — если клиент запрашивает TLS, он используется. Если нет, используется обычный TCP. Если клиент предъявляет сертификат клиента, он не проверяется;
  • prefer — то же, что allow;
  • require— клиент должен использовать TLS. В противном случае клиентское соединение будет отклонено. Если клиент предъявляет сертификат клиента, он не проверяется;
  • verify-ca — сертификат клиента проверяется на валидность;
  • 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), legacy (все).

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

client_tls_ciphers​

Разрешенные шифры TLS в синтаксисе OpenSSL.

Сокращения:

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

Затронуты только соединения, использующие TLS версии 1.2 и ниже. В настоящее время не существует настроек, контролирующих выбор шифров, используемых соединениями TLS версии 1.3.

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

client_tls_ecdhcurve​

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

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

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

client_tls_dheparams​

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

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

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

server_tls_sslmode​

Режим TLS, используемый для соединений с серверами PostgreSQL.

  • disable — обычный TCP. TLS даже не запрашивается у сервера;
  • allow — если сервер отклоняет обычную версию, попробовать использовать TLS;
  • prefer — TLS-соединение всегда запрашивается первым у PostgreSQL. В случае отказа соединение будет установлено по классическому TCP. Сертификат сервера не проверяется. Используется по умолчанию;
  • require — соединение должно проходить по протоколу TLS. Если сервер отклоняет его, попытка обычного TCP не предпринимается. Сертификат сервера не проверяется;
  • verify-ca — соединение должно осуществляться по протоколу TLS, а сертификат сервера должен быть действительным в соответствии с файлом server_tls_ca_file. Имя хоста сервера не проверяется на соответствие сертификату;
  • verify-full — соединение должно осуществляться по протоколу TLS, а сертификат сервера должен быть действительным в соответствии с файлом server_tls_ca_file. Имя хоста сервера должно соответствовать информации сертификата.

По умолчанию: prefer.

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 (все).

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

server_tls_ciphers​

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

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

Затронуты только соединения, использующие TLS версии 1.2 и ниже. В настоящее время не существует настройки, контролирующей выбор шифров, используемых соединениями TLS версии 1.3.

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

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

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

query_timeout​

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

По умолчанию: 0.0 (отключено, задается в секундах).

query_wait_timeout​

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

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

По умолчанию: 120.0 (секунды).

cancel_wait_timeout​

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

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

По умолчанию: 10.0 (секунды).

client_idle_timeout​

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

По умолчанию: 0.0 (отключено, задается в секундах).

idle_transaction_timeout​

Если клиент находится в состоянии «простоя в транзакции» дольше чем это значение, он будет отключен.

По умолчанию: 0.0 (отключено, задается в секундах).

suspend_timeout​

Сколько времени ждать очистки буфера при SUSPEND или перезагрузке (-R). Соединение будет разорвано, если очистка не удалась.

По умолчанию: 10 (секунды).

Низкоуровневые сетевые настройки​

pkt_buf​

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

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

max_packet_size​

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

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

listen_backlog​

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

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

sbuf_loopcnt​

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

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

so_reuseport​

Указывает, устанавливать ли параметр сокета SO_REUSEPORT для сокетов, прослушивающих TCP. В некоторых операционных системах это позволяет запустить несколько экземпляров PgBouncer на одном хосте, прослушивающих один и тот же порт, и заставить ядро автоматически распределять соединения. Эта опция — способ заставить PgBouncer использовать больше ядер процессора (PgBouncer является однопоточным и использует одно ядро процессора на экземпляр).

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

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

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

Чтобы убедиться, что отмена запросов работает, необходимо настроить пиринг PgBouncer между различными процессами 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​

Включает базовый 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, то используется значение по умолчанию операционной системы.

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

Раздел [databases]​

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

dbname = connection string

Где в качестве ключа будет взято имя базы данных, а в качестве значения — строка подключения, состоящая из пар ключ=значение параметров подключения, описанных ниже (аналогично 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​

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

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​

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

client_encoding​

Запрашивает у сервера использование указанной клиентской кодировки (client_encoding).

datestyle​

Запрашивает у сервера использование указанного стиля даты (datestyle).

timezone​

Запрашивает у сервера использование указанного часового пояса (timezone).

Раздел [users]​

Этот раздел содержит строки с ключом=значением, например:

user1 = settings

Где ключ будет восприниматься как имя пользователя, а значение — как список пар ключ=значение настроек конфигурации, специфичных для этого пользователя. Пример:

user1 = pool_mode=session

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

Обратите внимание, что при настройке auth_file, если пользователь указан в этом разделе, но не указан в auth_file, pgBouncer попытается использовать auth_query для поиска пароля для этого пользователя, если установлен auth_user. Если auth_user не установлен, pgBouncer будет делать вид, что пользователь существует, и не будет возвращать клиенту сообщения «такого пользователя нет», но и не будет принимать указанный пароль.

pool_size​

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

reserve_pool_size​

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

pool_mode​

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

max_user_connections​

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

query_timeout​

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

idle_transaction_timeout​

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

client_idle_timeout​

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

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

max_user_client_connections​

Настройте максимальное количество клиентских подключений для пользователя. Это пользовательский эквивалент параметра max_client_conn.

Раздел [peers]​

В разделе [peers] определяются пиры, которым PgBouncer может пересылать запросы на отмену и куда эти запросы будут направляться.

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

Раздел содержит строки с ключом=значением, например:

peer_id = connection string

Где в качестве ключа будет взят peer_id, а в качестве значения — строка соединения, состоящая из пар ключ=значение параметров соединения, описанных ниже (аналогично libpq, но реальная libpq не используется и набор доступных функций отличается). Пример:

1 = host=host1.example.com
2 = host=/tmp/pgbouncer-2  port=5555
Примечание

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

Примечание

Поддержка кросс-версионного пиринга возможна, если все пиры находятся на одной стороне границы версии 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​

Устанавливает максимальное количество запросов на отмену, которые могут одновременно поступать к пиру. Вполне нормально, что запросы на отмену приходят сериями, например, когда резервный сервер PostgreSQL медленный или не работает. Поэтому важно, чтобы размер пула не был настолько мал, чтобы он не мог справиться с такими всплесками.

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

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

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

%include filename

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

Формат файла аутентификации (userlist.txt)​

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

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

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

Формат MD5-хеша паролей PostgreSQL:

"md5" + md5(password + username)

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

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

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

Пароли или секреты, хранящиеся в файле аутентификации, служат двум целям. Во-первых, они используются для проверки паролей входящих клиентских соединений, если настроен метод аутентификации на основе пароля. Во-вторых, они используются в качестве паролей для исходящих соединений с внутренним сервером, если внутренний сервер требует аутентификации на основе пароля (если пароль не указан непосредственно в строке подключения к базе данных). Последний вариант работает, если пароль хранится в виде обычного текста или MD5-хеша. Секреты SCRAM можно использовать для входа на сервер только в том случае, если аутентификация клиента также использует SCRAM, в определении базы данных PgBouncer не указано имя пользователя, а секреты SCRAM идентичны в PgBouncer и на сервере PostgreSQL (одинаковая соль и итерации, а не просто одинаковый пароль). Это объясняется свойством безопасности, присущим SCRAM: хранимый секрет SCRAM сам по себе не может быть использован для получения учетных данных для входа в систему.

Ограничения​

Если пароль хранится в открытом виде, его можно использовать для любой аутентификации на основе пароля, используемой на внутреннем сервере: в открытом виде, с использованием 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_query вместо auth_file, чтобы избежать необходимости вести отдельный файл аутентификации.

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

Если серверная часть настроена на использование аутентификации по паролю SCRAM, PgBouncer не сможет успешно пройти аутентификацию, если не будет знать либо а) пароль пользователя в открытом виде, либо б) соответствующий секрет 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.

Если использовался другой инструмент, кроме 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.
  • Поле Database. Поддерживаются: all, replication, sameuser, @file, несколько имен. Не поддерживаются: samerole, samegroup.
  • Поле User name. Поддерживаются: all, @file, несколько имен. Не поддерживаются: +groupname.
  • Поле Address. Поддерживает IPv4, IPv6. Не поддерживаются: samehost, samenet, DNS-имена, доменные префиксы.
  • Поле Auth-method. Поддерживаются только методы, поддерживаемые auth_type PgBouncer, а также peer и reject, но кроме any и pam, которые работают только глобально.
  • Параметр User name map (map=) имени пользователя поддерживается, если auth_type является cert или peer.

Формат файла Ident map​

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

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

  • Поддерживаемые строки имеют только вид map-name system-username database-username.
  • Нет поддержки для включения файла / каталога.
  • Поле System-username: Не поддерживается: регулярные выражения.
  • Поле Database-username: поддерживает all или одно имя пользователя postgres. Не поддерживается: +groupname, регулярные выражения.

Примеры​

Небольшой пример конфигурации pgbouncer.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

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

[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;

Пример конфигурации для двух пиринговых (peer-to-peer) процессов 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