H.4. pgbouncer#
H.4. pgbouncer #
Легковесный пул соединений для Tantor BE.
H.4.2. Конфигурация #
H.4.2.1. Описание #
Файл конфигурации имеет формат “ini”. Имена секций находятся между “[” и “]”. Строки, начинающиеся с “;” или “#”, считаются комментариями и игнорируются. Символы “;” и “#” не распознаются как специальные, если они появляются позже в строке.
H.4.2.2. Общие настройки #
H.4.2.2.1. logfile
#
Указывает файл журнала. Для демонизации
(-d
), необходимо установить либо это, либо
syslog
.
Файл журнала остается открытым, поэтому после ротации
kill -HUP
или на консоли
RELOAD;
должно быть выполнено. В Windows
службу необходимо остановить и запустить заново.
Обратите внимание, что установка logfile
сама по себе не отключает ведение журнала в stderr. Для этого используйте параметр командной строки -q
или -d
.
По умолчанию: не установлено
H.4.2.2.2. pidfile
#
Указывает файл PID. Без установки pidfile
демонизация (-d
) не разрешена.
По умолчанию: не установлено
H.4.2.2.3. listen_addr
#
Указывает список (через запятую) адресов, на которых следует
слушать TCP-соединения. Вы также можете использовать
*
, что означает «слушать на всех адресах». Если
не установлено, принимаются только соединения через Unix-сокеты.
Адреса могут быть указаны численно (IPv4/IPv6) или по имени.
По умолчанию: не установлено
H.4.2.2.4. listen_port
#
На каком порту слушать. Применяется как к TCP, так и к Unix сокетам.
По умолчанию: 6432
H.4.2.2.5. unix_socket_dir
#
Указывает расположение для Unix-сокетов. Применяется как к
прослушивающему сокету, так и к соединениям сервера. Если установлено в пустую
строку, Unix-сокеты отключены. Значение, которое начинается с
@
, указывает, что должен быть создан Unix-сокет в
абстрактном пространстве имен (в настоящее время поддерживается в
Linux и Windows).
Для онлайн перезагрузки (-R
) необходимо настроить Unix-сокет, и он должен находиться в пространстве имен файловой системы.
По умолчанию: /tmp
(пусто в Windows)
H.4.2.2.6. unix_socket_mode
#
Режим файловой системы для Unix-сокета. Игнорируется для сокетов в абстрактном пространстве имен. Не поддерживается в Windows.
По умолчанию: 0777
H.4.2.2.7. unix_socket_group
#
Имя группы для использования с Unix-сокетом. Игнорируется для сокетов в абстрактном пространстве имен. Не поддерживается в Windows.
По умолчанию: не установлено
H.4.2.2.8. user
#
Если установлено, указывает Unix-пользователя, на которого нужно переключиться после запуска. Работает только в том случае, если PgBouncer запущен от имени root или если он уже работает как указанный пользователь. Не поддерживается в Windows.
По умолчанию: не установлено
H.4.2.2.9. pool_mode
#
Указывает, когда соединение с сервером может быть повторно использовано другими клиентами.
- session
Сервер возвращается в пул после отключения клиента. По умолчанию.
- transaction
Сервер возвращается в пул после завершения транзакции.
- statement
Сервер возвращается в пул после завершения запроса. Транзакции, охватывающие несколько операторов, не допускаются в этом режиме.
H.4.2.2.10. max_client_conn
#
Максимальное количество разрешенных клиентских подключений.
Когда это значение увеличивается, возможно, также потребуется увеличить
ограничения на файловые дескрипторы в операционной системе. Обратите внимание, что количество потенциально используемых файловых дескрипторов
больше, чем
max_client_conn
. Если каждый пользователь подключается
под своим именем пользователя к серверу, теоретический максимум
использования составляет:
max_client_conn + (max pool_size * total databases * total users)
Если пользователь базы данных указан в строке подключения (все пользователи подключаются под одним именем пользователя), теоретический максимум составляет:
max_client_conn + (max pool_size * total databases)
Теоретический максимум никогда не должен быть достигнут, если только кто-то намеренно не создаст специальную нагрузку для этого. Тем не менее, это означает, что вы должны установить количество файловых дескрипторов на безопасно высокое значение.
Ищите ulimit
в руководстве по вашей любимой оболочке.
Примечание
ulimit
не применяется в
среде Windows.
По умолчанию: 100
H.4.2.2.11. default_pool_size
#
Сколько серверных подключений разрешить на пару пользователь/база данных. Может быть переопределено в конфигурации для каждой базы данных.
По умолчанию: 20
H.4.2.2.12. min_pool_size
#
Добавьте больше серверных подключений в пул, если их количество ниже этого числа. Улучшает поведение, когда нормальная нагрузка внезапно возвращается после периода полной неактивности. Значение фактически ограничено размером пула.
Применяется только для пулов, где хотя бы одно из следующих утверждений истинно:
запись в разделе
[database]
для пула имеет значение, установленное для ключаuser
(также известного как принудительный пользователь)в пул подключен хотя бы один клиент
По умолчанию: 0 (отключено)
H.4.2.2.13. reserve_pool_size
#
Сколько дополнительных подключений разрешить в пул (см.
reserve_pool_timeout
). 0 отключает.
По умолчанию: 0 (отключено)
H.4.2.2.14. reserve_pool_timeout
#
Если клиент не был обслужен за это время, используйте дополнительные соединения из резервного пула. 0 отключает. [секунды]
По умолчанию: 5.0
H.4.2.2.15. max_db_connections
#
Не разрешать более этого количества подключений к серверу на базу данных (независимо от пользователя). Это учитывает базу данных PgBouncer, к которой подключился клиент, а не базу данных Tantor BE исходящего соединения.
Это также можно установить для каждой базы данных в
[databases]
разделе.
Обратите внимание, что при достижении предела закрытие клиентского соединения с одним пулом не позволит немедленно установить серверное соединение для другого пула, поскольку серверное соединение для первого пула все еще открыто. Как только серверное соединение закроется (из-за тайм-аута бездействия), новое серверное соединение будет немедленно открыто для ожидающего пула.
По умолчанию: 0 (неограниченно)
H.4.2.2.16. max_user_connections
#
Не разрешать более этого количества подключений к серверу на пользователя (независимо от базы данных). Это учитывает пользователя PgBouncer, который связан с пулом, который является либо пользователем, указанным для подключения к серверу, либо, при его отсутствии, пользователем, под которым подключился клиент.
Это также можно установить для каждого пользователя в
[users]
разделе.
Обратите внимание, что при достижении предела закрытие клиентского соединения с одним пулом не позволит немедленно установить серверное соединение для другого пула, поскольку серверное соединение для первого пула все еще открыто. Как только серверное соединение закроется (из-за тайм-аута бездействия), новое серверное соединение будет немедленно открыто для ожидающего пула.
По умолчанию: 0 (неограниченно)
H.4.2.2.17. server_round_robin
#
По умолчанию, PgBouncer повторно использует серверные соединения в порядке LIFO (последний пришел, первый вышел), так что несколько соединений получают наибольшую нагрузку. Это обеспечивает наилучшую производительность, если у вас есть один сервер, обслуживающий базу данных. Но если за адресом базы данных (TCP, DNS или список хостов) стоит система с круговым распределением, то лучше, если PgBouncer также использует соединения таким образом, достигая равномерной нагрузки.
По умолчанию: 0
H.4.2.2.18. 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
. Однако невозможно включить сам options
в track_extra_parameters
, только параметры, содержащиеся в options
.
По умолчанию: IntervalStyle
H.4.2.2.19. 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
.
По умолчанию: пусто
H.4.2.2.20. peer_id
#
Идентификатор peer, используемый для идентификации этого процесса PgBouncer в группе
процессов PgBouncer, которые объединены в одноранговую сеть. Значение
peer_id
должно быть уникальным в пределах
группы одноранговых процессов PgBouncer. Если установлено значение 0, одноранговая сеть pgbouncer
отключена. См. документацию для
[peers]
раздела для получения дополнительной информации. Максимальное значение, которое можно использовать для
peer_id
, составляет 16383.
По умолчанию: 0
H.4.2.2.21. disable_pqexec
#
Отключить протокол простого запроса (PQexec). В отличие от протокола расширенного запроса, простой запрос позволяет выполнять несколько запросов в одном пакете, что позволяет некоторым классам атак с использованием SQL-инъекций. Отключение может повысить безопасность. Очевидно, это означает, что будут работать только клиенты, которые используют исключительно протокол расширенного запроса.
По умолчанию: 0
H.4.2.2.22. application_name_add_host
#
Добавьте адрес и порт клиента к имени приложения, установленному при запуске соединения. Это помогает в идентификации источника плохих запросов и т.д. Эта логика применяется только при начале соединения. Если application_name
позже изменяется с помощью SET
, PgBouncer не изменяет его снова.
По умолчанию: 0
H.4.2.2.23. conffile
#
Показать расположение текущего конфигурационного файла. Изменение его заставит
PgBouncer использовать другой конфигурационный файл при следующем
RELOAD
/ SIGHUP
.
По умолчанию: файл из командной строки
H.4.2.2.25. job_name
#
Псевдоним для service_name
.
H.4.2.2.26. stats_period
#
Устанавливает, как часто обновляются средние значения, показанные в различных
SHOW
командах, и как часто
агрегированные статистики записываются в журнал (но см.
log_stats
). [секунды]
По умолчанию: 60
H.4.2.2.27. max_prepared_statements
#
Когда это установлено в ненулевое значение, PgBouncer отслеживает команды, связанные с именованными подготовленными операторами на уровне протокола, отправленные клиентом в режиме пула транзакций и операторов. PgBouncer гарантирует, что любой оператор, подготовленный клиентом, доступен на соединении с сервером поддержки. Даже если оператор изначально был подготовлен на другом соединении с сервером.
PgBouncer внутренне анализирует все запросы, которые отправляются клиентами как подготовленные операторы, и присваивает каждой уникальной строке запроса внутреннее имя в формате PGBOUNCER_{unique_id}
. Если одна и та же строка запроса подготавливается несколько раз (возможно, разными клиентами), то эти запросы используют одно и то же внутреннее имя. PgBouncer подготавливает оператор на фактическом сервере Tantor BE только с использованием внутреннего имени (а не имени, предоставленного клиентом). PgBouncer отслеживает имя, которое клиент дал каждому подготовленному оператору. Затем он переписывает каждую команду, использующую подготовленный оператор, заменяя клиентское имя на внутреннее имя (например, заменяя my_prepared_statement
на PGBOUNCER_123
) перед отправкой этой команды на сервер. Более важно, если подготовленный оператор, который клиент хочет выполнить, еще не подготовлен на сервере (например, потому что другому серверу теперь назначен клиент, чем когда клиент подготовил оператор), то PgBouncer прозрачно подготавливает оператор перед его выполнением.
Примечание
Это отслеживание и переписывание команд подготовленных операторов не работает для команд подготовленных операторов на уровне SQL, поэтому PREPARE
, EXECUTE
и DEALLOCATE
пересылаются напрямую в Postgres. Исключением из этого правила являются команды DEALLOCATE ALL
и DISCARD ALL
, которые работают как ожидалось и очистят подготовленные операторы, которые PgBouncer отслеживал для клиента, отправляющего эту команду.
Фактическое значение этой настройки контролирует количество подготовленных операторов, хранящихся активными в кэше LRU на одном серверном соединении. Когда настройка установлена в 0, поддержка подготовленных операторов для транзакционного и операторного пуллинга отключена. Чтобы добиться наилучшей производительности, следует попытаться убедиться, что это значение больше, чем количество часто используемых подготовленных операторов в вашем приложении. Имейте в виду, что чем выше это значение, тем больше объем памяти каждой PgBouncer-сессии на вашем сервере Tantor BE, потому что будет храниться больше подготовленных запросов на этих соединениях. Это также увеличивает объем памяти самого PgBouncer, так как теперь ему нужно отслеживать строки запросов.
Однако влияние на использование памяти PgBouncer не такое большое:
Каждый уникальный запрос хранится один раз в глобальном кэше запросов.
Каждое клиентское соединение сохраняет буфер, который используется для переписывания пакетов. Это, в большинстве случаев, в 4 раза больше размера
pkt_buf
. Однако этот предел часто не достигается, это происходит только тогда, когда запросы в ваших подготовленных операторах находятся в диапазоне от 2 до 4 раз больше размераpkt_buf
.
Таким образом, если рассмотреть следующее как пример сценария:
Существует 1000 активных клиентов
Клиенты подготавливают 200 уникальных запросов
Средний размер запроса составляет 5 кБ
pkt_buf
параметр установлен по умолчанию на 4096 (4кБ)
Затем PgBouncer требуется максимум следующий объем памяти для обработки этих подготовленных операторов:
200 x 5кБ + 1000 x 4 x 4кБ = ~17МБ памяти.
Отслеживание подготовленных операторов связано не только с затратами памяти, но и с увеличением использования ЦП, поскольку PgBouncer необходимо проверять и переписывать запросы. Несколько экземпляров PgBouncer могут прослушивать один и тот же порт, чтобы использовать более одного ядра для обработки, см. документацию по опции so_reuseport
для подробностей.
Но, конечно, подготовленные операторы также имеют преимущества в производительности. Так же, как при прямом подключении к Tantor BE, подготовка запроса, который выполняется много раз, уменьшает общее количество анализа и планирования, которое необходимо выполнить. Способ, которым PgBouncer отслеживает подготовленные операторы, особенно полезен для производительности, когда несколько клиентов подготавливают одни и те же запросы. Поскольку клиентские подключения автоматически повторно используют подготовленный оператор на серверном подключении, даже если он был подготовлен другим клиентом. Например, если у вас есть pool_size
равный 20 и у вас есть 100 клиентов, которые все подготавливают точно такой же запрос, то запрос подготавливается (и, следовательно, анализируется) только 20 раз на сервере Tantor BE.
Повторное использование подготовленных операторов имеет один недостаток. Если типы возвращаемых значений или аргументов подготовленного оператора изменяются между выполнениями, то Tantor BE в настоящее время выдает ошибку, такую как:
ERROR: cached plan must not change result type
Вы можете избежать таких ошибок, если не использовать несколько клиентов, которые
используют точно такую же строку запроса в подготовленном операторе, но
ожидают разные типы аргументов или результатов. Один из самых
распространенных способов столкнуться с этой проблемой — это миграция DDL,
когда вы добавляете новый столбец или изменяете тип столбца
в существующей таблице. В таких случаях вы можете выполнить
RECONNECT
в консоли администратора PgBouncer
после выполнения миграции, чтобы принудительно повторно подготовить запрос
и устранить ошибку.
По умолчанию: 0
H.4.2.3. Настройки аутентификации #
PgBouncer обрабатывает собственную аутентификацию клиентов и имеет собственную базу данных пользователей. Эти настройки управляют этим.
H.4.2.3.1. 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.- pam
PAM используется для аутентификации пользователей,
auth_file
игнорируется. Этот метод несовместим с базами данных, использующими опциюauth_user
. Имя сервиса, передаваемое в PAM, — “pgbouncer”.pam
не поддерживается в файле конфигурации HBA.
H.4.2.3.2. auth_hba_file
#
Файл конфигурации HBA для использования, когда
auth_type
— это hba
. См.
раздел Формат файла HBA
ниже для подробностей.
По умолчанию: не установлено
H.4.2.3.3. auth_ident_file
#
Файл карты идентификации для использования, когда auth_type
является
hba
и будет определена карта пользователя. См.
раздел Формат файла карты идентификации ниже для подробностей.
По умолчанию: не установлено
H.4.2.3.4. auth_file
#
Имя файла для загрузки имен пользователей и паролей. См. раздел Формат файла аутентификации ниже для подробностей.
Большинство типов аутентификации (см. выше) требуют, чтобы либо
auth_file
, либо auth_user
были установлены; в противном случае не будет определено ни одного пользователя.
По умолчанию: не установлено
H.4.2.3.5. auth_user
#
Если auth_user
установлен, то любой пользователь, не указанный в auth_file
, будет запрашиваться через запрос auth_query
из pg_shadow в базе данных, используя auth_user
. Пароль auth_user
будет взят из auth_file
. (Если auth_user
не требует пароля, то его не нужно определять в auth_file
.)
Прямой доступ к pg_shadow требует прав администратора. Предпочтительнее использовать не-суперпользователя, который вызывает функцию SECURITY DEFINER.
По умолчанию: не установлено
H.4.2.3.6. auth_query
#
Запрос для загрузки пароля пользователя из базы данных.
Прямой доступ к pg_shadow требует прав администратора. Предпочтительнее использовать не-суперпользователя, который вызывает функцию SECURITY DEFINER.
Обратите внимание, что запрос выполняется внутри целевой базы данных. Поэтому, если используется функция, её необходимо установить в каждую базу данных.
По умолчанию:
SELECT usename, passwd FROM pg_shadow WHERE usename=$1
H.4.2.3.7. auth_dbname
#
Имя базы данных в разделе [database]
для
использования в целях аутентификации. Этот параметр может быть
либо глобальным, либо переопределён в строке подключения, если
этот параметр указан.
H.4.2.4. Настройки журнала #
H.4.2.4.1. syslog
#
Переключает syslog в режим вкл/выкл. В Windows вместо этого используется журнал событий.
По умолчанию: 0
H.4.2.4.2. syslog_ident
#
Под каким именем отправлять логи в syslog.
По умолчанию: pgbouncer
(имя программы)
H.4.2.4.3. syslog_facility
#
Под каким идентификатором отправлять логи в syslog. Возможные варианты:
auth
, authpriv
,
daemon
, user
,
local0-7
.
По умолчанию: daemon
H.4.2.4.6. log_pooler_errors
#
Регистрировать сообщения об ошибках, которые пулер отправляет клиентам.
По умолчанию: 1
H.4.2.4.7. log_stats
#
Записывать агрегированную статистику в журнал каждые
stats_period
. Это можно отключить, если
используются внешние инструменты мониторинга для получения тех же данных из
команд SHOW
.
По умолчанию: 1
H.4.2.4.8. verbose
#
Увеличить подробность. Отражает переключатель «-v» в командной строке. Например, использование «-v -v» в командной строке эквивалентно verbose=2
.
По умолчанию: 0
H.4.2.5. Управление доступом к консоли #
H.4.2.5.1. admin_users
#
Список пользователей базы данных, разделенных запятыми, которым разрешено
подключаться и выполнять все команды в консоли. Игнорируется, когда
auth_type
имеет значение any
, в
этом случае любое имя пользователя допускается в качестве администратора.
По умолчанию: пусто
H.4.2.5.2. stats_users
#
Список пользователей базы данных, разделенных запятыми, которым разрешено
подключаться и выполнять запросы только для чтения в консоли. Это означает
все команды SHOW
, кроме
SHOW FDS
.
По умолчанию: пусто
H.4.2.6. Проверка корректности соединения, тайм-ауты #
H.4.2.6.1. server_reset_query
#
Запрос отправлен на сервер при освобождении соединения, прежде чем сделать его доступным для других клиентов. В этот момент транзакция не выполняется, поэтому значение не должно включать ABORT
или ROLLBACK
.
Запрос предназначен для очистки любых изменений, внесенных в
сеанс базы данных, чтобы следующий клиент получил соединение
в четко определенном состоянии. По умолчанию используется
DISCARD ALL
, который очищает все, но
это оставляет следующего клиента без предварительно кэшированного состояния. Это может быть
сделано легче, например, DEALLOCATE ALL
, чтобы просто
удалить подготовленные операторы, если приложение не ломается,
когда некоторое состояние сохраняется.
Когда используется пул транзакций,
server_reset_query
не используется, потому что в
этом режиме клиенты не должны использовать какие-либо функции, основанные на сессии,
так как каждая транзакция оказывается в другом соединении и, таким образом, получает другое состояние сессии.
По умолчанию: DISCARD ALL
H.4.2.6.2. server_reset_query_always
#
Будет ли server_reset_query
выполняться во всех режимах пула. Когда этот параметр отключен (по умолчанию), server_reset_query
будет выполняться только в пулах, которые находятся в режиме пула сессий. Соединения в режиме пула транзакций не должны нуждаться в запросе сброса.
Этот параметр предназначен для обхода некорректных настроек, которые запускают приложения, использующие функции сессии через PgBouncer с пулом транзакций. Он изменяет недетерминированные поломки на детерминированные: клиенты всегда теряют свое состояние после каждой транзакции.
По умолчанию: 0
H.4.2.6.3. server_check_delay
#
Как долго сохранять освобожденные соединения доступными для немедленного
повторного использования, без выполнения server_check_query
на них. Если 0, то проверка всегда выполняется.
По умолчанию: 30.0
H.4.2.6.4. server_check_query
#
Простой запрос, который ничего не делает, чтобы проверить, активное ли соединение с сервером.
Если пустая строка, то проверка на корректность отключена.
По умолчанию: select 1
H.4.2.6.5. server_fast_close
#
Отключить сервер в режиме пуллинга сессий немедленно или
после завершения текущей транзакции, если он находится в
режиме “close_needed” (установлен с помощью RECONNECT
,
RELOAD
, который изменяет настройки подключения, или
изменения DNS), вместо ожидания завершения сессии. В
режиме пуллинга операторов или транзакций это не имеет эффекта,
так как это поведение по умолчанию.
Если из-за этой настройки соединение с сервером закрывается до окончания сеанса клиента, соединение клиента также закрывается. Это гарантирует, что клиент заметит, что сеанс был прерван.
Этот параметр позволяет изменениям конфигурации подключения вступать в силу быстрее, если используется пуллинг сессий и длительные сессии. Недостатком является то, что клиентские сессии могут быть прерваны из-за изменения конфигурации, поэтому клиентским приложениям потребуется логика для повторного подключения и восстановления состояния сессии. Но обратите внимание, что транзакции не будут потеряны, так как выполняющиеся транзакции не прерываются, только бездействующие сессии.
По умолчанию: 0
H.4.2.6.6. server_lifetime
#
Пуллер закроет неиспользуемое (в настоящее время не связанное ни с одним клиентским соединением) серверное соединение, которое было подключено дольше этого времени. Установка значения 0 означает, что соединение будет использоваться только один раз, а затем закрываться. [секунды]
Это также можно установить для каждой базы данных в
[databases]
разделе.
По умолчанию: 3600.0
H.4.2.6.7. server_idle_timeout
#
Если соединение с сервером было бездействующим более указанного количества секунд, оно будет закрыто. Если 0, то этот тайм-аут отключен. [секунды]
По умолчанию: 600.0
H.4.2.6.8. server_connect_timeout
#
Если соединение и вход не завершатся за это время, соединение будет закрыто. [секунды]
По умолчанию: 15.0
H.4.2.6.9. server_login_retry
#
Если вход на сервер не удался из-за сбоя подключения или аутентификации, пулер ждет это время перед повторной попыткой подключения. В течение интервала ожидания новые клиенты, пытающиеся подключиться к неработающему серверу, получат ошибку немедленно без повторной попытки подключения. [секунды]
Цель этого поведения заключается в том, чтобы клиенты не
ждали в очереди без необходимости, пока серверное соединение
не станет доступным, если сервер не работает. Однако это
также означает, что если сервер временно не работает, например,
во время перезапуска или если конфигурация была
ошибочной, то потребуется как минимум столько времени, чтобы
пулер снова рассмотрел возможность подключения к нему. Планируемые события,
такие как перезапуски, обычно должны управляться с помощью команды
PAUSE
, чтобы избежать этого.
По умолчанию: 15.0
H.4.2.6.10. client_login_timeout
#
Если клиент подключается, но не успевает войти в систему за это
время, он будет отключен. В основном необходимо для
предотвращения зависания соединений, блокирующих SUSPEND
и
таким образом онлайн перезапуск. [секунды]
По умолчанию: 60.0
H.4.2.6.11. autodb_idle_timeout
#
Если автоматически созданные (через «*») пулы баз данных не использовались в течение этого количества секунд, они освобождаются. Отрицательный аспект этого заключается в том, что их статистика также забывается. [секунды]
По умолчанию: 3600.0
H.4.2.6.12. dns_max_ttl
#
Как долго результаты DNS-запросов могут кэшироваться. Фактический TTL DNS игнорируется. [секунды]
По умолчанию: 15.0
H.4.2.6.13. dns_nxdomain_ttl
#
Как долго ошибки DNS и запросы NXDOMAIN DNS могут кэшироваться. [секунды]
По умолчанию: 15.0
H.4.2.6.14. dns_zone_check_period
#
Период для проверки, изменился ли серийный номер зоны.
PgBouncer может собирать DNS-зоны из имен хостов (все после первой точки) и затем периодически проверять, изменяется ли серийный номер зоны. Если он замечает изменения, все имена хостов в этой зоне проверяются снова. Если какой-либо IP-адрес хоста изменяется, его соединения аннулируются.
Работает только с бэкендом c-ares (configure
опция --with-cares
).
По умолчанию: 0.0 (отключено)
H.4.2.6.15. resolv_conf
#
Расположение пользовательского файла resolv.conf
.
Это позволяет указывать пользовательские DNS-серверы и, возможно,
другие параметры разрешения имен, независимо от глобальной
конфигурации операционной системы.
Требуется evdns (>= 2.0.3) или c-ares (>= 1.15.0) бэкенд.
Разбор файла выполняется библиотекой DNS backend, а не PgBouncer, поэтому см. документацию библиотеки для получения подробной информации о допустимом синтаксисе и директивах.
По умолчанию: пусто (используются значения по умолчанию операционной системы)
H.4.2.7. Настройки TLS #
H.4.2.7.1. client_tls_sslmode
#
Режим TLS для использования при подключениях от клиентов. Подключения TLS
отключены по умолчанию. Когда включены,
client_tls_key_file
и
client_tls_cert_file
также должны быть
настроены для установки ключа и сертификата, которые PgBouncer использует для
принятия подключений от клиентов. Наиболее распространенный формат файла сертификата,
используемый PgBouncer, - это pem.
- disable
Обычный TCP. Если клиент запрашивает TLS, это игнорируется. По умолчанию.
- allow
Если клиент запрашивает TLS, он используется. Если нет, используется простой TCP. Если клиент предоставляет клиентский сертификат, он не проверяется.
- prefer
То же, что и
allow
.- require
Клиент должен использовать TLS. В противном случае соединение клиента отклоняется. Если клиент предоставляет клиентский сертификат, он не проверяется.
- verify-ca
Клиент должен использовать TLS с действительным клиентским сертификатом.
- verify-full
То же, что и
verify-ca
.
H.4.2.7.2. client_tls_key_file
#
Закрытый ключ для PgBouncer для принятия подключений клиентов.
По умолчанию: не установлено
H.4.2.7.3. client_tls_cert_file
#
Сертификат для закрытого ключа. Клиенты могут его проверить.
По умолчанию: не установлено
H.4.2.7.4. client_tls_ca_file
#
Файл корневого сертификата для проверки клиентских сертификатов.
По умолчанию: не установлено
H.4.2.7.5. 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
H.4.2.7.6. client_tls_ciphers
#
Разрешенные шифры TLS, в синтаксисе OpenSSL. Сокращения:
по умолчанию
/безопасный
/быстрый
/нормальный
(все они используют системные настройки OpenSSL по умолчанию)all
(включает все шифры, не рекомендуется)
Только соединения, использующие TLS версии 1.2 и ниже, подвержены воздействию. В настоящее время нет настройки, которая контролирует выбор шифров, используемых соединениями TLS версии 1.3.
По умолчанию: default
H.4.2.7.7. client_tls_ecdhcurve
#
Имя эллиптической кривой для использования в обменах ключами ECDH.
Допустимые значения: none
(DH отключен),
auto
(256-битный ECDH), имя кривой
По умолчанию: auto
H.4.2.7.8. client_tls_dheparams
#
Тип обмена ключами DHE.
Допустимые значения: none
(DH отключен),
auto
(2048-битный DH),
legacy
(1024-битный DH)
По умолчанию: auto
H.4.2.7.9. server_tls_sslmode
#
Режим TLS для использования при подключениях к серверам Tantor BE.
Режим по умолчанию — prefer
.
- disable
Простой TCP. TLS даже не запрашивается у сервера.
- allow
FIXME: если сервер отклоняет обычное соединение, попробовать TLS?
- prefer
TLS соединение всегда запрашивается сначала от Tantor BE. Если отказано, соединение будет установлено по обычному TCP. Сертификат сервера не проверяется. По умолчанию
- require
Соединение должно проходить через TLS. Если сервер отклоняет его, обычный TCP не используется. Сертификат сервера не проверяется.
- verify-ca
Соединение должно осуществляться через TLS, и сертификат сервера должен быть действительным в соответствии с
server_tls_ca_file
. Имя хоста сервера не проверяется по сертификату.- verify-full
Соединение должно осуществляться через TLS, и сертификат сервера должен быть действительным в соответствии с
server_tls_ca_file
. Имя хоста сервера должно соответствовать информации в сертификате.
H.4.2.7.10. server_tls_ca_file
#
Файл корневого сертификата для проверки сертификатов сервера Tantor BE.
По умолчанию: не установлено
H.4.2.7.11. server_tls_key_file
#
Закрытый ключ для PgBouncer для аутентификации на сервере Tantor BE.
По умолчанию: не установлено
H.4.2.7.12. server_tls_cert_file
#
Сертификат для закрытого ключа. Сервер Tantor BE может его проверить.
По умолчанию: не установлено
H.4.2.7.13. 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
H.4.2.7.14. server_tls_ciphers
#
Разрешенные шифры TLS, в синтаксисе OpenSSL. Сокращения:
по умолчанию
/безопасный
/быстрый
/нормальный
(все они используют системные настройки OpenSSL по умолчанию)all
(включает все шифры, не рекомендуется)
Только соединения, использующие TLS версии 1.2 и ниже, подвержены воздействию. В настоящее время нет настройки, которая контролирует выбор шифров, используемых соединениями TLS версии 1.3.
По умолчанию: default
H.4.2.8. Опасные тайм-ауты #
Установка следующих тайм-аутов может вызвать неожиданные ошибки.
H.4.2.8.1. query_timeout
#
Запросы, выполняющиеся дольше этого времени, отменяются. Это следует
использовать только с немного меньшим серверным
statement_timeout
, чтобы применять только для
сетевых проблем. [секунды]
По умолчанию: 0.0 (отключено)
H.4.2.8.2. query_wait_timeout
#
Максимальное время, которое запросы могут ожидать выполнения. Если запрос не назначен серверу в течение этого времени, клиент отключается. 0 отключает. Если это отключено, клиенты будут находиться в очереди бесконечно. [секунды]
Этот параметр используется для предотвращения захвата соединений неотзывчивыми серверами. Он также помогает, когда сервер не работает или отклоняет соединения по любой причине.
По умолчанию: 120.0
H.4.2.8.3. cancel_wait_timeout
#
Максимальное время, в течение которого запросы на отмену могут ожидать выполнения. Если запрос на отмену не назначен серверу в течение этого времени, клиент отключается. 0 отключает. Если это отключено, запросы на отмену будут находиться в очереди бесконечно. [секунды]
Этот параметр используется для предотвращения блокировки клиента, когда отмена не может быть передана из-за недоступности сервера.
По умолчанию: 10.0
H.4.2.8.4. client_idle_timeout
#
Клиентские подключения, простаивающие дольше этого количества секунд, закрываются. Это значение должно быть больше, чем настройки времени жизни подключения на стороне клиента, и использоваться только для проблем с сетью. [секунды]
По умолчанию: 0.0 (отключено)
H.4.2.8.5. idle_transaction_timeout
#
Если клиент находится в состоянии «бездействие в транзакции» дольше, он будет отключен. [секунды]
По умолчанию: 0.0 (отключено)
H.4.2.8.6. suspend_timeout
#
Сколько времени ждать сброса буфера во время
SUSPEND
или перезагрузки (-R
).
Соединение разрывается, если сброс не удается.
[секунды]
По умолчанию: 10
H.4.2.9. Настройки низкоуровневой сети #
H.4.2.9.1. pkt_buf
#
Внутренний размер буфера для пакетов. Влияет на размер отправляемых TCP-пакетов и общее использование памяти. Фактические пакеты libpq могут быть больше этого, поэтому нет необходимости устанавливать его большим.
По умолчанию: 4096
H.4.2.9.2. max_packet_size
#
Максимальный размер пакетов для Tantor BE, которые PgBouncer позволяет пропускать. Один пакет - это либо один запрос, либо одна строка результата. Полный набор результатов может быть больше.
По умолчанию: 2147483647
H.4.2.9.3. listen_backlog
#
Аргумент Backlog для listen(2). Определяет, сколько новых неотвеченных попыток подключения сохраняется в очереди. Когда очередь заполнена, дальнейшие новые подключения отклоняются.
По умолчанию: 128
H.4.2.9.4. sbuf_loopcnt
#
Сколько раз обрабатывать данные на одном соединении, прежде чем продолжить. Без этого ограничения одно соединение с большим набором результатов может надолго задержать PgBouncer. Один цикл обрабатывает один объем данных pkt_buf
. 0 означает отсутствие ограничения.
По умолчанию: 5
H.4.2.9.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
H.4.2.9.6. tcp_defer_accept
#
Устанавливает опцию сокета TCP_DEFER_ACCEPT
;
см. man 7 tcp
для подробностей. (Это
логическая опция: 1 означает включено. Фактическое значение,
установленное при включении, в настоящее время жестко задано на 45 секунд.)
Это в настоящее время поддерживается только на Linux.
По умолчанию: 1 на Linux, в противном случае 0
H.4.2.9.7. tcp_socket_buffer
#
По умолчанию: не установлено
H.4.2.9.8. tcp_keepalive
#
Включает базовый keepalive с настройками ОС по умолчанию.
На Linux системные значения по умолчанию: tcp_keepidle=7200, tcp_keepintvl=75, tcp_keepcnt=9. Они, вероятно, аналогичны на других операционных системах.
По умолчанию: 1
H.4.2.9.9. tcp_keepcnt
#
По умолчанию: не установлено
H.4.2.9.10. tcp_keepidle
#
По умолчанию: не установлено
H.4.2.9.11. tcp_keepintvl
#
По умолчанию: не установлено
H.4.2.9.12. tcp_user_timeout
#
Устанавливает опцию сокета TCP_USER_TIMEOUT
.
Это указывает максимальное количество времени в миллисекундах,
в течение которого переданные данные могут оставаться неподтвержденными
до принудительного закрытия TCP-соединения. Если установлено значение 0,
используется значение по умолчанию операционной системы.
Это в настоящее время поддерживается только на Linux.
По умолчанию: 0
H.4.2.10. Раздел [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
.
H.4.2.10.1. dbname
#
Имя целевой базы данных.
По умолчанию: то же, что и имя базы данных на стороне клиента
H.4.2.10.2. 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-сокета
H.4.2.10.3. port
#
По умолчанию: 5432
H.4.2.10.4. user
#
Если user=
установлен, все подключения к
целевой базе данных будут выполняться с указанным пользователем,
что означает, что будет только один пул для этой базы данных.
В противном случае PgBouncer входит в целевую базу данных с именем пользователя клиента, что означает, что будет один пул на пользователя.
H.4.2.10.5. password
#
Если здесь не указан пароль, будет использован пароль из
auth_file
для пользователя,
указанного выше. Динамические формы обнаружения пароля, такие как
auth_query
, в настоящее время не поддерживаются.
H.4.2.10.6. auth_user
#
Переопределение глобальной настройки auth_user
,
если указано.
H.4.2.10.7. auth_query
#
Переопределение глобальной настройки auth_query
,
если указано. Весь SQL-запрос должен быть заключен в
одиночные кавычки.
H.4.2.10.8. auth_dbname
#
Переопределение глобальной настройки auth_dbname
,
если указано.
H.4.2.10.9. pool_size
#
Установите максимальный размер пулов для этой базы данных. Если не установлено,
используется default_pool_size
.
H.4.2.10.10. min_pool_size
#
Установите минимальный размер пула для этой базы данных. Если не установлено, используется
глобальный min_pool_size
.
Применяется только в том случае, если выполняется хотя бы одно из следующих условий:
эта запись в разделе
[database]
имеет установленное значение для ключаuser
(также известного как принудительный пользователь)в пул подключен хотя бы один клиент
H.4.2.10.11. reserve_pool
#
Установите дополнительные подключения для этой базы данных. Если не установлено,
используется reserve_pool_size
.
H.4.2.10.12. connect_query
#
Запрос, который будет выполнен после установления соединения, но до того, как соединение будет использовано любыми клиентами. Если запрос вызывает ошибки, они регистрируются, но в остальном игнорируются.
H.4.2.10.13. pool_mode
#
Установите режим пула, специфичный для этой базы данных. Если не установлено, используется
режим пула по умолчанию pool_mode
.
H.4.2.10.14. max_db_connections
#
Настройте максимальное количество подключений для всей базы данных (т.е. все пулы в базе данных не будут иметь больше этого количества подключений к серверу).
H.4.2.10.15. server_lifetime
#
Настройте server_lifetime для каждой базы данных. Если не установлено,
база данных будет использовать значение, настроенное для всего экземпляра,
для server_lifetime
H.4.2.10.16. client_encoding
#
Запросить конкретную client_encoding
с сервера.
H.4.2.10.17. datestyle
#
Запросить конкретный datestyle
с сервера.
H.4.2.10.18. timezone
#
Запросить конкретный timezone
с сервера.
H.4.2.11. Раздел [users]
#
Этот раздел содержит строки в формате ключ=значение, такие как
user1 = settings
где ключ будет принят как имя пользователя, а значение как список пар ключ=значение настроек конфигурации, специфичных для этого пользователя. Пример:
user1 = pool_mode=session
Только несколько настроек доступны здесь.
Обратите внимание, что когда настроен auth_file
, если
пользователь определен в этом разделе, но не указан в
auth_file
, pgBouncer попытается использовать
auth_query
для поиска пароля для этого пользователя,
если установлен auth_user
. Если
auth_user
не установлен, pgBouncer будет делать вид,
что пользователь существует, и не будет возвращать сообщения
«нет такого пользователя» клиенту, но также не примет
предоставленный пароль.
H.4.2.11.1. pool_size
#
Установите максимальный размер пулов для всех подключений от этого
пользователя. Если не установлено, используется база данных или
default_pool_size
.
H.4.2.11.2. pool_mode
#
Установите режим пула, который будет использоваться для всех подключений от этого
пользователя. Если не установлено, используется база данных или режим пула по умолчанию
pool_mode
.
H.4.2.11.3. max_user_connections
#
Настройте максимальное значение для пользователя (т.е. все пулы с этим пользователем не будут иметь больше этого количества серверных подключений).
H.4.2.12. Раздел [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 были внесены некоторые изменения, нарушающие совместимость, в способ кодирования токенов отмены, что сделало их несовместимыми с токенами, созданными более ранними версиями.
H.4.2.12.1. 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
H.4.2.12.2. port
#
По умолчанию: 6432
H.4.2.12.3. pool_size
#
Установите максимальное количество запросов на отмену, которые могут быть
отправлены одноранговому узлу одновременно. Это вполне нормально, когда
запросы на отмену приходят сериями, например, когда сервер
Postgres работает медленно или не работает. Поэтому важно, чтобы
pool_size
не был настолько мал, чтобы не справляться с этими сериями.
Если не установлено, используется default_pool_size
.
H.4.2.13. Include директивы #
Файл конфигурации PgBouncer может содержать директивы include, которые указывают на другой конфигурационный файл для чтения и обработки. Это позволяет разделить файл конфигурации на физически отдельные части. Директивы include выглядят следующим образом:
%include filename
Если имя файла не является абсолютным путем, оно рассматривается как относительное к текущему рабочему каталогу.
H.4.2.14. Формат файла аутентификации #
Этот раздел описывает формат файла, указанного настройкой
auth_file
. Это текстовый файл в
следующем формате:
"username1" "password" ... "username2" "md5abcdef012342345" ... "username2" "SCRAM-SHA-256$<iterations>:<salt>$<storedkey>:<serverkey>"
Должно быть как минимум 2 поля, заключенные в двойные кавычки. Первое поле - это имя пользователя, а второе - либо пароль в открытом виде, либо пароль, хэшированный с помощью MD5, либо секрет SCRAM. PgBouncer игнорирует остальную часть строки. Двойные кавычки в значении поля могут быть экранированы, написав две двойные кавычки.
Tantor BE формат пароля с хешированием MD5:
"md5" + md5(password + username)
Таким образом, пользователь admin
с паролем
1234
будет иметь пароль с хешем MD5
md545f2603610af569b6155c45067268c6b
.
Tantor BE Формат секрета SCRAM:
SCRAM-SHA-256$<iterations>:<salt>$<storedkey>:<serverkey>
См. документацию Tantor BE и RFC 5803 для получения подробной информации об этом.
Пароли или секреты, хранящиеся в файле аутентификации, служат двум целям. Во-первых, они используются для проверки паролей входящих клиентских подключений, если настроен метод аутентификации на основе пароля. Во-вторых, они используются в качестве паролей для исходящих подключений к серверу бэкенда, если сервер бэкенда требует аутентификации на основе пароля (если только пароль не указан напрямую в строке подключения к базе данных).
H.4.2.14.1. Ограничения #
Если пароль хранится в виде обычного текста, он может быть использован для любой аутентификации на основе пароля, используемой в сервере бэкенда; обычный текст, MD5 или SCRAM (см. Аутентификация по паролю для подробностей).
Пароли с хешированием MD5 могут использоваться, если серверная часть использует аутентификацию MD5 (или у конкретных пользователей есть пароли с хешированием MD5).
SCRAM-секреты могут использоваться для входа на сервер только в том случае, если аутентификация клиента также использует SCRAM, определение базы данных PgBouncer не указывает имя пользователя, и SCRAM-секреты идентичны в PgBouncer и на сервере Tantor BE (одинаковая соль и итерации, а не просто одинаковый пароль). Это связано с присущим свойством безопасности SCRAM: сохраненный SCRAM-секрет не может сам по себе использоваться для получения учетных данных для входа.
Файл аутентификации можно написать вручную, но также
полезно сгенерировать его из какого-либо другого списка пользователей и
паролей. См. ./etc/mkauth.py
для примера
скрипта, который генерирует файл аутентификации из
системной таблицы pg_shadow
. В качестве альтернативы, используйте
auth_query
вместо
auth_file
, чтобы избежать необходимости поддерживать
отдельный файл аутентификации.
H.4.2.14.2. Примечание относительно управляемых серверов #
Если серверная часть настроена на использование SCRAM-аутентификации по паролю, PgBouncer не может успешно аутентифицироваться, если он не знает либо a) пароль пользователя в открытом виде, либо b) соответствующий SCRAM-секрет.
Некоторые облачные провайдеры (например, AWS RDS) запрещают доступ к
Tantor BE чувствительным системным таблицам для получения паролей.
Даже для самого привилегированного пользователя (например, члена
rds_superuser) команда select * from pg_authid
;
возвращает
ОШИБКА: отказано в доступе к таблице 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 секрет из ЗАПРОСА и установите его в
userlist.txt
PgBouncer.
Если вы использовали инструмент, отличный от
psql --echo-hidden
, то вам также нужно установить
SCRAM секрет на сервере (вы можете использовать
alter role <role_name> password '<scram_secret>'
для этого).
H.4.2.15. Формат файла HBA #
Расположение файла HBA указывается настройкой
auth_hba_file
. Он используется только если
auth_type
установлен в hba
.
Файл следует формату файла Tantor BE
pg_hba.conf
(см.
Файл pg_hba.conf
).
Поддерживаемые типы записей:
local
,host
,hostssl
,hostnossl
.Поле базы данных: Поддерживает
all
,replication
,sameuser
,@file
, несколько имен. Не поддерживается:samerole
,samegroup
.Поле имени пользователя: Поддерживает
все
,@file
, несколько имен. Не поддерживается:+groupname
.Поле адреса: Поддерживает
все
, IPv4, IPv6. Не поддерживается:samehost
,samenet
, DNS имена, префиксы доменов.Auth-method field: Поддерживаются только методы, поддерживаемые
auth_type
PgBouncer, плюсpeer
иreject
, но за исключениемany
иpam
, которые работают только глобально.Параметр карты имен пользователей (
map=
) поддерживается, когдаauth_type
являетсяcert
илиpeer
.
H.4.2.16. Формат файла карты идентификаторов #
Расположение файла карты ident указывается настройкой
auth_ident_file
. Он загружается только если
auth_type
установлен в hba
.
Формат файла является упрощенной вариацией файла карты идентификации Tantor BE (см. Карты имен пользователей).
Поддерживаются только строки вида
map-name system-username database-username
.Нет поддержки для включения файла/каталога.
Поле System-username: Не поддерживается: регулярные выражения.
Поле имени пользователя базы данных: Поддерживает
all
или одно имя пользователя postgres. Не поддерживается:+groupname
, регулярные выражения.
H.4.2.17. Примеры #
Небольшой пример конфигурации:
[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 usename, passwd FROM pg_catalog.pg_shadow WHERE usename = i_username INTO uname, phash; RETURN; END; $$ LANGUAGE plpgsql SECURITY DEFINER; 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
H.4.2.18. См. также #
pgbouncer(1) - man-страница для общего использования, консольные команды
H.4.3. Использование #
H.4.3.1. Краткий обзор #
pgbouncer [-d][-R][-v][-u user] <pgbouncer.ini> pgbouncer -V|-h
На Windows, параметры следующие:
pgbouncer.exe [-v][-u user] <pgbouncer.ini> pgbouncer.exe -V|-h
Дополнительные параметры для настройки службы Windows:
pgbouncer.exe --regservice <pgbouncer.ini> pgbouncer.exe --unregservice <pgbouncer.ini>
H.4.3.2. Описание #
pgbouncer это пул соединений для Tantor BE. Любое целевое приложение может подключаться к pgbouncer так, как если бы это был сервер Tantor BE, и pgbouncer создаст соединение с реальным сервером или повторно использует одно из существующих соединений.
Цель pgbouncer заключается в снижении влияния на производительность при открытии новых подключений к Tantor BE.
Чтобы не нарушать семантику транзакций при использовании пула подключений, pgbouncer поддерживает несколько типов пулов при ротации подключений:
- Session pooling
Наиболее вежливый метод. Когда клиент подключается, ему будет назначено серверное соединение на все время, пока клиент остается подключенным. Когда клиент отключается, серверное соединение будет возвращено в пул. Это метод по умолчанию.
- Transaction pooling
Соединение с сервером назначается клиенту только во время транзакции. Когда PgBouncer замечает, что транзакция завершена, соединение с сервером будет возвращено в пул.
- Statement pooling
Наиболее агрессивный метод. Соединение с сервером будет возвращено в пул сразу после завершения запроса. Многооператорные транзакции запрещены в этом режиме, так как они могут нарушиться.
Интерфейс администрирования
pgbouncer состоит из некоторых
новых команд SHOW
, доступных при подключении к
специальной "виртуальной" базе данных
pgbouncer.
H.4.3.3. Быстрый старт #
Основная настройка и использование следующие.
Создайте файл pgbouncer.ini. Подробности в pgbouncer(5). Простой пример:
[databases] template1 = host=localhost port=5432 dbname=template1 [pgbouncer] listen_port = 6432 listen_addr = localhost auth_type = md5 auth_file = userlist.txt logfile = pgbouncer.log pidfile = pgbouncer.pid admin_users = someuser
Создайте файл
userlist.txt
, который содержит пользователей, которым разрешен доступ:"someuser" "same_password_as_in_server"
Запуск pgbouncer:
$ pgbouncer -d pgbouncer.ini
Подключите ваше приложение (или клиент psql) к pgbouncer вместо прямого подключения к серверу Tantor BE:
$ psql -p 6432 -U someuser template1
Управляйте pgbouncer, подключаясь к специальной административной базе данных pgbouncer и выполняя
SHOW HELP;
для начала:$ psql -p 6432 -U someuser pgbouncer pgbouncer=# SHOW HELP; NOTICE: Console usage DETAIL: SHOW [HELP|CONFIG|DATABASES|FDS|POOLS|CLIENTS|SERVERS|SOCKETS|LISTS|VERSION|...] SET key = arg RELOAD PAUSE SUSPEND RESUME SHUTDOWN [...]
Если вы внесли изменения в файл pgbouncer.ini, вы можете перезагрузить его с помощью:
pgbouncer=# RELOAD;
H.4.3.4. Командные параметры #
-
-d
,--daemon
Запустить в фоновом режиме. Без этого процесс будет выполняться на переднем плане.
В режиме демона необходимо установить
pidfile
, а такжеlogfile
илиsyslog
. После перехода в фоновый режим сообщения журнала не будут записываться в stderr.Примечание
Не работает на Windows; pgbouncer должен запускаться как служба.
-
-R
,--reboot
УСТАРЕЛО: Вместо этого параметра используйте поочередную перезагрузку с несколькими процессами pgbouncer, прослушивающими один и тот же порт с использованием so_reuseport вместо этого Выполните онлайн перезапуск. Это означает подключение к запущенному процессу, загрузку открытых сокетов из него и их использование. Если активного процесса нет, загрузитесь в обычном режиме.
Примечание
Работает только в том случае, если ОС поддерживает Unix-сокеты и
unix_socket_dir
не отключен в конфигурации. Не работает в Windows. Не работает с TLS-соединениями, они сбрасываются.-
-u
USERNAME,--user=
USERNAME Переключиться на указанного пользователя при запуске.
-
-v
,--verbose
Увеличить подробность. Может использоваться несколько раз.
-
-q
,--quiet
Будьте тихими: не записывайте в stderr. Это не влияет на подробность ведения журнала, только на то, что stderr не будет использоваться. Для использования в скриптах init.d.
-
-V
,--version
Показать версию.
-
-h
,--help
Показать краткую справку.
-
--regservice
Win32: Зарегистрируйте pgbouncer для запуска как служба Windows. Значение параметра конфигурации service_name используется в качестве имени для регистрации.
-
--unregservice
Win32: Отменить регистрацию службы Windows.
H.4.3.5. Консоль администратора #
Консоль доступна при подключении, как обычно, к базе данных pgbouncer:
$ psql -p 6432 pgbouncer
Только пользователи, перечисленные в параметрах конфигурации
admin_users или
stats_users, имеют право
входить в консоль. (За исключением случая, когда
auth_type=any
, тогда любой пользователь допускается как
stats_user.)
Кроме того, имя пользователя pgbouncer разрешено для входа без пароля, если вход осуществляется через Unix-сокет и клиент имеет тот же UID Unix-пользователя, что и выполняющийся процесс.
Консоль администратора в настоящее время поддерживает только протокол простого запроса. Некоторые драйверы используют расширенный протокол запроса для всех команд; эти драйверы не будут работать для этого.
H.4.3.5.1. Показать команды #
Команды SHOW выводят информацию. Каждая команда описана ниже.
H.4.3.5.1.1. SHOW STATS
#
Показывает статистику. В этой и связанных командах общие
показатели с момента запуска процесса, средние значения обновляются
каждые stats_period
.
- database
Статистика представлена по каждой базе данных.
- total_xact_count
Общее количество SQL транзакций, объединенных pgbouncer.
- total_query_count
Общее количество SQL-команд, объединенных pgbouncer.
- total_server_assignment_count
Общее количество раз, когда сервер был назначен клиенту
- total_received
Общий объем в байтах сетевого трафика, полученного pgbouncer.
- total_sent
Общий объем в байтах сетевого трафика, отправленного pgbouncer.
- total_xact_time
Общее количество микросекунд, проведенных pgbouncer при подключении к Tantor BE в транзакции, либо в состоянии простоя в транзакции, либо при выполнении запросов.
- total_query_time
Общее количество микросекунд, проведенных pgbouncer при активном подключении к Tantor BE, выполняя запросы.
- total_wait_time
Время, затраченное клиентами в ожидании сервера, в микросекундах. Обновляется, когда клиентскому подключению назначается подключение к серверу.
- avg_xact_count
Среднее количество транзакций в секунду за последний период статистики.
- avg_query_count
Среднее количество запросов в секунду за последний период статистики.
- avg_server_assignment_count
Среднее количество раз, когда сервер назначался клиенту в секунду за последний период статистики.
- avg_recv
Среднее количество полученных (от клиентов) байт в секунду.
- avg_sent
Среднее количество отправленных (клиентам) байт в секунду.
- avg_xact_time
Средняя продолжительность транзакции в микросекундах.
- avg_query_time
Средняя продолжительность запроса в микросекундах.
- avg_wait_time
Время, затраченное клиентами в ожидании сервера, в микросекундах (среднее время ожидания для клиентов, назначенных серверу в течение текущего
stats_period
).
H.4.3.5.1.2. ПОКАЗАТЬ STATS_TOTALS
#
Подмножество SHOW STATS, показывающее общие значения (total_).
H.4.3.5.1.3. SHOW STATS_AVERAGES
#
Подмножество SHOW STATS показывающее средние значения (avg_).
H.4.3.5.1.4. SHOW TOTALS
#
Как SHOW STATS, но агрегировано по всем базам данных.
H.4.3.5.1.5. SHOW SERVERS
#
- type
S, для сервера.
- user
Имя пользователя pgbouncer используется для подключения к серверу.
- database
Имя базы данных.
- replication
Если соединение с сервером использует репликацию. Может быть none, logical или physical.
- state
Состояние соединения сервера pgbouncer, одно из active, idle, used, tested, new, active_cancel, being_canceled.
- addr
IP-адрес сервера Tantor BE.
- port
Порт сервера Tantor BE.
- local_addr
Адрес начала подключения на локальной машине.
- local_port
Порт начала соединения на локальной машине.
- connect_time
Когда было установлено соединение.
- request_time
Когда был выдан последний запрос.
- wait
Не используется для серверных подключений.
- wait_us
Не используется для серверных подключений.
- close_needed
1 если соединение будет закрыто как можно скорее, потому что перезагрузка конфигурационного файла или обновление DNS изменили информацию о соединении или была выдана команда RECONNECT.
- ptr
Адрес внутреннего объекта для этого соединения. Используется в качестве уникального идентификатора.
- link
Адрес клиентского соединения, с которым сервер связан.
- remote_pid
PID серверного процесса. В случае подключения через Unix-сокет и если ОС поддерживает получение информации о процессе, это PID ОС. В противном случае он извлекается из пакета отмены, отправленного сервером, который должен быть PID в случае, если сервер — это Tantor BE, но это случайное число, если сервер — это другой PgBouncer.
- tls
Строка с информацией о подключении TLS, или пустая, если TLS не используется.
- application_name
Строка, содержащая
application_name
, установленное на связанном клиентском соединении, или пустая, если это не установлено, или если нет связанного соединения.- prepared_statements
Количество подготовленных операторов, которые подготовлены на сервере. Это число ограничено настройкой
max_prepared_statements
.
H.4.3.5.1.6. SHOW CLIENTS
#
- type
C, для клиента.
- user
Клиент подключен пользователем.
- database
Имя базы данных.
- replication
Если клиентское соединение использует репликацию. Может быть none, logical или physical.
- state
Состояние подключения клиента, одно из active, waiting, active_cancel_req, или waiting_cancel_req.
- addr
IP-адрес клиента.
- port
Исходный порт клиента.
- local_addr
Адрес окончания соединения на локальной машине.
- local_port
Порт окончания соединения на локальной машине.
- connect_time
Метка времени подключения.
- request_time
Метка времени последнего запроса клиента.
- wait
Текущее время ожидания в секундах.
- wait_us
Микросекундная часть текущего времени ожидания.
- close_needed
не используется для клиентов
- ptr
Адрес внутреннего объекта для этого соединения. Используется в качестве уникального идентификатора.
- link
Адрес подключения сервера, с которым клиент соединен.
- remote_pid
Идентификатор процесса, в случае если клиент подключается через Unix-сокет и ОС поддерживает его получение.
- tls
Строка с информацией о подключении TLS, или пустая, если TLS не используется.
- application_name
Строка, содержащая
application_name
, установленное клиентом для этого соединения, или пустая, если это не было установлено.- prepared_statements
Количество подготовленных операторов, которые клиент подготовил
H.4.3.5.1.7. SHOW POOLS
#
Новая запись в пул создается для каждой пары (база данных, пользователь).
- database
Имя базы данных.
- user
Имя пользователя.
- cl_active
Клиентские подключения, которые либо связаны с серверными подключениями, либо находятся в состоянии ожидания без запросов, ожидающих обработки.
- cl_waiting
Клиентские подключения, которые отправили запросы, но еще не получили подключение к серверу.
- cl_active_cancel_req
Клиентские подключения, которые переслали отмены запросов на сервер и ожидают ответа от сервера.
- cl_waiting_cancel_req
Клиентские подключения, которые еще не передали отмену запроса на сервер.
- sv_active
Соединения сервера, которые связаны с клиентом.
- sv_active_cancel
Серверные соединения, которые в настоящее время пересылают запрос на отмену.
- sv_being_canceled
Серверы, которые обычно могут стать бездействующими, но ожидают этого, пока не будут завершены все запросы на отмену, отправленные для отмены запроса на этом сервере.
- sv_idle
Неиспользуемые серверные соединения, которые могут быть немедленно использованы для запросов клиентов.
- sv_used
Серверные соединения, которые были бездействующими более чем
server_check_delay
, поэтому им необходимоserver_check_query
для выполнения, прежде чем они могут быть использованы снова.- sv_tested
Серверные соединения, которые в настоящее время выполняют либо
server_reset_query
, либоserver_check_query
.- sv_login
Серверные подключения, которые в настоящее время находятся в процессе входа в систему.
- maxwait
Сколько времени первый (самый старый) клиент в очереди ждал, в секундах. Если это значение начинает увеличиваться, то текущий пул серверов не обрабатывает запросы достаточно быстро. Причиной может быть либо перегруженный сервер, либо просто слишком маленькое значение pool_size.
- maxwait_us
Микросекундная часть максимального времени ожидания.
- pool_mode
Режим использования пула.
H.4.3.5.1.8. SHOW PEER_POOLS
#
Для каждого настроенного однорангового узла создается новая запись в peer_pool.
- database
ID настроенной записи однорангового узла.
- cl_active_cancel_req
Клиентские подключения, которые переслали отмены запросов на сервер и ожидают ответа от сервера.
- cl_waiting_cancel_req
Клиентские подключения, которые еще не передали отмену запроса на сервер.
- sv_active_cancel
Серверные соединения, которые в настоящее время пересылают запрос на отмену.
- sv_login
Серверные подключения, которые в настоящее время находятся в процессе входа в систему.
H.4.3.5.1.9. SHOW LISTS
#
Показать следующую внутреннюю информацию в виде столбцов (не строк):
- databases
Количество баз данных.
- users
Количество пользователей.
- pools
Количество пулов.
- free_clients
Количество свободных клиентов. Это клиенты, которые отключены, но PgBouncer сохраняет выделенную для них память, чтобы она могла быть использована повторно для будущих клиентов, чтобы избежать выделений.
- used_clients
Количество использованных клиентов.
- login_clients
Количество клиентов в состоянии входа.
- free_servers
Количество свободных серверов. Это серверы, которые отключены, но PgBouncer сохраняет выделенную для них память, чтобы она могла быть использована повторно для будущих серверов, избегая повторных выделений.
- used_servers
Количество используемых серверов.
- dns_names
Количество DNS-имен в кэше.
- dns_zones
Количество DNS зон в кэше.
- dns_queries
Количество выполняемых DNS-запросов.
- dns_pending
не используется
H.4.3.5.1.10. SHOW USERS
#
- name
Имя пользователя
- pool_size
Переопределение pool_size пользователем или NULL, если не установлено.
- pool_mode
Пользовательский режим pool_mode, или NULL, если не установлен.
- max_user_connections
Максимальное количество подключений пользователя, заданное в max_user_connections. Если это значение не установлено для данного конкретного пользователя, то будет отображено значение по умолчанию.
- current_connections
Текущее количество подключений, которые этот пользователь открыл ко всем серверам.
H.4.3.5.1.11. SHOW DATABASES
#
- name
Имя настроенной записи базы данных.
- host
Хост, к которому подключается pgbouncer.
- port
Порт, к которому подключается pgbouncer.
- database
Фактическое имя базы данных, к которой подключается pgbouncer.
- force_user
Когда пользователь является частью строки подключения, соединение между pgbouncer и Tantor BE принудительно устанавливается для данного пользователя, независимо от пользователя клиента.
- pool_size
Максимальное количество подключений к серверу.
- min_pool_size
Минимальное количество подключений к серверу.
- reserve_pool
Максимальное количество дополнительных подключений для этой базы данных.
- server_lifetime
Максимальный срок жизни соединения с сервером для этой базы данных
- pool_mode
Переопределение pool_mode базы данных, или NULL, если будет использоваться значение по умолчанию.
- max_connections
Максимальное количество разрешенных подключений для этой базы данных, как установлено max_db_connections, либо глобально, либо для каждой базы данных.
- current_connections
Текущее количество подключений к этой базе данных.
- paused
1 если эта база данных в настоящее время приостановлена, иначе 0.
- disabled
1 если эта база данных в настоящее время отключена, иначе 0.
H.4.3.5.1.12. SHOW PEERS
#
- peer_id
ID настроенной записи однорангового узла.
- host
Хост, к которому подключается pgbouncer.
- port
Порт, к которому подключается pgbouncer.
- pool_size
Максимальное количество подключений к серверу, которые могут быть установлены с этим узлом
H.4.3.5.1.13. SHOW FDS
#
Внутренняя команда - показывает список файловых дескрипторов в использовании с прикрепленным к ним внутренним состоянием.
Когда подключенный пользователь имеет имя пользователя «pgbouncer», подключается через Unix-сокет и имеет тот же UID, что и выполняющийся процесс, фактические FDs передаются через соединение. Этот механизм используется для онлайн-перезапуска.
Примечание
Это не работает в Windows.
Эта команда также блокирует внутренний цикл событий, поэтому не должна использоваться, пока PgBouncer находится в использовании.
- fd
Числовое значение файлового дескриптора.
- task
Один из pooler, client или server.
- user
Пользователь соединения, использующий FD.
- database
База данных соединения с использованием FD.
- addr
IP-адрес соединения с использованием FD, unix, если используется Unix сокет.
- port
Порт, используемый соединением с использованием FD.
- cancel
Ключ отмены для этого соединения.
- link
fd для соответствующего сервера/клиента. NULL, если бездействует.
H.4.3.5.1.14. SHOW SOCKETS, SHOW ACTIVE_SOCKETS
#
Показывает низкоуровневую информацию о сокетах или только активных сокетах. Это включает информацию, показанную в SHOW CLIENTS и SHOW SERVERS, а также другую более низкоуровневую информацию.
H.4.3.5.1.15. SHOW CONFIG
#
Показать текущие настройки конфигурации, по одной на строку, со следующими столбцами:
- key
Имя переменной конфигурации
- value
Значение конфигурации
- default
Значение по умолчанию конфигурации
- changeable
Либо yes или no, показывает, может ли переменная быть изменена во время выполнения. Если no, переменная может быть изменена только при загрузке. Используйте SET, чтобы изменить переменную во время выполнения.
H.4.3.5.1.16. SHOW MEM
#
Показывает низкоуровневую информацию о текущих размерах различных внутренних выделений памяти. Представленная информация может измениться.
H.4.3.5.1.17. SHOW DNS_HOSTS
#
Показать имена хостов в DNS-кэше.
- hostname
Имя хоста.
- ttl
Сколько секунд до следующего поиска.
- addrs
Список адресов, разделенных запятыми.
H.4.3.5.1.18. SHOW DNS_ZONES
#
Показать зоны DNS в кэше.
- zonename
Имя зоны.
- serial
Текущий серийный.
- count
Имена хостов, принадлежащие этой зоне.
H.4.3.5.1.19. SHOW VERSION
#
Показать строку версии PgBouncer.
H.4.3.5.1.20. SHOW STATE
#
Показать настройки состояния PgBouncer. Текущие состояния: активный, приостановленный и временно отключенный.
H.4.3.5.2. Команды управления процессами #
H.4.3.5.2.1. PAUSE [db]
#
PgBouncer пытается отключиться от всех серверов. Отключение каждого серверного соединения ожидает, пока это серверное соединение не будет освобождено в соответствии с режимом пуллинга серверного пула (в режиме транзакционного пуллинга транзакция должна завершиться, в режиме операторного пуллинга оператор должен завершиться, а в режиме сессионного пуллинга клиент должен отключиться). Команда не вернется до тех пор, пока все серверные соединения не будут отключены. Используется во время перезапуска базы данных.
Если указано имя базы данных, будет приостановлена только эта база данных.
Новые клиентские подключения к приостановленной базе данных будут ожидать, пока не будет вызвано RESUME.
H.4.3.5.2.2. DISABLE db
#
Отклонить все новые клиентские подключения к данной базе данных.
H.4.3.5.2.3. ENABLE db
#
Разрешить новые клиентские подключения после предыдущей DISABLE команды.
H.4.3.5.2.4. RECONNECT [db]
#
Закрыть каждое открытое серверное соединение для данной базы данных или всех баз данных после его освобождения (в соответствии с режимом пуллинга), даже если его срок жизни еще не истек. Новые серверные соединения могут быть установлены немедленно и будут подключаться по мере необходимости в соответствии с настройками размера пула.
Эта команда полезна, когда настройка подключения к серверу изменилась, например, для постепенного переключения на новый сервер. Не обязательно запускать эту команду, когда строка подключения в pgbouncer.ini была изменена и перезагружена (см. RELOAD) или когда изменилось разрешение DNS, потому что в этом случае эквивалент этой команды будет выполнен автоматически. Эта команда необходима только в том случае, если что-то ниже по потоку от PgBouncer маршрутизирует подключения.
После выполнения этой команды может быть продолжительный период, когда некоторые серверные подключения идут к старому месту назначения, а некоторые серверные подключения идут к новому месту назначения. Это, вероятно, имеет смысл только при переключении трафика только для чтения между репликами только для чтения или при переключении между узлами в настройке многомастеровской репликации. Если необходимо переключить все подключения одновременно, рекомендуется использовать PAUSE. Чтобы закрыть серверные подключения без ожидания (например, в случае аварийного переключения, а не постепенного переключения), также рассмотрите KILL.
H.4.3.5.2.5. KILL db
#
Немедленно разорвать все клиентские и серверные соединения с указанной базой данных.
Новые клиентские подключения к завершенной базе данных будут ожидать, пока не будет вызвано RESUME.
H.4.3.5.2.6. SUSPEND
#
Все буферы сокетов очищаются, и PgBouncer прекращает прослушивание данных на них. Команда не вернется, пока все буферы не будут пусты. Используется во время онлайн-перезагрузки PgBouncer.
Новые клиентские подключения к приостановленной базе данных будут ожидать, пока не будет вызвано RESUME.
H.4.3.5.2.7. RESUME [db]
#
Возобновить работу после предыдущей KILL, PAUSE или SUSPEND команды.
H.4.3.5.2.8. SHUTDOWN
#
Процесс PgBouncer завершится.
H.4.3.5.2.9. SHUTDOWN WAIT_FOR_SERVERS
#
Прекратить принимать новые подключения и завершить работу после того, как все серверы будут освобождены. Это в основном то же самое, что и выполнение PAUSE и SHUTDOWN, за исключением того, что это также прекращает принимать новые подключения, ожидая PAUSE, а также активно отключает клиентов, которые ожидают получения подключения к серверу.
H.4.3.5.2.10. SHUTDOWN WAIT_FOR_CLIENTS
#
Прекратить принимать новые подключения и завершить процесс после отключения всех существующих клиентов. Эта команда может быть использована для безостановочной поэтапной перезагрузки двух процессов PgBouncer с использованием следующей процедуры:
Запустите два или более процесса PgBouncer на одном и том же порту, используя
so_reuseport
(настройка пиров рекомендуется, но не обязательна). Чтобы достичь нулевого времени простоя при перезапуске, мы будем перезапускать эти процессы поочередно, оставляя другие работающими для принятия подключений, пока один из них перезапускается.Выберите процесс для перезапуска первым, назовем его A.
Выполните
SHUTDOWN WAIT_FOR_CLIENTS
(или отправьтеSIGTERM
) для процесса A.Заставьте всех клиентов переподключиться. Возможно, подождите некоторое время, пока пул клиентской стороны не вызовет переподключения из-за своего
server_idle_timeout
(или аналогичной настройки). Или, если пул клиентской стороны не используется, возможно, перезапустите клиентов. Как только все клиенты переподключатся. Процесс A завершится автоматически, потому что к нему больше не подключены клиенты.Запустите процесс A снова.
Повторите шаги 3, 4 и 5 для каждого из оставшихся процессов, по одному, пока не перезапустите все процессы.
H.4.3.5.2.11. RELOAD
#
Процесс PgBouncer перезагрузит свои файлы конфигурации
и обновит изменяемые настройки. Это включает основной
конфигурационный файл, а также файлы, указанные в
настройках auth_file
и
auth_hba_file
.
PgBouncer замечает, когда перезагрузка файла конфигурации изменяет параметры подключения определения базы данных. Существующее серверное подключение к старому месту назначения будет закрыто, когда серверное подключение будет в следующий раз освобождено (в соответствии с режимом пуллинга), и новые серверные подключения немедленно будут использовать обновленные параметры подключения.
H.4.3.5.2.12. WAIT_CLOSE [db]
#
Подождите, пока все серверные соединения, либо указанной базы данных, либо всех баз данных, не выйдут из состояния “close_needed” (см. SHOW SERVERS). Это можно вызвать после RECONNECT или RELOAD, чтобы дождаться полной активации соответствующего изменения конфигурации, например, в скриптах переключения.
H.4.3.5.3. Другие команды #
H.4.3.5.3.1. SET key = arg
#
Изменяет настройку конфигурации (см. также SHOW CONFIG). Например:
SET log_connections = 1; SET server_check_query = 'select 2';
(Обратите внимание, что эта команда выполняется в консоли администратора PgBouncer и устанавливает настройки PgBouncer. Команда SET, выполненная в другой базе данных, будет передана в бекенд Tantor BE как любая другая SQL-команда.)
H.4.3.5.4. Сигналы #
- SIGHUP
Перезагрузить конфигурацию. То же самое, что и выполнение команды RELOAD в консоли.
- SIGTERM
Супер безопасное завершение. Ожидание отключения всех существующих клиентов, но не принятие новых подключений. Это то же самое, что и выполнение SHUTDOWN WAIT_FOR_CLIENTS в консоли. Если этот сигнал получен, когда завершение уже в процессе, то вместо «супер безопасного завершения» запускается «немедленное завершение». В версиях PgBouncer ранее 1.23.0 этот сигнал вызывал бы «немедленное завершение».
- SIGINT
Безопасное завершение работы. То же, что и выполнение SHUTDOWN WAIT_FOR_SERVERS в консоли. Если этот сигнал получен, когда завершение работы уже выполняется, то вместо «безопасного завершения» инициируется «немедленное завершение».
- SIGQUIT
Немедленное завершение работы. То же самое, что и выполнение SHUTDOWN на консоли.
- SIGUSR1
То же самое, что и выполнение PAUSE в консоли.
- SIGUSR2
То же самое, что и выполнение RESUME в консоли.
H.4.3.5.5. Настройки Libevent #
Из документации Libevent:
Можно отключить поддержку epoll, kqueue, devpoll, poll или select, установив переменную окружения EVENT_NOEPOLL, EVENT_NOKQUEUE, EVENT_NODEVPOLL, EVENT_NOPOLL или EVENT_NOSELECT, соответственно.
Установив переменную окружения EVENT_SHOW_METHOD, libevent отображает метод уведомления ядра, который он использует.
H.4.3.6. См. также #
pgbouncer(5) - man страница описаний настроек конфигурации
H.4.4. Установка #
H.4.4.1. Построение #
PgBouncer зависит от нескольких вещей для компиляции:
Когда зависимости установлены, просто выполните:
$ ./configure --prefix=/usr/local $ make $ make install
Если вы собираете из Git или собираете для Windows, пожалуйста, смотрите отдельные инструкции по сборке ниже.
H.4.4.2. Поддержка поиска DNS #
PgBouncer выполняет поиск имени хоста во время подключения, а не только один раз при загрузке конфигурации. Это требует асинхронной реализации DNS. В следующей таблице показаны поддерживаемые бэкенды и порядок их проверки:
серверная часть | параллельно | EDNS0 (1) | /etc/hosts | поиск SOA (2) | примечание |
---|---|---|---|---|---|
c-ares | да | да | да | да | IPv6+CNAME с ошибками в <=1.10 |
evdns, libevent 2.x | да | нет | да | нет | не проверяет обновления /etc/hosts |
getaddrinfo_a, glibc 2.9+ | да | да (3) | да | нет | Н/Д на non-glibc |
getaddrinfo, libc | нет | да (3) | да | нет | требует pthreads |
EDNS0 требуется для наличия более 8 адресов за одним именем хоста.
Проверка SOA необходима для повторной проверки имен хостов при изменении серийного номера зоны.
Чтобы включить EDNS0, добавьте
options edns0
в/etc/resolv.conf
.
c-ares является наиболее полнофункциональной реализацией и рекомендуется для большинства случаев использования и бинарной упаковки (если доступна достаточно новая версия). Встроенный evdns в Libevent также подходит для многих случаев использования, с указанными ограничениями. Другие бэкенды в основном являются устаревшими опциями на данный момент и больше не проходят много тестирования.
По умолчанию используется c-ares, если он может быть найден. Его использование можно
принудительно включить с помощью configure --with-cares
или
отключить с помощью --without-cares
. Если c-ares
не используется (не найден или отключен), то используется Libevent. Укажите
--disable-evdns
, чтобы отключить использование
evdns из Libevent и вернуться к реализации на основе libc.
H.4.4.3. PAM аутентификация #
Чтобы включить аутентификацию PAM, ./configure
имеет
флаг --with-pam
(значение по умолчанию - нет). При
компиляции с поддержкой PAM доступен новый глобальный тип аутентификации
pam
для проверки пользователей через
PAM.
H.4.4.4. Интеграция с systemd #
Чтобы включить интеграцию с systemd, используйте
опцию configure
--with-systemd
. Это позволяет использовать
единицы обслуживания с Type=notify
, а также активацию сокетов. См. etc/pgbouncer.service
и
etc/pgbouncer.socket
для примеров.
H.4.4.5. Сборка из Git #
Сборка PgBouncer из Git требует, чтобы вы извлекли подмодули libusual
и uthash и сгенерировали заголовочные и конфигурационные
файлы, прежде чем вы сможете запустить configure
:
$ git clone https://github.com/pgbouncer/pgbouncer.git $ cd pgbouncer $ git submodule init $ git submodule update $ ./autogen.sh $ ./configure $ make $ make install
Все файлы будут установлены в /usr/local
по умолчанию. Вы можете указать один или несколько параметров командной строки для
configure
. Запустите
./configure --help
, чтобы вывести список доступных
параметров и переменных окружения, которые настраивают
конфигурацию.
Дополнительные пакеты, необходимые: autoconf, automake, libtool, pandoc
H.4.4.6. Тестирование #
См. файл README.md
в тестовом каталоге о том, как запускать тесты.
H.4.4.7. Сборка на Windows #
Единственная поддерживаемая среда сборки на Windows - это MinGW. Cygwin и Visual $ANYTHING не поддерживаются.
Чтобы собрать на MinGW, выполните следующее:
$ ./configure $ make
Если выполняется кросс-компиляция из Unix:
$ ./configure --host=i586-mingw32msvc
H.4.4.8. Запуск на Windows #
Запуск из командной строки происходит как обычно, за исключением того, что
переключатели -d
(демонизация), -R
(перезагрузка) и -u
(смена пользователя) не будут работать.
Чтобы запустить PgBouncer как службу Windows, необходимо настроить
параметр service_name
, чтобы задать имя для
службы. Затем:
$ pgbouncer -regservice config.ini
Чтобы удалить службу:
$ pgbouncer -unregservice config.ini
Чтобы использовать журнал событий Windows, установите syslog = 1
в файле конфигурации. Но перед этим необходимо зарегистрировать
pgbevent.dll
:
$ regsvr32 pgbevent.dll
Чтобы отменить регистрацию, выполните:
$ regsvr32 /u pgbevent.dll
H.4.5. FAQ #
H.4.5.1. Как подключиться к PgBouncer? #
PgBouncer действует как сервер Postgres, поэтому просто укажите вашему клиенту порт PgBouncer.
H.4.5.2. Как распределить нагрузку запросов между несколькими серверами? #
PgBouncer не имеет внутренней конфигурации для нескольких хостов. Это возможно с помощью внешних инструментов:
DNS round-robin. Используйте несколько IP-адресов за одним DNS-именем. PgBouncer не выполняет поиск DNS каждый раз при запуске нового соединения. Вместо этого он кэширует все IP-адреса и выполняет round-robin внутренне.
Примечание
Если за одним именем находится более 8 IP-адресов, DNS-бэкенд должен поддерживать протокол EDNS0. Подробности см. в README.
Используйте балансировщик нагрузки TCP-соединений. Либо LVS или HAProxy кажутся хорошими вариантами. Со стороны PgBouncer может быть хорошей идеей сделать
server_lifetime
меньше и также включитьserver_round_robin
: по умолчанию, неактивные соединения повторно используются алгоритмом LIFO, что может работать не так хорошо, когда требуется балансировка нагрузки.
H.4.5.3. Как выполнить переключение на резервный сервер? #
PgBouncer не имеет внутренней конфигурации резервного хоста или обнаружения. Это возможно с помощью внешних инструментов:
Перенастройка DNS: Когда IP-адрес за DNS-именем перенастраивается, PgBouncer переподключится к новому серверу. Это поведение можно настроить с помощью двух параметров конфигурации:
dns_max_ttl
настраивает время жизни для одного имени хоста, аdns_zone_check_period
настраивает, как часто будет запрашиваться зона SOA на предмет изменений. Если запись зоны SOA изменилась, PgBouncer повторно запросит все имена хостов в этой зоне.Запишите нового хоста в конфигурацию и позвольте PgBouncer перезагрузить его: отправьте SIGHUP или используйте команду
RELOAD
в консоли. PgBouncer обнаружит измененную конфигурацию хоста и переподключится к новому серверу.Используйте команду
RECONNECT
. Это предназначено для ситуаций, когда ни один из двух вышеперечисленных вариантов не применим, например, когда вы используете упомянутый выше HAProxy для маршрутизации соединений вниз по потоку от PgBouncer.RECONNECT
просто вызывает повторное открытие всех серверных соединений. Поэтому выполните это после того, как другой компонент изменил информацию о маршрутизации соединений.
H.4.5.4. Как использовать подготовленные операторы с пулом сессий? #
В режиме пула сессий запрос сброса должен очищать старые подготовленные
инструкции. Это можно сделать с помощью
server_reset_query = DISCARD ALL;
или, по крайней мере,
DEALLOCATE ALL;
H.4.5.5. Как использовать подготовленные операторы с пулом транзакций? #
Начиная с версии 1.21.0 PgBouncer может отслеживать подготовленные операторы в режиме пула транзакций и обеспечивать их подготовку на лету на подключенном сервере. Чтобы включить эту функцию, необходимо установить max_prepared_statements
в ненулевое значение. См. документацию по max_prepared_statements
для получения более подробной информации.
Из-за того, как PHP/PDO использует подготовленные выражения (#991) поддержка подготовленных выражений в PgBouncer 1.21.0 не работает для PHP/PDO. Таким образом, для PHP/PDO и версий PgBouncer до 1.21.0 единственным обходным решением является отключение подготовленных выражений на стороне клиента.
H.4.5.5.1. Отключение подготовленных операторов в JDBC #
Правильный способ сделать это для JDBC - добавить параметр
prepareThreshold=0
в строку подключения.
H.4.5.5.2. Отключение подготовленных операторов в PHP/PDO #
Чтобы отключить использование подготовленных операторов на стороне сервера, атрибут PDO
PDO::ATTR_EMULATE_PREPARES
должен
быть установлен в true
. Либо во время подключения:
$db = new PDO("dsn", "user", "pass", array(PDO::ATTR_EMULATE_PREPARES => true));
или позже:
$db->setAttribute(PDO::ATTR_EMULATE_PREPARES, true);
H.4.5.6. Как обновить PgBouncer без разрыва соединений? #
УСТАРЕЛО: Вместо этого варианта используйте поочередную перезагрузку с несколькими процессами pgbouncer, прослушивающими один и тот же порт, используя so_reuseport
Это так же просто, как запустить новый процесс PgBouncer с
-R
переключателем и той же конфигурацией:
$ pgbouncer -R -d config.ini
Переключатель -R
(перезагрузка) заставляет новый процесс
подключиться к консоли старого процесса (dbname=pgbouncer) через
Unix-сокет и выполнить следующие команды:
SUSPEND; SHOW FDS; SHUTDOWN;
После этого, если новый процесс замечает, что старый исчез, он
возобновляет работу со старыми соединениями. Магия происходит во время
команды SHOW FDS
, которая передает
фактические файловые дескрипторы новому процессу.
Если захват не работает по какой-либо причине, новый процесс можно просто завершить. Старый процесс замечает это и возобновляет работу.
H.4.5.7. Как узнать, какой клиент находится на каком серверном соединении? #
Используйте команды SHOW CLIENTS
и
SHOW SERVERS
в консоли.
Используйте
ptr
иlink
для сопоставления локального клиентского соединения с серверным соединением.Используйте
addr
иport
клиентского соединения для идентификации TCP-соединения от клиента.Используйте
local_addr
иlocal_port
для идентификации TCP-соединения с сервером.
H.4.5.8. Следует ли устанавливать PgBouncer на веб-сервере или сервере базы данных? #
Это зависит от обстоятельств.
Установка PgBouncer на веб-сервере хороша, когда используются кратковременные соединения. Тогда задержка при установке соединения минимизируется. (TCP требует несколько раунд-трипов пакетов, прежде чем соединение становится доступным.) Установка PgBouncer на сервере базы данных хороша, когда к нему подключается множество различных хостов (например, веб- серверов). Тогда их соединения могут быть оптимизированы вместе.
Также возможно установить PgBouncer как на веб-сервер, так и на сервер базы данных. Один из отрицательных аспектов этого заключается в том, что каждый переход через PgBouncer добавляет небольшую задержку к каждому запросу.
В конце концов, вам нужно будет протестировать, какая модель лучше всего подходит для ваших потребностей в производительности. Вам также следует учитывать, как установка PgBouncer повлияет на переключение ваших приложений в случае отказа веб-сервера или сервера базы данных.