Improve the documentation on 8.4 visibility map related VACUUM changes.

Explain how vacuum_freeze_table_age should be tuned, and how it relates
to the other settings. Mention that vacuum_freeze_table_age also affects
when autovacuum scans the whole table.

diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index 6c142feab3badc57fcb7911a93a3e801723747b9..6e1f63879dae164b683f575eb70e4bfc6e7a4b66 100644 (file)
--- a/doc/src/sgml/maintenance.sgml
+++ b/doc/src/sgml/maintenance.sgml
@@ -1,4 +1,4 @@
-
+
 
 
  Routine Database Maintenance Tasks
@@ -375,14 +375,21 @@
    
 
    
-    VACUUM's behavior is controlled by the two configuration
-    parameters:  and
-    .
-    vacuum_freeze_table_age controls when VACUUM
-    performs a full sweep of the table, in order to replace old XID values 
-    with FrozenXID.  vacuum_freeze_min_age 
+    VACUUM normally skips pages that don't have any dead row
+    versions, but those pages might still have tuples with old XID values.
+    To replace them too, a scan of the whole table is needed.
+     controls when
+    VACUUM does that: a whole table sweep is forced if
+    the table hasn't been fully scanned for vacuum_freeze_table_age
+    - vacuum_freeze_min_age transactions. Setting it to 0
+    makes VACUUM to ignore the visibility map and always scan all
+    pages.
+   
+
+   
+     
     controls how old an XID value has to be before it's replaced with
-    FrozenXID.  Larger values of these settings
+    FrozenXID.  Larger values of this setting
     preserve transactional information longer, while smaller values increase
     the number of transactions that can elapse before the table must be
     vacuumed again.
@@ -416,8 +423,25 @@
    
 
    
-    The sole disadvantage of increasing vacuum_freeze_table_age
-    and autovacuum_freeze_max_age
+    The effective maximum for vacuum_table_age is 0.95 * 
+    autovacuum_freeze_max_age; a setting higher than that will be
+    capped to that maximum. A value higher than
+    autovacuum_freeze_max_age wouldn't make sense because an
+    anti-wraparound autovacuum would be triggered at that point anyway, and
+    the 0.95 multiplier leaves some breathing room to run a manual
+    VACUUM before that happens.  As a rule of thumb,
+    vacuum_freeze_table_age should be set to a value somewhat
+    below autovacuum_freeze_max_age, leaving enough gap so that
+    a regularly scheduled VACUUM or an autovacuum triggered by
+    normal delete and update activity is run in that window.  Setting it too
+    close could lead to anti-wraparound autovacuums, even though the table
+    was recently vacuumed to reclaim space, whereas lower values lead to more
+    frequent whole-table scans.
+   
+
+   
+    The sole disadvantage of increasing autovacuum_freeze_max_age
+    (and vacuum_freeze_table_age along with it)
     is that the pg_clog subdirectory of the database cluster
     will take more space, because it must store the commit status for all
     transactions back to the autovacuum_freeze_max_age horizon.
@@ -425,9 +449,8 @@
     autovacuum_freeze_max_age has its maximum allowed value of
     a little less than two billion, pg_clog can be expected to
     grow to about half a gigabyte.  If this is trivial compared to your
-    total database size, setting autovacuum_freeze_max_age and
-    vacuum_freeze_table_age to their maximum allowed values
-    is recommended.  Otherwise, set them depending
+    total database size, setting autovacuum_freeze_max_age to
+    its maximum allowed value is recommended.  Otherwise, set it depending
     on what you are willing to allow for pg_clog storage.
     (The default, 200 million transactions, translates to about 50MB of
     pg_clog storage.)
@@ -470,24 +493,19 @@ SELECT datname, age(datfrozenxid) FROM pg_database;
 
 
     The age column measures the number of transactions from the
-    cutoff XID to the current transaction's XID.  When VACUUM
+    cutoff XID to the current transaction's XID.  VACUUM normally
+    only scans pages that have been modified since last vacuum, but
+    relfrozenxid can only be advanced when the whole table is
+    scanned. The whole table is scanned when relfrozenxid is
+    more than vacuum_freeze_table_age transactions old, if
+    VACUUM FREEZE command is used, or if all pages happen to
+    require vacuuming to remove dead row versions. When VACUUM
     scans the whole table, after it's finished age(relfrozenxid)
     should be a little more than the vacuum_freeze_min_age setting
     that was used (more by the number of transactions started since the
-    VACUUM started).
-   
-
-   
-    VACUUM normally only scans pages that have been modified
-    since last vacuum, but relfrozenxid can only be advanced
-    when the whole table is scanned. The whole table is scanned when
-    relfrozenxid is more than
-    vacuum_freeze_table_age transactions old, if
-    VACUUM FREEZE command is used, or if all pages happen to
-    require vacuuming to remove dead row versions. If no whole-table-scanning
-    VACUUM is issued on the table until
-    autovacuum_freeze_max_age is reached, an autovacuum will soon
-    be forced for the table.
+    VACUUM started).  If no whole-table-scanning VACUUM
+    is issued on the table until autovacuum_freeze_max_age is
+    reached, an autovacuum will soon be forced for the table.
    
 
    
@@ -599,7 +617,11 @@ vacuum threshold = vacuum base threshold + vacuum scale factor * number of tuple
     collector; it is a semi-accurate count updated by each
     UPDATE and DELETE operation.  (It
     is only semi-accurate because some information might be lost under heavy
-    load.)
+    load.)  If the relfrozenxid value of the table is more
+    than vacuum_freeze_table_age transactions old, the whole
+    table is scanned to freeze old tuples and advance
+    relfrozenxid, otherwise only pages that have been modified
+    since last vacuum are vacuumed.