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

Operational runbook · Quick reference

Checkpoints are driving I/O pressure

Correlate checkpoint work, WAL generation, buffer writes, and host storage queues before tuning.

periodic latencyI/O queuecheckpoint spikewrite stalls

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. Record the affected recovery or production objective, scope, start time, and current user impact.
  2. Preserve logs, identifiers, timestamps, and before/after evidence before retrying or restarting work.
  3. Identify the owning application, change, job, or infrastructure boundary and its rollback constraints.

Observe

Gather evidence

Diagnostic query

Inspect cumulative checkpoint activity

Read checkpoint counts, write time, sync time, and buffers written for interval comparison.

SELECT
  num_timed,
  num_requested,
  write_time,
  sync_time,
  buffers_written,
  stats_reset
FROM pg_stat_checkpointer;
low observation cost

Interpret

Interpret the evidence

  • Cumulative counters need two samples over a known interval before they describe a rate.
  • Requested checkpoints, high write time, or high sync time point to different tuning and capacity questions.

Act

Take the safest useful action

  1. Reduce the proven burst source or pace maintenance work while protecting user latency.
  2. Tune checkpoint pacing only with WAL rate, recovery time, memory, and storage capacity considered together.
  3. Verify later intervals and recovery objectives after any change.

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 storage queues do not converge, requested checkpoints dominate, or any tuning would change durability or recovery objectives.

Prevent recurrence

Study the underlying system

postgres health observability

Certification competency

Refresh the assessed operating model

Architecture and system model WAL, checkpoints, and storage behaviour

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