Connection pooling: «too many clients», CONN_MAX_AGE, psycopg pool и PgBouncer
Вы увеличили число подов с 4 до 16, а PostgreSQL ответил «too many clients». Почему соединение дорогое, как им управляет Django и когда нужен CONN_MAX_AGE, psycopg pool или PgBouncer.
Представьте день распродажи. Трафик растёт, и вы увеличиваете число подов с gunicorn с 4 до 16. Через пару минут в логах одна и та же ошибка:
psycopg.OperationalError: connection failed: FATAL: sorry, too many clients already
База не тормозит, CPU свободен. Проблема не в запросах, а в количестве соединений. Каждый под принёс с собой новые соединения к PostgreSQL, и сервер упёрся в max_connections. Масштабирование не ускорило приложение, а положило его.
Разберём, почему соединение дорогое, как Django им управляет, и три инструмента: CONN_MAX_AGE, psycopg pool из Django 5.1 и PgBouncer. В конце посчитаем max_connections.
Почему соединение дорогое
В PostgreSQL каждое соединение — это отдельный процесс ОС. Когда клиент подключается, происходит следующее:
- TCP handshake, а с включённым TLS ещё и TLS handshake.
- Аутентификация: для
scram-sha-256это несколько обменов сообщениями и вычисления. postmasterделаетfork()нового backend-процесса.- Новый процесс заполняет кэши каталога с нуля: первые запросы заново читают метаданные таблиц и индексов.
Всё это происходит до выполнения вашего запроса. К тому же каждое открытое соединение занимает память, даже простаивая, а max_connections задаётся при старте сервера, и для его изменения нужен рестарт.
Цену легко измерить на своём сервере. Флаг -C у pgbench открывает новое соединение на каждую транзакцию:
# one-time: create test tables
pgbench -i -s 10 shop
# 1) connections are kept open for the whole run
pgbench -S -c 10 -j 2 -T 30 shop
# 2) -C: a NEW connection for every transaction
pgbench -S -c 10 -j 2 -T 30 -C shop
Сравните tps в двух прогонах. Разница — это и есть стоимость подключения. Если база на другом хосте и за TLS, разница будет ещё заметнее. Конкретные цифры зависят от сети и конфигурации, поэтому меряйте у себя.
Что Django делает по умолчанию
По умолчанию CONN_MAX_AGE = 0. Django открывает новое соединение при первом обращении ORM к базе в рамках HTTP-запроса и закрывает его по окончании запроса (сигнал request_finished).
То есть на странице, которая отдаётся за 200 мс, каждый раз повторяется открытие и закрытие соединения. В маленьком проекте этого не видно. Но с ростом нагрузки заметная доля времени уходит не на полезную работу, а на handshake, а PostgreSQL постоянно форкает новые процессы и убивает старые.
Вторая проблема — число соединений никто не контролирует. Каждый воркер, каждый поток, каждый процесс Celery открывает своё. Добавили поды — соединений стало линейно больше.
CONN_MAX_AGE: постоянные соединения
Первое и самое простое решение — не закрывать соединение после запроса.
# settings.py
import os
DATABASES = {
"default": {
"ENGINE": "django.db.backends.postgresql",
"NAME": "shop",
"USER": "shop",
"PASSWORD": os.environ["DB_PASSWORD"],
"HOST": "127.0.0.1",
"PORT": "5432",
"CONN_MAX_AGE": 60, # keep the connection for up to 60 s
"CONN_HEALTH_CHECKS": True, # ping it before reusing (Django 4.1+)
}
}
Как это работает:
- Соединение привязано к потоку. Каждый поток держит своё одно соединение.
- В начале и в конце каждого запроса Django вызывает
close_old_connections(): если соединение старшеCONN_MAX_AGEили находится в ошибочном состоянии, оно закрывается. CONN_MAX_AGE = Noneозначает «без ограничения»: соединение живёт, пока жив воркер.- С
CONN_HEALTH_CHECKS = TrueDjango перед повторным использованием в начале запроса проверяет, живо ли соединение. Это спасает первый запрос после рестарта базы от ошибки «server closed the connection».
Ограничение CONN_MAX_AGE в том, что это не пул. Он лишь продлевает жизнь схеме «один поток — одно соединение». Gunicorn-воркер с 8 потоками постоянно держит 8 соединений, даже если они ничего не делают. Общее число соединений всё так же растёт по формуле воркеры × потоки × поды.
Django 5.1+: psycopg pool
Начиная с Django 5.1 бэкенд PostgreSQL поддерживает настоящий пул соединений через psycopg 3. Пул один на процесс, потоки берут из него соединение, используют и возвращают.
pip install "psycopg[binary,pool]"
# settings.py (Django 5.1+, psycopg 3)
DATABASES = {
"default": {
"ENGINE": "django.db.backends.postgresql",
"NAME": "shop",
"USER": "shop",
"PASSWORD": os.environ["DB_PASSWORD"],
"HOST": "127.0.0.1",
"PORT": "5432",
# CONN_MAX_AGE stays 0: the pool replaces persistent connections
"OPTIONS": {
"pool": {
"min_size": 2, # opened up front, per process
"max_size": 8, # hard cap per process
"timeout": 10, # seconds to wait for a free connection
},
},
}
}
Механика:
"pool": Trueсоздаёт пул с настройками по умолчанию, а словарь передаётся аргументами вpsycopg_pool.ConnectionPool.- Пул создаётся лениво — при первом обращении к базе в процессе.
- В конце запроса Django «закрывает» соединение, а на деле возвращает его в пул.
- Если все
max_sizeсоединений заняты, новый запрос ждёт доtimeoutсекунд, после чего получаетPoolTimeout. Это полезная ошибка: она показывает нехватку соединений на уровне приложения задолго до «too many clients» от PostgreSQL. - Пул нельзя сочетать с
CONN_MAX_AGE: это два способа решить одну задачу, и Django такую конфигурацию не примет. ОставьтеCONN_MAX_AGEравным 0.
Когда пул даёт больше всего? Когда в одном процессе много потоков (gunicorn gthread, ASGI) и они обращаются к базе не одновременно, а по очереди. У синхронного gunicorn-воркера один поток, значит max_size больше 1 — это лишние соединения. Там главная польза пула — переиспользование, а min_size стоит держать маленьким.
PgBouncer: делим соединения между процессами
И пул Django, и CONN_MAX_AGE работают внутри одного процесса. 16 подов по 4 процесса с max_size=8 в худшем случае дают 512 соединений. Процессы не умеют делиться соединениями друг с другом.
PgBouncer решает это, вставая между приложением и PostgreSQL. Приложение открывает тысячи дешёвых соединений к PgBouncer, а он раскладывает их по небольшому числу настоящих серверных соединений.
; /etc/pgbouncer/pgbouncer.ini
[databases]
shop = host=127.0.0.1 port=5432 dbname=shop
[pgbouncer]
listen_addr = 127.0.0.1
listen_port = 6432
auth_type = scram-sha-256
auth_file = /etc/pgbouncer/userlist.txt
pool_mode = transaction
max_client_conn = 2000 ; client connections PgBouncer accepts
default_pool_size = 20 ; real server connections per db/user pair
max_prepared_statements = 100
# settings.py: Django talks to PgBouncer, not to PostgreSQL directly
DATABASES["default"].update({
"PORT": "6432",
"CONN_MAX_AGE": 60, # cheap: this is a PgBouncer connection
"CONN_HEALTH_CHECKS": True,
"DISABLE_SERVER_SIDE_CURSORS": True, # .iterator() must not use named cursors
})
У PgBouncer три режима:
| Режим | Когда клиент получает серверное соединение | Состояние сессии | Эффективность |
|---|---|---|---|
session |
На всё время подключения клиента | Сохраняется полностью | Низкая: почти не отличается от пула Django |
transaction |
Только на время одной транзакции | Не сохраняется | Высокая: обычный выбор |
statement |
На один statement | Не сохраняется, многостейтментные транзакции не работают | Для Django не подходит |
В transaction mode соединение Django идёт к PgBouncer и стоит дёшево, поэтому CONN_MAX_AGE здесь использовать можно и нужно.
Ограничения transaction mode
Главное правило transaction mode: между двумя транзакциями вы можете оказаться на другом серверном соединении. Значит, любое состояние уровня сессии становится ненадёжным.
В transaction mode надёжно только то, что живёт внутри одной транзакции. Всё остальное —
SET, advisory lock, временные таблицы,LISTEN— может остаться на другом соединении к следующему запросу.
Django работает в режиме autocommit: каждый запрос вне atomic() — отдельная транзакция. Классическая ошибка:
from django.db import connection
from orders.models import Order
# WRONG behind PgBouncer in transaction mode
def heavy_report():
with connection.cursor() as cur:
cur.execute("SET statement_timeout = '2s'")
# autocommit: the SET has already finished its own transaction,
# the next query may go to a different server connection
return list(Order.objects.filter(status="paid").values("id", "amount"))
SET может остаться на другом серверном соединении и, что хуже, повлиять на чужой запрос, который получит это соединение потом. Правильный вариант:
from django.db import connection, transaction
from orders.models import Order
# RIGHT: SET LOCAL lives exactly as long as the transaction
def heavy_report():
with transaction.atomic():
with connection.cursor() as cur:
cur.execute("SET LOCAL statement_timeout = '2s'")
return list(Order.objects.filter(status="paid").values("id", "amount"))
# Same idea for advisory locks: transaction-level, not session-level
def charge_once(order_id: int) -> None:
with transaction.atomic():
with connection.cursor() as cur:
cur.execute("SELECT pg_advisory_xact_lock(%s)", [order_id])
... # the lock is released automatically on COMMIT/ROLLBACK
Другие ограничения:
- Серверные курсоры.
QuerySet.iterator()в PostgreSQL открывает именованный курсор. В autocommit Django использует курсорWITH HOLD, который переживает транзакцию и может оказаться на другом соединении. Поэтому ставятDISABLE_SERVER_SIDE_CURSORS = True. Тогдаiterator()не стримит результат порциями через psycopg, но всё равно экономит память, потому что объекты моделей создаются частями. - Prepared statements. С psycopg 3 Django по умолчанию использует client-side binding: параметры подставляются в текст запроса на клиенте, серверных prepared statements не создаётся. Если включить в
OPTIONS"server_side_binding": True, psycopg начнёт подготавливать запросы на сервере, и с transaction mode начнутся проблемы. PgBouncer начиная с 1.21 умеет отслеживать prepared statements уровня протокола черезmax_prepared_statements, но SQL-уровневыеPREPARE/EXECUTEпо-прежнему не работают. Надёжнее всего оставить server-side binding выключенным. LISTEN/NOTIFY, временные таблицы,pg_advisory_lock(сессионная версия) через transaction mode надёжно не работают. Для них заведите отдельное прямое соединение в обход PgBouncer.- Миграции. Они могут брать долгие блокировки и использовать
SET. Обычноmigrateзапускают с прямым подключением к PostgreSQL (5432).
Пул в ASGI и async
В async-представлениях Django вызовы ORM выполняются в потоке через sync_to_async. Документация Django рекомендует под ASGI отключать постоянные соединения (CONN_MAX_AGE) и использовать вместо них пул: в async-окружении сложно контролировать, в каком потоке остаётся соединение, и они могут копиться незакрытыми.
# views.py: async view, ORM behind a pool
from django.http import JsonResponse
from orders.models import Order
async def my_orders(request):
user = await request.auser()
orders = [
{"id": o.id, "amount": str(o.amount)}
async for o in Order.objects.filter(user=user).order_by("-id")[:20]
]
return JsonResponse({"orders": orders})
Практическая схема для ASGI:
CONN_MAX_AGE = 0плюсOPTIONS["pool"]или внешний PgBouncer.max_sizeвыбирайте не по числу параллельных запросов в event loop, а по числу параллельных обращений к базе. Один процесс uvicorn может держать сотни запросов, но если они одновременно пойдут в базу, пул заполнится и посыплетсяPoolTimeout. И это хорошо: это backpressure, который защищает базу.- Не держите соединение всю сессию в долгоживущем стриме или websocket-обработчике.
Считаем max_connections
Теперь главный вопрос: сколько соединений нужно?
SHOW max_connections;
SHOW superuser_reserved_connections;
-- who is holding connections right now
SELECT usename, application_name, state, count(*)
FROM pg_stat_activity
WHERE backend_type = 'client backend'
GROUP BY usename, application_name, state
ORDER BY count(*) DESC;
Выпишите всех потребителей:
| Потребитель | Формула |
|---|---|
| Web (CONN_MAX_AGE) | поды × воркеры × потоки |
| Web (пул Django) | поды × воркеры × max_size |
| Celery | воркеры × concurrency |
| Через PgBouncer | default_pool_size × число пар (db, user) |
| Прочее | migrate, cron, admin/psql, мониторинг, репликация |
Добавьте запас и проверьте, что сумма не превышает max_connections - superuser_reserved_connections. В PostgreSQL 16 появился ещё параметр reserved_connections, который резервирует слоты для роли pg_use_reserved_connections.
Важное наблюдение: просто поднять max_connections до 1000 — не решение. Каждый backend занимает память, а work_mem выделяется на каждую операцию отдельно. Кроме того, активных запросов сильно больше, чем ядер CPU, база быстрее не выполнит. Часто маленький пул с очередью работает быстрее большого. Это тоже можно измерить: увеличивайте -c в pgbench и смотрите на tps и latency.
Чтобы различать потребителей, задайте application_name:
DATABASES["default"]["OPTIONS"] = {
"application_name": "shop-web", # shows up in pg_stat_activity
"pool": {"min_size": 2, "max_size": 8, "timeout": 10},
}
Грабли в продакшене
- Celery. Интеграция Celery с Django вызывает
close_old_connectionsвокруг задач и учитываетCONN_MAX_AGE. Ноconcurrency=16— это 16 соединений, не забудьте их в расчёте. - Соединение до fork. gunicorn с
--preloadзагружает приложение в master-процессе. Если при импорте происходит обращение к базе, соединение или пул после fork окажутся общими для нескольких воркеров. Не трогайте ORM при импорте. - Висящие транзакции. Соединение в состоянии
idle in transactionзанимает и место в пуле, и серверное соединение в PgBouncer. Настройтеidle_in_transaction_session_timeout. - Двойной пул. Пул Django и PgBouncer могут работать вместе, но лимиты будут в двух местах. Мониторьте оба, чтобы понимать, где образуется очередь (
SHOW POOLS;в админ-консоли PgBouncer). - Долгие запросы. В transaction mode 30-секундный отчёт 30 секунд держит одно серверное соединение. Тяжёлые отчёты уводите в отдельный пул или на реплику.
Чеклист
- Измерьте стоимость подключения в своём окружении через
pgbench -C. - Обычный sync-проект:
CONN_MAX_AGE = 60+CONN_HEALTH_CHECKS = True. - Много потоков или ASGI на Django 5.1+:
OPTIONS["pool"],CONN_MAX_AGE = 0, маленькийmin_size. - Много подов и процессов: PgBouncer в transaction mode,
DISABLE_SERVER_SIDE_CURSORS = True. - В transaction mode:
SET LOCAL,pg_advisory_xact_lock, server-side binding выключен. - Для
migrateиLISTEN/NOTIFY— прямое соединение. - Сведите всех потребителей в таблицу и сверьте с
max_connections. - Задайте
application_nameи следите заpg_stat_activity.
Итог
Соединение с PostgreSQL — не дешёвый ресурс, а отдельный процесс. CONN_MAX_AGE убирает handshake, psycopg pool из Django 5.1 делит соединения внутри процесса, а PgBouncer — между всеми процессами кластера. Что бы вы ни выбрали, сначала посчитайте всех потребителей: «too many clients» почти всегда результат масштабирования без арифметики.
// комментарии
Загружаем комментарии...