karandashov.com – Infra

PgBouncer: лекарство с побочными эффектами. Часть 2 - конфигурация и эксплуатация

vlad.karandashov.tech@gmail.com (Влад Карандашов) — Fri, 26 Jun 2026 00:00:00 +0000

PgBouncer: как не выстрелить в ногу при эксплуатации

В первой части мы разобрали базовую механику PgBouncer: client/server connections, режимы pooling, ограничения transaction pooling и prepared statements.

Теперь более приземленная часть. Какой конфиг брать за стартовую точку, как выбирать размеры пулов, какие таймауты согласовать с HikariCP, что мониторить и где PgBouncer ставить в production.

Часть 1: обзор

Pooling modes, session state и prepared statements

PgBouncer config

Официальное описание параметров

Стартовая точка для конфига

Ниже я привел не идеальный production config на все случаи жизни. Такого не бывает. Но это нормальная стартовая точка для backend сервисов, которые хотят использовать transaction pooling, не гонять DDL через PgBouncer и оставить себе пространство для мониторинга.

pgbouncer.ini

[databases]
; Пул для прикладного runtime-трафика.
; В production пароль лучше не класть прямо в строку базы.
; PgBouncer может брать данные из auth_file/auth_query, а PostgreSQL должен принимать выбранную схему аутентификации.
app_db = host=postgres-primary port=5432 dbname=app_db \
 pool_mode=transaction pool_size=20 reserve_pool_size=5 \
 connect_query='SET search_path TO app_schema'

[pgbouncer]
; Сетевой интерфейс PgBouncer.
listen_addr = 0.0.0.0
listen_port = 6432

; Для production лучше scram-sha-256 или hba/auth_query.
; plain годится для локального демо.
auth_type = scram-sha-256
auth_file = /etc/pgbouncer/userlist.txt
admin_users = pgbouncer_admin
stats_users = pgbouncer_monitor

; Кажется уже обсудили.
pool_mode = transaction

; Сколько клиентских соединений PgBouncer готов принять.
; Это иожет быть гораздо больше числа реальных соединений к PostgreSQL.
max_client_conn = 300

; Размер server pool на пару database/user.
default_pool_size = 20
reserve_pool_size = 5
reserve_pool_timeout = 2

; Предохранители от случайного съедания всей базы одним пользователем или одной базой.
max_db_connections = 25
max_user_connections = 25

; Поддержка protocol-level prepared statements в transaction pooling.
max_prepared_statements = 200

; pgJDBC часто присылает extra_float_digits как startup parameter.
ignore_startup_parameters = extra_float_digits

; В transaction pooling нельзя полагаться на session reset.
server_reset_query =
server_reset_query_always = 0

; Таймауты server connections к PostgreSQL.
server_idle_timeout = 300
server_lifetime = 1800

; Очередь ожидания свободного server connection.
query_wait_timeout = 10

; Защита от зависших транзакций и медленного login.
idle_transaction_timeout = 30
client_login_timeout = 10

; Логи и агрегированная статистика.
log_connections = 1
log_disconnections = 1
log_pooler_errors = 1
log_stats = 1

Что здесь важно:

pool_size считается на пару database/user. Если у вас много пользователей или баз, суммарный лимит может оказаться выше, чем кажется.
max_db_connections и max_user_connections нужны как предохранители. Один забытый пользователь не должен съесть весь PostgreSQL.
reserve_pool_size помогает пережить короткий всплеск, но не должен маскировать постоянную нехватку основного пула.
server_reset_query в transaction pooling обычно не используется. Документация прямо говорит, что в transaction mode клиенты не должны полагаться на session-based features.
DDL, миграции, CREATE EXTENSION, CREATE INDEX CONCURRENTLY, codegen и ручной maintenance лучше вести прямым подключением к PostgreSQL, а не через этот runtime pool.

Для локального стенда можно упростить auth и положить user/password в строку базы. Для production так делать не надо: секреты потом придется ротировать, а PgBouncer — отдельный сервер аутентификации со своей процедурой обслуживания.

Как выбирать размеры пулов

При подборе размеров можно идти в таком порядке:

Сначала ограничить локальный пул в приложении: maximumPoolSize не должен быть сильно больше реальной потребности сервиса.
Оценить, сколько ваша инсталляция PostgreSQL реально переваривает backend-процессов под нагрузкой.
Поставить pool_size PgBouncer ниже этого числа, оставив место для админских подключений, миграций, maintenance и фоновых задач.
Добавить небольшой reserve_pool_size, если бывают короткие всплески.
Дальше мониторить wait time и tail latency, а не только количество открытых соединений.

И не надо путать max_client_conn с емкостью базы. Большое значение max_client_conn означает, что PgBouncer примет много клиентов. Это не значит, что PostgreSQL внезапно стал готов выполнять столько же запросов одновременно. Запросы просто будут ожидать в очереди.

Помните: PgBouncer не решает проблемы плохих запросов. Почитайте домкликовский разбор «Выдерни шнур, выдави стекло». Если запрос стал медленным из-за плана, статистики, временных файлов или новых параметров — пулер не вылечит причину. Он только скроет ее за очередь.

Таймауты: PgBouncer и внутренний пул приложения должны договориться

Таймауты — это место, где PgBouncer легко превратить в генератор странных разрывов соединений. Они спасают систему от зависших клиентов, но при неправильных значениях дают неожиданные ошибки.

`server_idle_timeout`

server_idle_timeout закрывает server connection к PostgreSQL, если он простаивает дольше заданного времени. Дефолт — 600 секунд.

Слишком маленькое значение приводит к постоянному циклу:

load spike → PgBouncer opens server connections
short idle → PgBouncer closes them
next spike → PgBouncer opens them again

PostgreSQL снова тратит ресурсы на login, auth, backend process, прогрев кэшей. В мониторинге это будет похоже на зубчатый график server connections.

Слишком большое значение держит лишние backend-процессы в PostgreSQL даже после того, как нагрузка ушла.

Стартовая рекомендация: не ставить секунды «на всякий случай». Для web-нагрузки часто разумнее минуты: условные 300–600 секунд. Если нагрузка приходит редкими большими пачками, значение надо подбирать по реальному профилю.

`server_lifetime`

server_lifetime закрывает неиспользуемое server connection, если оно прожило дольше заданного времени. Дефолт — 3600 секунд.

Эта настройка помогает не держать backend-процессы бесконечно. В старом соединении могут накопиться prepared statements, кэши, relcache, session-level мусор от неидеального приложения. Но слишком короткий lifetime снова дает много накладных расходов.

`query_wait_timeout`

query_wait_timeout ограничивает время, которое query ждет свободный server connection. Если за это время PgBouncer не назначил backend, клиентское соединение отключается. Дефолт — 120 секунд.

120 секунд для web API часто слишком много. Пользователь уже ушел, upstream gateway уже вернул timeout, а PgBouncer все еще честно держит запрос в очереди. Потом он наконец выполнится или отвалится, но приложению от этого легче не станет.

Настраивайте query_wait_timeout от SLA запроса. Если API должен отвечать за 2 секунды, нет смысла держать запрос в очереди PgBouncer минуту. Лучше получить раннюю ошибку, заалертиться по saturation и чинить причину.

`idle_transaction_timeout` и `transaction_timeout`

idle_transaction_timeout отключает клиента, если он слишком долго сидит в idle in transaction. transaction_timeout ограничивает общее время состояния in transaction.

В transaction pooling это особенно полезно. Пока клиент держит транзакцию открытой, он держит server connection. Один забытый код вроде «открыли транзакцию, сходили в другой сервис, подождали ответ, потом продолжили SQL» быстро съедает пул.

Я бы не начинал с агрессивных значений на первом деплое. Сначала включить мониторинг, найти реальные длинные транзакции, починить код, потом ставить защитные лимиты. Но в целом это отличная гигиена: разработчики лишний раз подумают, что именно происходит внутри @Transactional метода.

`client_idle_timeout`

client_idle_timeout закрывает idle client connections. Документация советует держать его больше client-side connection lifetime и использовать в основном для сетевых проблем.

Для HikariCP это означает: не ставьте client_idle_timeout меньше, чем пул ожидает жить со своим соединением к PgBouncer. Иначе Hikari будет получать закрытые соединения извне, чаще валидировать и переоткрывать их.

В документации HikariCP для maxLifetime есть похожая логика: значение должно быть на несколько секунд меньше внешнего лимита жизни соединения. Если где-то между приложением и PgBouncer есть load balancer, NAT или proxy idle timeout, Hikari должен узнать об этом раньше пользователя.

Примерный набор для приложения:

application.yaml

spring:
 datasource:
 hikari:
 maximum-pool-size: 10
 minimum-idle: 10
 connection-timeout: 5000
 max-lifetime: 1700000
 keepalive-time: 120000

И в PgBouncer:

pgbouncer.ini

server_idle_timeout = 300
server_lifetime = 1800
query_wait_timeout = 10
idle_transaction_timeout = 30

Не копируйте бездумно, смотрите на смысл:

Hikari connection-timeout отвечает за ожидание свободного соединения внутри приложения.
PgBouncer query_wait_timeout отвечает за ожидание свободного server connection к PostgreSQL.
Hikari max-lifetime и keepalive-time относятся к client connection до PgBouncer.
PgBouncer server_idle_timeout и server_lifetime относятся к server connection до PostgreSQL.

Когда эти уровни путают, начинаются лишние reconnect storm.

Мониторинг

У PgBouncer есть admin database pgbouncer, где доступны SHOW STATS, SHOW POOLS, SHOW CLIENTS, SHOW SERVERS.

Что смотреть в первую очередь:

cl_waiting в SHOW POOLS - клиенты ждут свободный server connection;
maxwait - сколько ждет самый старый клиент в очереди;
sv_active, sv_idle, sv_used, sv_login - состояние server connections;
total_wait_time / avg_wait_time в SHOW STATS - накопленное и среднее ожидание backend connection;
avg_xact_time и avg_query_time - насколько транзакции длиннее самих запросов;
total_client_parse_count, total_server_parse_count, total_bind_count - что происходит с prepared statements;
количество ошибок в логах: лимиты, login failures, query timeouts, pooler errors.

Мне нравится подход из статьи USE, RED, PgBouncer, его настройки и мониторинг. Там PgBouncer разбирают по USE:

Utilization: насколько заняты server connections, сколько времени они проводят в query/transaction.
Saturation: есть ли cl_waiting, растет ли maxwait, появляется ли total_wait_time.
Errors: отказы по лимитам, таймауты, ошибки авторизации, pooler errors.

Отдельно полезно смотреть разницу между total_xact_time и total_query_time. Если транзакции заметно длиннее запросов, приложение держит соединение, но не выполняет SQL. Для transaction pooling это по сути налог на емкость пула.

В production метрики PgBouncer надо смотреть рядом с:

Hikari active/idle/pending connections;
latency HTTP endpoints;
PostgreSQL pg_stat_activity;
PostgreSQL locks;
CPU PostgreSQL и PgBouncer;
количеством backend-процессов;
p95/p99 query latency.

Иначе легко перепутать причину и следствие. cl_waiting может расти потому, что pool_size мал. А может потому, что один SQL стал в 20 раз медленнее и занял все server connections.

Production: где поставить PgBouncer

Есть несколько типичных схем.

PgBouncer рядом с приложением

Sidecar или локальный процесс около приложения уменьшает latency на client connection и хорошо подходит для короткоживущих клиентов. Но каждый экземпляр приложения получает свой PgBouncer, а значит надо внимательно считать суммарные server connections к PostgreSQL.

Если 20 pod’ов и у каждого pool_size=20, база потенциально увидит 400 server connections. В этом случае PgBouncer перестает быть глобальным ограничителем.

PgBouncer как отдельный сервис

Один или несколько PgBouncer перед PostgreSQL лучше агрегируют нагрузку от многих приложений. Проще контролировать общий лимит соединений к базе, проще мониторить.

Цена - еще один сетевой hop и отдельная точка отказа. Нужны HA, rolling restart, health checks, понятная схема failover.

Официальный FAQ PgBouncer аккуратно отвечает на вопрос «ставить на web server или database server»: зависит от нагрузки и модели failover. То есть универсальной схемы нет.

Несколько PgBouncer под разные профили

Иногда один общий PgBouncer становится узким местом. Разные приложения могут иметь разный профиль:

короткие OLTP-запросы;
длинные read-only отчеты;
фоновые batch-job’ы;
админские операции;
отдельные listener’ы для LISTEN/NOTIFY;
сервисы с разными требованиями к latency.

В таком случае разумно разделить ресурсы: один PgBouncer или один pool для коротких runtime-запросов, другой — для длинных операций, третий — для отдельной группы приложений. Это не обязательно должны быть разные инстансы; иногда достаточно разных database aliases с разными pool_size, max_db_connections и query_wait_timeout.

Смысл простой: медленный batch не должен съедать server connections у пользовательского API. А пользовательский API не должен мешать maintenance-задачам, которым нужен отдельный прямой доступ к PostgreSQL.

Несколько PgBouncer и `so_reuseport`

PgBouncer исторически однопоточный: один процесс в основном использует одно CPU-ядро. На большой нагрузке это может стать бутылочным горлышком, особенно с включенным prepared statement tracking, где PgBouncer разбирает и переписывает сообщения.

Если не хотите делать полноценные разные экземпляры на разные группы сервисов — можно запускать несколько процессов на одном порту через so_reuseport. В документации это же используется как часть rolling restart сценария: несколько процессов слушают один порт, перезапускаются по одному, клиенты переподключаются без полного простоя.

Failover

Отдельно стоит сказать про работу в отказоустойчивом режиме.

PgBouncer не делает полноценный PostgreSQL failover. Он может перечитать DNS, принять RELOAD, выполнить RECONNECT, закрыть старые server connections и открыть новые. Но решение «кто теперь primary» принимает не PgBouncer.

Если за PgBouncer стоит HAProxy, Patroni, managed PostgreSQL или другой слой маршрутизации, надо отдельно проверять:

что происходит с уже открытыми server connections;
как быстро PgBouncer узнает новый адрес;
нужно ли выполнять RECONNECT;
что видят приложения во время переключения;
какие ошибки retry-логика считает безопасными.

Лучше один раз отрепетировать failover на стенде, чем впервые узнать реальное поведение PgBouncer ночью.

Где PgBouncer не нужен

PgBouncer не надо тащить в каждый проект просто потому что «в проде так делают».

Он может быть лишним, если:

у вас один маленький сервис и max_connections не проблема;
вы достаточно богаты и поднимаете отдельные БД на каждый чих;
приложение уже держит аккуратный маленький pool, а реплик мало;
workload завязан на session state;
нужно много LISTEN/NOTIFY;
используются server-side cursors между транзакциями;
миграции, аналитика и runtime перемешаны в одном канале;
проще поднять managed PostgreSQL с подходящим лимитом соединений.

Иногда первый правильный шаг — уменьшить Hikari maximumPoolSize, найти длинные транзакции и добавить индекс. PgBouncer не должен становиться способом отложить работу по оптимизации.

Итог

PgBouncer хорош, когда у вас много клиентов и ограниченное число PostgreSQL backend-процессов. Он особенно полезен в микросервисной среде, где каждый сервис приносит свой connection pool и сумма этих пулов быстро становится больше разумного max_connections. А ресурсы БД имеет смысл перераспределять.

PgBouncer не отменяет пул внутри приложения. HikariCP защищает сам сервис от лишней локальной конкуренции и затрат на подключение, а PgBouncer защищает PostgreSQL от лишних соединений, процессов и затрат.

Самый рабочий режим - transaction pooling, но он требует дисциплины: никаких session-level ожиданий, миграции напрямую, LISTEN отдельно, prepared statements настроены согласованно, таймауты замерены, мониторинг включен.

Когда эта дисциплина есть, PgBouncer становится скучным и полезным инфраструктурным компонентом. Именно таким он и должен быть.

PgBouncer: лекарство с побочными эффектами. Часть 1 - обзор

vlad.karandashov.tech@gmail.com (Влад Карандашов) — Thu, 25 Jun 2026 00:00:00 +0000

PgBouncer: лекарство с побочными эффектами

Про PgBouncer обычно вспоминают в двух ситуациях. Либо PostgreSQL уже начал ругаться на too many connections, а приложение завопило PSQLException: FATAL: sorry, too many clients already. Либо кто-то заранее посмотрел на количество pod’ов, умножил его на размер Hikari pool и тихо отложил кофе.

На первый взгляд PgBouncer элегантно решает проблему: поставили маленький прокси перед PostgreSQL, направили туда приложения, получили меньше настоящих соединений к базе. Но PgBouncer тем и опасен, что долго работает «прозрачно». А потом в один день выясняется, что временная таблица пропала, LISTEN не слушает, миграция оставила странную ошибку prepared statement cache, а SET search_path повел себя не как на локальной базе.

Это первая обзорная часть: зачем PgBouncer нужен, почему он не заменяет connection pool внутри приложения, чем отличаются session, transaction и statement pooling, где ломается session state и что сейчас происходит с prepared statements.

Во второй части разберем эксплуатацию: стартовый конфиг, sizing, таймауты, мониторинг, production-топологии и failover.

Примеры дальше в основном из Java-мира, поэтому часто встречаются HikariCP, pgJDBC и Spring Boot. Это не принципиально. Та же логика работает для Hibernate, jOOQ, Spring Data JDBC, Go-сервисов, Python ORM и любого клиента PostgreSQL. Меняются только названия драйверов и конкретные настройки.

Пример использования PgBouncer можно посмотреть в этом демо примере.

PgBouncer features

Официальная карта режимов и несовместимых PostgreSQL-фич

Часть 2: эксплуатация

Конфиг, sizing, таймауты, мониторинг и production

Что делает PgBouncer

PostgreSQL обслуживает обычные клиентские соединения отдельными процессами. У соединения с базой есть память, session state, кэши, prepared statements, параметры сессии, возможные временные объекты и открытая транзакция.

Если у нас один монолит и пул с 10 соединениями, жизнь спокойная. Если у нас 40 экземпляров сервиса с таким же пулом, получается уже до 400 соединений. Даже если большинство из них почти ничего не делает, PostgreSQL все равно должен их держать: память, backend-процессы, планировщик ОС, служебные проверки, контекстные переключения.

Официальная документация PgBouncer описывает его как слой, через который клиент подключается так же, как к PostgreSQL. С точки зрения приложения это обычный PostgreSQL port. Внутри PgBouncer принимает клиентские соединения и держит собственный ограниченный набор серверных соединений к базе.

В результате появляются два разных типа соединений:

client connection - соединение приложения с PgBouncer;
server connection - настоящее соединение PgBouncer с PostgreSQL.

Другими словами, HikariCP в условном Java-приложении управляет client connections к PgBouncer. PgBouncer управляет server connections к PostgreSQL. Они стоят на разных этажах и решают разные задачи.

Почему именно PgBouncer

Есть и другие подходы: Pgpool-II, PgCat, Odyssey и множество других. Но PgBouncer выбирают из-за простоты и понятной зоны ответственности.

Он не пытается быть балансировщиком запросов, репликатором, query router’ом и полноценной HA-платформой одновременно. Он делает одну вещь: принимает много клиентских соединений и ограничивает число реальных соединений к PostgreSQL.

PgBouncer маленький и быстро стартует;
хорошо совместим с большинством стандартных PostgreSQL-фич, поэтому приложения часто его не замечают;
конфиг читается за вечер, а не за неделю;
есть понятная admin console: SHOW POOLS, SHOW STATS, SHOW CLIENTS, SHOW SERVERS;
легко поставить как отдельный сервис или рядом с приложением;
давно используется в production и хорошо описан в документации.

Цена простоты тоже есть: PgBouncer использует однопоточную архитектуру и работает только на одном ядре процессора на один экземпляр. Из-за этого при пиковых нагрузках PgBouncer может упираться в процессор. Но такая архитектура обеспечивает отличную производительность и низкое потребление памяти для большинства стандартных задач. К тому же есть весьма понятные способы обходить это ограничение.

Почему PgBouncer не заменяет connection pool внутри сервиса

Иногда PgBouncer воспринимают как внешний HikariCP: раз есть пул перед базой, можно убрать пул в приложении или сделать его очень большим. Обычно это плохой план.

Pool внутри сервиса отвечает за локальную дисциплину:

ограничивает количество потоков или virtual threads, которые одновременно полезут в базу;
переиспользует уже открытые соединения;
не тратит время бизнес-запроса на новое подключение;
проверяет живость соединений;
интегрируется с транзакциями фреймворка и ORM;
дает метрики на уровне конкретного сервиса.

PgBouncer отвечает за другое:

принимает много клиентских соединений от разных сервисов;
не дает приложениям открыть слишком много реальных процессов в PostgreSQL;
переиспользует настоящие соединения к базе между клиентами;
перераспределяет ограниченный пул server connections между приложениями;
ставит клиентов в очередь, если все server connections заняты.

Если убрать локальный пул и ходить в PgBouncer «на каждый запрос новым connection», мы снова заплатим за создание JDBC-объекта, аутентификацию, TLS/сетевые расходы и лишние ошибки при всплесках. PostgreSQL будет защищен, но приложение хуже проконтролирует собственную конкуренцию.

Если оставить локальный пул, но поставить maximum-pool-size в сотни «потому что PgBouncer все равно ограничит», мы просто перенесем очередь из приложения в PgBouncer. Сервис будет держать много занятых worker threads или virtual threads, а пользователи увидят задержку уже после того, как запрос добрался до базы.

Размер локального пула подбирается от профиля конкретного сервиса. Размер PgBouncer pool — от возможностей PostgreSQL и общей нагрузки всех клиентов.

PgBouncer не делает базу быстрее. Он помогает пережить большое количество клиентов и перераспределить нагрузку. Но если запросы медленные, индексов нет, а транзакции держат locks по секундам, PgBouncer просто выстроит ваши проблемы в аккуратную очередь.

Режимы pooling

У PgBouncer три основных режима. В документации они описаны как разные уровни “brutality”, и эта шутка в документации довольно точно передает инженерный смысл.

Session pooling

session - самый спокойный режим и дефолт PgBouncer.

Клиент подключился к PgBouncer, PgBouncer выдал ему server connection к PostgreSQL и держит эту пару до конца клиентской сессии. Когда клиент отключается, server connection возвращается в пул.

Плюсы:

почти все PostgreSQL-фичи работают как при прямом подключении;
можно использовать LISTEN, session-level advisory locks, временные таблицы, session variables;
меньше сюрпризов для ORM и старого кода.

Минус очевидный: если приложение держит постоянные соединения, то экономия слабая. Десять соединений в одном экземпляре приложения займут десять server connections в PgBouncer на все время жизни сервиса.

session полезен, когда нужно снизить стоимость переподключений или обслужить короткоживущих клиентов, но нельзя ломать session state.

Transaction pooling

transaction - самый популярный режим, ради которого и используют PgBouncer.

Server connection выдается клиенту только на время транзакции. Транзакция закончилась — соединение возвращается в пул, а следующая транзакция этого же клиента может попасть уже на другое соединение с PostgreSQL.

Это дает главную экономию: приложение может держать много client connections к PgBouncer, но настоящих PostgreSQL соединений будет заметно меньше. Особенно хорошо это работает, если сервисы делают короткие транзакции.

Цена — потеря стабильной привязки клиента к одной PostgreSQL-сессии. Если приложение работает классическими короткими запросами без session state, вы можете этого не почувствовать. Более сложные ситуации требуют отдельной проверки. В официальной таблице совместимости это сформулировано так: transaction pooling специально разрывает ожидание клиента, что за ним закреплен один server connection. Использовать его можно, только если приложение не опирается на session state. Но не стоит пугаться, в современных микросервисах эти ситуации встречаются крайне редко.

Statement pooling

statement - самый агрессивный режим. Server connection возвращается в пул после каждого statement. Многошаговые транзакции запрещены, потому что иначе PgBouncer сломал бы саму семантику транзакции.

Для обычного backend это почти никогда не то, что нужно. Такой режим можно рассматривать для очень специфичной нагрузки: много коротких независимых запросов в autocommit и полная уверенность, что приложению не нужны транзакции из нескольких SQL-команд.

Если сомневаетесь между transaction и statement, почти наверняка вам нужен transaction.

Что ломается в transaction pooling

Окей, вероятнее всего, если вы задумались над PgBouncer, то вам нужен transaction pooling. Но какие именно ограничения в нем есть?

Главный принцип простой: все, что живет дольше одной транзакции и привязано к PostgreSQL-сессии, под transaction pooling становится подозрительным.

Официальная таблица совместимости PgBouncer отдельно отмечает несколько важных случаев:

Возможность PostgreSQL	`session`	`transaction`
`SET` / `RESET` session state	да	нет
`LISTEN`	да	нет
`NOTIFY`	да	да
protocol-level prepared plans	да	да, при `max_prepared_statements > 0`
SQL `PREPARE` / `DEALLOCATE`	да	нет
temp tables `ON COMMIT DROP`	да	да
temp tables `PRESERVE ROWS` / `DELETE ROWS`	да	нет
session-level advisory locks	да	нет
`LOAD`	да	нет

Это не произвольные ограничения именно PgBouncer. Это следствие того, что после завершения транзакции следующий statement клиента может попасть на другую PostgreSQL-сессию.

`SET`, `search_path` и переменные

В transaction pooling нельзя полагаться на обычный SET something = ..., если это session-level изменение.

Плохая идея:

set search_path to surveys_schema;
select *
from surveys;

Первый statement мог выполниться на одном server connection, второй — на другом. Даже если сегодня повезло, контракт уже сломан.

Варианты лучше:

задавать search_path на роли или базе в PostgreSQL;
использовать SET LOCAL внутри транзакции;
указывать схему явно;
для PgBouncer использовать connect_query, если это подходит вашей модели;
для параметров, которые PostgreSQL умеет репортить клиенту, смотреть в сторону track_extra_parameters.

Пример настройки PgBouncer с помощью connect_query:

pgbouncer.ini

jooq_demo_db = host=postgres port=5432 dbname=jooq_demo_db user=test password=test \
 pool_mode=transaction pool_size=20 reserve_pool_size=5 \
 connect_query='SET search_path TO surveys_schema'

Это лучше, чем выполнять SET search_path из приложения в начале каждой «сессии», которой в transaction pooling фактически нет. Но и здесь надо понимать границы: connect_query выполняется при создании server connection, а не перед каждым клиентским запросом.

Временные таблицы

Временные таблицы живут в PostgreSQL-сессии. Поэтому обычный сценарий «создал temp table, потом в другой транзакции дочитал из нее данные» не совместим с transaction pooling.

Совместимый вариант — временная таблица, которая целиком живет внутри одной транзакции и умирает на COMMIT:

good.sql

begin;

create temporary table tmp_ids
(
 id uuid
) on commit drop;

insert into tmp_ids
values ('018f0000-0000-7000-8000-000000000001');

select *
from orders
where id in (select id from tmp_ids);

commit;

Этот фрагмент нормальный для transaction pooling: ON COMMIT DROP попадает в совместимую зону, потому что таблица умирает вместе с транзакцией.

Плохой вариант — создать temp table и ожидать, что она переживет несколько транзакций клиента:

bad.sql

create temporary table tmp_ids(id uuid) on commit preserve rows;

insert into tmp_ids
values ('018f0000-0000-7000-8000-000000000001');

commit;

select *
from orders
where id in (select id from tmp_ids);

После COMMIT следующий запрос может попасть на другой server connection, где такой временной таблицы нет. Поэтому ON COMMIT PRESERVE ROWS и ON COMMIT DELETE ROWS в официальной таблице совместимости помечены как несовместимые с transaction pooling.

Для прикладного кода это хороший повод спросить себя: а точно ли здесь нужна временная таблица? Часто ее можно заменить CTE, VALUES, массивом параметров, JSON-to-recordset или нормальной staging-таблицей с ключом batch/job.

LISTEN / NOTIFY

NOTIFY можно выполнить через transaction pooling. LISTEN - уже нельзя.

PostgreSQL сам описывает LISTEN как регистрацию текущей session на notification channel. Регистрация очищается, когда сессия заканчивается. PgBouncer в transaction mode не дает приложению стабильную server session, значит подписчик будет сломан концептуально.

Если приложению нужен LISTEN/NOTIFY, делайте отдельный канал с уровнем session pooling или прямым подключением к PostgreSQL. Для Java это особенно важно: pgJDBC получает notifications через PGConnection, то есть listener и так обычно живет на отдельном выделенном соединении.

Advisory locks

Session-level advisory locks через transaction pooling использовать нельзя. Они привязаны к сессии, а сессия после транзакции больше не принадлежит клиенту.

Transaction-level advisory locks (pg_advisory_xact_lock) обычно укладываются в модель transaction pooling, потому что их жизненный цикл совпадает с транзакцией. Но это не повод превращать PgBouncer в распределенный lock manager. Если lock держится долго, он занимает server connection и уменьшает полезную емкость пула.

Если хочется отдельно освежить механику advisory locks, есть хороший разбор на Хабре: «Advisory Locks в PostgreSQL». Для PgBouncer там особенно важна разница между session-level и transaction-level блокировками.

DDL и миграции

DDL лучше не гонять через transaction pool. Не потому, что PgBouncer вообще не умеет DDL, а потому что миграции любят ровно те вещи, которые плохо дружат с агрессивным pooling:

долгие транзакции;
advisory locks;
смена схемы под работающими prepared statements;
команды, которым нужен особый transaction mode;
расширения и session state;
отдельные прямые проверки metadata.

Практичный паттерн такой:

application.yaml

spring:
 datasource:
 url: jdbc:postgresql://pgbouncer-app:6432/app_db
 flyway:
 url: jdbc:postgresql://postgres:5432/app_db

Runtime-трафик идет через PgBouncer. Flyway, Liquibase, CREATE EXTENSION, CREATE INDEX CONCURRENTLY и прочие DDL-задачи идут напрямую в PostgreSQL.

После DDL, который меняет форму результата prepared statements, можно получить cached plan must not change result type. В документации PgBouncer для max_prepared_statements прямо советуют после таких миграций выполнять RECONNECT в admin console, чтобы серверные соединения переподготовили statements.

Prepared statements: старый страх и новая реальность

Самая частая страшилка про PgBouncer: «transaction pooling несовместим с prepared statements». Она пугала много лет, но сейчас ее надо произносить аккуратнее.

PgBouncer и Prepared Statement: друзья или враги

Есть два разных уровня:

SQL-level prepared statements: PREPARE, EXECUTE, DEALLOCATE.
Protocol-level prepared statements: то, что используют драйверы через PostgreSQL extended query protocol.

Первый вариант по-прежнему не работает нормально в transaction pooling. Если вы выполняете:

bad.sql

prepare find_survey(uuid) as
 select *
 from surveys
 where id = $1;

execute find_survey('018f0000-0000-7000-8000-000000000001');

то PREPARE может случиться на одном server connection, а EXECUTE - на другом. PgBouncer не переписывает SQL-level PREPARE/EXECUTE/DEALLOCATE, он отправляет их в PostgreSQL как есть.

Второй вариант интереснее. Начиная с PgBouncer 1.21.0, появился tracking protocol-level named prepared statements. В свежем PgBouncer max_prepared_statements уже по умолчанию равен 200, а не 0.

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

клиент готовит statement под своим именем;
PgBouncer хранит соответствие клиентского имени и внутреннего имени;
одинаковый SQL получает общий internal name вида PGBOUNCER_123;
если текущий server connection еще не знает этот statement, PgBouncer подготовит его перед выполнением;
при max_prepared_statements = 0 эта поддержка выключена.

Это важная поправка для Java. Все популярные ORM вроде Hibernate, Spring Data JDBC, jOOQ и другие по умолчанию используют JDBC PreparedStatement, когда им надо передавать bind values.

pgJDBC, в свою очередь, использует extended protocol, а после нескольких выполнений может перейти к server-side prepared statement. В документации pgJDBC дефолтный prepareThreshold равен 5. Отключается это параметром prepareThreshold=0.

То есть современные варианты такие:

application.properties

# Вариант 1: используем поддержку PgBouncer 1.21+
spring.datasource.url=jdbc:postgresql://pgbouncer:6432/app_db

# Вариант 2: отключаем server-side prepared statements в pgJDBC
spring.datasource.url=jdbc:postgresql://pgbouncer:6432/app_db?prepareThreshold=0

Первый вариант обычно лучше для классического Java backend, если PgBouncer свежий и max_prepared_statements включен. Prepared statements уменьшают parse/plan overhead и не заставляют драйвер каждый раз слать полный SQL.

Второй вариант полезен как диагностика или временное решение, если:

PgBouncer старый;
используется не PgBouncer, а совместимый пулер с другими ограничениями;
приложение ловит ошибки prepared statement cache после DDL;
есть библиотека, которая странно именует statements или смешивает типы параметров.

У поддержки prepared statements есть цена. PgBouncer должен разбирать и переписывать protocol messages, хранить query cache, держать prepared statements на server connections. На больших нагрузках это добавляет CPU и память. Зато один подготовленный план запроса может переиспользоваться между разными клиентами, если SQL совпадает.

Supabase в документации по Supavisor transaction mode до сих пор рекомендует отключать prepared statements для ряда клиентов. Это хороший пример, почему нельзя переносить правила между разными pooler’ами автоматически. PgBouncer 1.25 и managed pooler у провайдера могут вести себя по-разному.

Что дальше

На уровне обзора картина такая:

PgBouncer нужен, чтобы ограничить количество настоящих соединений к PostgreSQL.
Он не заменяет connection pool внутри приложения.
Самый полезный режим для backend-сервисов - transaction.
transaction pooling требует дисциплины вокруг session state.
Prepared statements больше не надо автоматически выключать, но надо понимать разницу между SQL-level и protocol-level prepared statements.
Миграции и DDL лучше вести прямым подключением к PostgreSQL.

Во второй части разберем, как это эксплуатировать: с какого конфига стартовать, как выбирать размеры пулов, какие таймауты согласовать с HikariCP, какие метрики смотреть и где PgBouncer лучше ставить в production.

PgBouncer: эксплуатация, таймауты и production

Продолжение: конфиг, sizing, мониторинг, топологии и failover

karandashov.com – Infra

PgBouncer: лекарство с побочными эффектами. Часть 2 - конфигурация и эксплуатация

Стартовая точка для конфига

Как выбирать размеры пулов

Таймауты: PgBouncer и внутренний пул приложения должны договориться

server_idle_timeout

server_lifetime

query_wait_timeout

idle_transaction_timeout и transaction_timeout

client_idle_timeout

Мониторинг

Production: где поставить PgBouncer

PgBouncer рядом с приложением

PgBouncer как отдельный сервис

Несколько PgBouncer под разные профили

Несколько PgBouncer и so_reuseport

Failover

Где PgBouncer не нужен

Итог

PgBouncer: лекарство с побочными эффектами. Часть 1 - обзор

Что делает PgBouncer

Почему PgBouncer не заменяет connection pool внутри сервиса

Режимы pooling

Session pooling

Transaction pooling

Statement pooling

Что ломается в transaction pooling

SET, search_path и переменные

Временные таблицы

LISTEN / NOTIFY

Advisory locks

DDL и миграции

Prepared statements: старый страх и новая реальность

Что дальше

`server_idle_timeout`

`server_lifetime`

`query_wait_timeout`

`idle_transaction_timeout` и `transaction_timeout`

`client_idle_timeout`

Несколько PgBouncer и `so_reuseport`

`SET`, `search_path` и переменные