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

Operational runbook · Quick reference

The replica is falling behind

Separate WAL generation, transport, flush, and replay before deciding whether the replica needs load relief, conflict resolution, or capacity.

replica lagstale readsWAL retainedreplay stopped

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 the replica serves reads, disaster recovery, backups, or failover obligations.
  2. Measure the WAL byte gap and whether it is growing or shrinking across an interval.
  3. Check primary disk exposure when slots or archiving retain WAL for the lagging replica.

Observe

Gather evidence

Diagnostic query

Compare connected replica WAL gaps

Show sender state and the byte gap between current primary WAL and each replica's replay position.

SELECT
  application_name,
  client_addr,
  state,
  sync_state,
  write_lag,
  flush_lag,
  replay_lag,
  pg_wal_lsn_diff(pg_current_wal_lsn(), replay_lsn) AS replay_gap_bytes
FROM pg_stat_replication
ORDER BY replay_gap_bytes DESC NULLS LAST;
low observation cost

Interpret

Interpret the evidence

  • Rates matter more than one snapshot: a large gap that shrinks can be healthier than a small gap growing continuously.
  • Inspect standby query conflicts, storage latency, receiver status, recovery pauses, and configured delay.

Act

Take the safest useful action

  1. Reduce non-essential read workload on the standby when replay is resource-constrained.
  2. Resolve the specific long query or conflict only after confirming its business impact.
  3. Protect primary disk by reviewing slot ownership and WAL retention without dropping a required slot impulsively.

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 the catch-up rate remains below WAL generation, failover objectives are threatened, or primary disk headroom is falling rapidly.

Prevent recurrence

Study the underlying system

replication observability

Certification competency

Refresh the assessed operating model

Replication, lag, and failover readiness

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