Все заметки
Программирование

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 каждое соединение — это отдельный процесс ОС. Когда клиент подключается, происходит следующее:

  1. TCP handshake, а с включённым TLS ещё и TLS handshake.
  2. Аутентификация: для scram-sha-256 это несколько обменов сообщениями и вычисления.
  3. postmaster делает fork() нового backend-процесса.
  4. Новый процесс заполняет кэши каталога с нуля: первые запросы заново читают метаданные таблиц и индексов.

Всё это происходит до выполнения вашего запроса. К тому же каждое открытое соединение занимает память, даже простаивая, а 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 = True Django перед повторным использованием в начале запроса проверяет, живо ли соединение. Это спасает первый запрос после рестарта базы от ошибки «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» почти всегда результат масштабирования без арифметики.

// комментарии

Загружаем комментарии...

    // следующий шаг

    Давайте построим что-нибудь вместе.

    Написать в Telegram
    aslbek@asldev: ~
    ❯