DEV Community

sizan mahmud0
sizan mahmud0

Posted on

Django + PostgreSQL Connection Pooling: CONN_MAX_AGE, Native Pool, and PgBouncer

How to avoid 'too many clients already' with persistent connections, Django 5.1's native pool, and PgBouncer.

If you've seen FATAL: sorry, too many clients already, you've run out of PostgreSQL connections. Here are the three ways to deal with it in Django.

Why it happens

PostgreSQL runs one OS process per connection, so connections are expensive to open and expensive to keep in large numbers. Django's default (CONN_MAX_AGE = 0) opens a connection per request.

1. Persistent connections

DATABASES = {
    "default": {
        # ...
        "CONN_MAX_AGE": 60,
        "CONN_HEALTH_CHECKS": True,
    }
}
Enter fullscreen mode Exit fullscreen mode
  • Reuse, not a true pool
  • One connection per thread, held even when idle
  • Not recommended for ASGI

2. Native pool (Django 5.1+, psycopg 3)

pip install "psycopg[binary,pool]"
Enter fullscreen mode Exit fullscreen mode
DATABASES = {
    "default": {
        # ...
        "CONN_MAX_AGE": 0,  # must be 0 with the pool
        "OPTIONS": {
            "pool": {
                "min_size": 2,
                "max_size": 10,
                "timeout": 10,
                "max_lifetime": 1800,
                "max_idle": 300,
            },
        },
    }
}
Enter fullscreen mode Exit fullscreen mode
  • The pool is per process: 8 workers × max_size 10 = up to 80 connections
  • Doesn't cap the total across servers

3. PgBouncer

[pgbouncer]
pool_mode = transaction
max_client_conn = 1000
default_pool_size = 20
reserve_pool_size = 5
Enter fullscreen mode Exit fullscreen mode
DATABASES = {
    "default": {
        # ...
        "PORT": "6432",
        "CONN_MAX_AGE": 0,
        "DISABLE_SERVER_SIDE_CURSORS": True,
    }
}
Enter fullscreen mode Exit fullscreen mode

Transaction pooling gotchas

Feature Problem Alternative
Server-side cursors Live on one server connection DISABLE_SERVER_SIDE_CURSORS = True
pg_advisory_lock Session-level pg_advisory_xact_lock
LISTEN / NOTIFY Needs a stable session Direct connection
Session SET May not stick SET LOCAL or per-role config
Prepared statements Can fail on older PgBouncer PgBouncer 1.21+, or psycopg prepare_threshold: None
Temp tables Session-scoped Avoid, or use a direct connection

Sizing

total app connections =
    (web processes × pool max_size)
  + (celery processes × connections each)
  + cron, admin tools, migrations, monitoring
Enter fullscreen mode Exit fullscreen mode

Keep that under max_connections, with headroom.

Monitor it

SELECT state, count(*) FROM pg_stat_activity GROUP BY state;
SHOW max_connections;
Enter fullscreen mode Exit fullscreen mode

Watch for many idle in transaction connections, and consider idle_in_transaction_session_timeout.

Which to choose

Situation Approach
Small app CONN_MAX_AGE + health checks
Single server, Django 5.1+ Native pool
ASGI Native pool or PgBouncer
Many web servers + Celery PgBouncer (transaction mode)

Full guide

The complete post covers Celery connection usage, pool sizing, monitoring, a checklist, and an FAQ:

👉 https://blog.reiteachaigean.com/blog/django-database-connection-pooling-postgresql

Related reads:

What's your pooling setup in production?

Top comments (0)