vacuum_buffer_usage_limit

Definition PG 18 manual

Specifies the size of the Buffer Access Strategy used by the VACUUM and ANALYZE commands. A setting of 0 will allow the operation to use any number of shared_buffers. Otherwise valid sizes range from 128 kB to 16 GB. If the specified size would exceed 1/8 the size of shared_buffers, the size is silently capped to that value. The default value is 2MB. If this value is specified without units, it is taken as kilobytes. This parameter can be set at any time. It can be overridden for VACUUM and ANALYZE when passing the BUFFER_USAGE_LIMIT option. Higher settings can allow VACUUM and ANALYZE to run more quickly, but having too large a setting may cause too many other useful pages to be evicted from shared buffers.

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.

Operational considerations

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.

Workload guidance

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.

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.

SMALL: 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.