From 35af5422f640e74029a167d106604da35ae64c5f Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Mon, 21 Aug 2006 16:16:31 +0000
Subject: Make the server track an 'XID epoch', that is, maintain higher-order
 bits of the transaction ID counter.  Nothing is done with the epoch except to
 store it in checkpoint records, but this provides a foundation with which
 add-on code can pretend that XIDs never wrap around.  This is a severely
 trimmed and rewritten version of the xxid patch submitted by Marko Kreen. Per
 discussion, the epoch counter seems the only part of xxid that really needs
 to be in the core server.

---
 doc/src/sgml/ref/pg_resetxlog.sgml | 28 +++++++++++++++++++++-------
 1 file changed, 21 insertions(+), 7 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/ref/pg_resetxlog.sgml b/doc/src/sgml/ref/pg_resetxlog.sgml
index acdf0c7aed4..24504621694 100644
--- a/doc/src/sgml/ref/pg_resetxlog.sgml
+++ b/doc/src/sgml/ref/pg_resetxlog.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/pg_resetxlog.sgml,v 1.16 2006/06/18 15:38:36 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/pg_resetxlog.sgml,v 1.17 2006/08/21 16:16:31 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -22,6 +22,7 @@ PostgreSQL documentation
    <arg>-n</arg>
    <arg>-o<replaceable class="parameter">oid</replaceable> </arg>
    <arg>-x <replaceable class="parameter">xid</replaceable> </arg>
+   <arg>-e <replaceable class="parameter">xid_epoch</replaceable> </arg>
    <arg>-m <replaceable class="parameter">mxid</replaceable> </arg>
    <arg>-O <replaceable class="parameter">mxoff</replaceable> </arg>
    <arg>-l <replaceable class="parameter">timelineid</replaceable>,<replaceable class="parameter">fileid</replaceable>,<replaceable class="parameter">seg</replaceable> </arg>
@@ -61,9 +62,9 @@ PostgreSQL documentation
    by specifying the <literal>-f</> (force) switch.  In this case plausible
    values will be substituted for the missing data.  Most of the fields can be
    expected to match, but manual assistance may be needed for the next OID,
-   next transaction ID, next multitransaction ID and offset,
+   next transaction ID and epoch, next multitransaction ID and offset,
    WAL starting address, and database locale fields.
-   The first five of these can be set using the switches discussed below.
+   The first six of these can be set using the switches discussed below.
    <command>pg_resetxlog</command>'s own environment is the source for its
    guess at the locale fields; take care that <envar>LANG</> and so forth
    match the environment that <command>initdb</> was run in.
@@ -76,11 +77,12 @@ PostgreSQL documentation
   </para>
 
   <para>
-   The <literal>-o</>, <literal>-x</>, <literal>-m</>, <literal>-O</>,
+   The <literal>-o</>, <literal>-x</>, <literal>-e</>,
+   <literal>-m</>, <literal>-O</>,
    and <literal>-l</>
-   switches allow the next OID, next transaction ID, next multitransaction
-   ID, next multitransaction offset, and WAL starting address values to
-   be set manually.  These are only needed when
+   switches allow the next OID, next transaction ID, next transaction ID's
+   epoch, next multitransaction ID, next multitransaction offset, and WAL
+   starting address values to be set manually.  These are only needed when
    <command>pg_resetxlog</command> is unable to determine appropriate values
    by reading <filename>pg_control</>.  Safe values may be determined as
    follows:
@@ -146,6 +148,18 @@ PostgreSQL documentation
       get the next-OID setting right.
      </para>
     </listitem>
+
+    <listitem>
+     <para>
+      The transaction ID epoch is not actually stored anywhere in the database
+      except in the field that is set by <command>pg_resetxlog</command>,
+      so any value will work so far as the database itself is concerned.
+      You might need to adjust this value to ensure that replication
+      systems such as <application>Slony-I</> work correctly &mdash;
+      if so, an appropriate value should be obtainable from the state of
+      the downstream replicated database.
+     </para>
+    </listitem>
    </itemizedlist>
   </para>
 
-- 
cgit v1.2.3