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

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

$ psql -p 6544 pgbouncer

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

Сам интерфейс администрирования Pangolin Pooler состоит из нескольких команд SHOW, а также команд управления процессами, доступных при подключении к административной базе данных 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
 [...]

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

$ 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 для просмотра информации о статусе или результатах работы сквозной аутентификации:

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

SHOW STATS#

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

SHOW SERVERS#

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

SHOW CLIENTS#

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

SHOW POOLS#

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

SHOW PEER_POOLS#

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

SHOW LISTS#

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

SHOW USERS#

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

SHOW DATABASES#

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

SHOW PEERS#

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

SHOW FDS#

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

SHOW CONFIG#

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

SHOW DNS_HOSTS#

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

SHOW DNS_ZONES#

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

SHOW AUTHSERVERS#

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

SHOW AUTHPOOLS#

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

SHOW AUTHUSERS#

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

SHOW LAST#

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

SHOW LOCKED_USERS#

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

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

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

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

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

SET log_connections = 1;
SET server_check_query = 'select 2';

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

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

Сигналы#

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

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

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

-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