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

Operational runbook · Quick reference

A deployment changed database behaviour

Tie timing, query shapes, plans, locks, and resource changes to a compatible mitigation or rollback.

post-deploy latencynew locksplan regressionconnection spike

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

Find high-contribution changed statements

Rank the current workload while retaining call volume and mean time for deploy comparison.

SELECT
  queryid,
  calls,
  total_exec_time,
  mean_exec_time,
  rows,
  left(query, 180) AS query_preview
FROM pg_stat_statements
ORDER BY total_exec_time DESC
LIMIT 30;
low observation cost

Interpret

Interpret the evidence

  • Timing correlation narrows the search but requires plan, parameter, wait, and resource evidence.
  • A compatible application rollback can still be unsafe after irreversible data or schema changes.

Act

Take the safest useful action

  1. Stop further rollout and preserve before/after workload and plan evidence.
  2. Use the rehearsed compatible rollback, feature control, or narrow query mitigation that addresses the proven boundary.
  3. Keep measuring user impact, locks, connections, WAL, and replicas until the system converges.

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 rollback compatibility is uncertain, DDL is blocked or blocking, or the change affected data semantics or recovery safety.

Prevent recurrence

Study the underlying system

query workload locks indexes

Certification competency

Refresh the assessed operating model

Safe SQL and data integrity Roles, privileges, and access security Safe changes, upgrades, and handover

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