Add vacuum_freeze_table_age GUC option, to control when VACUUM should

ignore the visibility map and scan the whole table, to advance
relfrozenxid.

doc/src/sgml/catalogs.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.188 2009/01/09 15:02:22 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.189 2009/01/16 13:27:23 heikki Exp $ -->
 <!--
  Documentation of the system catalogs, directed toward PostgreSQL developers
  -->
@@ -1361,6 +1361,13 @@
       <entry></entry>
       <entry>Custom <varname>autovacuum_freeze_max_age</> parameter</entry>
      </row>
+
+     <row>
+      <entry><structfield>freeze_table_age</structfield></entry>
+      <entry><type>integer</type></entry>
+      <entry></entry>
+      <entry>Custom <varname>vacuum_freeze_table_age</> parameter</entry>
+     </row>
     </tbody>
    </tgroup>
   </table>

doc/src/sgml/config.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.205 2009/01/12 05:10:44 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.206 2009/01/16 13:27:23 heikki Exp $ -->
 
 <chapter Id="runtime-config">
   <title>Server Configuration</title>
@@ -3950,6 +3950,27 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
       </listitem>
      </varlistentry>
 
+     <varlistentry id="guc-vacuum-freeze-table-age" xreflabel="vacuum_freeze_table_age">
+      <term><varname>vacuum_freeze_table_age</varname> (<type>integer</type>)</term>
+      <indexterm>
+       <primary><varname>vacuum_freeze_table_age</> configuration parameter</primary>
+      </indexterm>
+      <listitem>
+       <para>
+        <command>VACUUM</> performs a whole-table scan if the table's
+        <structname>pg_class</>.<structfield>relfrozenxid</> field has reached
+        the age specified by this setting.  The default is 150 million
+        transactions.  Although users can set this value anywhere from zero to
+        one billion, <command>VACUUM</> will silently limit the effective value
+        to 95% of <xref linkend="guc-autovacuum-freeze-max-age">, so that a
+        periodical manual <command>VACUUM</> has a chance to run before an
+        anti-wraparound autovacuum is launched for the table. For more
+        information see
+        <xref linkend="vacuum-for-wraparound">.
+       </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry id="guc-vacuum-freeze-min-age" xreflabel="vacuum_freeze_min_age">
       <term><varname>vacuum_freeze_min_age</varname> (<type>integer</type>)</term>
       <indexterm>
@@ -3960,7 +3981,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
         Specifies the cutoff age (in transactions) that <command>VACUUM</>
         should use to decide whether to replace transaction IDs with
         <literal>FrozenXID</> while scanning a table.
-        The default is 100 million transactions.  Although
+        The default is 50 million transactions.  Although
         users can set this value anywhere from zero to one billion,
         <command>VACUUM</> will silently limit the effective value to half
         the value of <xref linkend="guc-autovacuum-freeze-max-age">, so

doc/src/sgml/maintenance.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/maintenance.sgml,v 1.88 2008/12/11 18:16:18 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/maintenance.sgml,v 1.89 2009/01/16 13:27:23 heikki Exp $ -->
 
 <chapter id="maintenance">
  <title>Routine Database Maintenance Tasks</title>
@@ -367,10 +367,14 @@
    </para>
 
    <para>
-    <command>VACUUM</>'s behavior is controlled by the configuration parameter
-    <xref linkend="guc-vacuum-freeze-min-age">: any XID older than
-    <varname>vacuum_freeze_min_age</> transactions is replaced by
-    <literal>FrozenXID</>.  Larger values of <varname>vacuum_freeze_min_age</>
+    <command>VACUUM</>'s behavior is controlled by the two configuration
+    parameters: <xref linkend="guc-vacuum-freeze-min-age"> and
+    <xref linkend="guc-vacuum-freeze-table-age">.
+    <varname>vacuum_freeze_table_age</> controls when <command>VACUUM</>
+    performs a full sweep of the table, in order to replace old XID values 
+    with <literal>FrozenXID</>.  <varname>vacuum_freeze_min_age</> 
+    controls how old an XID value has to be before it's replaced with
+    <literal>FrozenXID</>.  Larger values of these settings
     preserve transactional information longer, while smaller values increase
     the number of transactions that can elapse before the table must be
     vacuumed again.
@@ -379,7 +383,8 @@
    <para>
     The maximum time that a table can go unvacuumed is two billion
     transactions minus the <varname>vacuum_freeze_min_age</> that was used
-    when it was last vacuumed.  If it were to go unvacuumed for longer than
+    when <command>VACUUM</> last scanned the whole table.  If it were to go
+    unvacuumed for longer than
     that, data loss could result.  To ensure that this does not happen,
     autovacuum is invoked on any table that might contain XIDs older than the
     age specified by the configuration parameter <xref
@@ -403,7 +408,8 @@
    </para>
 
    <para>
-    The sole disadvantage of increasing <varname>autovacuum_freeze_max_age</>
+    The sole disadvantage of increasing <varname>vacuum_freeze_table_age</>
+    and <varname>autovacuum_freeze_max_age</>
     is that the <filename>pg_clog</> subdirectory of the database cluster
     will take more space, because it must store the commit status for all
     transactions back to the <varname>autovacuum_freeze_max_age</> horizon.
@@ -411,8 +417,9 @@
     <varname>autovacuum_freeze_max_age</> has its maximum allowed value of
     a little less than two billion, <filename>pg_clog</> can be expected to
     grow to about half a gigabyte.  If this is trivial compared to your
-    total database size, setting <varname>autovacuum_freeze_max_age</> to
-    its maximum allowed value is recommended.  Otherwise, set it depending
+    total database size, setting <varname>autovacuum_freeze_max_age</> and
+    <varname>vacuum_freeze_table_age</varname> to their maximum allowed values
+    is recommended.  Otherwise, set them depending
     on what you are willing to allow for <filename>pg_clog</> storage.
     (The default, 200 million transactions, translates to about 50MB of
     <filename>pg_clog</> storage.)
@@ -455,13 +462,24 @@ SELECT datname, age(datfrozenxid) FROM pg_database;
 </programlisting>
 
     The <literal>age</> column measures the number of transactions from the
-    cutoff XID to the current transaction's XID.  Immediately after a
-    <command>VACUUM</>, <literal>age(relfrozenxid)</> should be a little
-    more than the <varname>vacuum_freeze_min_age</> setting that was used
-    (more by the number of transactions started since the <command>VACUUM</>
-    started).  If <literal>age(relfrozenxid)</> exceeds
-    <varname>autovacuum_freeze_max_age</>, an autovacuum will soon be forced
-    for the table.
+    cutoff XID to the current transaction's XID.  When <command>VACUUM</>
+    scans the whole table, after it's finished <literal>age(relfrozenxid)</>
+    should be a little more than the <varname>vacuum_freeze_min_age</> setting
+    that was used (more by the number of transactions started since the
+    <command>VACUUM</> started).
+   </para>
+
+   <para>
+    <command>VACUUM</> normally only scans pages that have been modified
+    since last vacuum, but <structfield>relfrozenxid</> can only be advanced
+    when the whole table is scanned. The whole table is scanned when
+    <structfield>relfrozenxid</> is more than
+    <varname>vacuum_freeze_table_age</> transactions old, if
+    <command>VACUUM FREEZE</> command is used, or if all pages happen to
+    require vacuuming to remove dead row versions. If no whole-table-scanning
+    <command>VACUUM</> is issued on the table until
+    <varname>autovacuum_freeze_max_age</> is reached, an autovacuum will soon
+    be forced for the table.
    </para>
 
    <para>