PgBouncer, Pgpool-II и другие: пулеры соединений для PostgreSQL

Пулер соединений для PostgreSQL — это программа между приложением и базой, которая держит небольшое число реальных подключений к серверу и раздаёт их клиентам по очереди. Самые известные — PgBouncer и Pgpool-II, из новых — Odyssey и PgCat.

Зачем PostgreSQL пулер

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

PgBouncer

PgBouncer — лёгкий однопоточный пулер, стандартный выбор для большинства проектов. Актуальная ветка — 1.25 (выпуск 1.25.2 вышел в мае 2026 года). Он ничего не знает о структуре базы и только управляет подключениями.

Режимы пула

• session (по умолчанию) — серверное подключение закреплено за клиентом, пока тот не отключится. Совместим со всем, но экономии почти не даёт.
• transaction — подключение возвращается в пул после окончания транзакции. Основной режим для экономии: сотни клиентов обслуживаются десятком подключений.
• statement — подключение возвращается после каждого запроса; транзакции из нескольких запросов запрещены.

Что ломается в режиме transaction

Между транзакциями клиент может попасть на другое серверное подключение, поэтому не работает всё, что хранит состояние сессии. По документации PgBouncer несовместимы с режимом transaction:

• SET и RESET на уровне сессии;
• LISTEN;
• курсоры WITH HOLD;
• SQL-команды PREPARE и DEALLOCATE;
• временные таблицы с PRESERVE или DELETE ROWS;
• LOAD;
• рекомендательные блокировки (advisory locks) на уровне сессии.

Подготовленные запросы на уровне протокола — их используют драйверы вроде JDBC и asyncpg — PgBouncer в новых версиях поддерживает и в режиме transaction: он сам подготавливает их на серверных подключениях. За это отвечает параметр max_prepared_statements (в текущей документации по умолчанию 200; значение 0 выключает поддержку).

Минимальная конфигурация

[databases]
app = host=127.0.0.1 port=5432 dbname=app

[pgbouncer]
listen_addr = 127.0.0.1
listen_port = 6432
auth_type = scram-sha-256
auth_file = /etc/pgbouncer/userlist.txt
pool_mode = transaction
max_client_conn = 1000
default_pool_size = 20

Приложение подключается к порту 6432 вместо 5432. default_pool_size — сколько серверных подключений держится на пару «пользователь — база» (по умолчанию 20), max_client_conn — сколько клиентов может подключиться к самому PgBouncer (по умолчанию 100).

Pgpool-II

Pgpool-II — не только пулер, а связующее звено для кластера: балансировка чтения между репликами, автоматическое переключение при отказе основного сервера, сторожевой процесс (watchdog) для отказоустойчивости самого Pgpool. Актуальная ветка — 4.7 (выпуск 4.7.2, июнь 2026 года), поддерживаются ветки с 4.3 по 4.7.

Платой за возможности становится сложность: Pgpool-II разбирает SQL, чтобы решить, куда отправить запрос, у него больше настроек и больше мест для ошибки. Его пул работает по модели «процесс на клиента», поэтому для экономии подключений он проще и эффективнее в связке, где пул держит PgBouncer.

PgBouncer или Pgpool-II

Если нужен только пул — PgBouncer. Если нужно автоматически распределять чтение по репликам и переключаться при отказе и вы готовы поддерживать сложную конфигурацию — Pgpool-II. Для отказоустойчивого кластера сегодня часто берут Patroni, а перед ним — PgBouncer и HAProxy (подробнее о HAProxy — в цикле о прокси).

Odyssey

Odyssey — многопоточный пулер, созданный в Яндексе, лицензия BSD-3-Clause, проект активно развивается (выпуск 1.5.2 — сентябрь 2026 года). Он рассчитан на большие нагрузки, где однопоточный PgBouncer упирается в одно ядро процессора. Для большинства проектов это избыточно, но при десятках тысяч подключений стоит сравнить его с несколькими экземплярами PgBouncer.

PgCat

PgCat — пулер на Rust с шардированием и балансировкой, лицензия MIT. Проект заметно замедлился: последний выпуск 0.2.5 вышел в ноябре 2024 года, последние изменения в репозитории — в феврале 2025-го. Для новых продакшен-установок его стоит выбирать осторожно.

Типичные ошибки

• Режим transaction без проверки приложения. SET search_path, LISTEN или сессионные блокировки начинают вести себя непредсказуемо.
• Пулер как единая точка отказа. Ставьте его рядом с каждым сервером приложения или в двух экземплярах.
• Сумма пулов больше max_connections сервера. Считайте default_pool_size × число пар «пользователь — база» плюс резерв для администратора.
• Два пула подряд. Пул в приложении с большим размером поверх PgBouncer не экономит подключения, а только усложняет диагностику.

Полезные ссылки

• PgBouncer: настройки
• PgBouncer: совместимость режимов
• Pgpool-II
• Odyssey на GitHub