Improve documentation around autovacuum-related storage parameters.

tglsfdc · tglsfdc · commit 6404751ce91f · 2015-11-11T17:13:38.000-05:00
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.
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
@@ -5234,8 +5234,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>
@@ -5253,7 +5255,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
@@ -5281,8 +5284,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>
@@ -5296,7 +5301,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>
@@ -5333,9 +5338,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>
@@ -5352,9 +5357,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>
@@ -5372,9 +5377,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>
@@ -5392,9 +5397,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>
@@ -5421,7 +5426,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>
@@ -5448,8 +5453,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>
@@ -5468,9 +5473,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>
@@ -5488,12 +5493,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>
@@ -6072,7 +6077,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
@@ -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
