Объяснение пула транзакций PgBouncer

PgBouncer предлагает три режима, которые отличаются только тем, когда соединение с сервером Postgres возвращается в общий пул. В официальной документации они называются session, transaction и statement (pgbouncer.org/features.html, раздел «Режимы объединения», по состоянию на 24 августа 2026 г.).

Сеансовый режим является наиболее разрешающим, но наименее эффективным с точки зрения масштабируемости: соединение Postgres остается зарезервированным для клиента до тех пор, пока оно остается подключенным, даже если между двумя запросами оно ничего не делает. Режим операторов зарезервирован для очень специфических случаев (прокси-сервер только для чтения, проверки работоспособности) и даже нарушает классические явные транзакции. Режим транзакций — это компромисс, который на практике доминирует в REST API: каждый HTTP-запрос обычно соответствует одной короткой транзакции Postgres.

В режиме транзакции PgBouncer подключает соединение с сервером к клиенту только тогда, когда последний открывает транзакцию, и возвращает ее в пул при COMMIT или ROLLBACK. Между двумя транзакциями один и тот же клиент может быть переназначен на совершенно другое соединение с сервером.

Конкретно, с default_pool_size, равным 20, PgBouncer может одновременно обрабатывать несколько сотен клиентов, у которых в любой момент времени фактически выполняются только несколько транзакций. Именно это соотношение оправдывает режим транзакций для REST API с высоким трафиком, но короткими транзакциями: редкий ресурс (соединение Postgres, требующее больших затрат памяти на стороне сервера) занят только на строго необходимое время.

[pgbouncer]
listen_port = 5432

; La connexion serveur est libérée dès la fin de chaque transaction
pool_mode = transaction

default_pool_size = 80
max_client_conn = 1000

; Ne pas utiliser avec des sessions stateful (SET, advisory locks, LISTEN/NOTIFY)

Этот последний комментарий суммирует суть: режим транзакций работает, потому что он намеренно разрывает связь между «сеансом моего приложения» и «моим соединением Postgres». Все, что основано на этой ссылке, ломается. В следующем разделе перечислено именно то, что именно.

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

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

Подготовленный протоколом оператор получает имя и кэшируется на определенном соединении с сервером во время Parse. В режиме транзакции это соединение можно переназначить другому клиенту между двумя запросами от одного и того же логического клиента. Если драйвер затем воспроизводит то же имя оператора в соединении, где оно никогда не было подготовлено, Postgres отвечает явной ошибкой, обычно prepared statement "sqlx_s_N" does not exist для клиента sqlx. Поведение прерывистое: оно зависит от того, как соединения работают под нагрузкой, а не от детерминированной ошибки, воспроизводимой при каждом вызове.

Исправление на стороне клиента одинаково, независимо от языка: отключите кеш именованных подготовленных операторов или принудительно задайте неименованные запросы для любого пула, который пересекает средство объединения в режиме транзакций. В Rust с sqlx в параметрах подключения он проходит через statement_cache_capacity(0).

let connect_options = url
    .parse::<PgConnectOptions>()?
    .statement_cache_capacity(0);

// Эквиваленты: asyncpg ->statement_cache_size=0, pgjdbc ->preparThreshold=0.

Начиная с версии 1.21, PgBouncer частично устраняет проблему на стороне сервера: он может следовать подготовленным протоколом операторам в режиме транзакций и готовить их на лету в назначенном соединении с LRU-кешем для каждого соединения, размер которого настраивается с помощью max_prepared_statements. Это уменьшает количество промахов, но не освобождает вас от отключения кэша клиента в многотенантном пуле, где search_path меняется от одного запроса к другому: кэшированный план замораживает внутренний идентификатор (OID) разрешенной таблицы во время Parse, и его воспроизведение в другой схеме может вернуть данные не от того клиента, а не простую ошибку.

Репозиторий Aurabase развертывает PgBouncer как pool_mode=transaction перед общей плоскостью данных (deploy/helm/aurabase/templates/infra/pgbouncer.yaml) и идентично настроенный Pooler CNPG перед каждым выделенным экземпляром Postgres клиента (deploy/cnpg/tenant-pooler.yaml). Оба пути применяют одну и ту же дисциплину, описанную выше.

В исходном коде указана конкретная причина этого выбора, связанная с безопасностью, а не только причина стабильности. Пулы Postgres, совместно используемые арендаторами, размещают разные search_path для каждого проекта в повторно используемых соединениях. Кэшированный подготовленный оператор замораживает OID разрешенной таблицы во время Parse; воспроизведение его для другого арендатора в том же соединении приведет к запуску запроса к схеме первого арендатора, что является обходом изоляции, а не просто ошибкой приложения. Таким образом, statement_cache_capacity(0) применяется без исключения, в том числе к выделенным экземплярам, ​​которые также проходят через пул CNPG в режиме транзакций.

Вторая мера гигиены сеанса: когда каждое соединение возвращается в пул, перехват выполняет DISCARD ALL (сброс настроек, освобождение подготовленных операторов на стороне сервера, снятие консультативных блокировок, очистка курсоров и временных таблиц). Без этого перехватчика остаток сеанса, созданный предыдущим запросом, может просочиться при следующем запросе от другого клиента, повторно использующего то же переработанное соединение.

Принимается исключение: выделенные экземпляры PostgREST остаются в прямом соединении с основным, минуя пул. Перезагрузка схемы PostgREST опирается на LISTEN/NOTIFY, который предполагает постоянное соединение, а это именно та функциональность, которую нарушает режим транзакций (подробности уже описаны в нашей статье о совместимости PostgREST на Aurabase). Параметры RLS для каждого запроса передаются в SET LOCAL в рамках явной транзакции. Это единственный способ сохранить совместимость с пулом, который может изменять подключения к серверу при любом COMMIT (см. нашу статью о мультитенантной изоляции RLS).

Краткий контрольный список, применимый к любому бэкэнду, переходящему с прямого соединения Postgres на PgBouncer в режиме транзакции.

1. Проведите аудит кода приложения. Ищите нетранзакционные SET, LISTEN/NOTIFY, консультативные блокировки сеанса, курсоры WITH HOLD и временные таблицы, повторно используемые между запросами.
2. Замените сеансовые SET на LOCAL SET в рамках явной транзакции. Это единственный параметр, который правильно выдерживает перезапуск соединения, поскольку он очищается при COMMIT/ROLLBACK, а не теряется при следующем соединении.
3. Отключите кэш подготовленных операторов на стороне драйвера, если ваш пул проходит через средство объединения и схема или роль изменяются от одного запроса к другому. Затраты на производительность реальны, но измеримы и намного ниже, чем риск утечки информации между арендаторами.
4. Изолируйте соединения, которым действительно нужен режим сеанса (миграции, сценарии администратора и все, что зависит от LISTEN/NOTIFY), прямым соединением без объединения в пул, а не отказывайтесь от режима транзакций для всего остального трафика.
5. Размер default_pool_size и max_client_conn относительно фактического max_connectionsPostgres, а не произвольной цифры, скопированной из другого проекта.
6. Тестируйте под реальной нагрузкой, а не просто дымовым тестом. Ошибки подготовленных операторов и утечки настроек сеанса практически никогда не возникают при одном локальном соединении.
7. Мониторинг SHOW POOLS и SHOW STATS из консоли администрирования PgBouncer после запуска в производство, чтобы определить насыщение пула до того, как оно станет видимым на стороне клиента.

Нет, но это правильный выбор по умолчанию для подавляющего большинства REST API. Режим сеанса остается предпочтительным для устаревшего приложения, сильно зависящего от функций сеанса, которые невозможно быстро реорганизовать, или для низкого трафика, когда выигрыш от объединения не компенсирует усилия по миграции.

PgBouncer — не единственная реализация этой модели объединения: Supavisor (Supabase) и PgCat — две недавние альтернативы с разными компромиссами в распределении нагрузки и кластеризации. См. наше подробное сравнение PgBouncer, Supavisor и PgCat, чтобы выбрать один из трех в зависимости от вашей топологии.

Вопросы, которые возникают чаще всего после активации режима транзакций в рабочей среде.