vacuum_buffer_usage_limit

vacuum_buffer_usage_limit — Sets the buffer pool size for VACUUM, ANALYZE, and autovacuum. Observed in PG16–19 Beta 3; its last measured boot default is 2 MiB in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.

Note

Fact — official short description: “Sets the buffer pool size for VACUUM, ANALYZE, and autovacuum.”

Identity

Type , Valueinteger: Upstream pg_settings type
Context , Valueuser: Settable by an ordinary user
Unit , ValuekB: Raw unit
Range , Value0 – 16777216: Raw limits in the last observed version
Enum values , Value—: — for non-enum types
Category , ValueResource Usage / Memory: Upstream classification
Latest boot value , Value2048: 2 MiB

Lifecycle

Fact	Value
First observed	PG16
Present in	PG16–19 Beta 3
Removed in	No
Introduction commit	`1cbbee033857` — Add VACUUM/ANALYZE BUFFER_USAGE_LIMIT option
Commit date	2023-04-07
Discussion	thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions	Raw `boot_val`	Unit	Human value
PG16	`256`	`kB`	256 KiB
PG17–19 Beta 3	`2048`	`kB`	2 MiB

How it works

vacuum_buffer_usage_limit sizes the shared-buffer access-strategy ring used by VACUUM, ANALYZE, and autovacuum. It is not a private memory allocation and does not cap all buffers those operations can ever touch.

A nonzero value is silently capped at one eighth of shared_buffers; zero allows unrestricted shared-buffer use. The ring reduces eviction of unrelated hot pages while permitting repeated reuse during scans.

Larger rings can improve maintenance throughput but can displace more useful cache. VACUUM and ANALYZE can override it per command with BUFFER_USAGE_LIMIT, and the boot default rose from 256kB in PG16 to 2MB in PG17. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Tuning advice

Tip

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

Workload	Guidance
OLTP	Change vacuum_buffer_usage_limit only after identifying the corresponding resource bottleneck under concurrency. Budget total memory, I/O, disk, or kernel capacity rather than optimizing one process in isolation.
OLAP	Benchmark vacuum_buffer_usage_limit with representative bulk and scan phases. Include sustained throughput, spill/writeback, and interference with other sessions, not only one operation’s elapsed time.
Small nodes	Keep vacuum_buffer_usage_limit conservative on a small host and prefer the upstream default when evidence is weak. A setting copied from a large server can consume a disproportionate share of resources.

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: PG16–19 Beta 3 unmodified; OLAP: PG16–19 Beta 3 unmodified; CRIT: PG16–19 Beta 3 unmodified; TINY: PG16–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

Changing vacuum_buffer_usage_limit 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.

shared_buffers · maintenance_work_mem · autovacuum_work_mem · maintenance_io_concurrency · track_io_timing