# 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 {#identity}

| Field | Value | Meaning |
| --- | --- | --- |
| Type | `integer` | Upstream pg_settings type |
| Context | `sighup` | Takes effect after configuration reload |
| Unit | — | Raw unit |
| Range | `0` – `1073741823` | Raw limits in the last observed version |
| Enum values | — | — for non-enum types |
| Category | Resource Usage / Background Writer | Upstream classification |
| Latest boot value | `100` | 100 |
{.fields meta="-"}

## Lifecycle {#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 {#default-history}

| Versions | Raw `boot_val` | Unit | Human value |
| --- | --- | --- | --- |
| PG9.0–19 Beta 3 | `100` | — | 100 |
{.full-width caption="Measured PG9.0–19 Beta 3 boot defaults"}

## How it works {#mechanism}

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 {#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. |
{.full-width}

## Pigsty {#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` |
{.full-width}

> [!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 {#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.

## Related parameters {#related-parameters}

[`bgwriter_lru_multiplier`](/parameters/bgwriter-lru-multiplier/) · [`bgwriter_delay`](/parameters/bgwriter-delay/) · [`bgwriter_flush_after`](/parameters/bgwriter-flush-after/) · [`shared_buffers`](/parameters/shared-buffers/) · [`checkpoint_completion_target`](/parameters/checkpoint-completion-target/)

## References {#references}

- [PostgreSQL 19 Beta 3 — bgwriter_lru_maxpages](https://www.postgresql.org/docs/19/runtime-config-resource.html#GUC-BGWRITER-LRU-MAXPAGES)
- [PostgreSQL 19 release notes](https://www.postgresql.org/docs/19/release-19.html)
- [Machine-readable GUC export](/data/guc.jsonl)