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

| Field | Value | Meaning |
| --- | --- | --- |
| Type | `integer` | Upstream pg_settings type |
| Context | `user` | Settable by an ordinary user |
| Unit | `kB` | Raw unit |
| Range | `0` – `16777216` | Raw limits in the last observed version |
| Enum values | — | — for non-enum types |
| Category | Resource Usage / Memory | Upstream classification |
| Latest boot value | `2048` | 2 MiB |
{.fields meta="-"}

## Lifecycle {#lifecycle}

| Fact | Value |
| --- | --- |
| First observed | PG16 |
| Present in | PG16–19 Beta 3 |
| Removed in | No |
| Introduction commit | [`1cbbee033857`](https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=1cbbee03385763b066ae3961fc61f2cd01a0d0d7) — Add VACUUM/ANALYZE BUFFER_USAGE_LIMIT option |
| Commit date | 2023-04-07 |
| Discussion | [thread 1](https://postgr.es/m/20230111182720.ejifsclfwymw2reb@awork3.anarazel.de) |

## Default history {#default-history}

| Versions | Raw `boot_val` | Unit | Human value |
| --- | --- | --- | --- |
| PG16 | `256` | `kB` | 256 KiB |
| PG17–19 Beta 3 | `2048` | `kB` | 2 MiB |
{.full-width caption="Measured PG9.0–19 Beta 3 boot defaults"}

## How it works {#mechanism}

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 {#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. |
{.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 | Unmodified | — | — |
| OLAP | Unmodified | — | — |
| CRIT | Unmodified | — | — |
| TINY | Unmodified | — | — |
{.full-width}

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

## Related parameters {#related-parameters}

[`shared_buffers`](/parameters/shared-buffers/) · [`maintenance_work_mem`](/parameters/maintenance-work-mem/) · [`autovacuum_work_mem`](/parameters/autovacuum-work-mem/) · [`maintenance_io_concurrency`](/parameters/maintenance-io-concurrency/) · [`track_io_timing`](/parameters/track-io-timing/)

## References {#references}

- [PostgreSQL 19 Beta 3 — vacuum_buffer_usage_limit](https://www.postgresql.org/docs/19/runtime-config-resource.html#GUC-VACUUM-BUFFER-USAGE-LIMIT)
- [PostgreSQL 19 release notes](https://www.postgresql.org/docs/19/release-19.html)
- [Machine-readable GUC export](/data/guc.jsonl)