Django REST Framework and PostgreSQL: Managing Connection Pool Exhaustion with CONN_MAX_AGE

The Short Answer

Django does not have a configurable internal connection pool size; it only supports connection persistence per process. To prevent exhaustion, you must use an external pooler like PgBouncer if your total worker count (processes × threads) exceeds PostgreSQL's max_connections. When using PgBouncer in transaction mode, CONN_MAX_AGE should be set to 0 (the default) to ensure connections are released back to the pool immediately after the request.

Persistence vs. Pooling

It is critical to distinguish between CONN_MAX_AGE and true connection pooling. CONN_MAX_AGE enables persistence: it tells a specific Django worker process to keep its single database connection open for a set duration. It does not allow workers to share a pool of connections.

Likely Exhaustion Scenario

In a high-traffic DRF environment using a multi-process server (like Gunicorn), the math is linear:
Total Connections = (Number of Worker Processes) × (Threads per Worker)

If you set CONN_MAX_AGE to a high value, every worker holds a slot in PostgreSQL even when idle. If your worker count exceeds the database max_connections limit, you will encounter too many clients already errors.

Implementation Strategies

Option A: Direct Connection (No PgBouncer)

Use this only for low-to-medium scale deployments where you can guarantee the worker count is well below max_connections.

• Set CONN_MAX_AGE to a low value (e.g., 60 seconds) to reduce handshake overhead without holding slots indefinitely.
• Ensure max_connections in postgresql.conf is higher than your total possible worker threads.

Option B: External Pooling (PgBouncer)

This is the standard for high-traffic DRF apps. PgBouncer sits between Django and PostgreSQL, multiplexing many application connections into a few database connections.

• PgBouncer Mode: Use transaction mode for maximum efficiency.
• Django Setting: Set CONN_MAX_AGE = 0. Since PgBouncer manages the pool, Django should close its connection to the proxy at the end of the request to allow the proxy to reassign that slot.

Verification

To verify current connection usage, run the following query on your PostgreSQL instance:

SELECT count(*), state FROM pg_stat_activity GROUP BY state;

If the number of idle connections matches your total worker count, CONN_MAX_AGE is effectively pinning those slots.

Missing Diagnostic: Are you using Gunicorn/uWSGI with a threaded or eventlet/gevent worker class? This significantly changes the number of concurrent connections generated per process.