Базовое использование PgDoorman

PgDoorman -- пулер соединений PostgreSQL, основанный на PgCat. В этом руководстве описаны конфигурация, эксплуатация и администрирование.

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

PgDoorman поддерживает несколько параметров командной строки для настройки поведения при запуске:

$ pg_doorman --help

PgDoorman: Nextgen PostgreSQL Pooler (based on PgCat)

Usage: pg_doorman [OPTIONS] [CONFIG_FILE] [COMMAND]

Commands:
  generate  Generate configuration for pg_doorman by connecting to PostgreSQL and auto-detecting databases and users
  help      Print this message or the help of the given subcommand(s)

Arguments:
  [CONFIG_FILE]  [env: CONFIG_FILE=] [default: pg_doorman.toml]

Options:
  -l, --log-level <LOG_LEVEL>    [env: LOG_LEVEL=] [default: INFO]
  -F, --log-format <LOG_FORMAT>  [env: LOG_FORMAT=] [default: text] [possible values: text, structured, debug]
  -n, --no-color                 disable colors in the log output [env: NO_COLOR=]
  -d, --daemon                   run as daemon [env: DAEMON=]
  -h, --help                     Print help
  -V, --version                  Print version

Доступные параметры

Установка и настройка

Структура файла конфигурации

PgDoorman поддерживает форматы YAML и TOML. Для новых установок рекомендуется YAML. Конфигурация разбита на несколько секций:

general:        # Глобальные настройки сервиса PgDoorman
pools:
  <name>:       # Настройки конкретного пула базы данных
    users:
      - ...     # Настройки пользователя для этого пула

Минимальный пример конфигурации

Минимальный пример конфигурации для старта:

YAML (рекомендуется)

general:
  host: "0.0.0.0"         # Слушать на всех интерфейсах
  port: 6432               # Порт для клиентских соединений
  admin_username: "admin"
  admin_password: "admin"  # Поменяйте это в production!

pools:
  exampledb:
    server_host: "127.0.0.1"  # Адрес сервера PostgreSQL
    server_port: 5432          # Порт сервера PostgreSQL
    pool_mode: "transaction"   # Режим пулинга
    users:
      - pool_size: 40
        username: "doorman"
        password: "SCRAM-SHA-256$4096:6nD+Ppi9rgaNyP7...MBiTld7xJipwG/X4="

TOML

[general]
host = "0.0.0.0"
port = 6432
admin_username = "admin"
admin_password = "admin"

[pools.exampledb]
server_host = "127.0.0.1"
server_port = 5432
pool_mode = "transaction"

[pools.exampledb.users.0]
pool_size = 40
username = "doorman"
password = "SCRAM-SHA-256$4096:6nD+Ppi9rgaNyP7...MBiTld7xJipwG/X4="

Полный список параметров конфигурации можно получить командой pg_doorman generate --reference --output ref.yaml -- она генерирует аннотированный конфиг со всеми параметрами и значениями по умолчанию.

Автоматическая генерация конфигурации

Команда generate создаёт файл конфигурации, подключаясь к серверу PostgreSQL и определяя базы данных и пользователей. По умолчанию сгенерированный конфиг содержит inline-комментарии, объясняющие каждый параметр.

# Посмотреть все доступные опции
pg_doorman generate --help

# Сгенерировать YAML-конфиг (рекомендуется)
pg_doorman generate --output pg_doorman.yaml

# Сгенерировать TOML-конфиг (для обратной совместимости)
pg_doorman generate --output pg_doorman.toml

# Сгенерировать reference-конфиг со всеми настройками (без подключения к PG)
pg_doorman generate --reference --output pg_doorman.yaml

# Сгенерировать reference-конфиг с русскими комментариями для быстрого старта
pg_doorman generate --reference --ru --output pg_doorman.yaml

# Сгенерировать конфиг без комментариев (plain serialization)
pg_doorman generate --no-comments --output pg_doorman.yaml

Команда generate поддерживает несколько опций:

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

users:
  - username: "app_user"              # имя для клиента
    password: "md5..."                # хэш для аутентификации клиента
    server_username: "pg_app_user"    # другой backend-пользователь PostgreSQL
    server_password: "real_password"  # plaintext-пароль для этого пользователя

Контроль доступа клиентов (pg_hba)

PgDoorman может применять правила доступа клиентов в стиле PostgreSQL pg_hba.conf через параметр general.pg_hba. Правила можно встроить прямо в конфиг или сослаться на путь к файлу. Полные примеры -- в reference-разделе.

Trust-режим: когда правило использует trust, PgDoorman принимает соединения без запроса пароля у клиента -- зеркально поведению PostgreSQL. Учитываются TLS-зависимые типы правил: hostssl требует TLS, hostnossl его запрещает.

Запуск PgDoorman

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

$ pg_doorman pg_doorman.toml

Если файл конфигурации не указан, PgDoorman будет искать pg_doorman.toml в текущей директории.

Подключение к PostgreSQL через PgDoorman

После запуска PgDoorman подключайтесь к нему вместо прямого подключения к PostgreSQL:

$ psql -h localhost -p 6432 -U doorman exampledb

Строку подключения вашего приложения нужно изменить так, чтобы она указывала на PgDoorman, а не напрямую на PostgreSQL:

postgresql://doorman:password@localhost:6432/exampledb

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

Администрирование

Admin-консоль

PgDoorman предоставляет административный интерфейс через специальную базу данных pgdoorman (или pgbouncer для обратной совместимости):

$ psql -h localhost -p 6432 -U admin pgdoorman

После подключения можно посмотреть доступные команды:

pgdoorman=> SHOW HELP;
NOTICE:  Console usage
DETAIL:
	SHOW HELP|CONFIG|DATABASES|POOLS|POOLS_EXTENDED|POOLS_MEMORY|POOL_COORDINATOR|POOL_SCALING
	SHOW CLIENTS|SERVERS|USERS|CONNECTIONS|STATS|PREPARED_STATEMENTS|AUTH_QUERY
	SHOW LISTS|SOCKETS|LOG_LEVEL|VERSION
	SET log_level = '<filter>'
	RELOAD
	SHUTDOWN
	UPGRADE
	PAUSE [db]
	RESUME [db]
	RECONNECT [db]

# Разрешить только локальному admin доступ к admin-БД без пароля
host  pgdoorman  admin  127.0.0.1/32  trust

Мониторинг PgDoorman

Admin-консоль предоставляет несколько команд для мониторинга текущего состояния PgDoorman:

• SHOW STATS -- посмотреть статистику производительности.
• SHOW CLIENTS -- список текущих клиентских соединений.
• SHOW SERVERS -- список текущих серверных соединений.
• SHOW POOLS -- состояние пулов соединений.
• SHOW DATABASES -- список настроенных баз данных.
• SHOW USERS -- список настроенных пользователей.

Эти команды подробно описаны в разделе Команды admin-консоли ниже.

Перечитывание конфигурации

Если вы изменили pg_doorman.toml, изменения можно применить без перезапуска сервиса:

pgdoorman=# RELOAD;

При перечитывании конфигурации:

1. PgDoorman читает обновлённый файл конфигурации.
2. Обнаруживаются изменения параметров подключения к базам.
3. Существующие серверные соединения закрываются при следующем возврате в пул (в соответствии с режимом пулинга).
4. Новые серверные соединения сразу используют обновлённые параметры.

Это позволяет вносить изменения в конфигурацию с минимальным влиянием на приложения.

Команды admin-консоли

Admin-консоль предоставляет набор команд для мониторинга и управления PgDoorman. Команды используют SQL-подобный синтаксис и могут выполняться из любого PostgreSQL-клиента, подключённого к admin-консоли.

SHOW-команды

SHOW-команды отображают информацию о работе PgDoorman. Каждая команда даёт свой срез данных о производительности и текущем состоянии пулера.

SHOW STATS

SHOW STATS показывает развёрнутую статистику работы PgDoorman:

pgdoorman=> SHOW STATS;

Статистика приводится для каждой пары (database, user):

SHOW SERVERS

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

pgdoorman=> SHOW SERVERS;

SHOW CLIENTS

SHOW CLIENTS показывает информацию обо всех клиентских соединениях к PgDoorman:

pgdoorman=> SHOW CLIENTS;

SHOW POOLS

SHOW POOLS показывает информацию о пулах соединений. Для каждой пары (database, user) создаётся отдельная запись пула:

pgdoorman=> SHOW POOLS;

SHOW USERS

SHOW USERS показывает информацию обо всех настроенных пользователях:

pgdoorman=> SHOW USERS;

SHOW DATABASES

SHOW DATABASES показывает информацию обо всех настроенных пулах баз данных:

pgdoorman=> SHOW DATABASES;

SHOW SOCKETS

SHOW SOCKETS показывает количество сокетов в разных состояниях для TCP/TCP6/Unix (только Linux):

pgdoorman=> SHOW SOCKETS;

Показывает агрегированные счётчики состояний сокетов (ESTABLISHED, SYN_SENT и т.д.), полученные из /proc/net/tcp, /proc/net/tcp6 и /proc/net/unix.

SHOW VERSION

SHOW VERSION показывает информацию о версии PgDoorman:

pgdoorman=> SHOW VERSION;

Полезно, чтобы проверить, какая версия запущена, особенно после обновлений.

Управляющие команды

PgDoorman предоставляет управляющие команды, позволяющие управлять работой сервиса прямо из admin-консоли.

SHUTDOWN

Команда SHUTDOWN корректно завершает процесс PgDoorman:

pgdoorman=> SHUTDOWN;

При выполнении:

1. PgDoorman перестаёт принимать новые клиентские соединения.
2. Существующим транзакциям даётся время завершиться (в пределах настроенного таймаута).
3. Все соединения закрываются.
4. Процесс завершается.

SET log_level

Изменить уровень логирования на лету, не перезапуская пулер:

-- Глобальный уровень
pgdoorman=> SET log_level = 'debug';

-- На модуль (синтаксис RUST_LOG)
pgdoorman=> SET log_level = 'warn,pg_doorman::pool::pool_coordinator=debug';

-- Посмотреть текущий уровень
pgdoorman=> SHOW LOG_LEVEL;

-- Сбросить на стартовое значение
pgdoorman=> SET log_level = 'default';

Изменения временные -- теряются при перезапуске. Допустимые уровни: error, warn, info, debug, trace, off.

RELOAD

Команда RELOAD обновляет конфигурацию PgDoorman без перезапуска сервиса:

pgdoorman=> RELOAD;

Эта команда:

1. Перечитывает файл конфигурации.
2. Обновляет все изменяемые настройки.
3. Применяет изменения параметров соединений для новых соединений.
4. Сохраняет существующие соединения, пока они не вернутся в пул.

PAUSE

Команда PAUSE [db] блокирует получение новых backend-соединений для указанной базы (или всех баз, если аргумент не задан). Активные транзакции продолжают работать -- блокируются только запросы на новые соединения.

-- Поставить на паузу все пулы
pgdoorman=> PAUSE;

-- Поставить на паузу только пулы конкретной базы
pgdoorman=> PAUSE mydb;

Клиенты, которые запросят новое backend-соединение во время паузы, будут ждать RESUME или истечения query_wait_timeout -- что наступит раньше. Если истечёт таймаут, клиент получит ошибку timeout.

Используйте SHOW POOLS для проверки состояния паузы -- колонка paused покажет 1 для приостановленных пулов.

RESUME

Команда RESUME [db] снимает PAUSE и немедленно разблокирует всех ожидающих клиентов:

-- Снять паузу со всех пулов
pgdoorman=> RESUME;

-- Снять паузу только с пулов конкретной базы
pgdoorman=> RESUME mydb;

Клиенты, которые ждали из-за PAUSE, немедленно продолжат получать backend-соединения.

RECONNECT

Команда RECONNECT [db] форсирует пересоздание всех backend-соединений:

-- Reconnect для всех пулов
pgdoorman=> RECONNECT;

-- Reconnect только для пулов конкретной базы
pgdoorman=> RECONNECT mydb;

При выполнении:

1. Внутренний epoch-счётчик пула увеличивается.
2. Все idle-соединения сразу закрываются.
3. Активные соединения (которые сейчас обслуживают транзакцию) продолжают работать, но утилизируются при возврате в пул -- они не будут переиспользованы.

То есть RECONNECT не прерывает активные транзакции. Новые соединения создаются по запросу с текущим epoch, поэтому они будут приняты recycle().

Граничные случаи и поведение

В таблице ниже описано поведение PAUSE, RESUME и RECONNECT в граничных случаях:

Обработка сигналов

PgDoorman реагирует на стандартные Unix-сигналы для управления и контроля. Сигналы посылаются через kill (например, kill -HUP <pid>).