<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>15.2. When Can Parallel Query Be Used?</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="how-parallel-query-works.html" title="15.1. How Parallel Query Works" /><link rel="next" href="parallel-plans.html" title="15.3. Parallel Plans" /></head><body><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">15.2. When Can Parallel Query Be Used?</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="how-parallel-query-works.html" title="15.1. How Parallel Query Works">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="parallel-query.html" title="Chapter 15. Parallel Query">Up</a></td><th width="60%" align="center">Chapter 15. Parallel Query</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 11.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="parallel-plans.html" title="15.3. Parallel Plans">Next</a></td></tr></table><hr></hr></div><div class="sect1" id="WHEN-CAN-PARALLEL-QUERY-BE-USED"><div class="titlepage"><div><div><h2 class="title" style="clear: both">15.2. When Can Parallel Query Be Used?</h2></div></div></div><p>
There are several settings which can cause the query planner not to
generate a parallel query plan under any circumstances. In order for
any parallel query plans whatsoever to be generated, the following
settings must be configured as indicated.
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<a class="xref" href="runtime-config-resource.html#GUC-MAX-PARALLEL-WORKERS-PER-GATHER">max_parallel_workers_per_gather</a> must be set to a
value which is greater than zero. This is a special case of the more
general principle that no more workers should be used than the number
configured via <code class="varname">max_parallel_workers_per_gather</code>.
</p></li><li class="listitem"><p>
<a class="xref" href="runtime-config-resource.html#GUC-DYNAMIC-SHARED-MEMORY-TYPE">dynamic_shared_memory_type</a> must be set to a
value other than <code class="literal">none</code>. Parallel query requires dynamic
shared memory in order to pass data between cooperating processes.
</p></li></ul></div><p>
In addition, the system must not be running in single-user mode. Since
the entire database system is running in single process in this situation,
no background workers will be available.
</p><p>
Even when it is in general possible for parallel query plans to be
generated, the planner will not generate them for a given query
if any of the following are true:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The query writes any data or locks any database rows. If a query
contains a data-modifying operation either at the top level or within
a CTE, no parallel plans for that query will be generated. As an
exception, the commands <code class="literal">CREATE TABLE ... AS</code>, <code class="literal">SELECT
INTO</code>, and <code class="literal">CREATE MATERIALIZED VIEW</code> which create a new
table and populate it can use a parallel plan.
</p></li><li class="listitem"><p>
The query might be suspended during execution. In any situation in
which the system thinks that partial or incremental execution might
occur, no parallel plan is generated. For example, a cursor created
using <a class="link" href="sql-declare.html" title="DECLARE">DECLARE CURSOR</a> will never use
a parallel plan. Similarly, a PL/pgSQL loop of the form
<code class="literal">FOR x IN query LOOP .. END LOOP</code> will never use a
parallel plan, because the parallel query system is unable to verify
that the code in the loop is safe to execute while parallel query is
active.
</p></li><li class="listitem"><p>
The query uses any function marked <code class="literal">PARALLEL UNSAFE</code>.
Most system-defined functions are <code class="literal">PARALLEL SAFE</code>,
but user-defined functions are marked <code class="literal">PARALLEL
UNSAFE</code> by default. See the discussion of
<a class="xref" href="parallel-safety.html" title="15.4. Parallel Safety">Section 15.4</a>.
</p></li><li class="listitem"><p>
The query is running inside of another query that is already parallel.
For example, if a function called by a parallel query issues an SQL
query itself, that query will never use a parallel plan. This is a
limitation of the current implementation, but it may not be desirable
to remove this limitation, since it could result in a single query
using a very large number of processes.
</p></li><li class="listitem"><p>
The transaction isolation level is serializable. This is
a limitation of the current implementation.
</p></li></ul></div><p>
Even when parallel query plan is generated for a particular query, there
are several circumstances under which it will be impossible to execute
that plan in parallel at execution time. If this occurs, the leader
will execute the portion of the plan below the <code class="literal">Gather</code>
node entirely by itself, almost as if the <code class="literal">Gather</code> node were
not present. This will happen if any of the following conditions are met:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
No background workers can be obtained because of the limitation that
the total number of background workers cannot exceed
<a class="xref" href="runtime-config-resource.html#GUC-MAX-WORKER-PROCESSES">max_worker_processes</a>.
</p></li><li class="listitem"><p>
No background workers can be obtained because of the limitation that
the total number of background workers launched for purposes of
parallel query cannot exceed <a class="xref" href="runtime-config-resource.html#GUC-MAX-PARALLEL-WORKERS">max_parallel_workers</a>.
</p></li><li class="listitem"><p>
The client sends an Execute message with a non-zero fetch count.
See the discussion of the
<a class="link" href="protocol-flow.html#PROTOCOL-FLOW-EXT-QUERY" title="53.2.3. Extended Query">extended query protocol</a>.
Since <a class="link" href="libpq.html" title="Chapter 34. libpq - C Library">libpq</a> currently provides no way to
send such a message, this can only occur when using a client that
does not rely on libpq. If this is a frequent
occurrence, it may be a good idea to set
<a class="xref" href="runtime-config-resource.html#GUC-MAX-PARALLEL-WORKERS-PER-GATHER">max_parallel_workers_per_gather</a> to zero in
sessions where it is likely, so as to avoid generating query plans
that may be suboptimal when run serially.
</p></li><li class="listitem"><p>
The transaction isolation level is serializable. This situation
does not normally arise, because parallel query plans are not
generated when the transaction isolation level is serializable.
However, it can happen if the transaction isolation level is changed to
serializable after the plan is generated and before it is executed.
</p></li></ul></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="how-parallel-query-works.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="parallel-query.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="parallel-plans.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">15.1. How Parallel Query Works </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 15.3. Parallel Plans</td></tr></table></div></body></html>
