Technologies/Django/db.client.connections.usage

DjangoMetric

db.client.connections.usage

Active database connections

Dimensions:None

Available on:

OpenTelemetry (1)

Datadog (1)

Interface Metrics (2)

OpenTelemetry

db.client.connections.usage

Number of database connections in use by Django ORM

Dimensions:None

Datadog

django.db.connections.count

Number of active database connections

Dimensions:None

Sources

db.client.connections.usageopentelemetry.io

django.db.connections.countdocs.datadoghq.com

Technical Annotations (65)

Configuration Parameters (22)

CONN_MAX_AGErecommended: 0 for development, 60-300 for production

connection lifetime in seconds, too high prevents connection closure

DATABASES.default.ENGINE

database backend type

DATABASES.default.HOST

database server hostname or IP

DATABASES.default.PORT

database server port number

pool_moderecommended: transaction

PgBouncer pooling mode - connection assigned per transaction then returned to pool

max_client_connrecommended: 500

Maximum number of client connections PgBouncer accepts

default_pool_sizerecommended: 25

Pool size should be 25-50% of PostgreSQL max_connections

server_idle_timeoutrecommended: 600

Seconds before idle server connection is closed

DATABASES.default.CONN_MAX_AGErecommended: 300

Keeps database connections alive for 5 minutes to avoid reconnection overhead

DATABASES.default.CONN_HEALTH_CHECKSrecommended: True

Validates connections before use to prevent stale connection errors

page_sizerecommended: 50

Default pagination size for list endpoints when client doesn't specify

statement_timeoutrecommended: 10000

PostgreSQL query timeout in milliseconds to kill runaway queries

DATABASES

Dictionary containing database credentials and connection settings in settings.py

DATABASES.default.POOL_OPTIONS.POOL_SIZErecommended: 10

per-worker persistent connections, calculate based on worker count

DATABASES.default.POOL_OPTIONS.MAX_OVERFLOWrecommended: 5

extra connections beyond pool size during load spikes

DATABASES.default.POOL_OPTIONS.POOL_TIMEOUTrecommended: 3

seconds to wait for free connection before failing

wait_timeout

MySQL server-side timeout for idle connections; coordinate with CONN_MAX_AGE

DATABASES['default']['CONN_MAX_AGE']recommended: 10

Connection reuse timeout in seconds; set but not preventing connection spikes post-upgrade

DATABASES['default']['ATOMIC_REQUESTS']recommended: False

Disables automatic transaction wrapping per request

listen_portrecommended: 6432

Port where PgBouncer listens for client connections

PORTrecommended: 6432

Django must connect to PgBouncer port instead of PostgreSQL direct

lock.timeoutrecommended: 5

Prevents deadlocks if worker crashes during cache computation

Error Signatures (14)

Connection refusedexception

django.db.utils.OperationalErrorexception

OperationalErrorexception

OperationalError: server closed the connection unexpectedlyexception

timeout errorslog pattern

Connection pool exhaustedlog pattern

no more connections allowed (max_client_conn)error code

query_wait_timeouterror code

connection failed: connection to server at "...", port 6432 failed: ERROR: no more connections allowed (max_client_conn)error code

connection failed: FATAL: no more connections allowed (max_client_conn)log pattern

OperationalError: MySQL server has gone awayexception

OperationalError: sorry, too many clients alreadyexception

FATAL: sorry, too many clients alreadylog pattern

FATAL: memory quota exceededlog pattern

CLI Commands (8)

SELECT * FROM pg_stat_activitydiagnostic

SHOW PROCESSLISTdiagnostic

psql -U username -d dbnamediagnostic

SHOW POOLSmonitoring

EXPLAIN ANALYZE SELECT * FROM orders ORDER BY created_at DESC LIMIT 50 OFFSET 0;diagnostic

SELECT split_part(query, 'WHERE', 2) AS sql, COUNT(*) AS count FROM pg_stat_activity WHERE datname = '...' GROUP BY query

diagnostic

sudo apt-get install pgbouncerremediation

with cache.lock(f"lock:user_profile:{user_id}", timeout=5):remediation

Technical References (21)

connection poolconceptsettings.pyfile pathDATABASEScomponentPgBouncercomponentmax_connectionscomponentdjango_db_new_connections_totalcomponentpgbouncercomponentCONN_MAX_AGEcomponentCONN_HEALTH_CHECKScomponentOrder.objects.all()componentConnectionPoolMonitorcomponentconnection.poolcomponentpg_stat_activitycomponentDatabaseConnectionMiddlewarecomponentMIDDLEWAREcomponentASGIcomponentconnection poolingconceptDjango REST Frameworkcomponentcache.lock()componentcache stampedeconceptthundering herdconcept

Related Insights (18)

Database connection pool exhaustion causes Connection refused errorscritical

▸

Incorrect database settings prevent Django database connectioncritical

▸

Database server unreachable causes OperationalErrorcritical

▸

PostgreSQL connection count exceeds limits causing memory exhaustionwarning

▸

Database connection pool exhaustion or misconfigurationwarning

▸

Database connections timeout without connection pooling configurationcritical

▸

Unpaginated list endpoints cause outage at scalecritical

▸

Missing query timeout allows indefinite hangs and connection pool exhaustioncritical

▸

Database connection failure due to misconfigured credentialscritical

▸

Connection pool exhaustion during traffic spikescritical

▸

Django connections remain idle indefinitely despite CONN_MAX_AGE settingcritical

▸

Django 4.x leaks database connections with CONN_MAX_AGE enabledcritical

▸

MySQL connection timeout causes 'server has gone away' errors during traffic spikescritical

▸

PostgreSQL connection spike after Django 3.2 to 5.2 upgrade despite CONN_MAX_AGE settingcritical

▸

PostgreSQL connection spike after Django 3.2 to 5.2 upgrade with CONN_MAX_AGE configuredwarning

▸

PostgreSQL connection exhaustion from per-request Django connectionscritical

▸

Per-request database connections cause API latency under loadwarning

▸

Cache stampede causes database overload on cold cachewarning

▸