v33-0002-Documantation-for-parallel-autovacuum.patch

From 235f5c8b31db8b81ff9735707c95128201131d2d Mon Sep 17 00:00:00 2001
From: Daniil Davidov <d.davydov@postgrespro.ru>
Date: Sat, 28 Mar 2026 17:37:07 +0700
Subject: [PATCH v33 2/2] Documantation for parallel autovacuum

---
 doc/src/sgml/config.sgml           | 19 ++++++++++++++
 doc/src/sgml/maintenance.sgml      | 42 ++++++++++++++++++++++++++++++
 doc/src/sgml/ref/create_table.sgml | 18 +++++++++++++
 doc/src/sgml/ref/vacuum.sgml       | 24 +++--------------
 4 files changed, 83 insertions(+), 20 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 229f41353eb..cbe73172b2e 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -2918,6 +2918,7 @@ include_dir 'conf.d'
         <para>
          When changing this value, consider also adjusting
          <xref linkend="guc-max-parallel-workers"/>,
+         <xref linkend="guc-autovacuum-max-parallel-workers"/>,
          <xref linkend="guc-max-parallel-maintenance-workers"/>, and
          <xref linkend="guc-max-parallel-workers-per-gather"/>.
         </para>
@@ -9485,6 +9486,24 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
        </listitem>
       </varlistentry>
 
+      <varlistentry id="guc-autovacuum-max-parallel-workers" xreflabel="autovacuum_max_parallel_workers">
+        <term><varname>autovacuum_max_parallel_workers</varname> (<type>integer</type>)
+        <indexterm>
+         <primary><varname>autovacuum_max_parallel_workers</varname></primary>
+         <secondary>configuration parameter</secondary>
+        </indexterm>
+        </term>
+        <listitem>
+         <para>
+          Sets the maximum number of parallel autovacuum workers that
+          can be used for the <xref linkend="parallel-vacuum"/>
+          by a single autovacuum worker. Is capped by <xref linkend="guc-max-parallel-workers"/>.
+          The default is 0, which means no parallel index vacuuming for this
+          table.
+         </para>
+        </listitem>
+     </varlistentry>
+
      </variablelist>
     </sect2>
 
diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index 0d2a28207ed..e350226610a 100644
--- a/doc/src/sgml/maintenance.sgml
+++ b/doc/src/sgml/maintenance.sgml
@@ -927,6 +927,13 @@ HINT:  Execute a database-wide VACUUM in that database.
     autovacuum workers' activity.
    </para>
 
+   <para>
+    If an autovacuum worker process comes across a table with the enabled
+    <xref linkend="reloption-autovacuum-parallel-workers"/> storage parameter,
+    it will launch parallel workers in order to perform the
+    <xref linkend="parallel-vacuum"/>.
+   </para>
+
    <para>
     If several large tables all become eligible for vacuuming in a short
     amount of time, all autovacuum workers might become occupied with
@@ -1038,6 +1045,10 @@ analyze threshold = analyze base threshold + analyze scale factor * number of tu
     per-table <literal>autovacuum_vacuum_cost_delay</literal> or
     <literal>autovacuum_vacuum_cost_limit</literal> storage parameters have been set
     are not considered in the balancing algorithm.
+    Parallel workers launched for <xref linkend="parallel-vacuum"/> are using
+    the same cost delay parameters as the leader worker. If any of these
+    parameters are changed in the leader worker, it will propagate the new
+    parameter values to all of its parallel workers.
    </para>
 
    <para>
@@ -1166,6 +1177,37 @@ analyze threshold = analyze base threshold + analyze scale factor * number of tu
     </para>
    </sect3>
   </sect2>
+
+  <sect2 id="parallel-vacuum" xreflabel="Parallel Vacuum">
+   <title>Parallel Vacuum</title>
+
+   <para>
+    Both <command>VACUUM</command> command and autovacuum daemon can perform
+    index vacuum and index cleanup phases in parallel using
+    <replaceable class="parameter">integer</replaceable> background workers
+    (for the details of each vacuum phase, please refer to
+    <xref linkend="vacuum-phases"/>). The number of workers used to perform
+    the operation is equal to the number of indexes on the relation that
+    support parallel vacuum which may be further limited by the value specific
+    to <command>VACUUM</command> or autovacuum (see <literal>PARALLEL</literal>
+    option for <xref linkend="sql-vacuum"/> or
+    <xref linkend="reloption-autovacuum-parallel-workers"/>, respectively).
+   </para>
+
+   <para>
+    An index can participate in parallel vacuum if and only if the size of the
+    index is more than <xref linkend="guc-min-parallel-index-scan-size"/>.
+    Please note that it is not guaranteed that the number of parallel workers
+    specified in <replaceable class="parameter">integer</replaceable> will be
+    used during execution.  It is possible for a vacuum to run with fewer
+    workers than specified, or even with no workers at all.  Only one worker
+    can be used per index.  So parallel workers are launched only when there
+    are at least <literal>2</literal> indexes in the table.  Workers for
+    vacuum are launched before the start of each phase and exit at the end of
+    the phase.  These behaviors might change in a future release.
+   </para>
+
+  </sect2>
  </sect1>
 
 
diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml
index 80829b23945..8f5b25411cd 100644
--- a/doc/src/sgml/ref/create_table.sgml
+++ b/doc/src/sgml/ref/create_table.sgml
@@ -1738,6 +1738,24 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
     </listitem>
    </varlistentry>
 
+  <varlistentry id="reloption-autovacuum-parallel-workers" xreflabel="autovacuum_parallel_workers">
+    <term><literal>autovacuum_parallel_workers</literal> (<type>integer</type>)
+    <indexterm>
+     <primary><varname>autovacuum_parallel_workers</varname> storage parameter</primary>
+    </indexterm>
+    </term>
+    <listitem>
+     <para>
+      Sets the maximum number of parallel autovacuum workers that can be used
+      for the <xref linkend="parallel-vacuum"/>.
+      The default value is 0, which means no parallel index vacuuming for
+      this table. If value is -1 then parallel degree will computed based on
+      number of indexes and limited by the <xref linkend="guc-autovacuum-max-parallel-workers"/>
+      configuration parameter.
+     </para>
+    </listitem>
+   </varlistentry>
+
    <varlistentry id="reloption-autovacuum-vacuum-threshold" xreflabel="autovacuum_vacuum_threshold">
     <term><literal>autovacuum_vacuum_threshold</literal>, <literal>toast.autovacuum_vacuum_threshold</literal> (<type>integer</type>)
     <indexterm>
diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml
index ac5d083d468..d3f32851386 100644
--- a/doc/src/sgml/ref/vacuum.sgml
+++ b/doc/src/sgml/ref/vacuum.sgml
@@ -81,7 +81,7 @@ VACUUM [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <re
    is not obtained.  However, extra space is not returned to the operating
    system (in most cases); it's just kept available for re-use within the
    same table.  It also allows us to leverage multiple CPUs in order to process
-   indexes.  This feature is known as <firstterm>parallel vacuum</firstterm>.
+   indexes.  This feature is known as <xref linkend="parallel-vacuum"/>.
    To disable this feature, one can use <literal>PARALLEL</literal> option and
    specify parallel workers as zero.  <command>VACUUM FULL</command> rewrites
    the entire contents of the table into a new disk file with no extra space,
@@ -266,25 +266,9 @@ VACUUM [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <re
     <term><literal>PARALLEL</literal></term>
     <listitem>
      <para>
-      Perform index vacuum and index cleanup phases of <command>VACUUM</command>
-      in parallel using <replaceable class="parameter">integer</replaceable>
-      background workers (for the details of each vacuum phase, please
-      refer to <xref linkend="vacuum-phases"/>).  The number of workers used
-      to perform the operation is equal to the number of indexes on the
-      relation that support parallel vacuum which is limited by the number of
-      workers specified with <literal>PARALLEL</literal> option if any which is
-      further limited by <xref linkend="guc-max-parallel-maintenance-workers"/>.
-      An index can participate in parallel vacuum if and only if the size of the
-      index is more than <xref linkend="guc-min-parallel-index-scan-size"/>.
-      Please note that it is not guaranteed that the number of parallel workers
-      specified in <replaceable class="parameter">integer</replaceable> will be
-      used during execution.  It is possible for a vacuum to run with fewer
-      workers than specified, or even with no workers at all.  Only one worker
-      can be used per index.  So parallel workers are launched only when there
-      are at least <literal>2</literal> indexes in the table.  Workers for
-      vacuum are launched before the start of each phase and exit at the end of
-      the phase.  These behaviors might change in a future release.  This
-      option can't be used with the <literal>FULL</literal> option.
+      Limits the number of parallel workers used to perform the
+      <xref linkend="parallel-vacuum"/>, which is further limited by
+      <xref linkend="guc-max-parallel-maintenance-workers"/>.
      </para>
     </listitem>
    </varlistentry>
-- 
2.43.0