Database connection timeout with Django CONN_MAX_AGE

Answer

For a deployment handling ~500 concurrent requests, set CONN_MAX_AGE to a moderate value that keeps the number of idle DB connections roughly equal to your Django worker count (e.g., 10–30 seconds). This limits latency spikes caused by connection‑creation overhead while avoiding exhaustion of PostgreSQL’s max_connections.

Confirmed facts

• Django’s default CONN_MAX_AGE is 0, meaning each request opens and closes a new connection.
• A positive CONN_MAX_AGE enables persistent connections that are reused until the specified age elapses.
• Opening a new connection incurs TCP handshake and authentication overhead, which adds measurable latency under high concurrency.

Likely explanation

When CONN_MAX_AGE is too low (0), every request pays the connection‑setup cost, raising latency. When it is too high, idle connections accumulate; if the total (active + idle) approaches PostgreSQL’s max_connections, new requests block waiting for a free slot, producing latency spikes. A moderate age lets connections be reused for the burst of requests from each worker, then released before they idle long enough to threaten the connection limit.

Steps to apply

1. Determine your Django worker count (e.g., Gunicorn --workers or uvicorn workers).
2. Check PostgreSQL’s max_connections setting (SHOW max_connections;).
3. Choose CONN_MAX_AGE in the range 10–30 seconds. Start with 20 seconds and monitor.
4. Deploy the change (restart workers) and observe latency percentiles (p95/p99) under load.
5. If idle connections frequently approach max_connections, lower CONN_MAX_AGE; if connection‑setup latency dominates, raise it slightly.

Missing diagnostic detail

To refine the recommendation, please confirm your actual Django worker count and the PostgreSQL max_connections value. If the worker count is a significant fraction of max_connections, a lower CONN_MAX_AGE (e.g., ≤ 10 s) may be needed; otherwise the 10–30 s range is appropriate.