bgwriter_flush_after

bgwriter_flush_after — Number of pages after which previously performed writes are flushed to disk. Observed in PG9.6–19 Beta 3; its last measured boot default is 512 KiB (64 × 8kB) 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: “Number of pages after which previously performed writes are flushed to disk.”

Identity

Type , Valueinteger: Upstream pg_settings type
Context , Valuesighup: Takes effect after configuration reload
Unit , Value8kB: Raw unit
Range , Value0 – 256: Raw limits in the last observed version
Enum values , Value—: — for non-enum types
Category , ValueResource Usage / Background Writer: Upstream classification
Latest boot value , Value64: 512 KiB (64 × 8kB)

Lifecycle

Fact	Value
First observed	PG9.6
Present in	PG9.6–19 Beta 3
Removed in	No
Introduction commit	`428b1d6b29ca` — Allow to trigger kernel writeback after a configurable number of writes.
Commit date	2016-02-19
Discussion	—

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions	Raw `boot_val`	Unit	Human value
PG9.6–19 Beta 3	`64`	`8kB`	512 KiB (64 × 8kB)

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.

Tuning advice

Tip

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

Workload	Guidance
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.
OLAP	Bulk writes can reach bgwriter_flush_after 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_flush_after 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	Unmodified	—	—
OLAP	Unmodified	—	—
CRIT	Unmodified	—	—
TINY	Unmodified	—	—

Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.6–19 Beta 3 unmodified; OLAP: PG9.6–19 Beta 3 unmodified; CRIT: PG9.6–19 Beta 3 unmodified; TINY: PG9.6–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

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.

backend_flush_after · checkpoint_flush_after · bgwriter_delay · bgwriter_lru_maxpages · shared_buffers