bgwriter_lru_maxpages

Definition PG 18 manual

In each round, no more than this many buffers will be written by the background writer. Setting this to zero disables background writing. (Note that checkpoints, which are managed by a separate, dedicated auxiliary process, are unaffected.) The default value is 100 buffers. This parameter can only be set in the postgresql.conf file or on the server command line.

How it works

bgwriter_lru_maxpages caps how many LRU-selected dirty buffers the background writer writes in one round. Zero disables this background-writing activity but does not disable checkpoints.

The writer tries to create enough clean reusable buffers for predicted demand, but this cap bounds each round. If it is reached repeatedly, foreground backends may still have to write buffers themselves.

The prediction comes from recent allocations multiplied by bgwriter_lru_multiplier, and rounds are separated by bgwriter_delay. Raising the cap can smooth latency at the cost of extra write amplification. Its SIGHUP context allows configuration reload without a server restart.

Operational considerations

Changing bgwriter_lru_maxpages 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_lru_maxpages limits continuously. Measure total bytes written, checkpoints, and storage queueing, not just foreground query latency.

OLTP: Tune bgwriter_lru_maxpages 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_lru_maxpages can consume I/O needed by foreground work, so retain the default unless backend writes are a measured problem.