{"Entry":{"collection":"guc","key":"max_parallel_workers_per_gather","name":"max_parallel_workers_per_gather","aliases":[],"metadata":{"baseline":false,"boot_human":"Not specified","boot_val":null,"category":"Resource Usage / Worker Processes","category_zh":"","changed_in":["10","18"],"changes":[{"documentation_changed":false,"fields":{},"from":"9.5","status":"added","to":"9.6"},{"documentation_changed":true,"fields":{"boot_val":{"from":"0","to":"2"}},"from":"9.6","status":"changed","to":"10"},{"documentation_changed":false,"fields":{"category":{"from":"Resource Usage / Asynchronous Behavior","to":"Resource Usage / Worker Processes"}},"from":"17","status":"changed","to":"18"}],"content_hash":"3f344009efdc0f42790ae3b4010e1a812a466da8a70f1f402175f61338c6ab33","context":"","default_changed_in":["10"],"default_history":[{"from":"9.6","to":"9.6","value":"0"},{"from":"10","to":"19","value":"2"}],"editorial":{"advice":{"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.","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.","small":"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."},"mechanism":["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."],"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."],"references":[{"title":"PostgreSQL 19 Beta 4: max_parallel_workers_per_gather","url":"https://www.postgresql.org/docs/19/runtime-config-resource.html#GUC-MAX-PARALLEL-WORKERS-PER-GATHER"},{"title":"PostgreSQL 19 release notes","url":"https://www.postgresql.org/docs/19/release-19.html"}],"related":["max_parallel_workers","max_worker_processes","parallel_setup_cost","parallel_tuple_cost","parallel_leader_participation","work_mem"],"summary":"max_parallel_workers_per_gather — Sets the maximum number of parallel processes per executor node. Observed in PG9.6–19 Beta 4; its last measured boot default is 2 in PG19 Beta 4, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA."},"enumvals":[],"first_version":"9.6","group":"Resource Usage","group_slug":"resource","imported_at":"2026-09-27T17:57:31.717675+08:00","intro_commit":{"authored_at":"2016-06-09T09:08:27-04:00","discussion":[],"hash":"c9ce4a1c61ebf39c03885cc19fe7c32edc04a300","subject":"Eliminate \"parallel degree\" terminology.","url":"https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=c9ce4a1c61ebf39c03885cc19fe7c32edc04a300"},"key":"max_parallel_workers_per_gather","last_version":"20","max_val":"","min_val":"","name":"max_parallel_workers_per_gather","position":276,"present_in":["9.6","10","11","12","13","14","15","16","17","18","19","20"],"short_desc":"Sets the maximum number of workers that can be started by a single Gather or Gather Merge node.","short_desc_zh":"","source_rev":"english-manuals:c6d1f546c3eb93a0932d2259231ef6bd27d4de5edc1cf0c3066a9e78f57b92cc","unit":"","vartype":"integer"}},"Definition":{"Collection":"guc","Key":"max_parallel_workers_per_gather","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"max_parallel_workers_per_gather","SourceRevision":"english-manuals:c6d1f546c3eb93a0932d2259231ef6bd27d4de5edc1cf0c3066a9e78f57b92cc","Facts":{"boot_val":"2","category":"Resource Usage / Worker Processes","context":"user","description":"Sets the maximum number of workers that can be started by a single Gather or Gather Merge node. 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 plan will run with fewer workers than expected, which may be inefficient. The default value is 2. Setting this value to 0 disables parallel query execution. Note that parallel queries may consume very substantially more resources than non-parallel queries, because each worker process is a completely separate process which has roughly the same impact on the system as an additional user session. This should be taken into account when choosing a value for this setting, as well as when configuring other settings that control resource utilization, such as work_mem. Resource limits such as work_mem are applied individually to each worker, which means the total utilization may be much higher across all processes than it would normally be for any single process. For example, a parallel query using 4 workers may use up to 5 times as much CPU time, memory, I/O bandwidth, and so forth as a query which uses no workers at all. For more information on parallel query, see Chapter 15.","doc":{"anchor":"GUC-MAX-PARALLEL-WORKERS-PER-GATHER","file":"runtime-config-resource.html","lang":"en","sha256":"2e207c599f0884dfbe594558c478a2c7c132578981071e980e2015f31dfce28c","slug":"18"},"documented":true,"enumvals":null,"extra_desc":null,"lang":"en","max_val":"1024","metadata_version":"18","min_val":"0","name":"max_parallel_workers_per_gather","short_desc":"Sets the maximum number of parallel processes per executor node.","source":"pg-settings-source-snapshot","unit":null,"vartype":"integer"},"ManualEvidence":{"doc":{"anchor":"GUC-MAX-PARALLEL-WORKERS-PER-GATHER","file":"runtime-config-resource.html","lang":"en","sha256":"2e207c599f0884dfbe594558c478a2c7c132578981071e980e2015f31dfce28c","slug":"18"}},"MeasuredEvidence":{"metadata_version":"18"}},"Text":{"Collection":"guc","Key":"max_parallel_workers_per_gather","SourceDatabase":"pgweb","Version":"18","Locale":"zh-Hans","Title":"max_parallel_workers_per_gather","Summary":"","BodyHTML":"\u003cp\u003e设置单个 \u003ccode\u003eGather\u003c/code\u003e 或 \u003ccode\u003eGather Merge\u003c/code\u003e 节点能够启动的工作进程的最大数量。并行工作进程取自\u003ca href=\"/docs/18/runtime-config-resource.html#GUC-MAX-WORKER-PROCESSES\" rel=\"nofollow\"\u003emax_worker_processes\u003c/a\u003e建立的进程池，并受到\u003ca href=\"/docs/18/runtime-config-resource.html#GUC-MAX-PARALLEL-WORKERS\" rel=\"nofollow\"\u003emax_parallel_workers\u003c/a\u003e的限制。注意，运行时实际可用的工作进程可能不足请求的数量。此时，计划会使用少于预期的工作进程运行，效率可能较低。默认值为 2。设为 0 会禁用并行查询执行。\u003c/p\u003e\u003cp\u003e注意，并行查询消耗的资源可能远多于非并行查询，因为每个工作进程都是完全独立的进程，对系统的影响大致相当于额外增加一个用户会话。选择此设置的值，以及配置其他控制资源使用的设置（如\u003ca href=\"/docs/18/runtime-config-resource.html#GUC-WORK-MEM\" rel=\"nofollow\"\u003ework_mem\u003c/a\u003e）时，都应考虑这一点。\u003ccode\u003ework_mem\u003c/code\u003e 等资源限制分别应用于每个工作进程，因此所有进程的总资源用量可能远高于单个进程通常的用量。例如，使用 4 个工作进程的并行查询，其 CPU 时间、内存、I/O 带宽等用量可能达到完全不使用工作进程的查询的 5 倍。\u003c/p\u003e\u003cp\u003e并行查询的更多信息参见\u003ca href=\"/docs/18/parallel-query.html\" rel=\"nofollow\"\u003e第 15 章\u003c/a\u003e。\u003c/p\u003e","SourceRevision":"2026-09-11@29c86d9","ContentHash":"30d7b969ced800bdb22cd2147a692a80679a59076d4c8226c859520522d78f0a","Payload":{"carried_from":"","carry_reason":"","doc_html":"\u003cp\u003e设置单个 \u003ccode class=\"literal\"\u003eGather\u003c/code\u003e 或 \u003ccode class=\"literal\"\u003eGather Merge\u003c/code\u003e 节点能够启动的工作进程的最大数量。并行工作进程取自\u003ca href=\"/docs/18/runtime-config-resource.html#GUC-MAX-WORKER-PROCESSES\"\u003emax_worker_processes\u003c/a\u003e建立的进程池，并受到\u003ca href=\"/docs/18/runtime-config-resource.html#GUC-MAX-PARALLEL-WORKERS\"\u003emax_parallel_workers\u003c/a\u003e的限制。注意，运行时实际可用的工作进程可能不足请求的数量。此时，计划会使用少于预期的工作进程运行，效率可能较低。默认值为 2。设为 0 会禁用并行查询执行。\u003c/p\u003e\u003cp\u003e注意，并行查询消耗的资源可能远多于非并行查询，因为每个工作进程都是完全独立的进程，对系统的影响大致相当于额外增加一个用户会话。选择此设置的值，以及配置其他控制资源使用的设置（如\u003ca href=\"/docs/18/runtime-config-resource.html#GUC-WORK-MEM\"\u003ework_mem\u003c/a\u003e）时，都应考虑这一点。\u003ccode class=\"varname\"\u003ework_mem\u003c/code\u003e 等资源限制分别应用于每个工作进程，因此所有进程的总资源用量可能远高于单个进程通常的用量。例如，使用 4 个工作进程的并行查询，其 CPU 时间、内存、I/O 带宽等用量可能达到完全不使用工作进程的查询的 5 倍。\u003c/p\u003e\u003cp\u003e并行查询的更多信息参见\u003ca href=\"/docs/18/parallel-query.html\" title=\"第 15 章 并行查询\"\u003e第 15 章\u003c/a\u003e。\u003c/p\u003e","doc_same_as":""}},"RequestedLocale":"zh-Hans","Fallback":false,"Versions":["10","11","12","13","14","15","16","17","18","19","20","9.6"],"Locales":["en","zh-Hans"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}