begriffs open source - ai-pg/blob - full-docs/html/parallel-safety.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!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.4. Parallel Safety</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="parallel-plans.html" title="15.3. Parallel Plans" /><link rel="next" href="admin.html" title="Part III. Server Administration" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">15.4. Parallel Safety</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="parallel-plans.html" title="15.3. Parallel Plans">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 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="admin.html" title="Part III. Server Administration">Next</a></td></tr></table><hr /></div><div class="sect1" id="PARALLEL-SAFETY"><div class="titlepage"><div><div><h2 class="title" style="clear: both">15.4. Parallel Safety <a href="#PARALLEL-SAFETY" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="parallel-safety.html#PARALLEL-LABELING">15.4.1. Parallel Labeling for Functions and Aggregates</a></span></dt></dl></div><p>
   3     The planner classifies operations involved in a query as either
   4     <em class="firstterm">parallel safe</em>, <em class="firstterm">parallel restricted</em>,
   5     or <em class="firstterm">parallel unsafe</em>.  A parallel safe operation is one that
   6     does not conflict with the use of parallel query.  A parallel restricted
   7     operation is one that cannot be performed in a parallel worker, but that
   8     can be performed in the leader while parallel query is in use.  Therefore,
   9     parallel restricted operations can never occur below a <code class="literal">Gather</code>
  10     or <code class="literal">Gather Merge</code> node, but can occur elsewhere in a plan that
  11     contains such a node.  A parallel unsafe operation is one that cannot
  12     be performed while parallel query is in use, not even in the leader.
  13     When a query contains anything that is parallel unsafe, parallel query
  14     is completely disabled for that query.
  15   </p><p>
  16     The following operations are always parallel restricted:
  17   </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
  18         Scans of common table expressions (CTEs).
  19       </p></li><li class="listitem"><p>
  20         Scans of temporary tables.
  21       </p></li><li class="listitem"><p>
  22         Scans of foreign tables, unless the foreign data wrapper has
  23         an <code class="literal">IsForeignScanParallelSafe</code> API that indicates otherwise.
  24       </p></li><li class="listitem"><p>
  25         Plan nodes that reference a correlated <code class="literal">SubPlan</code>.
  26       </p></li></ul></div><div class="sect2" id="PARALLEL-LABELING"><div class="titlepage"><div><div><h3 class="title">15.4.1. Parallel Labeling for Functions and Aggregates <a href="#PARALLEL-LABELING" class="id_link">#</a></h3></div></div></div><p>
  27     The planner cannot automatically determine whether a user-defined
  28     function or aggregate is parallel safe, parallel restricted, or parallel
  29     unsafe, because this would require predicting every operation that the
  30     function could possibly perform.  In general, this is equivalent to the
  31     Halting Problem and therefore impossible.  Even for simple functions
  32     where it could conceivably be done, we do not try, since this would be expensive
  33     and error-prone.  Instead, all user-defined functions are assumed to
  34     be parallel unsafe unless otherwise marked.  When using
  35     <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a> or
  36     <a class="xref" href="sql-alterfunction.html" title="ALTER FUNCTION"><span class="refentrytitle">ALTER FUNCTION</span></a>, markings can be set by specifying
  37     <code class="literal">PARALLEL SAFE</code>, <code class="literal">PARALLEL RESTRICTED</code>, or
  38     <code class="literal">PARALLEL UNSAFE</code> as appropriate.  When using
  39     <a class="xref" href="sql-createaggregate.html" title="CREATE AGGREGATE"><span class="refentrytitle">CREATE AGGREGATE</span></a>, the
  40     <code class="literal">PARALLEL</code> option can be specified with <code class="literal">SAFE</code>,
  41     <code class="literal">RESTRICTED</code>, or <code class="literal">UNSAFE</code> as the corresponding value.
  42   </p><p>
  43     Functions and aggregates must be marked <code class="literal">PARALLEL UNSAFE</code>
  44     if they write to the database, change the transaction state (other than by
  45     using a subtransaction for error recovery), access sequences, or make
  46     persistent changes to
  47     settings.  Similarly, functions must be marked <code class="literal">PARALLEL
  48     RESTRICTED</code> if they access temporary tables, client connection state,
  49     cursors, prepared statements, or miscellaneous backend-local state that
  50     the system cannot synchronize across workers. For example,
  51     <code class="literal">setseed</code> and <code class="literal">random</code> are parallel restricted for
  52     this last reason.
  53   </p><p>
  54     In general, if a function is labeled as being safe when it is restricted or
  55     unsafe, or if it is labeled as being restricted when it is in fact unsafe,
  56     it may throw errors or produce wrong answers when used in a parallel query.
  57     C-language functions could in theory exhibit totally undefined behavior if
  58     mislabeled, since there is no way for the system to protect itself against
  59     arbitrary C code, but in most likely cases the result will be no worse than
  60     for any other function. If in doubt, it is probably best to label functions
  61     as <code class="literal">UNSAFE</code>.
  62   </p><p>
  63     If a function executed within a parallel worker acquires locks that are
  64     not held by the leader, for example by querying a table not referenced in
  65     the query, those locks will be released at worker exit, not end of
  66     transaction. If you write a function that does this, and this behavior
  67     difference is important to you, mark such functions as
  68     <code class="literal">PARALLEL RESTRICTED</code>
  69     to ensure that they execute only in the leader.
  70   </p><p>
  71     Note that the query planner does not consider deferring the evaluation of
  72     parallel-restricted functions or aggregates involved in the query in
  73     order to obtain a superior plan.  So, for example, if a <code class="literal">WHERE</code>
  74     clause applied to a particular table is parallel restricted, the query
  75     planner will not consider performing a scan of that table in the parallel
  76     portion of a plan.  In some cases, it would be
  77     possible (and perhaps even efficient) to include the scan of that table in
  78     the parallel portion of the query and defer the evaluation of the
  79     <code class="literal">WHERE</code> clause so that it happens above the <code class="literal">Gather</code>
  80     node.  However, the planner does not do this.
  81   </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="parallel-plans.html" title="15.3. Parallel Plans">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="parallel-query.html" title="Chapter 15. Parallel Query">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="admin.html" title="Part III. Server Administration">Next</a></td></tr><tr><td width="40%" align="left" valign="top">15.3. Parallel Plans </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Part III. Server Administration</td></tr></table></div></body></html>