projects / postgresql.git / commitdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | patch | inline | side by side (parent: da3751c)
Improve documentation around autovacuum-related storage parameters.
authorTom Lane
Wed, 11 Nov 2015 22:13:38 +0000 (17:13 -0500)
committerTom Lane
Wed, 11 Nov 2015 22:13:38 +0000 (17:13 -0500)
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.

doc/src/sgml/config.sgml patch | blob | blame | history
doc/src/sgml/maintenance.sgml patch | blob | blame | history
doc/src/sgml/ref/create_table.sgml patch | blob | blame | history

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 5549de7558d74a8fec711c789bd6e450dfde7e03..6e14851f69634533ebeb94dc465a139524df2e43 100644 (file)
--- 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;
 
      
       These settings control the behavior of the autovacuum
-      feature.  Refer to  for
-      more information.
+      feature.  Refer to  for more information.
+      Note that many of these settings can be overridden on a per-table
+      basis; see 
+      endterm="sql-createtable-storage-parameters-title">.
      
 
     
@@ -5253,7 +5255,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
          must also be enabled for
         autovacuum to work.
         This parameter can only be set in the 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.
        
        
         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 -1, 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 postgresql.conf file or on the server command line.
+        in tracking autovacuum activity.  This parameter can only be set in
+        the postgresql.conf file or on the server command line;
+        but the setting can be overridden for individual tables by
+        changing table storage parameters.
        
       
      
@@ -5296,7 +5301,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
       
        
         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.
        
       
@@ -5333,9 +5338,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
         to trigger a VACUUM in any one table.
         The default is 50 tuples.
         This parameter can only be set in the 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.
        
       
      
@@ -5352,9 +5357,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
         needed to trigger an ANALYZE in any one table.
         The default is 50 tuples.
         This parameter can only be set in the 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.
        
       
      
@@ -5372,9 +5377,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
         when deciding whether to trigger a VACUUM.
         The default is 0.2 (20% of table size).
         This parameter can only be set in the 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.
        
       
      
@@ -5392,9 +5397,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
         when deciding whether to trigger an ANALYZE.
         The default is 0.1 (10% of table size).
         This parameter can only be set in the 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.
        
       
      
@@ -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 .
        
       
@@ -5448,8 +5453,8 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
         pg_multixact/members and 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 .
        
       
@@ -5468,9 +5473,9 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
          value will be used.
         The default value is 20 milliseconds.
         This parameter can only be set in the 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.
        
       
      
@@ -5488,12 +5493,12 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
         default), the regular
          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 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.
        
       
      
@@ -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 (4MB). This setting
         can be overridden for individual GIN indexes by changing
-        storage parameters.
+        index storage parameters.
          See  and 
          for more information.
        
diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index b5d405024d8a4d4395beab427f9501dc617081ee..5204b34c75abc435b4cc39d56de8aed77300e728 100644 (file)
--- 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 VACUUM and/or ANALYZE as needed.
-    <varname>log_autovacuum_min_duration can be used to monitor
-    autovacuum activity.
+    <xref linkend="guc-log-autovacuum-min-duration"> can be set to monitor
+    autovacuum workers' activity.
    
 
    
     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
    
     The default thresholds and scale factors are taken from
     postgresql.conf, 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
     
     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  for
-    more details on the global settings.
-   
-
-   
-    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, autovacuum_enabled,
-    can be set to false 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,
-    autovacuum_vacuum_cost_delay and
-    autovacuum_vacuum_cost_limit, are used to set
-    table-specific values for the cost-based vacuum delay feature
-    (see ).
-    autovacuum_freeze_min_age,
-    autovacuum_freeze_max_age and
-    autovacuum_freeze_table_age are used to set
-    values for ,
-     and
-     respectively.
-   
-
-   
-    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  for more details on
+    the global settings.
+   
+
+   
+    When multiple workers are running, the autovacuum cost delay parameters
+    (see ) are
     balanced 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
-    autovacuum_vacuum_cost_delay or
-    autovacuum_vacuum_cost_limit have been set are not considered
-    in the balancing algorithm.
+    per-table autovacuum_vacuum_cost_delay or
+    autovacuum_vacuum_cost_limit storage parameters have been set
+    are not considered in the balancing algorithm.
    
   
  
diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml
index a2d0b0cbe1e2e99de441e94b86922d1c588b1516..f0c94d591efa155257edfb976fad9b03749aa6b4 100644 (file)
--- 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 .
     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
-    toast., 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
+    toast., which controls the behavior of the
     table's secondary TOAST table, if any
     (see  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 toast. parameter is not, the TOAST table
+    will use the table's parameter value.
    
 
    
@@ -912,22 +912,19 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     autovacuum_enabled, toast.autovacuum_enabled (boolean)
     
      
-     Enables or disables the autovacuum daemon on a particular table.
-     If true, the autovacuum daemon will initiate a VACUUM operation
-     on a particular table when the number of updated or deleted tuples exceeds
-     autovacuum_vacuum_threshold plus
-     autovacuum_vacuum_scale_factor times the number of live tuples
-     currently estimated to be in the relation.
-     Similarly, it will initiate an ANALYZE operation when the
-     number of inserted, updated or deleted tuples exceeds
-     autovacuum_analyze_threshold plus
-     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 VACUUM
+     and/or ANALYZE operations on this table following the rules
+     discussed in .
      If false, this table will not be autovacuumed, except to prevent
-     transaction Id wraparound. See  for
+     transaction ID wraparound. See  for
      more about wraparound prevention.
-     Observe that this variable inherits its value from the 
-     linkend="guc-autovacuum"> setting.
+     Note that the autovacuum daemon does not run at all (except to prevent
+     transaction ID wraparound) if the 
+     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 true, only
+     to false.
      
     
    
@@ -936,8 +933,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     autovacuum_vacuum_threshold, toast.autovacuum_vacuum_threshold (integer)
     
      
-     Minimum number of updated or deleted tuples before initiate a
-     VACUUM operation on a particular table.
+      Per-table value for 
+      parameter.
      
     
    
@@ -946,8 +943,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     autovacuum_vacuum_scale_factor, toast.autovacuum_vacuum_scale_factor (float4)
     
      
-     Multiplier for reltuples to add to
-     autovacuum_vacuum_threshold.
+      Per-table value for 
+      parameter.
      
     
    
@@ -956,8 +953,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     autovacuum_analyze_threshold (integer)
     
      
-     Minimum number of inserted, updated, or deleted tuples before initiate an
-     ANALYZE operation on a particular table.
+      Per-table value for 
+      parameter.
      
     
    
@@ -966,8 +963,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     autovacuum_analyze_scale_factor (float4)
     
      
-     Multiplier for reltuples to add to
-     autovacuum_analyze_threshold.
+      Per-table value for 
+      parameter.
      
     
    
@@ -976,7 +973,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     autovacuum_vacuum_cost_delay, toast.autovacuum_vacuum_cost_delay (integer)
     
      
-     Custom  parameter.
+      Per-table value for 
+      parameter.
      
     
    
@@ -985,7 +983,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     autovacuum_vacuum_cost_limit, toast.autovacuum_vacuum_cost_limit (integer)
     
      
-     Custom  parameter.
+      Per-table value for 
+      parameter.
      
     
    
@@ -994,10 +993,11 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     autovacuum_freeze_min_age, toast.autovacuum_freeze_min_age (integer)
     
      
-     Custom  parameter. Note that
-     autovacuum will ignore attempts to set a per-table
-     autovacuum_freeze_min_age larger than half the system-wide
-      setting.
+      Per-table value for 
+      parameter.  Note that autovacuum will ignore
+      per-table autovacuum_freeze_min_age parameters that are
+      larger than half the
+      system-wide  setting.
      
     
    
@@ -1006,10 +1006,10 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     autovacuum_freeze_max_age, toast.autovacuum_freeze_max_age (integer)
     
      
-     Custom  parameter. Note that
-     autovacuum will ignore attempts to set a per-table
-     autovacuum_freeze_max_age larger than the system-wide setting
-     (it can only be set smaller).
+      Per-table value for 
+      parameter.  Note that autovacuum will ignore
+      per-table autovacuum_freeze_max_age parameters that are
+      larger than the system-wide setting (it can only be set smaller).
      
     
    
@@ -1018,7 +1018,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     autovacuum_freeze_table_age, toast.autovacuum_freeze_table_age (integer)
     
      
-      Custom  parameter.
+      Per-table value for 
+      parameter.
      
     
    
@@ -1027,9 +1028,10 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     autovacuum_multixact_freeze_min_age, toast.autovacuum_multixact_freeze_min_age (integer)
     
      
-      Custom  parameter.
-      Note that autovacuum will ignore attempts to set a per-table
-      autovacuum_multixact_freeze_min_age larger than half the
+      Per-table value for 
+      parameter.  Note that autovacuum will ignore
+      per-table autovacuum_multixact_freeze_min_age parameters
+      that are larger than half the
       system-wide 
       setting.
      
@@ -1040,10 +1042,12 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     autovacuum_multixact_freeze_max_age, toast.autovacuum_multixact_freeze_max_age (integer)
     
      
-      Custom  parameter. Note
-      that autovacuum will ignore attempts to set a per-table
-      autovacuum_multixact_freeze_max_age larger than the
-      system-wide setting (it can only be set smaller).
+      Per-table value
+      for  parameter.
+      Note that autovacuum will ignore
+      per-table autovacuum_multixact_freeze_max_age parameters
+      that are larger than the system-wide setting (it can only be set
+      smaller).
      
     
    
@@ -1052,7 +1056,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     autovacuum_multixact_freeze_table_age, toast.autovacuum_multixact_freeze_table_age (integer)
     
      
-      Custom  parameter.
+      Per-table value
+      for  parameter.
      
     
    
@@ -1061,7 +1066,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     log_autovacuum_min_duration, toast.log_autovacuum_min_duration (integer)
     
      
-      Custom  parameter.
+      Per-table value for 
+      parameter.
      
     
    
@@ -1070,7 +1076,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     user_catalog_table (boolean)
     
      
-      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
        for details.
       This parameter cannot be set for TOAST tables.
This is the main PostgreSQL git repository.