{"Entry":{"collection":"guc","key":"debug_parallel_query","name":"debug_parallel_query","aliases":[],"metadata":{"baseline":false,"boot_human":"Not specified","boot_val":null,"category":"Developer Options","category_zh":"","changed_in":[],"changes":[{"documentation_changed":false,"fields":{},"from":"15","status":"added","to":"16"}],"content_hash":"d4b594291345de8b4d5f63dad9801f23470aa651b72efde83f218b81d32fdc68","context":"","default_changed_in":[],"default_history":[{"from":"16","to":"19","value":"off"}],"derived_content_hash":"06cc82fe199583d68bf7ee73bd0aabaae54db58f137c925fa6e614036e21ca0f","documentation_refresh":{"batch":"20261113","original_source_rev":"wiki-repair-20261023:b6c5a3975c8e17dc40f13ffe34de7dd417cf00d9193ec3cbf375ee3607b3f44d","versions":{"16":"16.16","17":"17.12","18":"18.7","19":"19rc2"}},"editorial":{"advice":{"olap":"Long analytical runs can amplify debug_parallel_query's debug overhead and artifacts. Prefer standard EXPLAIN and statistics first, and isolate any developer experiment from normal users.","oltp":"Do not tune production OLTP with debug_parallel_query. Enable it only for a bounded reproduction with an owner, log/disk budget, rollback condition, and evidence-capture plan; restore the default immediately afterward.","small":"Keep debug_parallel_query at its upstream default. A small host has less spare CPU, disk, connection, and log capacity for developer instrumentation."},"mechanism":["debug_parallel_query forces safe queries through parallel mode even when no performance benefit is expected. on adds a top-level Gather where safe; regress also hides testing-only output differences.","Parallel-safety restrictions still apply. The forced context can expose functions incorrectly marked parallel safe and can prohibit operations such as subtransactions even when no worker is ultimately available.","It replaced the earlier force_parallel_mode name in PG16. Its purpose is regression testing, not making production queries faster or overriding all parallel cost decisions. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value."],"pitfalls":["Leaving debug_parallel_query enabled after the bounded diagnostic or recovery task.","Running the experiment on the only copy of production data.","Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.","Treating a server that merely starts or completes a query as proof that data and behavior are correct."],"references":[{"title":"PostgreSQL 19 Beta 4: debug_parallel_query","url":"https://www.postgresql.org/docs/19/runtime-config-developer.html#GUC-DEBUG-PARALLEL-QUERY"},{"title":"PostgreSQL 19 release notes","url":"https://www.postgresql.org/docs/19/release-19.html"}],"related":["force_parallel_mode","max_parallel_workers_per_gather","max_parallel_workers","parallel_setup_cost","parallel_leader_participation"],"summary":"debug_parallel_query — Forces the planner's use parallel query nodes. Observed in PG16–19 Beta 4; its last measured boot default is off in PG19 Beta 4, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA."},"enumvals":[],"first_version":"16","group":"Developer Options","group_slug":"developer","imported_at":"2026-09-27T17:57:31.053974+08:00","intro_commit":{"authored_at":"2023-02-15T21:21:59+13:00","discussion":["https://postgr.es/m/CAApHDvrsOi92_uA7PEaHZMH-S4Xv+MGhQWA+GrP8b1kjpS1HjQ@mail.gmail.com"],"hash":"5352ca22e0012d48055453ca9992a9515d811291","subject":"Rename force_parallel_mode to debug_parallel_query","url":"https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=5352ca22e0012d48055453ca9992a9515d811291"},"key":"debug_parallel_query","last_version":"20","max_val":"","min_val":"","name":"debug_parallel_query","position":89,"present_in":["16","17","18","19","20"],"repair_provenance":{"original_source_revision":"english-manuals:d349d33f273b83884b8a33699cf1f9bc6c7d372c16df875eda1e690ee4d5145a","receipt_sha256":"44e0f29a73cb18dc04d872fe2af825cb134255ad48a18fa7933b4ec31c88b0ac","repair":"wiki-repair-20261023"},"short_desc":"Allows the use of parallel queries for testing purposes even in cases where no performance benefit is expected.","short_desc_zh":"","source_rev":"wiki-repair-20261023:b6c5a3975c8e17dc40f13ffe34de7dd417cf00d9193ec3cbf375ee3607b3f44d","unit":"","vartype":"enum"}},"Definition":{"Collection":"guc","Key":"debug_parallel_query","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"debug_parallel_query","SourceRevision":"wiki-repair-20261023:b6c5a3975c8e17dc40f13ffe34de7dd417cf00d9193ec3cbf375ee3607b3f44d","Facts":{"boot_val":"off","category":"Developer Options","context":"user","description":"Allows the use of parallel queries for testing purposes even in cases where no performance benefit is expected. The allowed values of debug_parallel_query are off (use parallel mode only when it is expected to improve performance), on (force parallel query for all queries for which it is thought to be safe), and regress (like on, but with additional behavior changes as explained below). More specifically, setting this value to on will add a Gather node to the top of any query plan for which this appears to be safe, so that the query runs inside of a parallel worker. Even when a parallel worker is not available or cannot be used, operations such as starting a subtransaction that would be prohibited in a parallel query context will be prohibited unless the planner believes that this will cause the query to fail. If failures or unexpected results occur when this option is set, some functions used by the query may need to be marked PARALLEL UNSAFE (or, possibly, PARALLEL RESTRICTED). Setting this value to regress has all of the same effects as setting it to on plus some additional effects that are intended to facilitate automated regression testing. Normally, messages from a parallel worker include a context line indicating that, but a setting of regress suppresses this line so that the output is the same as in non-parallel execution. Also, the Gather nodes added to plans by this setting are hidden in EXPLAIN output so that the output matches what would be obtained if this setting were turned off.","description_zh":"允许出于测试目的使用并行查询，即使预计不会带来性能收益也是如此。debug_parallel_query 的允许值为 off（仅在预期会提高性能时使用并行模式），on（对所有被认为安全的查询强制使用并行查询），以及 regress（类似于 on，但有下文所述的额外行为变化）。 更具体地说，将该值设置为 on 会在任何看起来安全的查询计划顶部添加一个 Gather 节点，以便查询在并行工作进程中运行。即使并行工作进程不可用或无法使用，启动子事务等在并行查询上下文中被禁止的操作也将被禁止，除非规划器认为这样会导致查询失败。如果设置此选项时出现故障或意外结果，则可能需要将查询使用的一些函数标记为 PARALLEL UNSAFE（或可能是 PARALLEL RESTRICTED）。 将该值设置为 regress 会产生与设置为 on 相同的所有效果，并额外启用一些行为，以便进行自动回归测试。通常，来自并行工作进程的消息会包含一行上下文说明，但 regress 会抑制这一行，因此输出与非并行执行时相同。此外，由该设置添加到计划中的 Gather 节点会在 EXPLAIN 输出中被隐藏，以便输出与此设置为 off 时得到的结果一致。","description_zh_html":"\u003cp\u003e\n        允许出于测试目的使用并行查询，即使预计不会带来性能收益也是如此。\u003ccode class=\"varname\"\u003edebug_parallel_query\u003c/code\u003e 的允许值为 \u003ccode class=\"literal\"\u003eoff\u003c/code\u003e（仅在预期会提高性能时使用并行模式），\u003ccode class=\"literal\"\u003eon\u003c/code\u003e（对所有被认为安全的查询强制使用并行查询），以及 \u003ccode class=\"literal\"\u003eregress\u003c/code\u003e（类似于 \u003ccode class=\"literal\"\u003eon\u003c/code\u003e，但有下文所述的额外行为变化）。\n       \u003c/p\u003e\u003cp\u003e\n        更具体地说，将该值设置为 \u003ccode class=\"literal\"\u003eon\u003c/code\u003e 会在任何看起来安全的查询计划顶部添加一个\n        \u003ccode class=\"literal\"\u003eGather\u003c/code\u003e 节点，以便查询在并行工作进程中运行。即使并行工作进程不可用或无法使用，启动子事务等在并行查询上下文中被禁止的操作也将被禁止，除非规划器认为这样会导致查询失败。如果设置此选项时出现故障或意外结果，则可能需要将查询使用的一些函数标记为\n        \u003ccode class=\"literal\"\u003ePARALLEL UNSAFE\u003c/code\u003e（或可能是 \u003ccode class=\"literal\"\u003ePARALLEL RESTRICTED\u003c/code\u003e）。\n       \u003c/p\u003e\u003cp\u003e\n        将该值设置为 \u003ccode class=\"literal\"\u003eregress\u003c/code\u003e 会产生与设置为 \u003ccode class=\"literal\"\u003eon\u003c/code\u003e 相同的所有效果，并额外启用一些行为，以便进行自动回归测试。通常，来自并行工作进程的消息会包含一行上下文说明，但 \u003ccode class=\"literal\"\u003eregress\u003c/code\u003e 会抑制这一行，因此输出与非并行执行时相同。此外，由该设置添加到计划中的 \u003ccode class=\"literal\"\u003eGather\u003c/code\u003e 节点会在 \u003ccode class=\"literal\"\u003eEXPLAIN\u003c/code\u003e 输出中被隐藏，以便输出与此设置为 \u003ccode class=\"literal\"\u003eoff\u003c/code\u003e 时得到的结果一致。\n       \u003c/p\u003e","doc":{"anchor":"GUC-DEBUG-PARALLEL-QUERY","file":"runtime-config-developer.html","lang":"en","sha256":"a3f6a107ed6ba4edaf6df03e52f4a469bd09350d545e4ff419e62844025ec1cf","slug":"18"},"doc_html":"\u003cp\u003e\n        Allows the use of parallel queries for testing purposes even in cases\n        where no performance benefit is expected.\n        The allowed values of \u003ccode class=\"varname\"\u003edebug_parallel_query\u003c/code\u003e are\n        \u003ccode class=\"literal\"\u003eoff\u003c/code\u003e (use parallel mode only when it is expected to improve\n        performance), \u003ccode class=\"literal\"\u003eon\u003c/code\u003e (force parallel query for all queries\n        for which it is thought to be safe), and \u003ccode class=\"literal\"\u003eregress\u003c/code\u003e (like\n        \u003ccode class=\"literal\"\u003eon\u003c/code\u003e, but with additional behavior changes as explained\n        below).\n       \u003c/p\u003e\u003cp\u003e\n        More specifically, setting this value to \u003ccode class=\"literal\"\u003eon\u003c/code\u003e will add\n        a \u003ccode class=\"literal\"\u003eGather\u003c/code\u003e node to the top of any query plan for which this\n        appears to be safe, so that the query runs inside of a parallel worker.\n        Even when a parallel worker is not available or cannot be used,\n        operations such as starting a subtransaction that would be prohibited\n        in a parallel query context will be prohibited unless the planner\n        believes that this will cause the query to fail.  If failures or\n        unexpected results occur when this option is set, some functions used\n        by the query may need to be marked \u003ccode class=\"literal\"\u003ePARALLEL UNSAFE\u003c/code\u003e\n        (or, possibly, \u003ccode class=\"literal\"\u003ePARALLEL RESTRICTED\u003c/code\u003e).\n       \u003c/p\u003e\u003cp\u003e\n        Setting this value to \u003ccode class=\"literal\"\u003eregress\u003c/code\u003e has all of the same effects\n        as setting it to \u003ccode class=\"literal\"\u003eon\u003c/code\u003e plus some additional effects that are\n        intended to facilitate automated regression testing.  Normally,\n        messages from a parallel worker include a context line indicating that,\n        but a setting of \u003ccode class=\"literal\"\u003eregress\u003c/code\u003e suppresses this line so that the\n        output is the same as in non-parallel execution.  Also,\n        the \u003ccode class=\"literal\"\u003eGather\u003c/code\u003e nodes added to plans by this setting are hidden\n        in \u003ccode class=\"literal\"\u003eEXPLAIN\u003c/code\u003e output so that the output matches what\n        would be obtained if this setting were turned \u003ccode class=\"literal\"\u003eoff\u003c/code\u003e.\n       \u003c/p\u003e","doc_same_as":"","documentation_revision":{"inputs":[{"file":"runtime-config-developer.html","kind":"same-version-reviewed-manual","locale":"en","sha256":"a3f6a107ed6ba4edaf6df03e52f4a469bd09350d545e4ff419e62844025ec1cf","version":"18.7"},{"file":"runtime-config-developer.html","kind":"same-version-reviewed-manual","locale":"zh-Hans","sha256":"e7e22aa5738a1d376b84af1adca796c5e14746266733f925eb50c3ef86a50655","version":"18.7"}],"release":"18.7","runtime_remeasured":false,"source_revision":"pgdoc:b9f0e7232f60f380d642ac9b99226606c254b552"},"documented":true,"enumvals":["off","on","regress"],"extra_desc":"This can be useful for testing the parallel query infrastructure by forcing the planner to generate plans that contain nodes that perform tuple communication between workers and the main process.","lang":"en","max_val":null,"metadata_version":"18","min_val":null,"name":"debug_parallel_query","short_desc":"Forces the planner's use parallel query nodes.","source":"pg-settings-source-snapshot","translation_provenance":{"inputs":[{"kind":"current-pgdoc-translation","path":"/Users/vonng/pgsty/pgdoc/zh/18/html/runtime-config-developer.html","sha256":"3c08bf624188bbb0733dc7854e61c0c251c2578311ac3dc8fa626ab21b7911d1"}],"kind":"same-version-pgdoc","locale":"zh-Hans","source_revision":"b1b500221dbe5437cfca004d6b04d3f6e422765d","version":"18"},"unit":null,"vartype":"enum","zh_from":"same-version-manual"},"ManualEvidence":{"doc":{"anchor":"GUC-DEBUG-PARALLEL-QUERY","file":"runtime-config-developer.html","lang":"en","sha256":"a3f6a107ed6ba4edaf6df03e52f4a469bd09350d545e4ff419e62844025ec1cf","slug":"18"}},"MeasuredEvidence":{"metadata_version":"18"}},"Text":{"Collection":"guc","Key":"debug_parallel_query","SourceDatabase":"center","Version":"18","Locale":"en","Title":"debug_parallel_query","Summary":"Allows the use of parallel queries for testing purposes even in cases where no performance benefit is expected. The allowed values of debug_parallel_query are off (use parallel mode only when it is expected to improve performance), on (force parallel query for all queries for which it is thought to be safe), and regress (like on, but with additional behavior changes as explained below). More specifically, setting this value to on will add a Gather node to the top of any query plan for which this appears to be safe, so that the query runs inside of a parallel worker. Even when a parallel worker is not available or cannot be used, operations such as starting a subtransaction that would be prohibited in a parallel query context will be prohibited unless the planner believes that this will cause the query to fail. If failures or unexpected results occur when this option is set, some functions used by the query may need to be marked PARALLEL UNSAFE (or, possibly, PARALLEL RESTRICTED). Setting this value to regress has all of the same effects as setting it to on plus some additional effects that are intended to facilitate automated regression testing. Normally, messages from a parallel worker include a context line indicating that, but a setting of regress suppresses this line so that the output is the same as in non-parallel execution. Also, the Gather nodes added to plans by this setting are hidden in EXPLAIN output so that the output matches what would be obtained if this setting were turned off.","BodyHTML":"\u003cp\u003e\n        Allows the use of parallel queries for testing purposes even in cases\n        where no performance benefit is expected.\n        The allowed values of \u003ccode\u003edebug_parallel_query\u003c/code\u003e are\n        \u003ccode\u003eoff\u003c/code\u003e (use parallel mode only when it is expected to improve\n        performance), \u003ccode\u003eon\u003c/code\u003e (force parallel query for all queries\n        for which it is thought to be safe), and \u003ccode\u003eregress\u003c/code\u003e (like\n        \u003ccode\u003eon\u003c/code\u003e, but with additional behavior changes as explained\n        below).\n       \u003c/p\u003e\u003cp\u003e\n        More specifically, setting this value to \u003ccode\u003eon\u003c/code\u003e will add\n        a \u003ccode\u003eGather\u003c/code\u003e node to the top of any query plan for which this\n        appears to be safe, so that the query runs inside of a parallel worker.\n        Even when a parallel worker is not available or cannot be used,\n        operations such as starting a subtransaction that would be prohibited\n        in a parallel query context will be prohibited unless the planner\n        believes that this will cause the query to fail.  If failures or\n        unexpected results occur when this option is set, some functions used\n        by the query may need to be marked \u003ccode\u003ePARALLEL UNSAFE\u003c/code\u003e\n        (or, possibly, \u003ccode\u003ePARALLEL RESTRICTED\u003c/code\u003e).\n       \u003c/p\u003e\u003cp\u003e\n        Setting this value to \u003ccode\u003eregress\u003c/code\u003e has all of the same effects\n        as setting it to \u003ccode\u003eon\u003c/code\u003e plus some additional effects that are\n        intended to facilitate automated regression testing.  Normally,\n        messages from a parallel worker include a context line indicating that,\n        but a setting of \u003ccode\u003eregress\u003c/code\u003e suppresses this line so that the\n        output is the same as in non-parallel execution.  Also,\n        the \u003ccode\u003eGather\u003c/code\u003e nodes added to plans by this setting are hidden\n        in \u003ccode\u003eEXPLAIN\u003c/code\u003e output so that the output matches what\n        would be obtained if this setting were turned \u003ccode\u003eoff\u003c/code\u003e.\n       \u003c/p\u003e","SourceRevision":"wiki-repair-20261023:b6c5a3975c8e17dc40f13ffe34de7dd417cf00d9193ec3cbf375ee3607b3f44d","ContentHash":"13903047bbdda10f816caaa6ef6e68e9ef5f8ac2a6d05b39996784a2f87e6c79","Payload":{"description":"Allows the use of parallel queries for testing purposes even in cases where no performance benefit is expected. The allowed values of debug_parallel_query are off (use parallel mode only when it is expected to improve performance), on (force parallel query for all queries for which it is thought to be safe), and regress (like on, but with additional behavior changes as explained below). More specifically, setting this value to on will add a Gather node to the top of any query plan for which this appears to be safe, so that the query runs inside of a parallel worker. Even when a parallel worker is not available or cannot be used, operations such as starting a subtransaction that would be prohibited in a parallel query context will be prohibited unless the planner believes that this will cause the query to fail. If failures or unexpected results occur when this option is set, some functions used by the query may need to be marked PARALLEL UNSAFE (or, possibly, PARALLEL RESTRICTED). Setting this value to regress has all of the same effects as setting it to on plus some additional effects that are intended to facilitate automated regression testing. Normally, messages from a parallel worker include a context line indicating that, but a setting of regress suppresses this line so that the output is the same as in non-parallel execution. Also, the Gather nodes added to plans by this setting are hidden in EXPLAIN output so that the output matches what would be obtained if this setting were turned off."}},"RequestedLocale":"en","Fallback":false,"Versions":["16","17","18","19","20"],"Locales":["en","zh-Hans"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}