checkpoint_completion_target

checkpoint_completion_target — Time spent flushing dirty buffers during checkpoint, as fraction of checkpoint interval. Observed in PG9.0–19 Beta 3; its last measured boot default is 0.9 in PG19 Beta 3, with sighup context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.

Note

Fact — official short description: “Time spent flushing dirty buffers during checkpoint, as fraction of checkpoint interval.”

Identity

Type , Valuereal: Upstream pg_settings type
Context , Valuesighup: Takes effect after configuration reload
Unit , Value—: Raw unit
Range , Value0 – 1: Raw limits in the last observed version
Enum values , Value—: — for non-enum types
Category , ValueWrite-Ahead Log / Checkpoints: Upstream classification
Latest boot value , Value0.9: 0.9

Lifecycle

Fact	Value
First observed	PG9.0 (research boundary)
Present in	PG9.0–19 Beta 3
Removed in	No
Introduction commit	Not asserted: predates the PG9.0 research boundary
Commit date	—
Discussion	—

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions	Raw `boot_val`	Unit	Human value
PG9.0–13	`0.5`	—	0.5
PG14–19 Beta 3	`0.9`	—	0.9

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.

Tuning advice

Tip

Advice. These are workload-specific starting points and must be validated with measurements.

Workload	Guidance
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.
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.
Small nodes	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.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG19 Beta 3; this does not assert current Pigsty support for that historical or beta release.

Template	Effective value	Versus upstream boot	Source expression
OLTP	`0.95`	different	`0.95`
OLAP	`0.95`	different	`0.95`
CRIT	`0.95`	different	`0.95`
TINY	`0.95`	different	`0.95`

Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 0.95 (dcs); OLAP: PG9.0–19 Beta 3 = 0.95 (dcs); CRIT: PG9.0–19 Beta 3 = 0.95 (dcs); TINY: PG9.0–19 Beta 3 = 0.95 (dcs). Advice, pending human review — confirm the operational intent against the current Pigsty templates and supported PostgreSQL versions before publication.

Common pitfalls

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.

checkpoint_timeout · max_wal_size · checkpoint_flush_after · checkpoint_warning · shared_buffers