checkpoint_completion_target

Definition PG 18 manual

Specifies the target of checkpoint completion, as a fraction of total time between checkpoints. The default is 0.9, which spreads the checkpoint across almost all of the available interval, providing fairly consistent I/O load while also leaving some time for checkpoint completion overhead. Reducing this parameter is not recommended because it causes the checkpoint to complete faster. This results in a higher rate of I/O during the checkpoint followed by a period of less I/O between the checkpoint completion and the next scheduled checkpoint. This parameter can only be set in the postgresql.conf file or on the server command line.

How it works

PostgreSQL throttles checkpoint writes so that they are expected to finish after this fraction of the available interval. The available interval ends at the next timed checkpoint or sooner if WAL volume forces a checkpoint, so this is a pacing target rather than a fixed duration.

A larger fraction generally smooths checkpoint I/O over more time. A smaller fraction finishes writes faster, producing a higher I/O rate followed by an idle gap; the official documentation discourages reducing it for that reason.

Values too close to 1 leave little room for final synchronization and other checkpoint work. PostgreSQL's historical default change from 0.5 to 0.9 is material when comparing otherwise identical configurations across major versions.

Operational considerations

Interpreting the value as seconds rather than a fraction.

Assuming a lower value reduces total I/O instead of concentrating it.

Setting 1.0 and leaving no margin for checkpoint completion overhead.

Ignoring early volume-triggered checkpoints from max_wal_size.

Overlooking the default change at PostgreSQL 14.

Workload guidance

OLAP: For bursty bulk workloads, raising max_wal_size is often the first lever because a volume-triggered checkpoint shortens the pacing window. Keep this target high enough to smooth I/O but not so high that final sync work bunches at the end.

OLTP: Start with the version default of 0.9 and optimize only with latency and pg_stat_checkpointer evidence. A value of 0.95 can smooth writes further, but verify that checkpoints consistently finish before the next trigger.

SMALL: Use 0.9 unless measurements show a clear benefit. Small or slow storage is especially vulnerable to an end-of-checkpoint sync spike when the target leaves insufficient margin.