max_parallel_workers_per_gather

max_parallel_workers_per_gather — Sets the maximum number of parallel processes per executor node. Observed in PG9.6–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 executor node.”

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	PG9.6
Present in	PG9.6–19 Beta 3
Removed in	No
Introduction commit	`c9ce4a1c61eb` — Eliminate “parallel degree” terminology.
Commit date	2016-06-09
Discussion	—

Default history

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

How it works

max_parallel_workers_per_gather limits how many workers one Gather or Gather Merge node may request. Zero prevents parallel query execution through these nodes without disabling other background workers.

Workers are not reserved and can be unavailable at execution time because max_parallel_workers and max_worker_processes are shared pools. The leader process is not included in this numeric limit.

Each parallel plan can multiply work_mem-limited nodes, CPU demand, and I/O. The planner weighs parallel_setup_cost and parallel_tuple_cost before deciding whether to request workers. 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_workers_per_gather 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_workers_per_gather, 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_workers_per_gather 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	`2`	same as boot	`{{ pg_max_parallel_workers_per_gather\|int }}`
OLAP	`4`	different	`{{ pg_max_parallel_workers_per_gather\|int }}`
CRIT	`0`	different	`{{ pg_max_parallel_workers_per_gather\|int }}`
TINY	`0`	different	`{{ pg_max_parallel_workers_per_gather\|int }}`

Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG9.6–19 Beta 3 = 2 (dcs); OLAP: PG9.6–19 Beta 3 = 4 (dcs); CRIT: PG9.6–19 Beta 3 = 0 (dcs); TINY: PG9.6–19 Beta 3 = 0 (dcs). Advice, pending human review — Editorial inference, pending maintainer review: The values allow modest OLTP and stronger OLAP query parallelism while explicitly suppressing Gather workers in crit and tiny profiles.

Common pitfalls

Treating max_parallel_workers_per_gather 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 · parallel_setup_cost · parallel_tuple_cost · parallel_leader_participation · work_mem