max_parallel_maintenance_workers

Definition PG 18 manual

Sets the maximum number of parallel workers that can be started by a single utility command. Currently, the parallel utility commands that support the use of parallel workers are CREATE INDEX when building a B-tree, GIN, or BRIN index, and VACUUM without FULL option. Parallel workers are taken from the pool of processes established by max_worker_processes, limited by max_parallel_workers. Note that the requested number of workers may not actually be available at run time. If this occurs, the utility operation will run with fewer workers than expected. The default value is 2. Setting this value to 0 disables the use of parallel workers by utility commands.

Note that parallel utility commands should not consume substantially more memory than equivalent non-parallel operations. This strategy differs from that of parallel query, where resource limits generally apply per worker process. Parallel utility commands treat the resource limit maintenance_work_mem as a limit to be applied to the entire utility command, regardless of the number of parallel worker processes. However, parallel utility commands may still consume substantially more CPU resources and I/O bandwidth.

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.

Operational considerations

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.

Workload guidance

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.

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.

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