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,
}
}
- 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]"
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,
},
},
}
}
- The pool is per process: 8 workers ×
max_size10 = 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
DATABASES = {
"default": {
# ...
"PORT": "6432",
"CONN_MAX_AGE": 0,
"DISABLE_SERVER_SIDE_CURSORS": True,
}
}
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
Keep that under max_connections, with headroom.
Monitor it
SELECT state, count(*) FROM pg_stat_activity GROUP BY state;
SHOW max_connections;
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:
- Process 5 Million Records with Django and Celery
- Django ORM Optimization for Millions of Records
- Celery: How to Prevent Duplicate Task Execution
What's your pooling setup in production?
Top comments (0)