Настройки

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

pg_doorman поддерживает два формата конфигурационного файла:

YAML (.yaml, .yml) — основной и рекомендуемый формат для новых конфигураций.
TOML (.toml) — поддерживается для обратной совместимости с уже существующими конфигурациями.

Формат определяется автоматически по расширению файла. Оба формата поддерживают одни и те же опции конфигурации и могут использоваться взаимозаменяемо.

Пример конфигурации YAML (рекомендуется)

general:
  host: "0.0.0.0"
  port: 6432
  admin_username: "admin"
  admin_password: "admin"

pools:
  mydb:
    server_host: "localhost"
    server_port: 5432
    pool_mode: "transaction"
    users:
      - username: "myuser"
        password: "mypassword"
        pool_size: 40

Пример конфигурации TOML (legacy)

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

[pools.mydb]
server_host = "localhost"
server_port = 5432
pool_mode = "transaction"

[[pools.mydb.users]]
username = "myuser"
password = "mypassword"
pool_size = 40

Команда generate

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

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

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

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

# Сгенерировать справочную конфигурацию с комментариями на русском
pg_doorman generate --reference --ru --output config.yaml

# Сгенерировать конфигурацию без комментариев (только сериализация)
pg_doorman generate --no-comments --output config.yaml

Флаг	Описание
`--no-comments`	Отключить inline-комментарии в сгенерированной конфигурации (по умолчанию комментарии включены)
`--reference`	Сгенерировать полную справочную конфигурацию с примерами значений, без подключения к PostgreSQL
`--russian-comments`, `--ru`	Генерировать комментарии на русском языке для быстрого старта
`--format`, `-f`	Формат вывода: `yaml` (по умолчанию) или `toml`. Если задан `--output`, формат определяется по расширению файла. Этот флаг переопределяет автоопределение

Подключаемые файлы

Подключаемые файлы могут быть в любом из форматов, форматы можно смешивать. Например, основная конфигурация в YAML может подключать TOML-файлы и наоборот:

include:
  files:
    - "pools.yaml"
    - "users.toml"

Человекочитаемые значения

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

Формат продолжительности

Значения продолжительности можно задавать как:

Простые числа: интерпретируются как миллисекунды (например, 5000 = 5 секунд)
Строка с суффиксом:
- ms — миллисекунды (например, "100ms")
- s — секунды (например, "5s" = 5000 миллисекунд)
- m — минуты (например, "5m" = 300000 миллисекунд)
- h — часы (например, "1h" = 3600000 миллисекунд)
- d — дни (например, "1d" = 86400000 миллисекунд)

Примеры:

general:
  # Все эти варианты эквивалентны (3 секунды):
  # connect_timeout: 3000      # обратная совместимость (миллисекунды)
  # connect_timeout: "3s"      # человекочитаемый формат
  # connect_timeout: "3000ms"  # явные миллисекунды
  connect_timeout: "3s"
  idle_timeout: "10m"        # 10 минут
  server_lifetime: "1h"      # 1 час

Формат размера в байтах

Значения размера в байтах можно задавать как:

Простые числа: интерпретируются как байты (например, 1048576 = 1 MB)
Строка с суффиксом (регистр не важен):
- B — байты (например, "1024B")
- K или KB — килобайты (например, "1K" или "1KB" = 1024 байта)
- M или MB — мегабайты (например, "1M" или "1MB" = 1048576 байт)
- G или GB — гигабайты (например, "1G" или "1GB" = 1073741824 байт)

Примечание: используются двоичные префиксы (1 KB = 1024 байта, не 1000 байт).

Примеры:

general:
  # Все эти варианты эквивалентны (256 MB):
  # max_memory_usage: 268435456  # обратная совместимость (байты)
  # max_memory_usage: "256MB"    # человекочитаемый формат
  # max_memory_usage: "256M"     # короткая форма
  max_memory_usage: "256MB"
  unix_socket_buffer_size: "1MB" # 1 MB
  worker_stack_size: "8MB"       # 8 MB

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

host

Хост, на котором сервер будет принимать соединения (только TCP v4).

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

port

Порт для входящих соединений.

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

backlog

TCP backlog для входящих соединений. При значении ноль в качестве TCP backlog используется значение max_connections.

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

max_connections

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

Клиент, подключающийся без SSL, получит ожидаемую ошибку (код: 53300, сообщение: sorry, too many clients already).
Клиент, подключающийся через SSL, увидит сообщение о том, что сервер не поддерживает протокол SSL.

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

max_concurrent_creates

Максимальное число серверных соединений, которые могут создаваться параллельно в одном пуле. Параметр использует семафор для ограничения параллельного создания соединений, что заметно повышает производительность при холодном старте и пиковых сценариях.

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

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

tls_mode

Режим TLS для входящих соединений. Может принимать одно из следующих значений:

allow — TLS-соединения разрешены, но не обязательны. pg_doorman попытается установить TLS-соединение, если клиент его запросит.
disable — TLS-соединения запрещены. Все соединения устанавливаются без шифрования TLS.
require — TLS-соединения обязательны. pg_doorman принимает только соединения, использующие TLS-шифрование.
verify-full — TLS-соединения обязательны, и pg_doorman проверяет клиентский сертификат. Этот режим обеспечивает максимальный уровень безопасности.

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

tls_ca_cert

Файл с CA-сертификатом для проверки клиентского сертификата. Обязателен, когда tls_mode установлен в verify-full.

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

tls_private_key

Путь к файлу приватного ключа для TLS-соединений. Требуется для включения TLS для входящих клиентских соединений. Должен использоваться вместе с tls_certificate.

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

tls_certificate

Путь к файлу сертификата для TLS-соединений. Требуется для включения TLS для входящих клиентских соединений. Должен использоваться вместе с tls_private_key.

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

tls_rate_limit_per_second

Ограничение числа одновременных попыток создания TLS-сессии. Любое значение, отличное от нуля, означает, что клиенты должны проходить через очередь для установки TLS-соединения. В некоторых случаях это необходимо, чтобы запустить приложение, которое открывает много соединений при старте (так называемый «горячий старт»).

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

daemon_pid_file

Включение этого параметра активирует режим демона. Закомментируйте, если хотите запускать pg_doorman в foreground с флагом -d.

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

syslog_prog_name

Если задан, pg_doorman начинает отправлять сообщения в syslog (через /dev/log или /var/run/syslog). Закомментируйте, если хотите логировать в stdout.

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

log_client_connections

Логировать подключения клиентов для мониторинга.

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

log_client_disconnections

Логировать отключения клиентов для мониторинга.

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

worker_threads

Число worker-потоков Tokio runtime (потоков ОС) для обслуживания клиентских соединений. Производительность масштабируется линейно до числа ядер CPU. Также определяет число шардов для внутренних concurrent hash maps (worker_threads * 4, округлённо до ближайшей степени двойки, минимум 4). В Kubernetes задавайте этот параметр явно — автоматическое определение CPU может вернуть число ядер хоста, а не лимит контейнера.

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

worker_cpu_affinity_pinning

Привязывать каждый worker-поток к отдельному ядру CPU (sched_setaffinity). Отключается, если доступно меньше 3 ядер.

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

tokio_global_queue_interval

Настройки Tokio runtime. Управляет тем, как часто шедулер проверяет глобальную очередь задач. Современные версии tokio хорошо справляются с этим по умолчанию, поэтому параметр опционален.

По умолчанию: not set (uses tokio's default).

tokio_event_interval

Настройки Tokio runtime. Управляет тем, как часто шедулер проверяет внешние события (I/O, таймеры). Современные версии tokio хорошо справляются с этим по умолчанию, поэтому параметр опционален.

По умолчанию: not set (uses tokio's default).

worker_stack_size

Настройки Tokio runtime. Задаёт размер стека для worker-потоков. Современные версии tokio хорошо справляются с этим по умолчанию, поэтому параметр опционален.

По умолчанию: not set (uses tokio's default).

max_blocking_threads

Настройки Tokio runtime. Задаёт максимальное число потоков для блокирующих операций. Современные версии tokio хорошо справляются с этим по умолчанию, поэтому параметр опционален.

По умолчанию: not set (uses tokio's default).

connect_timeout

Максимальное время ожидания при установке нового соединения с сервером PostgreSQL. Если соединение не удаётся установить за это время, попытка прерывается. Аналог server_connect_timeout из PgBouncer.

По умолчанию: 3000 (3 sec).

query_wait_timeout

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

По умолчанию: 5000 (5 sec).

idle_timeout

Закрывать серверное соединение, которое простаивает (не выдано ни одному клиенту) дольше этого значения. Применяется только к соединениям, обслужившим хотя бы один клиентский запрос. Прогретые или дополненные соединения, никогда не выдававшиеся клиенту, под действие idle_timeout не попадают — они закрываются только по истечении server_lifetime. Каждое соединение получает джиттер ±20%, чтобы избежать синхронных массовых закрытий. Установите 0, чтобы отключить. Аналог server_idle_timeout из PgBouncer.

По умолчанию: 600000 (10 min).

server_lifetime

Максимальный возраст серверного соединения. Когда соединение превышает этот возраст и переходит в idle, оно закрывается на ближайшем цикле retain. Активные транзакции не прерываются. Применяется ко всем соединениям, включая прогретые, которые никогда не выдавались клиенту. Каждое соединение получает джиттер ±20%, чтобы избежать thundering herd. Установите 0, чтобы отключить. Аналог server_lifetime из PgBouncer.

По умолчанию: 1200000 (20 min).

retain_connections_time

Интервал проверки и закрытия idle-соединений, превысивших idle_timeout или server_lifetime. Задача retain выполняется периодически с этим интервалом и удаляет просроченные соединения.

По умолчанию: 30000 (30 sec).

retain_connections_max

Максимальное число idle-соединений, закрываемых за один цикл retain. При значении 0 все idle-соединения, превысившие idle_timeout или server_lifetime, закрываются немедленно. При положительном значении за цикл по всем пулам закрывается не более указанного числа соединений.

Этот параметр управляет агрессивностью закрытия idle-соединений в pg_doorman. При значении по умолчанию 3 за цикл retain закрывается до 3 соединений, что обеспечивает контролируемую очистку. Если нужна более быстрая очистка просроченных соединений, установите 0 (без ограничений), чтобы закрывать все просроченные соединения за каждый цикл retain.

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

server_idle_check_timeout

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

Когда соединение простояло в пуле дольше этого таймаута, pg_doorman отправляет минимальный запрос (;), чтобы проверить, что соединение живо, прежде чем выдать его клиенту. Если проверка не проходит, соединение отбрасывается и берётся новое.

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

По умолчанию: 60s (60 seconds).

server_round_robin

Управляет тем, какое idle-серверное соединение выбирается для следующей транзакции. false (LRU): переиспользует самое недавно возвращённое соединение. Держит горячими меньше соединений, лучше для локальности shared buffer в PostgreSQL. true (Round Robin): равномерно ротирует все idle-соединения. Аналог server_round_robin из PgBouncer.

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

sync_server_parameters

В transaction mode каждая транзакция может попасть на разный бэкенд. При sync_server_parameters = true pg_doorman отслеживает изменения фиксированного набора параметров сессии и проигрывает их через SET на каждом новом бэкенде перед выполнением транзакции. Отслеживаемые параметры: client_encoding, DateStyle, TimeZone, standard_conforming_strings, application_name. Другие команды SET (например, statement_timeout, work_mem) НЕ отслеживаются. Каждый checkout стоит дополнительного roundtrip. Если вам нужна только видимость application_name в pg_stat_activity, используйте параметр application_name на уровне пула.

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

tcp_so_linger

По умолчанию pg_doorman отправляет RST вместо того, чтобы держать соединение открытым долгое время.

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

tcp_no_delay

TCP_NODELAY для отключения алгоритма Нэйгла ради более низкой задержки.

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

tcp_keepalives_count

Число неподтверждённых TCP keepalive probes, после которого соединение считается мёртвым и закрывается.

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

tcp_keepalives_idle

Keepalive включён по умолчанию и переопределяет дефолты ОС.

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

tcp_keepalives_interval

Интервал в секундах между отдельными TCP keepalive probes после прохождения начального периода простоя (tcp_keepalives_idle).

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

tcp_user_timeout

Задаёт опцию сокета TCP_USER_TIMEOUT для клиентских соединений (в секундах). Эта опция указывает максимальное время, в течение которого переданные данные могут оставаться неподтверждёнными, прежде чем TCP принудительно закроет соединение. Это помогает быстрее обнаруживать мёртвые клиентские соединения, чем keepalive probes, когда соединение активно отправляет данные, но удалённый конец стал недоступен (например, сбой сети, падение клиента).

При ненулевом значении, если данные остаются неподтверждёнными в течение указанного времени, соединение будет разорвано. Это особенно полезно, чтобы избежать задержек в 15–16 минут, вызванных TCP retransmission timeout, когда keepalive не помогает (например, при активной передаче данных).

Примечание: опция поддерживается только в Linux. На других ОС параметр игнорируется.

Установите 0, чтобы отключить (использовать значение по умолчанию ОС).

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

unix_socket_buffer_size

Размер буфера для операций чтения и записи при подключении к PostgreSQL через unix-сокет.

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

admin_username

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

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

admin_password

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

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

prepared_statements

Переключатель для включения/отключения кеширования prepared statements.

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

prepared_statements_cache_size

Размер кеша prepared statements на уровне пула (общий для всех клиентов, подключающихся к одному пулу). Кеш хранит соответствие между хешем запроса и переписанным именем prepared statement.

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

client_prepared_statements_cache_size

Максимальное число prepared statements, кешируемых в одном клиентском соединении. Это механизм защиты от вредоносных или некорректно работающих клиентов, которые не вызывают DEALLOCATE и могут вызвать исчерпание памяти, создавая неограниченное число prepared statements в долгоживущих соединениях.

При достижении лимита самая старая запись вытесняется из клиентского кеша. Вытесненный statement по-прежнему может быть переиспользован позже, потому что кеш уровня пула (prepared_statements_cache_size) сохраняет соответствие запроса и имени на сервере.

Установите 0, чтобы отключить лимит (неограниченный размер кеша, надежда на вызов DEALLOCATE клиентом).

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

message_size_to_be_stream

Когда сообщение DataRow PostgreSQL превышает этот порог, pg_doorman переключается в потоковый режим: данные пересылаются клиенту чанками по 4 KB вместо буферизации всего сообщения целиком. Это предотвращает OOM на запросах, возвращающих очень большие строки (например, таблицы с большими колонками bytea/text). Сам порог по умолчанию равен 1 MB.

По умолчанию: 1048576 (1 MB).

scaling_warm_pool_ratio

Доля прогретого пула в процентах (0–100). Когда размер пула ниже этого порога от max_size, новые соединения создаются немедленно. Выше порога пул сначала крутится через быстрые ретраи, затем переходит в event-driven цикл упреждающего ожидания, который ждёт возврата idle-соединения. Цикл ограничен оставшимся query_wait_timeout клиента минус резерв 500 ms на путь создания, поэтому он не может вытолкнуть вызывающего за его собственный дедлайн ожидания.

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

scaling_fast_retries

Число быстрых ретраев через yield_now() для ожидания с низкой задержкой при выдаче соединений выше порога прогрева пула. Каждый ретрай занимает примерно 1–5 мкс. После исчерпания быстрых ретраев пул переходит в event-driven цикл упреждающего ожидания, ограниченный оставшимся query_wait_timeout клиента.

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

scaling_max_parallel_creates

Ограничитель всплесков для создания соединений. Без этого лимита N параллельных вызывающих timeout_get, не нашедших соединения в idle-пуле, независимо инициируют backend-connect, создавая всплески thundering-herd под нагрузкой. С лимитом одновременно выполняется не больше указанного числа creates на пул; остальные кратко ждут на Notify и затем либо подхватывают только что возвращённое idle-соединение, либо занимают следующий слот для create. Значение по умолчанию 2 — компромисс между пропускной способностью и сглаживанием всплесков.

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

max_memory_usage

Общий бюджет памяти для внутренних буферов, хранящих данные in-flight запросов по всем клиентским соединениям. При достижении лимита pg_doorman отклоняет новые запросы с ошибкой, пока существующие запросы не завершатся и не освободят свои буферы. Защищает процесс пулера от OOM при тяжёлой нагрузке или больших результирующих наборах.

По умолчанию: 268435456 (256 MB).

shutdown_timeout

При graceful shutdown (SIGTERM) pg_doorman ждёт до этого времени завершения in-flight транзакций перед принудительным закрытием соединений.

По умолчанию: 10000 (10 sec).

proxy_copy_data_timeout

Максимальное время ожидания операций копирования данных при проксировании, в миллисекундах.

По умолчанию: 15000 (15 sec).

server_tls_mode

Режим TLS для исходящих соединений к серверам PostgreSQL.

allow — Сначала пробовать без TLS; если сервер отказывает, повторить с TLS. Соответствует libpq sslmode=allow (по умолчанию).
disable — TLS не используется.
prefer — TLS используется, если сервер его поддерживает; иначе обычное соединение.
require — TLS обязателен, но сертификат сервера не проверяется.
verify-ca — TLS обязателен, и сертификат сервера проверяется по server_tls_ca_cert.
verify-full — TLS обязателен, сертификат проверяется, и hostname сервера должен совпадать с сертификатом.

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

server_tls_ca_cert

CA-сертификат для проверки сертификатов серверов PostgreSQL. Обязателен, когда server_tls_mode равен verify-ca или verify-full.

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

server_tls_certificate

Клиентский сертификат для mTLS с серверами PostgreSQL. Используйте в паре с server_tls_private_key.

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

server_tls_private_key

Приватный ключ для клиентского сертификата mTLS. Используйте в паре с server_tls_certificate.

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

hba

Список IP-адресов, с которых разрешено подключаться к pg-doorman.

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

pg_hba

Новый стиль контроля доступа клиентов в нативном формате pg_hba.conf PostgreSQL. Позволяет задавать тонкие правила доступа аналогично PostgreSQL: per-database, per-user, диапазоны адресов, требования TLS.

Указать general.pg_hba можно тремя способами:

Как многострочную строку с содержимым файла pg_hba.conf
Как объект с path, указывающий на файл на диске
Как объект с content, содержащий правила в виде строки

Примеры:

[general]
# Inline-содержимое (TOML-строка в тройных кавычках)
pg_hba = """
# type   database  user   address         method
host     all       all    10.0.0.0/8      md5
hostssl  all       all    0.0.0.0/0       scram-sha-256
hostnossl all      all    192.168.1.0/24  trust
"""

# Или загрузить из файла
# pg_hba = { path = "./pg_hba.conf" }

# Или встроить как однострочную строку
# pg_hba = { content = "host all all 127.0.0.1/32 trust" }

Поддерживаемые поля и методы:

Типы соединений: local, host, hostssl, hostnossl (TLS-зависимое сопоставление учитывается)
Сопоставитель базы: имя или all
Сопоставитель пользователя: имя или all
Адрес: CIDR-форма вроде 1.2.3.4/32 или ::1/128 (обязателен для правил, отличных от local)
Методы: trust, md5, scram-sha-256 (неизвестные методы парсятся, но трактуются проверяющим как «не разрешено»)

Приоритет и совместимость:

general.pg_hba имеет приоритет над устаревшим списком general.hba. Нельзя задавать оба одновременно; валидация конфигурации отклонит такую комбинацию.
Правила вычисляются по порядку; первое совпавшее правило определяет результат.

Поведение method = trust:

Когда совпавшее правило имеет trust, PgDoorman принимает соединение без запроса пароля. Это повторяет поведение PostgreSQL.
В частности, при срабатывании trust PgDoorman пропускает проверку пароля, даже если у пользователя сохранён пароль md5 или scram-sha-256. Это распространяется и на MD5, и на SCRAM-потоки.
TLS-ограничения правила соблюдаются: hostssl требует TLS, hostnossl запрещает TLS.

Доступ к admin-консоли:

Правила general.pg_hba применяются и к специальной admin-базе pgdoorman.
Это означает, что admin-доступ можно разрешить методом trust при наличии совпавшего правила, например:
```
host  pgdoorman  admin  127.0.0.1/32  trust
```

Замечания и ограничения:

Поддерживается только минимальное подмножество pg_hba.conf, достаточное для большинства proxy-сценариев (type, database, user, address, method). Дополнительные опции (вроде clientcert) сейчас игнорируются.
Для методов аутентификации, отличных от trust, PgDoorman выполняет соответствующий challenge/response с клиентом.
Для потоков Talos/JWT/PAM, настроенных на уровне пула или пользователя, trust всё равно обходит запрос пароля у клиента; однако эти режимы могут использоваться, если trust не совпал.

pooler_check_query

Когда клиент отправляет ровно этот запрос как SimpleQuery, pg_doorman отвечает немедленно без перенаправления его в PostgreSQL. Полезно для health checks от балансировщиков нагрузки (HAProxy, в стиле pgbouncer SELECT 1) или keepalive-проб уровня приложения. Значение по умолчанию ; (пустой statement) — самая лёгкая возможная проверка.

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

Документация PgDoorman