autovacuum_max_workers

Sets the cluster-wide ceiling for concurrently running autovacuum workers, excluding the launcher. More workers improve scheduling capacity, but they also increase concurrent maintenance demand.

Note

Fact — official short description: “Sets the maximum number of simultaneously running autovacuum worker processes.”

Identity

Type , Valueinteger: Upstream pg_settings type
Context , Valuesighup: Takes effect after configuration reload
Unit , Value—: Raw unit
Range , Value1 – 262143: Raw limits in the last observed version
Enum values , Value—: — for non-enum types
Category , ValueVacuuming / Automatic Vacuuming: Upstream classification
Latest boot value , Value3: 3

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

Measured PG9.0–19 Beta 3 boot defaults
Versions	Raw `boot_val`	Unit	Human value
PG9.0–19 Beta 3	`3`	—	3

How it works

The launcher starts workers across databases up to this limit. A worker can process one table at a time, several workers may operate in the same database, and these processes do not consume max_connections slots.

In PostgreSQL 18, autovacuum workers are drawn from autovacuum_worker_slots, so setting this value above the slot count has no effect. The local fact matrix also records a context change: PG10-17 required server start, while PG18 makes the setting reloadable.

Autovacuum cost limits are normally balanced among active workers. Raising only the worker count therefore improves concurrency and queueing, but does not necessarily multiply the total permitted maintenance I/O rate.

Tuning advice

Tip

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

Workload	Guidance
OLTP	Increase gradually only when eligible tables wait too long and storage has headroom. Check worker saturation, vacuum duration, I/O latency, and autovacuum_worker_slots together.
OLAP	Large relations can occupy workers for long periods, so extra workers may reduce backlog across databases. Pair any increase with explicit maintenance windows and cost-limit review.
Small nodes	Two or three workers are usually a sensible starting range. Prefer fewer concurrent workers over disabling autovacuum on a constrained host.

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	`3`	same as boot	`3`
OLAP	`3`	same as boot	`3`
CRIT	`3`	same as boot	`3`
TINY	`2`	different	`2`

Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.0–19 Beta 3 = 3 (dcs); OLAP: PG9.0–19 Beta 3 = 3 (dcs); CRIT: PG9.0–19 Beta 3 = 3 (dcs); TINY: PG9.0–19 Beta 3 = 2 (dcs). Advice, pending human review — Editorial hypothesis, pending maintainer review: TINY reduces maintenance concurrency to limit CPU and I/O contention, while the other profiles retain conservative upstream concurrency.

Common pitfalls

A value above autovacuum_worker_slots is ineffective on PostgreSQL 18.
More workers can amplify I/O latency even when backlog improves.
Raising workers alone may not raise aggregate cost-based vacuum throughput.
A few very large tables can occupy all workers and delay unrelated databases.
Changing it on PG10-17 requires restart; PG18 behavior is reloadable.

autovacuum · autovacuum_worker_slots · autovacuum_naptime · autovacuum_vacuum_cost_limit · autovacuum_vacuum_cost_delay · max_worker_processes