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

Operational runbook · Quick reference

Disk usage keeps growing

Attribute growth to tables, indexes, WAL, temporary work, or logs before attempting reclamation.

disk growthvolume fullWAL growthtable bloat

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 free space, growth rate, and the time remaining at the current rate.
  2. Separate the data directory, WAL, temporary space, logs, and backup/archive destinations.
  3. Identify the relations or retention mechanisms responsible before deleting or rewriting anything.

Observe

Gather evidence

Diagnostic query

Find the largest user relations

Rank tables by total footprint and separate table, index, and auxiliary storage.

SELECT
  schemaname,
  relname AS table_name,
  pg_size_pretty(pg_total_relation_size(relid)) AS total_size,
  pg_size_pretty(pg_relation_size(relid)) AS table_size,
  pg_size_pretty(pg_indexes_size(relid)) AS index_size
FROM pg_stat_user_tables
ORDER BY pg_total_relation_size(relid) DESC
LIMIT 30;
low observation cost

Interpret

Interpret the evidence

  • If data relations are stable but disk grows, inspect WAL retention, logs, temporary files, and backup staging.
  • A relation can reuse vacuumed space without its operating-system file shrinking.

Act

Take the safest useful action

  1. Increase storage headroom before a forensic rewrite when the exhaustion window is short.
  2. Stop the specific growth source—runaway ingest, abandoned slot, logging flood, or temp-heavy query—before reclamation.
  3. Plan rewrite operations with locking, extra-space, WAL, replication, and rollback costs included.

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 immediately when available storage is below the worst-case response window or `pg_wal` growth is uncontrolled.

Prevent recurrence

Study the underlying system

vacuum indexes replication

Certification competency

Refresh the assessed operating model

MVCC, vacuum, autovacuum, and bloat Monitoring, capacity, and operational health WAL, checkpoints, and storage behaviour Incident diagnosis and response

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