max_parallel_maintenance_workers

max_parallel_maintenance_workers — Sets the maximum number of parallel processes per maintenance operation. Observed in PG11–19 Beta 3; its last measured boot default is 2 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 maximum number of parallel processes per maintenance operation.”

Identity

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

Lifecycle

Fact	Value
First observed	PG11
Present in	PG11–19 Beta 3
Removed in	No
Introduction commit	`9da0cc35284b` — Support parallel btree index builds.
Commit date	2018-02-02
Discussion	thread 1 · thread 2

Default history

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

How it works

max_parallel_maintenance_workers caps workers requested by one supported maintenance command, such as parallel CREATE INDEX or VACUUM. The leader is additional and may also perform work.

The cap does not reserve workers or guarantee they will be available. Requests compete within max_parallel_workers and max_worker_processes, and operation-specific rules can choose fewer.

Parallel maintenance can multiply CPU and I/O pressure; CREATE INDEX memory follows maintenance-specific accounting rather than simply granting maintenance_work_mem independently to every worker. 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	Set max_parallel_maintenance_workers from a concurrency budget, not core count alone. Protect latency-sensitive OLTP from report and maintenance bursts, and verify actual Workers Planned versus Workers Launched.
OLAP	Analytical work can use a larger max_parallel_maintenance_workers, but multiply per-node memory and I/O by concurrent statements. Benchmark throughput under realistic worker contention rather than one isolated query.
Small nodes	Keep max_parallel_maintenance_workers conservative on a small host. More possible workers can reduce throughput through context switching and memory pressure even when a single query becomes faster.

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

Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG11–19 Beta 3 = 3 (dcs); OLAP: PG11–19 Beta 3 = 3 (dcs); CRIT: PG11–19 Beta 3 = 3 (dcs); TINY: PG11–19 Beta 3 = 2 (dcs). Advice, pending human review — Editorial inference, pending maintainer review: The profile variables allocate modest parallel maintenance capacity, with one fewer worker in the tiny fixture to reduce resource pressure.

Common pitfalls

Treating max_parallel_maintenance_workers as reserved capacity rather than an upper bound shared with other work.
Ignoring that parallel plans multiply CPU, I/O, and work_mem-limited nodes.
Benchmarking one query without concurrent worker contention.
Assuming planned workers will always be launched at execution time.

max_parallel_workers · max_worker_processes · maintenance_work_mem · maintenance_io_concurrency · max_parallel_workers_per_gather