bgwriter_flush_after

Definition PG 18 manual

Whenever more than this amount of data has been written by the background writer, 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 a 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 512kB 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

After the background writer has written more than bgwriter_flush_after bytes, PostgreSQL asks the operating system to begin writing those page-cache pages toward storage. Zero disables the request.

The request is writeback smoothing, not a durability fsync. It can reduce large kernel flush stalls, but can also hurt workloads that benefit from retaining dirty data in the OS cache, and it has no effect on unsupported platforms.

The measured Docker/Linux boot value represents Linux behavior; PostgreSQL documents a platform-dependent default of 512kB on Linux and zero elsewhere. Backend and checkpointer writeback have separate thresholds. Its SIGHUP context allows configuration reload without a server restart.

Operational considerations

Changing bgwriter_flush_after without applying its documented unit and configuration context.

Optimizing an isolated benchmark while ignoring concurrent aggregate resource use.

Assuming a configured value guarantees operating-system or storage behavior.

Failing to retest startup, failover, and workload latency after the change.

Workload guidance

OLAP: Bulk writes can reach bgwriter_flush_after limits continuously. Measure total bytes written, checkpoints, and storage queueing, not just foreground query latency.

OLTP: Tune bgwriter_flush_after only with bgwriter and checkpoint metrics. The goal is fewer backend writes and smoother latency without excessive repeated writes; change one dimension at a time.

SMALL: A small host usually needs conservative write smoothing. Aggressive bgwriter_flush_after can consume I/O needed by foreground work, so retain the default unless backend writes are a measured problem.