re:re:actable
Урок 113 минуты чтения

Что такое пул соединений и как с ним работать

На этой странице
Кратко

Соединение с PostgreSQL дорогое: каждое — отдельный процесс сервера (несколько МБ памяти), установка занимает миллисекунды (TCP, TLS, аутентификация), а max_connections обычно около 100–500. Пул соединений держит набор открытых соединений и выдаёт их запросам на время работы, вместо того чтобы открывать новое на каждый запрос. Пулы бывают в приложении (pg.Pool, пул Prisma, TypeORM) и внешние (PgBouncer, pgcat, Supavisor, RDS Proxy) — последние нужны, когда инстансов приложения много или это serverless-функции, каждая из которых иначе открывала бы свои соединения. В режиме transaction pooling соединение закрепляется за клиентом только на время транзакции, что резко уменьшает число серверных соединений, но ломает сессионное состояние: SET без LOCAL, сессионные advisory locks, LISTEN, временные таблицы (prepared statements PgBouncer поддерживает с версии 1.21).

Вопрос

Что такое пул соединений, зачем он нужен и как его настроить?

Пул в приложении

import { Pool } from "pg";
 
export const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  max: 10,                       // соединений на инстанс
  idleTimeoutMillis: 30_000,
  connectionTimeoutMillis: 5_000,
});
 
// простой запрос — соединение берётся и возвращается автоматически
await pool.query("SELECT * FROM users WHERE id = $1", [id]);
 
// транзакция — одно соединение, обязательно release
const client = await pool.connect();
try {
  await client.query("BEGIN");
  // ...
  await client.query("COMMIT");
} catch (e) {
  await client.query("ROLLBACK");
  throw e;
} finally {
  client.release();
}

Пул создаётся один раз на процесс, а не на каждый запрос.

Размер пула

суммарно соединений = инстансов × размер пула ≤ max_connections − резерв
пример: 8 подов × 10 = 80 при max_connections = 100

Больше — не значит быстрее: у сервера ограничено число ядер и дисков, и сотни одновременно активных запросов конкурируют друг с другом. Хорошая отправная точка — несколько активных соединений на ядро CPU базы; остальные запросы ждут в очереди пула.

Serverless и внешний пул

Vercel / Lambda: 500 параллельных функций × свой пул → 500+ соединений → "too many connections"
 
Функции → PgBouncer (transaction mode) → 20 соединений → PostgreSQL
# Prisma за PgBouncer
DATABASE_URL="postgresql://app@pgbouncer:6432/shop?pgbouncer=true&connection_limit=1"
DIRECT_URL="postgresql://app@db:5432/shop"     # для миграций — напрямую

Облачные провайдеры (Supabase, Neon, RDS Proxy) предоставляют пулер «из коробки» — в serverless используют его адрес.

Режимы PgBouncer

РежимСоединение закрепленоОграничения
sessionНа всю сессию клиентаПочти нет, но экономия небольшая
transactionНа время транзакцииНет сессионного состояния: SET (используйте SET LOCAL), LISTEN, сессионные advisory locks, temp-таблицы
statementНа один операторНельзя многооператорные транзакции

Проблемы и диагностика

SELECT state, count(*) FROM pg_stat_activity GROUP BY state;
-- active / idle / idle in transaction
СимптомПричина
too many connectionsСумма пулов > max_connections, serverless без пулера
Таймаут получения соединенияПул исчерпан: медленные запросы, утечка (не вызван release)
Много idle in transactionТранзакции не закрываются, внешние вызовы внутри транзакции
Настройка «пропала»SET в transaction pooling ушёл на другое соединение

Частые ошибки

  • Новый Pool или PrismaClient на каждый запрос (или на каждый hot reload в dev).
  • Забыть client.release() — пул «утекает».
  • Огромный max в каждом инстансе.
  • Миграции через PgBouncer в transaction mode — используйте прямое подключение.

Что важно помнить

  • Соединения дорогие и ограничены; пул их переиспользует.
  • Суммарный размер всех пулов должен помещаться в max_connections.
  • Serverless и много инстансов → внешний пулер в transaction mode.

Мини-шпаргалка

  • new Pool({ max }) — один на процесс.
  • pool.connect() + release() для транзакций.
  • PgBouncer: pool_mode = transaction.
  • SET LOCAL вместо SET.
  • pg_stat_activity — состояние соединений.

Документация

node-postgres: Pooling, PgBouncer: Features, Prisma: Connection pool.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам