Parameter · Write-Ahead Log / Checkpoints
checkpoint_completion_target
Time spent flushing dirty buffers during checkpoint, as fraction of checkpoint interval.
- Default:
0.9 - Type: real
- Range: 0 … 1
- Applies: Reload
In plain words
A checkpoint does not write all dirty pages at once: it spreads them out so the disk is not flooded. checkpoint_completion_target says how much of the time until the next checkpoint it may take. With 0.9 (the default) the writes are spread over 90% of the interval.
For DBAs and operators
The checkpointer paces itself against two clocks: elapsed time as a share of checkpoint_timeout and WAL written as a share of the WAL-based trigger distance. It sleeps between writes as long as it is ahead of completion_target on both. The default changed from 0.5 to 0.9 in PostgreSQL 14; there is little reason to lower it.
It also shapes WAL retention: a WAL-triggered checkpoint starts after about max_wal_size / (1 + checkpoint_completion_target) of WAL, because WAL from the previous checkpoint start must be kept until the current one finishes. With 1 GB and 0.9 that is roughly 540 MB.
Pitfall: values near 1.0 leave no slack, so the checkpoint may still be running when the next one is due; the log then shows checkpoints back-to-back with write times close to the timeout.
How to change it
Change in postgresql.conf or ALTER SYSTEM, then run SELECT pg_reload_conf().