bgwriter_lru_maxpages

bgwriter_lru_maxpages — Background writer maximum number of LRU pages to flush per round. Observed in PG9.0–19 Beta 3; its last measured boot default is 100 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: “Background writer maximum number of LRU pages to flush per round.”

Identity

Type , Valueinteger: Upstream pg_settings type
Context , Valuesighup: Takes effect after configuration reload
Unit , Value—: Raw unit
Range , Value0 – 1073741823: Raw limits in the last observed version
Enum values , Value—: — for non-enum types
Category , ValueResource Usage / Background Writer: Upstream classification
Latest boot value , Value100: 100

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–19 Beta 3	`100`	—	100

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.

Tuning advice

Tip

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

Workload	Guidance
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.
OLAP	Bulk writes can reach bgwriter_lru_maxpages limits continuously. Measure total bytes written, checkpoints, and storage queueing, not just foreground query latency.
Small nodes	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.

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	`800`	different	`800`
OLAP	`800`	different	`800`
CRIT	`800`	different	`800`
TINY	`800`	different	`800`

Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 800 (dcs); OLAP: PG9.0–19 Beta 3 = 800 (dcs); CRIT: PG9.0–19 Beta 3 = 800 (dcs); TINY: PG9.0–19 Beta 3 = 800 (dcs). Advice, pending human review — Editorial inference, pending maintainer review: The higher per-round cap is intended to give the frequently running background writer enough capacity to prepare clean buffers instead of forcing foreground backends to write them.

Common pitfalls

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.

bgwriter_lru_multiplier · bgwriter_delay · bgwriter_flush_after · shared_buffers · checkpoint_completion_target