Parameter · Write-Ahead Log / Checkpoints

max_wal_size

Sets the WAL size that triggers a checkpoint.

Default: 1GB
Type: integer (MB)
Range: 2MB … max (2147483647)
Applies: Reload

In plain words

WAL piles up between checkpoints. Old WAL can only be recycled after a checkpoint, so PostgreSQL starts a checkpoint early, after roughly half of max_wal_size has been written (exactly max_wal_size / (1 + checkpoint_completion_target)), to keep pg_wal below this size. Too small, and a busy server checkpoints all the time (lots of extra disk writes). Bigger values smooth I/O but use more disk in pg_wal and make crash recovery longer.

It is a soft limit: pg_wal can grow beyond it under heavy load, failing archiving, replication slots or wal_keep_size.

For DBAs and operators

Trigger math: a checkpoint is requested after roughly max_wal_size / (1 + checkpoint_completion_target) of WAL since the last one (≈ 540 MB for 1 GB and 0.9), because WAL from the previous checkpoint's start must survive until the current checkpoint completes. So pg_wal normally peaks near max_wal_size.

Sizing

Aim for checkpoints to be timed, not WAL-requested: num_timed ≫ num_requested in pg_stat_checkpointer, and no LOG: checkpoints are occurring too frequently (8 seconds apart)
Estimate WAL per checkpoint_timeout from pg_stat_wal.wal_bytes deltas or the distance= field in checkpoint logs; set max_wal_size to ~2–3× that. 4–64 GB is common on busy servers.
Make sure the pg_wal file system has room: it can exceed this value.

Why pg_wal grows past it

WAL is not removed while it is still needed by: a failing archive_command (check pg_stat_archiver.failed_count), an inactive replication slot (pg_replication_slots.active = false, see max_slot_wal_keep_size), or wal_keep_size. These are the usual causes of "disk full in pg_wal" tickets.

How to change it

Change in postgresql.conf or ALTER SYSTEM, then run SELECT pg_reload_conf().

See it in context

Checkpoints Write-ahead log (WAL) Checkpointer Archiver Full-page writes Crash recovery Replication slots

Related parameters

min_wal_size checkpoint_timeout checkpoint_completion_target checkpoint_warning max_slot_wal_keep_size wal_keep_size

All Write-Ahead Log parameters