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

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

## Lifecycle {#lifecycle}

| Fact | Value |
| --- | --- |
| First observed | PG11 |
| Present in | PG11–19 Beta 3 |
| Removed in | No |
| Introduction commit | [`9da0cc35284b`](https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=9da0cc35284bdbe8d442d732963303ff0e0a40bc) — Support parallel btree index builds. |
| Commit date | 2018-02-02 |
| Discussion | [thread 1](https://postgr.es/m/CAM3SWZQKM=Pzc=CAHzRixKjp2eO5Q0Jg1SoFQqeXFQ647JiwqQ@mail.gmail.com) · [thread 2](https://postgr.es/m/CAH2-Wz=AxWqDoVvGU7dq856S4r6sJAj6DBn7VMtigkB33N5eyg@mail.gmail.com) |

## Default history {#default-history}

| Versions | Raw `boot_val` | Unit | Human value |
| --- | --- | --- | --- |
| PG11–19 Beta 3 | `2` | — | 2 |
{.full-width caption="Measured PG9.0–19 Beta 3 boot defaults"}

## How it works {#mechanism}

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 {#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. |
{.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 | `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 }}` |
{.full-width}

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

## Related parameters {#related-parameters}

[`max_parallel_workers`](/parameters/max-parallel-workers/) · [`max_worker_processes`](/parameters/max-worker-processes/) · [`maintenance_work_mem`](/parameters/maintenance-work-mem/) · [`maintenance_io_concurrency`](/parameters/maintenance-io-concurrency/) · [`max_parallel_workers_per_gather`](/parameters/max-parallel-workers-per-gather/)

## References {#references}

- [PostgreSQL 19 Beta 3 — max_parallel_maintenance_workers](https://www.postgresql.org/docs/19/runtime-config-resource.html#GUC-MAX-PARALLEL-MAINTENANCE-WORKERS)
- [PostgreSQL 19 release notes](https://www.postgresql.org/docs/19/release-19.html)
- [Machine-readable GUC export](/data/guc.jsonl)