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

Управление и использование

В Pangolin Pooler существует специальная «виртуальная» база данных, так называемая административная база данных, которая может использоваться для мониторинга и управления компонентом. Подключиться к ней можно через консоль, которая доступна при обычном подключении к базе pgbouncer:

$ psql -p 6544 pgbouncer

Подключаться к этой консоли разрешено только пользователям, перечисленным в параметрах конфигурации admin_users или stats_users (за исключением режима auth_mode = any, когда в качестве stats_user может подключиться любой пользователь).

Сам интерфейс администрирования Pangolin Pooler состоит из нескольких команд SHOW, а также команд управления процессами, доступных при подключении к административной базе данных pgbouncer. Их описание приведено в подразделах далее.

Вывод команды SHOW HELP

Вывод команды SHOW HELP в консоли администрирования:

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
 [...]

Для приложения Pangolin Pooler также доступен синтаксис опций из командной строки.

Вывод команды pangolin-pooler --help

$ pangolin-pooler --help
pangolin-pooler is a connection pooler for Pangolin DBMS.

Usage:
  pangolin-pooler [OPTION]... CONFIG_FILE

Options:
  -d, --daemon         run in background (as a daemon)
  -q, --quiet          run quietly
  -R, --reboot         do an online reboot
  -u, --user=USERNAME  assume identity of USERNAME
  -v, --verbose        increase verbosity
  -V, --version        show version, then exit
  -h, --help           show this help, then exit
  -l, --log=FILENAME   write (or append) server log to FILENAME


Pangolin product version information:
  --product_version        prints product name and version
  --product_build_info     prints product build number, date and hash
  --product_component_hash prints component hash string

Команды SHOW​

Интерфейс администрирования Pangolin Pooler состоит из нескольких новых команд SHOW, доступных при подключении к административной базе данных pgbouncer. Команды SHOW выводят различную информацию.

КомандаОписание
SHOW STATSСтатистика. В этой и связанных с ней командах общие показатели отсчитываются с момента запуска процесса, промежуточные значения обновляются раз в период, заданный в stats_period 
SHOW STATS_TOTALSПодмножество SHOW STATS, показывающее общие значения (total_)
SHOW STATS_AVERAGESПодмножество SHOW STATS, показывающее средние значения (avg_)
SHOW TOTALSКак SHOW STATS, но агрегированное по всем базам данных
SHOW SERVERSИнформация о серверных подключениях
SHOW CLIENTSИнформация о клиентских подключениях
SHOW POOLSДля каждой пары (база данных, пользователь) создается новая запись в пул. Данная команда выводит эту информацию
SHOW PEER_POOLSДля каждого настроенного узла создается новая запись peer_pool. Данная команда выводит эту информацию
SHOW LISTSСписок количества БД, пользователей, пулов и другой информации в виде столбцов
SHOW USERSПоказывает информацию о пользовательских настройках и количестве подключений
SHOW DATABASESИнформация о реализуемых подключениях к базам данных и их состоянии
SHOW PEERSПоказывает информацию о пирах
SHOW FDSВнутренняя команда. Показывает список используемых файловых дескрипторов с прикрепленным к ним внутренним состоянием
SHOW SOCKETS, SHOW ACTIVE_SOCKETSПоказывает низкоуровневую информацию о сокетах или только об активных сокетах. Сюда входит информация, отображаемая в разделах SHOW CLIENTS и SHOW SERVERS, а также другая низкоуровневая информация
SHOW CONFIGОтображаются текущие параметры конфигурации, по одному на строку
SHOW MEMПоказывает низкоуровневую информацию о текущих размерах различных разделов внутренней памяти. Представленная информация может быть изменена
SHOW DNS_HOSTSПоказывает имена хостов в кеше DNS
SHOW DNS_ZONESПоказывает зоны DNS в кеше
SHOW VERSIONПоказывает версию ядра компонента Pangolin Pooler - PgBouncer
SHOW STATEПоказывает настройки состояния компонента (активное, приостановленное и ожидающее)

Команды SHOW для просмотра информации о статусе или результатах работы сквозной аутентификации:

КомандаОписание
SHOW AUTHSERVERSПоказывает информацию по соединениям с сервером аутентификации
SHOW AUTHPOOLSПоказывает информацию по пулам аутентификации
SHOW AUTHUSERSПоказывает информацию о пользователях
SHOW LASTПоказывает информацию об аутентификации последних N пользователей
SHOW LOCKED_USERSПоказывает информацию о временно заблокированных пользователях

Описание полей, возвращаемых командами, приведено в последующих подразделах.

SHOW STATS​

Команда SHOW STATS показывает статистику. В этой и связанных с ней командах общие показатели отсчитываются с момента запуска процесса, промежуточные значения обновляются раз в период, заданный stats_period.

Название поляОписание поля
databaseСтатистика представлена по каждой базе данных
total_xact_countОбщее количество SQL-транзакций, объединенных в пул Pangolin Pooler
total_query_countОбщее количество SQL-команд, объединенных в пул Pangolin Pooler
total_server_assignment_countОбщее количество раз, когда сервер был назначен клиенту
total_receivedОбщий объем сетевого трафика в байтах, полученный Pangolin Pooler
total_sentОбщий объем сетевого трафика в байтах, отправленный Pangolin Pooler
total_xact_timeОбщее количество времени в микросекундах, затраченных Pangolin Pooler при подключении к СУБД в рамках транзакции, либо при простое в рамках транзакции, либо при выполнении запросов
total_query_timeОбщее количество времени в микросекундах, затраченных Pangolin Pooler на активное подключение к СУБД и выполнение запросов
total_wait_timeВремя, которое клиенты проводят в ожидании ответа сервера, в микросекундах. Обновляется, когда клиентскому соединению назначается внутреннее соединение
total_client_parse_countОбщее количество подготовленных запросов, созданных клиентами. Применимо только в режиме отслеживания именованных подготовленных запросов
total_server_parse_countОбщее количество подготовленных операторов, созданных Pangolin Pooler на сервере. Применимо только в режиме отслеживания именованных подготовленных запросов
total_bind_countОбщее количество подготовленных операторов, подготовленных для выполнения клиентами и отправленных в СУБД с помощью Pangolin Pooler. Применимо только в режиме отслеживания именованных подготовленных запросов
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)
avg_client_parse_countСреднее количество операторов, созданных клиентами. Применимо только в режиме отслеживания именованных подготовленных запросов
avg_server_parse_countСреднее количество операторов, созданных Pangolin Pooler на сервере. Применимо только в режиме отслеживания именованных подготовленных запросов
avg_bind_countСреднее количество операторов, подготовленных для выполнения клиентами и переданных в СУБД с помощью Pangolin Pooler. Применимо только в режиме отслеживания именованных подготовленных запросов

SHOW SERVERS​

В таблице ниже приведены поля вывода команды SHOW SERVERS.

Название поляОписание поля
typeТип соединения, «S» для сервера
userИмя пользователя, используемое Pangolin Pooler для подключения к серверу
databaseИмя базы данных
replicationЕсли для подключения к серверу используется репликация. Значение none, logical или physical
stateСостояние подключения к серверу Pangolin Pooler. Значения: active, idle, used, tested, new, active_cancel, being_canceled
addrIP-адрес сервера СУБД
portПорт сервера СУБД
local_addrЛокальный адрес начала подключения
local_portЛокальный порт начала подключения
connect_timeКогда было установлено соединение
loged_in_timeВремя подключения
loged_inДлительность поднятия соединения в секундах
loged_in_usДробная часть длительности поднятия соединения в микросекундах
request_timeВремя отправки последнего запроса
waitНе используется для подключений к серверу
wait_usНе используется для подключений к серверу
close_neededФлаг закрытия: 1 если соединение будет закрыто как можно скорее, потому что идет перезагрузка файла конфигурации / обновление DNS изменило информацию о соединении / был получен RECONNECT
ptrАдрес внутреннего объекта подключения
linkАдрес клиентского соединения, с которым сопряжен сервер
remote_pidPID процесса серверной стороны
tlsИнформация о TLS-соединении или пустая строка, если TLS не используется
application_nameИмя приложения, ассоциированное со связанным клиентским соединением, или пустая строка, если приложение не установлено / нет соединения
prepared_statementsКоличество подготовленных запросов на сервере, ограниченное значением max_prepared_statements
idУникальный идентификатор для сервера

SHOW CLIENTS​

В таблице ниже приведены поля вывода команды SHOW CLIENTS.

Название поляОписание поля
typeТип соединения, «C» для клиента
userПользователь, подключенный к клиенту
databaseИмя базы данных
replicationИспользование репликации. Значения: none, logical или physical
stateСостояние клиентского подключения (active, waiting, active_cancel_req или waiting_cancel_req)
addrIP-адрес клиента
portИсходный порт клиента
local_addrАдрес конечного подключения на локальном компьютере
local_portКонечный порт подключения на локальном компьютере
connect_timeВременная метка подключения
request_timeВременная метка последнего запроса клиента
waitТекущее время ожидания в секундах
wait_usДробная часть текущей времени ожидания в микросекундах
close_neededНе используется для клиентов
ptrВнутренний адрес объекта для этого подключения
linkАдрес подключения к серверу, с которым связан клиент
remote_pidИдентификатор процесса, если клиент подключается через сокет Unix и ОС поддерживает его получение
tlsИнформация о TLS-подключении или пустая строка, если TLS не используется
application_nameИмя приложения, ассоциированное со связанным клиентским соединением, или пустая строка, если приложение не установлено / нет соединения
prepared_statementsКоличество подготовленных запросов, подготовленных клиентом
idУникальный идентификатор клиента

SHOW POOLS​

В таблице ниже приведены поля вывода команды 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Время ожидания клиента в очереди. Если это значение начинает расти, значит, текущий пул серверов не обрабатывает запросы достаточно быстро. Причиной может быть либо перегрузка сервера, либо слишком маленький размер пула
maxwait_usДробная часть максимального времени ожидания в микросекундах
avg_timeСреднее время поднятия пула с учетом аутентификации в секундах
avg_time_usДробная часть среднего времени поднятия пула в микросекундах
max_timeМаксимальное время поднятия пула с учетом аутентификации в секундах
max_time_usМаксимальное время поднятия пула в микросекундах
pool_modeИспользуемый режим пула
load_balance_hostsЕсли хост пула содержит список, разделенный запятыми, используется load_balance_hosts

SHOW PEER_POOLS​

В таблице ниже приведены поля вывода команды SHOW PEER_POOLS.

Название поляОписание поля
databaseИдентификатор настроенной записи
cl_active_cancel_reqКлиентские подключения, ожидающие ответа сервера на запрос отмены
cl_waiting_cancel_reqКлиентские соединения, еще не отправившие запрос отмены на сервер
sv_active_cancelПодключения к серверу, выполняющие передачу запроса на отмену
sv_loginПодключения к серверу, находящиеся в процессе входа в систему

SHOW LISTS​

В таблице ниже приведены поля вывода команды SHOW LISTS.

Название поляОписание поля
databasesКоличество баз данных
usersКоличество пользователей
poolsКоличество пулов
free_clientsКоличество свободных клиентов, которые отключились, но Pangolin Pooler сохраняет выделенную для них память
used_clientsКоличество использованных клиентов
login_clientsКоличество клиентов в состоянии входа в систему
free_serversКоличество свободных серверов, которые отключены, но Pangolin Pooler сохраняет выделенную для них память
used_serversКоличество использованных серверов
auth_poolsКоличество пулов аутентификации
free_auth_serversКоличество свободных серверов аутентификации
used_auth_serversКоличество задействованных серверов аутентификации
dns_namesКоличество DNS-имен в кеше
dns_zonesКоличество DNS-зон в кеше
dns_queriesКоличество выполняемых DNS-запросов в настоящее время
dns_pendingНе используется

SHOW USERS​

В таблице ниже приведены поля вывода команды SHOW USERS.

Название поляОписание поля
nameИмя пользователя
pool_sizeПользовательское значение pool_size или NULL, если не задано
reserve_pool_sizeПользовательское переопределение reserve_pool_size или NULL, если не задано
pool_modeПереопределение пользователем pool_mode или NULL, если не задано
max_user_connectionsПараметр max_user_connections для пользователя. Если не задан, отображается значение по умолчанию
current_connectionsТекущее количество подключений к серверу, открытых этим пользователем ко всем серверам
max_user_client_connectionsПараметр max_user_client_connections для пользователя. Если не задан, отображается значение по умолчанию
current_client_connectionsТекущее количество клиентских подключений, открытых для Pangolin Pooler у этого пользователя

SHOW DATABASES​

В таблице ниже приведены поля вывода команды SHOW DATABASES.

Название поляОписание поля
nameИмя настроенной записи базы данных
hostIP-адрес, к которому подключается Pangolin Pooler
portПорт, к которому подключается Pangolin Pooler
databaseФактическое имя базы данных, к которой подключается Pangolin Pooler
force_userЕсли имя пользователя указано в строке подключения, то соединение между Pangolin Pooler и СУБД устанавливается с указанным пользователем, независимо от того, кто является клиентом
pool_sizeМаксимальное количество подключений к серверу
min_pool_sizeМинимальное количество подключений к серверу
reserve_pool_sizeМаксимальное количество дополнительных подключений к этой базе данных
server_lifetimeМаксимальное время жизни подключения к серверу для этой базы данных
pool_modeПереопределить режим пула базы данных или оставить значение NULL, если будет использоваться значение по умолчанию
load_balance_hostsЕсли хост содержит список, разделенный запятыми, то в load_balance_hosts базы данных он будет указан как хост
max_connectionsМаксимальное количество допустимых подключений к серверу для этой базы данных, заданное параметром max_db_connections, глобально или для каждой базы данных
current_connectionsТекущее количество подключений к серверу для этой базы данных
max_client_connectionsМаксимальное количество допустимых клиентских подключений для этого экземпляра Pangolin Pooler, заданное параметром max_db_client_connections для каждой базы данных
current_client_connectionsТекущее количество клиентских подключений к этой базе данных
paused1, если эта база данных в данный момент приостановлена, иначе 0
disabled1, если эта база данных в данный момент отключена, иначе 0

SHOW PEERS​

В таблице ниже приведены поля вывода команды SHOW PEERS.

Название поляОписание поля
peer_idИдентификатор настроенной записи
hostIP-адрес, к которому подключается Pangolin Pooler
portПорт, к которому подключается Pangolin Pooler
pool_sizeМаксимальное количество подключений к серверу, которые могут быть осуществлены к этому узлу

SHOW FDS​

Внимание!

Эта команда блокирует внутренний цикл обработки событий, поэтому ее не следует использовать во время работы Pangolin Pooler.

В таблице ниже приведены поля вывода команды SHOW FDS.

Название поляОписание поля
fdЧисловое значение файлового дескриптора (FD)
taskПредназначение. Принимает одно из значений: pooler, client или server
userПользователь соединения, использующий FD
databaseБаза данных соединения, использующего FD
addrIP-адрес соединения, использующего FD. Принимает значение unix, если используется сокет Unix
portПорт, используемый соединением с использованием FD
cancelКлавиша отмены для этого подключения
linkfd для соответствующего сервера/клиента. NULL, если неактивен

SHOW CONFIG​

В таблице ниже приведены поля вывода команды SHOW CONFIG.

Название поляОписание поля
keyИмя переменной конфигурации
valueЗначение конфигурации
defaultЗначение конфигурации по умолчанию
changeableЗначения yes или no. Показывает, можно ли изменить переменную во время работы. Если no, переменную можно изменить только при загрузке. Используйте SET, чтобы изменить переменную во время работы

SHOW DNS_HOSTS​

В таблице ниже приведены поля вывода команды SHOW DNS_HOSTS.

Название поляОписание поля
hostnameИмя хоста
ttlВремя в секундах до следующего поиска
addrsСписок адресов, разделенных запятыми

SHOW DNS_ZONES​

В таблице ниже приведены поля вывода команды SHOW DNS_ZONES.

Название поляОписание поля
zonenameНазвание зоны
serialТекущий серийный номер
countИмена хостов, принадлежащих этой зоне

SHOW AUTHSERVERS​

В таблице ниже приведены поля вывода команды SHOW AUTHSERVERS.

Название поляОписание поля
typeТип соединения, «A» для серверов аутентификации
databaseИмя базы данных
stateСостояние подключения к серверу Pangolin Pooler. Значения: active, used или idle
addrIP-адрес сервера СУБД
portПорт сервера СУБД
local_addrИсходный адрес подключения на локальной машине
local_portИсходный порт подключения на локальной машине
connect_timeВремя установления подключения
loged_in_timeВремя подключения (время, когда получен ответ на handshake запрос)
request_timeВремя выдачи последнего запроса
ptrАдрес внутреннего объекта для данного подключения. Используется как уникальный идентификатор
tlsИнформация о TLS-подключении. Пустая строка, если TLS не используется

SHOW AUTHPOOLS​

В таблице ниже приведены поля вывода команды SHOW AUTHPOOLS.

Название поляОписание поля
databaseИмя базы данных
cl_authКоличество клиентских подключений, которые выполняют запрос аутентификации к серверу аутентификации
sv_activeПодключения к серверу, которые используются в данный момент
sv_idleПодключения к серверу, которые не используются в данный момент
sv_usedПодключения к серверу, который простаивали более server_check_delay секунд, поэтому перед повторным использованием для подключения потребуется server_check_query секунд
sv_testedПодключения к серверу, в которых выполняются server_reset_query или server_check_query
sv_loginПодключения к серверу, находящиеся в процессе входа в систему
maxwaitВремя ожидания в очереди самого первого клиента в секундах. Если это число начинает увеличиваться, значит текущий пул серверов не справляется с запросами достаточно быстро
maxwait_usДробная часть максимального времени ожидания в микросекундах

SHOW AUTHUSERS​

В таблице ниже приведены поля вывода команды SHOW AUTHUSERS.

Название поляОписание поля
nameИмя пользователя
addrIP-адрес клиента
portПорт клиента
databaseИмя базы данных
pool_modeПереопределить режим пула базы данных или оставить значение NULL, если будет использоваться значение по умолчанию

SHOW LAST​

В таблице ниже приведены поля вывода команды SHOW LAST.

Название поляОписание поля
userИмя пользователя
addrIP-адрес клиента
portПорт клиента
tlsИнформация о TLS-подключении. Пустая строка, если TLS не используется
methodМетод аутентификации (например, md5, scram-sha-256, ldap, cert). Отображается только для аутентифицированных пользователей
placeМесто выполнения аутентификации (Pangolin Pooler, Pangolin DBMS)
statusСтатус аутентификации (ok, failed, expired)
connect_timeВремя установления подключения
waitВремя ожидания клиента в очереди до аутентификации в секундах
wait_usДробная часть времени ожидания в микросекундах
auth_timeВремя выполнения аутентификации (получения статуса аутентификации)
authВремя выполнения аутентификация (в секундах). Если это число начинает увеличиваться, значит текущий сервер аутентификации не справляется с запросами достаточно быстро. Причиной может быть перегруженный сервер, а в случае внешних аутентификаций (GSS, LDAP, RADIUS) перегруженный сервер аутентификации
auth_usДробная часть времени выполнения аутентификации в микросекундах

SHOW LOCKED_USERS​

В таблице ниже приведены поля вывода команды SHOW LOCKED_USERS.

Название поляОписание поля
userИмя пользователя
addrIP-адрес клиента
portПорт клиента
databaseИмя базы данных
beginВремя начала блокировки
endВремя окончания блокировки

Команды управления процессом​

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

Команда
Описание
PAUSE <database_name>
Pangolin Pooler пытается отключиться от всех серверов. При отключении от каждого сервера ожидается, что это подключение к серверу будет освобождено в соответствии с режимом объединения в пул (в режиме пула транзакций конкретная транзакция должна завершиться, в режиме пула операторов — конкретный оператор должен завершиться, а в режиме пула сеансов – должен отключиться клиент). Команда не будет выполнена до тех пор, пока все подключения к серверам не будут отключены. Команда используется во время перезапуска базы данных.

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

Новые подключения клиентов к приостановленной базе данных будут ожидать вызова команды RESUME
DISABLE <database_name>
Отклоняет все новые клиентские подключения к данной базе данных
ENABLE <database_name>
Разрешает новые клиентские подключения после команды DISABLE
RECONNECT <database_name>
Закрывает каждое открытое соединение с сервером для данной базы данных (или для всех баз данных) после его освобождения, в соответствии с режимом пула, даже если срок его действия еще не истек. Новые соединения с сервером могут быть установлены немедленно и реализовывать подключение по мере необходимости, в соответствии с настройками размера пула.

Эта команда полезна, если настройки подключения к серверу изменились, например, для постепенного перехода на новый сервер. Эту команду не нужно выполнять, если строка подключения в pangolin-pooler.ini была изменена и перезагружена (RELOAD) или если изменилось разрешение DNS, потому что в этом случае аналогичное действие будет выполнено автоматически. Эта команда нужна только в том случае, если что-то, находящееся «ниже» (по потоку данных) Pangolin Pooler, перенаправляет подключения.

После выполнения этой команды может пройти некоторое время, в течение которого некоторые серверные подключения будут направляться к старому месту назначения, а некоторые — к новому. Это имеет смысл при переключении трафика для чтения между репликами только для чтения или при переключении между узлами в конфигурации репликации с несколькими ведущими узлами. Если необходимо одновременно переключить все подключения, рекомендуется использовать PAUSE. Чтобы закрыть серверные подключения без ожидания (например, при аварийном переключении, а не при постепенном переключении), также рассмотрите KILL
KILL <database_name>
Немедленно завершает все клиентские и серверные подключения к данной базе данных.

Новые подключения клиентов к отключенной базе данных будут ожидать вызова RESUME
KILL_CLIENT <id>
Немедленно разрывает указанное клиентское соединение вместе со всеми серверными соединениями для данного клиента. Клиент, соединение с которым необходимо «разорвать», определяется по значению id, которое можно получить с помощью команды SHOW CLIENTS
SUSPEND
Очищает все буферы сокетов, и Pangolin Pooler перестает прослушивать данные в них. Команда не будет выполнена, пока все буферы не будут очищены. Используется во время «быстрой» перезагрузки Pangolin Pooler.

Новые подключения клиентов к приостановленной базе данных будут ожидать вызова RESUME
RESUME <database_name>
Восстанавливает работу после предыдущей команды KILL, PAUSE или SUSPEND
SHUTDOWN
Завершает процесс Pangolin Pooler
SHUTDOWN WAIT_FOR_SERVERS
Прекращает прием новых подключений и завершает работу после отключения всех серверов. Работает аналогично командам PAUSE и SHUTDOWN с той разницей, что в данном случае команда прекращает прием новых подключений в ожидании PAUSE, а также принудительно отключает клиентов, ожидающих подключения к серверу
SHUTDOWN WAIT_FOR_CLIENTS
Прекращает принимать новые подключения и завершает процесс после того, как все существующие клиенты отключатся. Эту команду можно использовать для перезапуска двух процессов Pangolin Pooler с нулевым временем простоя по следующей процедуре:

1. Запустите два или более процессов Pangolin Pooler на одном и том же порту с помощью so_reuseport (рекомендуется настроить секцию [peers]). Чтобы добиться нулевого времени простоя при перезапуске, перезапускайте эти процессы по очереди, оставляя остальные запущенными для приема соединений во время перезапуска одного из них.
2. Выберите процесс для перезапуска, например, с названием A.
3. Запустите SHUTDOWN WAIT_FOR_CLIENTS (или отправьте SIGTERM) процессу A.
4. Реализуйте повторное подключение всех клиентов. Возможно, потребуется подождать некоторое время, пока пул на стороне клиента не вызовет повторное подключение в соответствии с server_idle_timeout (или аналогичной) конфигурацией. Или, если пул на стороне клиента не используется, потребуется перезапустить клиентов. Как только все клиенты повторно подключатся, процесс A завершится автоматически, так как к нему больше не будут подключаться клиенты.
5. Запустите процесс A снова.
6. Повторите шаги 3, 4 и 5 для каждого из оставшихся процессов, пока все процессы не будут перезапущены.
RELOAD
Задает процессу Pangolin Pooler перезагрузку файлов конфигурации и обновление изменяемых параметров. Это касается основного файла конфигурации (pangolin-pooler.ini), а также файлов, указанных в параметрах auth_file (userlist.txt) и auth_hba_file

Pangolin Pooler уведомит, что при перезагрузке файла конфигурации изменяются параметры подключения к базе данных. Существующее подключение к серверу по старому адресу будет закрыто при следующем освобождении подключения к серверу (в соответствии с режимом пула), а новые подключения к серверу сразу будут использовать обновленные параметры подключения
WAIT_CLOSE
Ожидает, пока все серверные подключения к указанной базе данных или ко всем базам данных не выйдут из состояния close_needed (SHOW SERVERS). Это можно сделать после RECONNECT или RELOAD, чтобы дождаться полной активации соответствующего изменения конфигурации, например, в сценариях переключения

Другие команды​

В таблице ниже приведены команды, не вошедшие в таблицу выше.

:

Команда
Описание
SET <key = arg>

Изменяет параметр конфигурации (рассмотрите также команду SHOW CONFIG). Например:

SET log_connections = 1; 
SET server_check_query = 'select 2';
admonition :class: attention Данная команда запускается в консоли администрирования и устанавливает настройки компонента. Команда SET, запущенная в другой базе данных, будет передана серверу СУБД как любая другая команда SQL.
:: ::::

Дополнительно реализованные команды​

В таблице ниже приведены команды, которые были реализованы в процессе доработки компонента.

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

Параметры выборки пользователя передаются в формате: "[<user>[|<db>[|<addr>[|ssl]]]]", где:

- <user> – имя пользователя;
- <db> – наименование базы данных;
- <addr> – адрес хоста, с которого аутентифицировался пользователь;
- ssl – признак того, что пользователь аутентифицировался по защищенному соединению;
- * в качестве значения параметра выборки обозначает, что в выборку попадут пользователи с любым значением данного параметра.
NDC_KEEPALIVE
Переходит в режим NDC_ALLOWED (если до этого он был в другом режиме) и возобновляет прием новых клиентских соединений, а также их обработку. При этом Pangolin Pooler сохраняет момент времени получения этой команды и использует его в дальнейшем при автоматическом переключении в режим приостановки приема клиентских соединений.
NDC_SUSPEND
Прерывает все существующие соединения к базам данных, а также все клиентские соединения, кроме соединений с административной консолью (для обеспечения связи с базой pgbouncer). Получив эту команду, Pangolin Pooler переходит в режим NDC_DISALLOWED и прекращает обработку входящих клиентских соединений.

Поведение аналогично вызову команды KILL <database_name> для всех баз данных, с которыми были установлены соединения, за исключением того, что базы данных не переходят в режим выключения.

Сигналы​

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

Команда
Описание
SIGHUP
Перезагрузка конфигурации. Равнозначно выполнению команды RELOAD в консоли
SIGTERM
Завершение работы только при отключении всех существующих клиентов, без приема новых подключений. Равнозначно выполнению команды SHUTDOWN WAIT_FOR_CLIENTS в консоли. Если этот сигнал получен во время завершения работы, то происходит немедленное завершение работы
SIGINT
Безопасное завершение работы. Равнозначно выполнению командыSHUTDOWN WAIT_FOR_SERVERS в консоли. Если этот сигнал получен во время завершения работы, то вместо «безопасного завершения работы» запускается «немедленное завершение работы»
SIGQUIT
Немедленное завершение работы. Равнозначно выполнению команды SHUTDOWN в консоли
SIGUSR1
Равнозначно выполнению команды PAUSE в консоли
SIGUSR2
Равнозначно выполнению команды RESUME в консоли

Опции командной строки​

Ниже приведено описание опций компонента при работе в командной строке.

-d, --daemon
Запуск в фоновом режиме. Без этого указания процесс будет выполняться на переднем плане.

В фоновом режиме требуется указание pidfile и logfile или syslog. После перехода в фоновый режим сообщения журнала не будут записываться в stderr.

-R, --reboot
Выполнение перезапуска в режиме онлайн. Это означает подключение к работающему процессу, загрузку открытых сокетов из него и последующее их использование. Если активного процесса нет, будет осуществлен запуск в обычном режиме.
Внимание!

Опция устарела. Вместо этой опции используйте последовательный перезапуск с несколькими процессами, прослушивающими один и тот же порт с помощью so_reuseport.

примечание

Работает только в том случае, если ОС поддерживает сокеты Unix и unix_socket_dir не отключена в конфигурации. Не работает с TLS-соединениями, они прерываются.

-u <username>, --user=<username>
Переключение на данного пользователя при запуске.
-v, --verbose
Увеличение детализации сообщений. Может использоваться несколько раз.
-q, --quiet
Не выводить сообщения в stderr. Это не влияет на уровень детализации сообщений, но stderr использовать нельзя. Для использования в скриптах init.d.
-V, --version
Вывод версии.
-h, --help
Вывод краткой справки.

Сценарии использования​

Доступ в БД через Pangolin Pooler​

  1. Подключитесь в psql консоль пользователем postgres через Pangolin Pooler:

    $ psql -p 6544

    Результат: Вход успешный.

  2. Зайдите в консоль администрирования Pooler и проверьте количество подключенных к базе пользователей:

    $ psql -p 6544 -U pgbouncer -d pgbouncer
    SHOW CLIENTS;

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

    -[ RECORD 4 ]-------+------------------------
    type                | C
    user                | postgres
    database            | postgres
    state               | active
    addr                | {IP-Address}
    port                | {port}
    local_addr          | {IP-Address}
    local_port          | {local_port}
    connect_time        | 2024-07-29 16:40:55 MSK
    loged_in_time       | 2024-07-29 17:05:30 MSK
    request_time        | 2024-07-29 16:55:41 MSK
    wait                | 0
    wait_us             | 0
    loged_in            | 0
    loged_in_us         | 0
    close_needed        | 0
    ptr                 | 0x259cf70
    link                |
    remote_pid          | 0
    tls                 |
    application_name    | psql
    prepared_statements | 0

Вывод версии компонента​

Для вывода версии компонента Pangolin Pooler, а также ядра компонента (PgBouncer) выполните команду:

pangolin-pooler -V

Пример вывода:

Pangolin Pooler 1.5.0
PgBouncer 1.24.0
libevent 2.1.8-stable
adns: evdns2
tls: OpenSSL 1.1.1k  FIPS 25 Mar 2021
authproxy: yes
2fa: yes

Проверка работы двухфакторной аутентификации при подключении к Pangolin через Pangolin Pooler​

  1. Настройте двухфакторную аутентификацию для реализации подключения к СУБД через Pangolin Pooler с включенной или выключенной сквозной аутентификацией.

  2. Создайте пользователя и задайте ему пароль:

    postgres=#CREATE ROLE test_user;
    CREATE ROLE

    postgres=#ALTER user test_user WITH LOGIN;
    ALTER ROLE

    postgres=#ALTER user test_user WITH PASSWORD '<password>';
    ALTER ROLE

  3. Подключитесь к Pangolin, выполните команду:

    psql 'host=clustername port=5433 user=user1 sslmode=verify-ca sslcert=client-user1.crt sslkey=client-user1.key sslrootcert=root.crt'

    Введите на запрос пароля корректный пароль. В случае успеха psql перейдет в режим ожидания ввода запросов:

    Password for user test_user:

    Ожидаемый результат:

    psql (17.5)
    SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)
    Type "help" for help.

    postgres=>

  4. Проверьте, что выполняется запрос к БД, например:

    test_user@postgres=# SELECT now();

    +-------------------------------+
    |              now              |
    +-------------------------------+
    | 2025-06-27 17:18:22.813347+03 |
    +-------------------------------+
    (1 row)

Сброс контекста сквозной аутентификация​

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

  1. Выполните запрос списка пользователей:

    PGPASSWORD='<password3>' psql -p 6544 -d pgbouncer -U pgbouncer -c "SHOW AUTHUSERS"

    Ожидаемый результат: Запрос выполнен успешно. Все значения колонки auth_state равны done. Пример вывода:

    name   |    addr     | port  | database | pool_mode | tls | auth_state
    ------+--------------+-------+----------+-----------+-----+------------
     u1   | <IP-Address> | 44246 | d1       |           | yes | done
     u1   | <IP-Address> | 44260 | d2       |           | yes | done
     u2   | <IP-Address> | 43228 | d2       |           | yes | done
    (3 rows)

  2. Выполните сброс состояния аутентификация для всех пользователей:

    PGPASSWORD='<password3>' psql -p 6544 -d pgbouncer -U pgbouncer -c "RESET_AUTH"

    Результат: Запрос выполнен успешно:

    RESET_AUTH

  3. Повторно выполните запрос списка пользователей:

    PGPASSWORD='<password3>' psql -p 6544 -d pgbouncer -U pgbouncer -c "SHOW AUTHUSERS"

    Ожидаемый результат: Запрос выполнен успешно. Все значения колонки auth_state равны none. Пример вывода:

    name   |    addr     | port  | database | pool_mode | tls | auth_state
    ------+--------------+-------+----------+-----------+-----+------------
     u1   | <IP-Address> | 44246 | d1       |           | yes | none
     u1   | <IP-Address> | 44260 | d2       |           | yes | none
     u2   | <IP-Address> | 43228 | d2       |           | yes | none
    (3 rows)

Исправление попытки неудачной аутентификации​

  1. Выполните подключение к БД:

    psql "host=<IP-Address> port=<port> user=testuser dbname=testdb sslmode=require"

  2. Аутентификация завершена ошибкой:

    psql: error: FATAL

  3. Проверьте лог-файл Pangolin Pooler на наличие записи типа:

    2025-07-18 14:31:02.104 MSK [2102] FATAL testdb/testuser@<IP-Address>:<port> PgBouncer does not allow to use weak authentication type: "trust"

  4. Исправьте метод аутентификации в pg_hba на стороне СУБД, заменив trust на безопасный метод, например scram-sha-256:

    # Было:
    host    all             all             <IP-Address>/32            trust

    # Стало:
    host    all             all             <IP-Address>/32            scram-sha-256

  5. Перечитайте конфигурацию:

    sudo systemctl reload postgresql

  6. Повторите попытку подключения:

    psql "host=<IP-Address> port=<port> user=testuser dbname=testdb sslmode=require"

  7. Успешная аутентификация подтверждается сообщениями в логе:

    2025-07-18 14:34:44.412 MSK AUDIT testdb/testuser@<IP-Address>:<port> login attempt tls=yes
    2025-07-18 14:34:44.416 MSK AUDIT testdb/testuser@<IP-Address>:<port> send auth startup packet
    2025-07-18 14:34:44.491 MSK AUDIT testdb/testuser@<IP-Address>:<port> auth server login ok

Определение клиентского IP адреса, подключенного к СУБД через Pangolin Pooler​

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

  1. Выполните запрос для поиска целевого подключения и его параметров. Пример:

    postgres=# SELECT * FROM pg_stat_activity WHERE datname = 'tst1'\gx

    -[ RECORD 1 ]----+-------------------------------------------------------------------  
    datid            | 16734  
    datname          | tst1  
    pid              | 2366  
    usesysid         | 10  
    usename          | postgres  
    application_name | pgAdmin 4 - CONN:9435271  
    client_addr      | 
    client_hostname  |  
    client_port      |   
    backend_start    | 2023-11-13 11:57:06.347595+03  
    xact_start       | 2023-11-13 11:57:58.16217+03  
    query_start      | 2023-11-13 11:57:58.16217+03  
    state_change     | 2023-11-13 11:57:58.162323+03  
    wait_event_type  | Client  
    wait_event       | ClientRead  
    state            | idle in transaction  
    query            | begin;  
                     | select 1;  
    backend_type     | client backend

    Значения pid и client_port будут использоваться далее: pid = 2366, client_port = 54406.

  2. Подключитесь к административной БД pgbouncer:

    $ psql -p 6544 -U pgbouncer -d pgbouncer

  3. Выполните команду SHOW SERVERS и по значениям remote_pid и local_port найдите нужную запись:

    pgbouncer=# SHOW SERVERS\gx 

    -[ RECORD 3 ]-+------------------------  
    type          | S  
    user          | postgres  
    database      | tst1  
    state         | active  
    addr          | <IP-Address>
    port          | <port>   
    local_addr    | <IP-Address>
    local_port    | <port>   
    connect_time  | 2023-11-13 11:57:06 MSK  
    loged_in_time | 2023-11-13 11:57:06 MSK  
    request_time  | 2023-11-13 11:57:58 MSK  
    remote_pid    | 2366
    link          | 0x179d6b0

    Значение link равное 0x179d6b0 потребуется на следующем шаге.

  4. Выполните SHOW CLIENTS и найдите запись, где ptr совпадает с link из предыдущего шага:

    pgbouncer=# SHOW CLIENTS\gx

    -[ RECORD 3 ]-+------------------------  
    type          | C  
    user          | postgres  
    database      | tst1  
    state         | active  
    addr          | <IP-Address_client>  
    port          | <port> 
    local_addr    | <IP-Address>
    local_port    | <port>   
    connect_time  | 2023-11-13 11:57:28 MSK  
    loged_in_time | 2023-11-13 13:30:22 MSK  
    request_time  | 2023-11-13 11:57:58 MSK  
    ptr           | 0x179d6b0

    В поле addr указано значение IP-адреса клиента, а в port — клиентский порт подключения к pgbouncer.

  5. Дополнительно можно включить расширенное логирование, чтобы видеть IP-адрес клиента и его порт в логах. Для этого в конфигурационный файл pangolin-pooler.ini добавьте параметр log_audit в значении 1:

    log_audit = 1