Не увеличивайте pool_size сразу после сообщения «timeout acquiring connection». Свободный CPU не означает свободные подключения: транзакция может ждать внешний API, сессия — стоять idle in transaction, а десятки процессов — держать собственные пулы про запас. Сначала сопоставьте метрику ожидания пула в приложении со снимком pg_stat_activity в ту же минуту.

У PostgreSQL max_connections ограничивает число одновременных подключений, а увеличение параметра требует больше ресурсов, включая shared memory. Это потолок инстанса, а не рекомендуемый размер каждого пула. Если восемь pod по четыре worker создают pool_size=20, теоретический спрос уже равен 640 соединениям без миграций, cron и администраторов.

Снимок активности отвечает, кто держит места

SELECT application_name, state, wait_event_type, wait_event,
       count(*) AS sessions,
       max(now() - xact_start) AS oldest_xact,
       max(now() - state_change) AS oldest_state
FROM pg_stat_activity
WHERE datname = current_database()
  AND pid <> pg_backend_pid()
GROUP BY application_name, state, wait_event_type, wait_event
ORDER BY sessions DESC, oldest_xact DESC NULLS LAST;

pg_stat_activity показывает по одному ряду на серверный процесс, включая state, wait_event, query_start и xact_start. Для инцидента достаточно агрегатов и application_name; полный query text может содержать чувствительные параметры и не нужен в публичном отчёте. Особое внимание уделите долгому idle in transaction: запрос уже не работает, но транзакция остаётся открытой и соединение занято.

Одинаковый timeout скрывает разные механизмы

НаблюдениеВероятная причинаПроверка
Pool wait растёт, active почти нетСлишком много idle или утечка leaseChecked-out duration и stack owner
Много idle in transactionТранзакция открыта вокруг лишней работыxact_start и путь запроса
Active ждут LockБлокировка, а не малый poolwait_event и blocking PID
Только один pod исчерпал poolЛокальная утечка или skew трафикаМетрики по instance ID
После scale-out стало хужеКаждая реплика добавила новый poolСумма configured max по процессам
Ошибка во время deployСтарые и новые pod живут одновременноSurge replicas и shutdown grace

Смотрите минимум четыре метрики приложения: in_use, idle, pending acquire и acquisition duration. К ним добавьте hold duration — время от выдачи соединения до возврата. Высокий p95 hold duration объясняет очередь лучше, чем среднее время SQL: соединение может удерживаться при сериализации ответа, логировании или вызове другого сервиса.

Бюджет считается сверху вниз

db_budget = max_connections - reserved - admin - migrations - background_jobs

service_budget = db_budget * agreed_share
per_process_pool = floor(service_budget / (replicas * processes_per_replica))

example:
max_connections 200, reserve 20, service share 50%
8 replicas * 2 processes => floor(90 / 16) = 5 connections per process

Оставляйте резерв для аварийного входа и служебных задач, иначе расследовать насыщенную базу будет нечем. При rolling deploy учитывайте максимальное одновременное число старых и новых реплик. Если сервисов несколько, доли фиксируются явно; надежда, что все пулы не заполнятся одновременно, перестаёт работать ровно во время общей деградации.

Уменьшить удержание полезнее, чем купить очередь побольше

  • Открывайте транзакцию непосредственно перед SQL и завершайте до HTTP-вызова, публикации сообщения или тяжёлой сериализации.
  • Возвращайте соединение в finally или используйте scoped API, которое закрывает lease при любом исключении.
  • Задайте конечный acquisition timeout и ограниченную очередь, чтобы перегрузка проявлялась как контролируемая ошибка.
  • Присвойте разным сервисам application_name и добавьте instance ID в метрики пула.
  • Разберите долгие locks и queries отдельно: новый connection не ускоряет транзакции, ожидающие один и тот же ресурс.
  • idle_in_transaction_session_timeout используйте как страховку после анализа совместимости с pooling middleware, а не вместо исправления кода.

PostgreSQL отдельно предупреждает, что принудительное завершение idle-сессий может неожиданно работать с middleware или pooling layer. Таймаут полезен против забытых транзакций, но сначала найдите владельца и сократите область transaction. Иначе приложение продолжит держать соединения, только теперь будет получать внезапные разрывы.

Исправление проходит проверку очередью

  1. Воспроизведите обычный и пиковый трафик с известным числом реплик и процессов.
  2. Проверьте, что сумма настроенных pool maxima не превышает согласованный бюджет даже во время rolling update.
  3. Снимите распределение acquisition и hold duration и убедитесь, что pending queue возвращается к нулю.
  4. Искусственно задержите один SQL и подтвердите: очередь ограничена, timeout понятен, соединения после отмены возвращаются.
  5. Повторите исключение внутри транзакции и проверьте отсутствие нового idle in transaction в pg_stat_activity.

Нормальный результат не обязан использовать все подключения. Цель пула — повторное использование ограниченного ресурса, а не заполнение max_connections. Если после исправления CPU вырос, а latency и очередь уменьшились, это может быть хорошим признаком: база наконец выполняет работу вместо обслуживания множества простаивающих сессий.

Проверенные источники