The PostgreSQL administration field guideField notes · Runbooks · Free certification
pgdba.dev
Menu

Operational runbook · Quick reference

Connections are exhausted

Find which applications and states consume connection capacity, then restore admission without hiding a queueing problem.

too many connectionsconnection timeoutpool exhaustedmax_connections

Before you begin

Prerequisites

  • Confirm the target cluster, database, PostgreSQL major version, and your read-only access to the required statistics views.
  • Record the current user impact, incident owner, UTC timestamp, and a baseline before running diagnostics.

Control the blast radius

Safety boundary

Start with read-only observations. Do not restart, terminate, delete, fail over, or change configuration until ownership, blast radius, and an approved recovery path are explicit.

Triage

Establish impact

  1. Confirm whether all clients fail or whether reserved administrative access still works.
  2. Measure connections by database, role, application, client, and session state.
  3. Check whether demand increased or sessions stopped returning to their pool.

Observe

Gather evidence

Diagnostic query

Group connections by application and state

Reveal the application and session state consuming backend capacity.

SELECT
  datname,
  usename AS user_name,
  application_name,
  state,
  count(*) AS connection_count,
  max(now() - xact_start) AS oldest_transaction_age
FROM pg_stat_activity
GROUP BY datname, usename, application_name, state
ORDER BY connection_count DESC;
low observation cost

Interpret

Interpret the evidence

  • Increasing `max_connections` adds backend overhead and can move failure from admission to memory or CPU saturation.
  • Fix pool sizing, leaks, and request concurrency at the application boundary where possible.

Act

Take the safest useful action

  1. Preserve administrative access and reduce new application admission or concurrency.
  2. Terminate clearly abandoned sessions only after confirming ownership and transaction impact.
  3. Correct pool limits and connection lifecycle before raising the server limit.

Prove the outcome

Verification

  1. Repeat the baseline observation over a known interval and confirm that the measured queue or risk is moving in the intended direction.
  2. Verify the user-facing objective and every affected replica or dependency before closing or handing over the incident.

Keep recovery close

Rollback

Record the original state and rollback owner before acting. If verification worsens or the objective is missed, reverse only the bounded change, confirm the baseline is restored, and escalate with the before-and-after evidence.

Escalate

Escalate when

  • Escalate when administrative access is lost, idle-in-transaction sessions own locks, or memory pressure rises with connection count.

Prevent recurrence

Study the underlying system

postgres health observability locks

Certification competency

Refresh the assessed operating model

Connections, configuration, and memory

Reference assurance

Version and review

Compatible versions
PostgreSQL 16–18
Content version
2026.08
Reviewed
2026-08-04

Catalog columns, wait events, and operational controls can vary by PostgreSQL major version, extensions, and orchestration layer. Verify commands against the deployed version.

Verify independently

Sources