Improve documentation around autovacuum-related storage parameters.

These were discussed in three different sections of the manual, which
unsurprisingly had diverged over time; and the descriptions of individual
variables lacked stylistic consistency even within each section (and
frequently weren't in very good English anyway).  Clean up the mess, and
remove some of the redundant information in hopes that future additions
will be less likely to re-introduce inconsistency.  For instance I see
no need for maintenance.sgml to include its very own list of all the
autovacuum storage parameters, especially since that list was already
incomplete.

3 files changed, 106 insertions, 116 deletions

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index f2f4b1d13d..5a25b0308e 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -5180,8 +5180,10 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
 
      <para>
       These settings control the behavior of the <firstterm>autovacuum</>
-      feature.  Refer to <xref linkend="autovacuum"> for
-      more information.
+      feature.  Refer to <xref linkend="autovacuum"> for more information.
+      Note that many of these settings can be overridden on a per-table
+      basis; see <xref linkend="sql-createtable-storage-parameters"
+      endterm="sql-createtable-storage-parameters-title">.
      </para>
 
     <variablelist>
@@ -5199,7 +5201,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
         <xref linkend="guc-track-counts"> must also be enabled for
         autovacuum to work.
         This parameter can only be set in the <filename>postgresql.conf</>
-        file or on the server command line.
+        file or on the server command line; however, autovacuuming can be
+        disabled for individual tables by changing table storage parameters.
        </para>
        <para>
         Note that even when this parameter is disabled, the system
@@ -5227,8 +5230,10 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
         set to any value other than <literal>-1</literal>, a message will be
         logged if an autovacuum action is skipped due to the existence of a
         conflicting lock.  Enabling this parameter can be helpful
-        in tracking autovacuum activity.  This setting can only be set in
-        the <filename>postgresql.conf</> file or on the server command line.
+        in tracking autovacuum activity.  This parameter can only be set in
+        the <filename>postgresql.conf</> file or on the server command line;
+        but the setting can be overridden for individual tables by
+        changing table storage parameters.
        </para>
       </listitem>
      </varlistentry>
@@ -5242,7 +5247,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
       <listitem>
        <para>
         Specifies the maximum number of autovacuum processes (other than the
-        autovacuum launcher) which may be running at any one time.  The default
+        autovacuum launcher) that may be running at any one time.  The default
         is three.  This parameter can only be set at server start.
        </para>
       </listitem>
@@ -5279,9 +5284,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
         to trigger a <command>VACUUM</> in any one table.
         The default is 50 tuples.
         This parameter can only be set in the <filename>postgresql.conf</>
-        file or on the server command line.
-        This setting can be overridden for individual tables by
-        changing storage parameters.
+        file or on the server command line;
+        but the setting can be overridden for individual tables by
+        changing table storage parameters.
        </para>
       </listitem>
      </varlistentry>
@@ -5298,9 +5303,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
         needed to trigger an <command>ANALYZE</> in any one table.
         The default is 50 tuples.
         This parameter can only be set in the <filename>postgresql.conf</>
-        file or on the server command line.
-        This setting can be overridden for individual tables by
-        changing storage parameters.
+        file or on the server command line;
+        but the setting can be overridden for individual tables by
+        changing table storage parameters.
        </para>
       </listitem>
      </varlistentry>
@@ -5318,9 +5323,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
         when deciding whether to trigger a <command>VACUUM</>.
         The default is 0.2 (20% of table size).
         This parameter can only be set in the <filename>postgresql.conf</>
-        file or on the server command line.
-        This setting can be overridden for individual tables by
-        changing storage parameters.
+        file or on the server command line;
+        but the setting can be overridden for individual tables by
+        changing table storage parameters.
        </para>
       </listitem>
      </varlistentry>
@@ -5338,9 +5343,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
         when deciding whether to trigger an <command>ANALYZE</>.
         The default is 0.1 (10% of table size).
         This parameter can only be set in the <filename>postgresql.conf</>
-        file or on the server command line.
-        This setting can be overridden for individual tables by
-        changing storage parameters.
+        file or on the server command line;
+        but the setting can be overridden for individual tables by
+        changing table storage parameters.
        </para>
       </listitem>
      </varlistentry>
@@ -5367,7 +5372,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
         is a relatively low 200 million transactions.
         This parameter can only be set at server start, but the setting
         can be reduced for individual tables by
-        changing storage parameters.
+        changing table storage parameters.
         For more information see <xref linkend="vacuum-for-wraparound">.
        </para>
       </listitem>
@@ -5394,8 +5399,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
         <filename>pg_multixact/members</> and <filename>pg_multixact/offsets</>
         subdirectories, which is why the default is a relatively low
         400 million multixacts.
-        This parameter can only be set at server start, but the setting
-        can be reduced for individual tables by changing storage parameters.
+        This parameter can only be set at server start, but the setting can
+        be reduced for individual tables by changing table storage parameters.
         For more information see <xref linkend="vacuum-for-multixact-wraparound">.
        </para>
       </listitem>
@@ -5414,9 +5419,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
         <xref linkend="guc-vacuum-cost-delay"> value will be used.
         The default value is 20 milliseconds.
         This parameter can only be set in the <filename>postgresql.conf</>
-        file or on the server command line.
-        This setting can be overridden for individual tables by
-        changing storage parameters.
+        file or on the server command line;
+        but the setting can be overridden for individual tables by
+        changing table storage parameters.
        </para>
       </listitem>
      </varlistentry>
@@ -5434,12 +5439,12 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
         default), the regular
         <xref linkend="guc-vacuum-cost-limit"> value will be used.  Note that
         the value is distributed proportionally among the running autovacuum
-        workers, if there is more than one, so that the sum of the limits of
-        each worker never exceeds the limit on this variable.
+        workers, if there is more than one, so that the sum of the limits for
+        each worker does not exceed the value of this variable.
         This parameter can only be set in the <filename>postgresql.conf</>
-        file or on the server command line.
-        This setting can be overridden for individual tables by
-        changing storage parameters.
+        file or on the server command line;
+        but the setting can be overridden for individual tables by
+        changing table storage parameters.
        </para>
       </listitem>
      </varlistentry>
@@ -6018,7 +6023,7 @@ SET XML OPTION { DOCUMENT | CONTENT };
         the entries in it to the main GIN data structure in bulk.
         The default is four megabytes (<literal>4MB</>). This setting
         can be overridden for individual GIN indexes by changing
-        storage parameters.
+        index storage parameters.
          See <xref linkend="gin-fast-update"> and <xref linkend="gin-tips">
          for more information.
        </para>
diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index b5d405024d..5204b34c75 100644
--- a/doc/src/sgml/maintenance.sgml
+++ b/doc/src/sgml/maintenance.sgml
@@ -705,15 +705,15 @@ HINT:  Stop the postmaster and vacuum that database in single-user mode.
     the next database will be processed as soon as the first worker finishes.
     Each worker process will check each table within its database and
     execute <command>VACUUM</> and/or <command>ANALYZE</> as needed.
-    <varname>log_autovacuum_min_duration</varname> can be used to monitor
-    autovacuum activity.
+    <xref linkend="guc-log-autovacuum-min-duration"> can be set to monitor
+    autovacuum workers' activity.
    </para>
 
    <para>
     If several large tables all become eligible for vacuuming in a short
     amount of time, all autovacuum workers might become occupied with
     vacuuming those tables for a long period.  This would result
-    in other tables and databases not being vacuumed until a worker became
+    in other tables and databases not being vacuumed until a worker becomes
     available. There is no limit on how many workers might be in a
     single database, but workers do try to avoid repeating work that has
     already been done by other workers. Note that the number of running
@@ -767,45 +767,24 @@ analyze threshold = analyze base threshold + analyze scale factor * number of tu
    <para>
     The default thresholds and scale factors are taken from
     <filename>postgresql.conf</filename>, but it is possible to override them
-    on a table-by-table basis; see
+    (and many other autovacuum control parameters) on a per-table basis; see
     <xref linkend="sql-createtable-storage-parameters"
     endterm="sql-createtable-storage-parameters-title"> for more information.
-    If a setting
-    has been changed via storage parameters, that value is used; otherwise the
-    global settings are used. See <xref linkend="runtime-config-autovacuum"> for
-    more details on the global settings.
-   </para>
-
-   <para>
-    Besides the base threshold values and scale factors, there are six
-    more autovacuum parameters that can be set for each table via
-    storage parameters.
-    The first parameter, <literal>autovacuum_enabled</>,
-    can be set to <literal>false</literal> to instruct the autovacuum daemon
-    to skip that particular table entirely.  In this case
-    autovacuum will only touch the table if it must do so
-    to prevent transaction ID wraparound.
-    Another two parameters,
-    <varname>autovacuum_vacuum_cost_delay</> and
-    <varname>autovacuum_vacuum_cost_limit</>, are used to set
-    table-specific values for the cost-based vacuum delay feature
-    (see <xref linkend="runtime-config-resource-vacuum-cost">).
-    <varname>autovacuum_freeze_min_age</>,
-    <varname>autovacuum_freeze_max_age</> and
-    <varname>autovacuum_freeze_table_age</> are used to set
-    values for <xref linkend="guc-vacuum-freeze-min-age">,
-    <xref linkend="guc-autovacuum-freeze-max-age"> and
-    <xref linkend="guc-vacuum-freeze-table-age"> respectively.
-   </para>
-
-   <para>
-    When multiple workers are running, the cost delay parameters are
+    If a setting has been changed via a table's storage parameters, that value
+    is used when processing that table; otherwise the global settings are
+    used. See <xref linkend="runtime-config-autovacuum"> for more details on
+    the global settings.
+   </para>
+
+   <para>
+    When multiple workers are running, the autovacuum cost delay parameters
+    (see <xref linkend="runtime-config-resource-vacuum-cost">) are
     <quote>balanced</quote> among all the running workers, so that the
     total I/O impact on the system is the same regardless of the number
     of workers actually running.  However, any workers processing tables whose
-    <literal>autovacuum_vacuum_cost_delay</> or
-    <literal>autovacuum_vacuum_cost_limit</> have been set are not considered
-    in the balancing algorithm.
+    per-table <literal>autovacuum_vacuum_cost_delay</> or
+    <literal>autovacuum_vacuum_cost_limit</> storage parameters have been set
+    are not considered in the balancing algorithm.
    </para>
   </sect2>
  </sect1>
diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml
index a2d0b0cbe1..f0c94d591e 100644
--- a/doc/src/sgml/ref/create_table.sgml
+++ b/doc/src/sgml/ref/create_table.sgml
@@ -878,14 +878,14 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     Storage parameters for
     indexes are documented in <xref linkend="SQL-CREATEINDEX">.
     The storage parameters currently
-    available for tables are listed below.  For each parameter, unless noted,
-    there is an additional parameter with the same name prefixed with
-    <literal>toast.</literal>, which can be used to control the behavior of the
+    available for tables are listed below.  For many of these parameters, as
+    shown, there is an additional parameter with the same name prefixed with
+    <literal>toast.</literal>, which controls the behavior of the
     table's secondary <acronym>TOAST</> table, if any
     (see <xref linkend="storage-toast"> for more information about TOAST).
-    Note that the TOAST table uses the parameter values defined for
-    the main table, for each parameter applicable to TOAST tables and
-    for which no value is set in the TOAST table itself.
+    If a table parameter value is set and the
+    equivalent <literal>toast.</literal> parameter is not, the TOAST table
+    will use the table's parameter value.
    </para>
 
    <variablelist>
@@ -912,22 +912,19 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     <term><literal>autovacuum_enabled</>, <literal>toast.autovacuum_enabled</literal> (<type>boolean</>)</term>
     <listitem>
      <para>
-     Enables or disables the autovacuum daemon on a particular table.
-     If true, the autovacuum daemon will initiate a <command>VACUUM</> operation
-     on a particular table when the number of updated or deleted tuples exceeds
-     <literal>autovacuum_vacuum_threshold</> plus
-     <literal>autovacuum_vacuum_scale_factor</> times the number of live tuples
-     currently estimated to be in the relation.
-     Similarly, it will initiate an <command>ANALYZE</> operation when the
-     number of inserted, updated or deleted tuples exceeds
-     <literal>autovacuum_analyze_threshold</> plus
-     <literal>autovacuum_analyze_scale_factor</> times the number of live tuples
-     currently estimated to be in the relation.
+     Enables or disables the autovacuum daemon for a particular table.
+     If true, the autovacuum daemon will perform automatic <command>VACUUM</>
+     and/or <command>ANALYZE</> operations on this table following the rules
+     discussed in <xref linkend="autovacuum">.
      If false, this table will not be autovacuumed, except to prevent
-     transaction Id wraparound. See <xref linkend="vacuum-for-wraparound"> for
+     transaction ID wraparound. See <xref linkend="vacuum-for-wraparound"> for
      more about wraparound prevention.
-     Observe that this variable inherits its value from the <xref
-     linkend="guc-autovacuum"> setting.
+     Note that the autovacuum daemon does not run at all (except to prevent
+     transaction ID wraparound) if the <xref linkend="guc-autovacuum">
+     parameter is false; setting individual tables' storage parameters does
+     not override that.  Therefore there is seldom much point in explicitly
+     setting this storage parameter to <literal>true</>, only
+     to <literal>false</>.
      </para>
     </listitem>
    </varlistentry>
@@ -936,8 +933,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     <term><literal>autovacuum_vacuum_threshold</>, <literal>toast.autovacuum_vacuum_threshold</literal> (<type>integer</>)</term>
     <listitem>
      <para>
-     Minimum number of updated or deleted tuples before initiate a
-     <command>VACUUM</> operation on a particular table.
+      Per-table value for <xref linkend="guc-autovacuum-vacuum-threshold">
+      parameter.
      </para>
     </listitem>
    </varlistentry>
@@ -946,8 +943,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     <term><literal>autovacuum_vacuum_scale_factor</>, <literal>toast.autovacuum_vacuum_scale_factor</literal> (<type>float4</>)</term>
     <listitem>
      <para>
-     Multiplier for <structfield>reltuples</> to add to
-     <literal>autovacuum_vacuum_threshold</>.
+      Per-table value for <xref linkend="guc-autovacuum-vacuum-scale-factor">
+      parameter.
      </para>
     </listitem>
    </varlistentry>
@@ -956,8 +953,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     <term><literal>autovacuum_analyze_threshold</> (<type>integer</>)</term>
     <listitem>
      <para>
-     Minimum number of inserted, updated, or deleted tuples before initiate an
-     <command>ANALYZE</> operation on a particular table.
+      Per-table value for <xref linkend="guc-autovacuum-analyze-threshold">
+      parameter.
      </para>
     </listitem>
    </varlistentry>
@@ -966,8 +963,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     <term><literal>autovacuum_analyze_scale_factor</> (<type>float4</>)</term>
     <listitem>
      <para>
-     Multiplier for <structfield>reltuples</> to add to
-     <literal>autovacuum_analyze_threshold</>.
+      Per-table value for <xref linkend="guc-autovacuum-analyze-scale-factor">
+      parameter.
      </para>
     </listitem>
    </varlistentry>
@@ -976,7 +973,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     <term><literal>autovacuum_vacuum_cost_delay</>, <literal>toast.autovacuum_vacuum_cost_delay</literal> (<type>integer</>)</term>
     <listitem>
      <para>
-     Custom <xref linkend="guc-autovacuum-vacuum-cost-delay"> parameter.
+      Per-table value for <xref linkend="guc-autovacuum-vacuum-cost-delay">
+      parameter.
      </para>
     </listitem>
    </varlistentry>
@@ -985,7 +983,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     <term><literal>autovacuum_vacuum_cost_limit</>, <literal>toast.autovacuum_vacuum_cost_limit</literal> (<type>integer</>)</term>
     <listitem>
      <para>
-     Custom <xref linkend="guc-autovacuum-vacuum-cost-limit"> parameter.
+      Per-table value for <xref linkend="guc-autovacuum-vacuum-cost-limit">
+      parameter.
      </para>
     </listitem>
    </varlistentry>
@@ -994,10 +993,11 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     <term><literal>autovacuum_freeze_min_age</>, <literal>toast.autovacuum_freeze_min_age</literal> (<type>integer</>)</term>
     <listitem>
      <para>
-     Custom <xref linkend="guc-vacuum-freeze-min-age"> parameter. Note that
-     autovacuum will ignore attempts to set a per-table
-     <literal>autovacuum_freeze_min_age</> larger than half the system-wide
-     <xref linkend="guc-autovacuum-freeze-max-age"> setting.
+      Per-table value for <xref linkend="guc-vacuum-freeze-min-age">
+      parameter.  Note that autovacuum will ignore
+      per-table <literal>autovacuum_freeze_min_age</> parameters that are
+      larger than half the
+      system-wide <xref linkend="guc-autovacuum-freeze-max-age"> setting.
      </para>
     </listitem>
    </varlistentry>
@@ -1006,10 +1006,10 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     <term><literal>autovacuum_freeze_max_age</>, <literal>toast.autovacuum_freeze_max_age</literal> (<type>integer</>)</term>
     <listitem>
      <para>
-     Custom <xref linkend="guc-autovacuum-freeze-max-age"> parameter. Note that
-     autovacuum will ignore attempts to set a per-table
-     <literal>autovacuum_freeze_max_age</> larger than the system-wide setting
-     (it can only be set smaller).
+      Per-table value for <xref linkend="guc-autovacuum-freeze-max-age">
+      parameter.  Note that autovacuum will ignore
+      per-table <literal>autovacuum_freeze_max_age</> parameters that are
+      larger than the system-wide setting (it can only be set smaller).
      </para>
     </listitem>
    </varlistentry>
@@ -1018,7 +1018,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     <term><literal>autovacuum_freeze_table_age</literal>, <literal>toast.autovacuum_freeze_table_age</literal> (<type>integer</type>)</term>
     <listitem>
      <para>
-      Custom <xref linkend="guc-vacuum-freeze-table-age"> parameter.
+      Per-table value for <xref linkend="guc-vacuum-freeze-table-age">
+      parameter.
      </para>
     </listitem>
    </varlistentry>
@@ -1027,9 +1028,10 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     <term><literal>autovacuum_multixact_freeze_min_age</literal>, <literal>toast.autovacuum_multixact_freeze_min_age</literal> (<type>integer</type>)</term>
     <listitem>
      <para>
-      Custom <xref linkend="guc-vacuum-multixact-freeze-min-age"> parameter.
-      Note that autovacuum will ignore attempts to set a per-table
-      <literal>autovacuum_multixact_freeze_min_age</> larger than half the
+      Per-table value for <xref linkend="guc-vacuum-multixact-freeze-min-age">
+      parameter.  Note that autovacuum will ignore
+      per-table <literal>autovacuum_multixact_freeze_min_age</> parameters
+      that are larger than half the
       system-wide <xref linkend="guc-autovacuum-multixact-freeze-max-age">
       setting.
      </para>
@@ -1040,10 +1042,12 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     <term><literal>autovacuum_multixact_freeze_max_age</literal>, <literal>toast.autovacuum_multixact_freeze_max_age</literal> (<type>integer</type>)</term>
     <listitem>
      <para>
-      Custom <xref linkend="guc-autovacuum-multixact-freeze-max-age"> parameter. Note
-      that autovacuum will ignore attempts to set a per-table
-      <literal>autovacuum_multixact_freeze_max_age</> larger than the
-      system-wide setting (it can only be set smaller).
+      Per-table value
+      for <xref linkend="guc-autovacuum-multixact-freeze-max-age"> parameter.
+      Note that autovacuum will ignore
+      per-table <literal>autovacuum_multixact_freeze_max_age</> parameters
+      that are larger than the system-wide setting (it can only be set
+      smaller).
      </para>
     </listitem>
    </varlistentry>
@@ -1052,7 +1056,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     <term><literal>autovacuum_multixact_freeze_table_age</literal>, <literal>toast.autovacuum_multixact_freeze_table_age</literal> (<type>integer</type>)</term>
     <listitem>
      <para>
-      Custom <xref linkend="guc-vacuum-multixact-freeze-table-age"> parameter.
+      Per-table value
+      for <xref linkend="guc-vacuum-multixact-freeze-table-age"> parameter.
      </para>
     </listitem>
    </varlistentry>
@@ -1061,7 +1066,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     <term><literal>log_autovacuum_min_duration</literal>, <literal>toast.log_autovacuum_min_duration</literal> (<type>integer</type>)</term>
     <listitem>
      <para>
-      Custom <xref linkend="guc-log-autovacuum-min-duration"> parameter.
+      Per-table value for <xref linkend="guc-log-autovacuum-min-duration">
+      parameter.
      </para>
     </listitem>
    </varlistentry>
@@ -1070,7 +1076,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     <term><literal>user_catalog_table</literal> (<type>boolean</type>)</term>
     <listitem>
      <para>
-      Declare a table as an additional catalog table, e.g. for the purpose of
+      Declare the table as an additional catalog table for purposes of
       logical replication. See
       <xref linkend="logicaldecoding-capabilities"> for details.
       This parameter cannot be set for TOAST tables.