checkpoint_timeout

Definition PG 18 manual

Maximum time between automatic WAL checkpoints. If this value is specified without units, it is taken as seconds. The valid range is between 30 seconds and one day. The default is five minutes (5min). Increasing this parameter can increase the amount of time needed for crash recovery. This parameter can only be set in the postgresql.conf file or on the server command line.

How it works

An automatic checkpoint is considered after checkpoint_timeout, but max_wal_size can force one earlier. If no WAL has been written since the preceding checkpoint, PostgreSQL can skip the timed checkpoint, so this setting is a maximum scheduling interval rather than a promise of periodic physical work.

Longer intervals usually reduce checkpoint frequency and full-page-write amplification, while increasing the amount of WAL that crash recovery may need to replay. Shorter intervals bound that replay horizon more tightly but increase dirty-page flushing and post-checkpoint full-page images.

Checkpoint records also constrain restartpoints on standbys. This parameter should not be used to set a WAL-archive recovery point objective; archive_timeout is the control intended to force segment switches for low-WAL systems.

Operational considerations

Assuming a checkpoint occurs exactly every configured interval even on an idle system.

Forgetting that max_wal_size can trigger a checkpoint earlier.

Using checkpoint_timeout instead of archive_timeout to bound archive delay.

Increasing it without allowing for a longer crash-recovery replay horizon.

Reducing it so far that full-page writes and checkpoint I/O dominate.

Workload guidance

OLAP: During bulk work, max_wal_size often triggers before the timer. Increase WAL capacity first if volume-driven checkpoints dominate, and retain a timeout that still meets restart and recovery expectations.

OLTP: Tune it together with max_wal_size and keep checkpoint I/O spread with checkpoint_completion_target. Extend the interval only after measuring recovery requirements, requested versus timed checkpoints, write latency, and WAL volume.

SMALL: The upstream 5-minute default is a defensible starting point where recovery time matters and storage is limited. A longer interval needs explicit disk headroom and a tested crash-recovery budget.