Size WAL with max_wal_size and checkpoint_timeout
Measure WAL bytes and elapsed time for a representative workload, then project that rate across checkpoint_timeout. A PG16 Docker lab generated 25 MB in 0.261 s; the burst projection was 29 GB per five-minute interval.
Problem
What you're actually looking at
The symptom as it shows up on a real server.
max_wal_size is a soft target that helps determine when checkpoints begin. Guessing it from a blog post is unsafe: measure your WAL rate, compare it with checkpoint_timeout, and leave headroom for bursts, slots, and archiving.
A 100,000-row write batch records its real start/end LSN, time, and PG16 checkpoint counters. The measured burst rate is then projected across the configured checkpoint interval.
Simple terms
max_wal_size is not a hard disk cap. It helps PostgreSQL decide when WAL volume should start a checkpoint. The honest way to size it is to measure how much WAL your real work produces per second, project that rate across checkpoint_timeout, and compare the result with the current setting, while remembering a short burst is not a steady-state forecast.
Full runbook for this incident
- The full identify checklist, the exact signals that tell you it's this incident
- Every diagnostic query; lab output is attached only to the steps we actually captured
- The resolution path and the pitfalls that make it worse
- Mitigation steps to stop it recurring, plus a verify-you're-done query
Card required. Cancel before day 7 and you are not charged.
More in this category
Other WAL & replication runbooks
Neighbouring incidents that share the same diagnostic surface.
Connected
How this connects to the rest of the library
A live view of this page's real cross-references, what explains it, what fixes it, what to tune, and where to go next. Every link is an authored relationship, not a guess.
Fixes these errors
Need the full procedure?
Pro runbooks finish the incident path
Free runbooks teach the shape. Pro opens the full step transcript, edge cases, and prevention depth.