checkpoint_flush_after

Definition PG 18 manual

Whenever more than this amount of data has been written while performing a checkpoint, attempt to force the OS to issue these writes to the underlying storage. Doing so will limit the amount of dirty data in the kernel's page cache, reducing the likelihood of stalls when an fsync is issued at the end of the checkpoint, or when the OS writes data back in larger batches in the background. Often that will result in greatly reduced transaction latency, but there also are some cases, especially with workloads that are bigger than shared_buffers, but smaller than the OS's page cache, where performance might degrade. This setting may have no effect on some platforms. If this value is specified without units, it is taken as blocks, that is BLCKSZ bytes, typically 8kB. The valid range is between 0, which disables forced writeback, and 2MB. The default is 256kB on Linux, 0 elsewhere. (If BLCKSZ is not 8kB, the default and maximum values scale proportionally to it.) This parameter can only be set in the postgresql.conf file or on the server command line.

How it works

Number of pages after which previously performed writes are flushed to disk. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

Checkpoint writes are periodically handed to the operating system for writeback after this much data, smoothing the final sync and reducing dirty-cache bursts. Zero disables these intermediate flush requests; the best value is operating-system and storage dependent.

Monitor and change checkpoint_flush_after together with checkpoint_warning, checkpoint_timeout, checkpoint_completion_target. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Operational considerations

Treating the raw value as bytes even though an unqualified value is measured in database blocks.

Setting it too small and increasing writeback calls and I/O fragmentation.

Setting it too large and losing the intended smoothing before the checkpoint sync phase.

Confusing writeback hints with a durability guarantee; fsync and wal_sync_method still define persistence.

Copying a value across operating systems or filesystems without measuring checkpoint latency and dirty-page behavior.

Workload guidance

OLAP: Provision WAL, archive bandwidth, and recovery I/O for bulk-load peaks. Coordinate load pacing and checkpoints when reducing spikes; never break the recovery chain for throughput.

OLTP: Establish durability and recovery objectives first, then tune checkpoint_flush_after from WAL rate, flush latency, checkpoints, and peak pg_wal usage. Validate every change with crash/recovery and archive monitoring.

SMALL: Start from safe defaults and set explicit alerts for limited disk capacity. Do not disable durability or break the recovery chain merely to save modest I/O.