Миграция на transaction mode: план развёртывания и prepared statements в PgBouncer 1.21

У команды PgBouncer в session mode. Они хотят transaction mode — мультиплексирование 10×, — но боятся поломок. Аудит и canary-развёртывание занимают одну неделю, а не год; опасения по prepared statements были обоснованы до марта 2024 года и теперь решены.

Пятишаговое развёртывание

PgBouncer 1.21 и прорыв с prepared statements

До марта 2024 года операционный компромисс звучал так: transaction mode (мультиплексирование 10–100×) ИЛИ prepared statements (10–30% прирост пропускной способности на повторяющихся запросах) — не оба вместе.

Почему они конфликтовали: prepared statements на уровне проводного протокола Postgres привязывают именованный оператор к конкретной backend-сессии (PrepareStatement/PQprepare → слот на том backend’е). PgBouncer в transaction mode направляет следующий EXECUTE на любой свободный backend — если это другой backend, оператор там неизвестен. Драйверы случайным образом возвращали ошибку prepared statement does not exist. Обходное решение: отключить prepared statements на уровне драйвера — теряя выигрыш в производительности.

Что исправил PgBouncer 1.21 (март 2024): отслеживание prepared statements на уровне протокола. PgBouncer перехватывает wire-сообщения Parse/Bind/Execute, ведёт глобальный реестр на логического клиента и повторно подготавливает на любом назначенном backend’е. Приложение видит согласованное поведение prepared statements при всех checkout’ах пула.

Требует max_prepared_statements > 0 (типично: 1000) в pgbouncer.ini.

PostgreSQL 17 (сентябрь 2024) добавил DEALLOCATE на уровне протокола, позволяя PgBouncer чисто закрывать prepared statements на backend’е при отключении клиента — устраняя утечку ресурсов.

В 2026 году production-дефолт: PgBouncer 1.21+ + max_prepared_statements = 1000 + prepared statements под управлением драйвера + transaction mode. Все три выигрыша одновременно. Командам на PgBouncer 1.20 или старше следует обновиться в следующем окне обслуживания.

Проверка стека

Команде, переходящей на transaction mode + prepared statements в 2026 году, следует проверить:

1. Версия PgBouncer: 1.21.0 или новее. Проверить через pgbouncer -V или SHOW VERSION в admin-консоли.
2. max_prepared_statements: ненулевое значение в pgbouncer.ini (типично: 1000). Проверить через SHOW CONFIG.
3. Версия Postgres: 14+ для стабильной работы; 17+ для DEALLOCATE на уровне протокола.
4. Поведение драйвера: убедиться, что используются prepared statements на уровне протокола (JDBC prepareThreshold > 0, node-postgres аргумент name:, pgx Prepare, asyncpg — все по умолчанию используют prepared).
5. Нагрузочный тест: нагрузить prepared-запросами 30 минут; проверить логи PgBouncer на ошибки “prepared statement does not exist”.