Transaction IDs wrap around, per my proposal of 13-Aug-01. More

documentation to come, but the code is all here.  initdb forced.

3 files changed, 77 insertions, 15 deletions

diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index e2c3139d853..39c05e24bd8 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -1,6 +1,6 @@
 <!--
  Documentation of the system catalogs, directed toward PostgreSQL developers
- $Header: /cvsroot/pgsql/doc/src/sgml/catalogs.sgml,v 2.21 2001/08/21 16:35:58 tgl Exp $
+ $Header: /cvsroot/pgsql/doc/src/sgml/catalogs.sgml,v 2.22 2001/08/26 16:55:58 tgl Exp $
  -->
 
 <chapter id="catalogs">
@@ -840,12 +840,35 @@
       <entry><type>oid</type></entry>
       <entry></entry>
       <entry>
-       Last oid in existence after the database was created; useful
+       Last system OID in the database; useful
        particularly to <application>pg_dump</application>
       </entry>
      </row>
 
      <row>
+      <entry>datvacuumxid</entry>
+      <entry><type>xid</type></entry>
+      <entry></entry>
+      <entry>
+       All tuples inserted or deleted by transaction IDs before this one
+       have been marked as known committed or known aborted in this database.
+       This is used to determine when commit-log space can be recycled.
+      </entry>
+     </row>
+
+     <row>
+      <entry>datfrozenxid</entry>
+      <entry><type>xid</type></entry>
+      <entry></entry>
+      <entry>
+       All tuples inserted by transaction IDs before this one have been
+       relabeled with a permanent (<quote>frozen</>) transaction ID in this
+       database.  This is useful to check whether a database must be vacuumed
+       soon to avoid transaction ID wraparound problems.
+      </entry>
+     </row>
+
+     <row>
       <entry>datpath</entry>
       <entry><type>text</type></entry>
       <entry></entry>
diff --git a/doc/src/sgml/ref/create_database.sgml b/doc/src/sgml/ref/create_database.sgml
index e128c1891d0..20477ac191c 100644
--- a/doc/src/sgml/ref/create_database.sgml
+++ b/doc/src/sgml/ref/create_database.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_database.sgml,v 1.17 2000/11/15 19:43:39 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_database.sgml,v 1.18 2001/08/26 16:55:59 tgl Exp $
 Postgres documentation
 -->
 
@@ -284,6 +284,20 @@ comment from Olly; response from Thomas...
    simply by setting the flag false).  The <literal>template0</literal>
    database is normally marked this way to prevent modification of it.
   </para>
+
+  <para>
+   After preparing a template database, or making any changes to one,
+   it is a good idea to perform
+   <command>VACUUM FREEZE</> or <command>VACUUM FULL FREEZE</> in that
+   database.  If this is done when there are no other open transactions
+   in the same database, then it is guaranteed that all tuples in the
+   database are <quote>frozen</> and will not be subject to transaction
+   ID wraparound problems.  This is particularly important for a database
+   that will have <literal>datallowconn</literal> set to false, since it
+   will be impossible to do routine maintenance <command>VACUUM</>s on
+   such a database.
+    See the Administrator's Guide for more information.
+  </para>
   </refsect2>
  </refsect1>
 
diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml
index e8374725b34..62e47a7086d 100644
--- a/doc/src/sgml/ref/vacuum.sgml
+++ b/doc/src/sgml/ref/vacuum.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuum.sgml,v 1.17 2001/07/10 22:09:28 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuum.sgml,v 1.18 2001/08/26 16:55:59 tgl Exp $
 Postgres documentation
 -->
 
@@ -20,11 +20,11 @@ Postgres documentation
  </refnamediv>
  <refsynopsisdiv>
   <refsynopsisdivinfo>
-   <date>2001-07-10</date>
+   <date>2001-08-26</date>
   </refsynopsisdivinfo>
   <synopsis>
-VACUUM [ FULL ] [ VERBOSE ] [ <replaceable class="PARAMETER">table</replaceable> ]
-VACUUM [ FULL ] [ VERBOSE ] ANALYZE [ <replaceable class="PARAMETER">table</replaceable> [ (<replaceable class="PARAMETER">column</replaceable> [, ...] ) ] ]
+VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ <replaceable class="PARAMETER">table</replaceable> ]
+VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] ANALYZE [ <replaceable class="PARAMETER">table</replaceable> [ (<replaceable class="PARAMETER">column</replaceable> [, ...] ) ] ]
   </synopsis>
 
   <refsect2 id="R2-SQL-VACUUM-1">
@@ -47,6 +47,14 @@ VACUUM [ FULL ] [ VERBOSE ] ANALYZE [ <replaceable class="PARAMETER">table</repl
       </listitem>
      </varlistentry>
      <varlistentry>
+      <term>FREEZE</term>
+      <listitem>
+       <para>
+        Selects aggressive <quote>freezing</quote> of tuples.
+       </para>
+      </listitem>
+     </varlistentry>
+     <varlistentry>
       <term>VERBOSE</term>
       <listitem>
        <para>
@@ -169,21 +177,38 @@ NOTICE:  Index <replaceable class="PARAMETER">index</replaceable>: Pages 28;
   </para>
 
   <para>
-   Plain <command>VACUUM</command> simply reclaims space and makes it
+   <command>VACUUM ANALYZE</command> performs a <command>VACUUM</command>
+   and then an <command>ANALYZE</command> for each selected table.  This
+   is a handy combination form for routine maintenance scripts.  See
+   <xref linkend="sql-analyze" endterm="sql-analyze-title">
+   for more details about its processing.
+  </para>
+
+  <para>
+   Plain <command>VACUUM</command> (without <literal>FULL</>) simply reclaims
+   space and makes it
    available for re-use.  This form of the command can operate in parallel
    with normal reading and writing of the table.  <command>VACUUM
    FULL</command> does more extensive processing, including moving of tuples
    across blocks to try to compact the table to the minimum number of disk
-   blocks.  This is much slower and requires an exclusive lock on each table
-   while it is being processed.
+   blocks.  This form is much slower and requires an exclusive lock on each
+   table while it is being processed.
   </para>
 
   <para>
-   <command>VACUUM ANALYZE</command> performs a <command>VACUUM</command>
-   and then an <command>ANALYZE</command> for each selected table.  This
-   is a handy combination form for routine maintenance scripts.  See
-   <xref linkend="sql-analyze" endterm="sql-analyze-title">
-   for more details about its processing.
+   <command>FREEZE</command> is a special-purpose option that
+   causes tuples to be marked <quote>frozen</quote> as soon as possible,
+   rather than waiting until they are quite old.  If this is done when there
+   are no other open transactions in the same database, then it is guaranteed
+   that all tuples in the database are <quote>frozen</> and will not be
+   subject to transaction ID wraparound problems, no matter how long the
+   database is left un-vacuumed.
+   <command>FREEZE</command> is not recommended for routine use.  Its only
+   intended usage is in connection with preparation of user-defined template
+   databases, or other databases that are completely read-only and will not
+   receive routine maintenance <command>VACUUM</> operations.
+   See <xref linkend="sql-createdatabase" endterm="sql-createdatabase-title">
+   for details.
   </para>
 
   <refsect2 id="R2-SQL-VACUUM-3">