Rename user-facing tools with "xlog" in the name to say "wal".

This means pg_receivexlog because pg_receivewal, pg_resetxlog
becomes pg_resetwal, and pg_xlogdump becomes pg_waldump.

1 files changed, 293 insertions, 0 deletions

diff --git a/doc/src/sgml/ref/pg_resetwal.sgml b/doc/src/sgml/ref/pg_resetwal.sgml
new file mode 100644
index 00000000000..0cc6fb4c4db
--- /dev/null
+++ b/doc/src/sgml/ref/pg_resetwal.sgml
@@ -0,0 +1,293 @@
+<!--
+doc/src/sgml/ref/pg_resetwal.sgml
+PostgreSQL documentation
+-->
+
+<refentry id="APP-PGRESETWAL">
+ <indexterm zone="app-pgresetwal">
+  <primary>pg_resetwal</primary>
+ </indexterm>
+
+ <refmeta>
+  <refentrytitle><application>pg_resetwal</application></refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo>Application</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+  <refname>pg_resetwal</refname>
+  <refpurpose>reset the write-ahead log and other control information of a <productname>PostgreSQL</productname> database cluster</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+  <cmdsynopsis>
+   <command>pg_resetwal</command>
+   <arg choice="opt"><option>-f</option></arg>
+   <arg choice="opt"><option>-n</option></arg>
+   <arg rep="repeat"><replaceable>option</replaceable></arg>
+   <arg choice="req"><arg choice="opt"><option>-D</option></arg> <replaceable class="parameter">datadir</replaceable></arg>
+  </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-APP-PGRESETWAL-1">
+  <title>Description</title>
+  <para>
+   <command>pg_resetwal</command> clears the write-ahead log (WAL) and
+   optionally resets some other control information stored in the
+   <filename>pg_control</> file.  This function is sometimes needed
+   if these files have become corrupted.  It should be used only as a
+   last resort, when the server will not start due to such corruption.
+  </para>
+
+  <para>
+   After running this command, it should be possible to start the server,
+   but bear in mind that the database might contain inconsistent data due to
+   partially-committed transactions.  You should immediately dump your data,
+   run <command>initdb</>, and reload.  After reload, check for
+   inconsistencies and repair as needed.
+  </para>
+
+  <para>
+   This utility can only be run by the user who installed the server, because
+   it requires read/write access to the data directory.
+   For safety reasons, you must specify the data directory on the command line.
+   <command>pg_resetwal</command> does not use the environment variable
+   <envar>PGDATA</>.
+  </para>
+
+  <para>
+   If <command>pg_resetwal</command> complains that it cannot determine
+   valid data for <filename>pg_control</>, you can force it to proceed anyway
+   by specifying the <option>-f</> (force) option.  In this case plausible
+   values will be substituted for the missing data.  Most of the fields can be
+   expected to match, but manual assistance might be needed for the next OID,
+   next transaction ID and epoch, next multitransaction ID and offset, and
+   WAL starting address fields. These fields can be set using the options
+   discussed below. If you are not able to determine correct values for all
+   these fields, <option>-f</> can still be used, but
+   the recovered database must be treated with even more suspicion than
+   usual: an immediate dump and reload is imperative.  <emphasis>Do not</>
+   execute any data-modifying operations in the database before you dump,
+   as any such action is likely to make the corruption worse.
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>Options</title>
+
+  <variablelist>
+   <varlistentry>
+    <term><option>-f</option></term>
+    <listitem>
+     <para>
+      Force <command>pg_resetwal</command> to proceed even if it cannot determine
+      valid data for <filename>pg_control</>, as explained above.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><option>-n</option></term>
+    <listitem>
+     <para>
+      The <option>-n</> (no operation) option instructs
+      <command>pg_resetwal</command> to print the values reconstructed from
+      <filename>pg_control</> and values about to be changed, and then exit
+      without modifying anything. This is mainly a debugging tool, but can be
+      useful as a sanity check before allowing <command>pg_resetwal</command>
+      to proceed for real.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><option>-V</option></term>
+    <term><option>--version</option></term>
+    <listitem><para>Display version information, then exit.</para></listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><option>-?</option></term>
+    <term><option>--help</option></term>
+    <listitem><para>Show help, then exit.</para></listitem>
+   </varlistentry>
+  </variablelist>
+
+  <para>
+   The following options are only needed when
+   <command>pg_resetwal</command> is unable to determine appropriate values
+   by reading <filename>pg_control</>.  Safe values can be determined as
+   described below.  For values that take numeric arguments, hexadecimal
+   values can be specified by using the prefix <literal>0x</literal>.
+  </para>
+
+  <variablelist>
+   <varlistentry>
+    <term><option>-c</option> <replaceable class="parameter">xid</replaceable>,<replaceable class="parameter">xid</replaceable></term>
+    <listitem>
+     <para>
+      Manually set the oldest and newest transaction IDs for which the commit
+      time can be retrieved.
+     </para>
+
+     <para>
+      A safe value for the oldest transaction ID for which the commit time can
+      be retrieved (first part) can be determined by looking
+      for the numerically smallest file name in the directory
+      <filename>pg_commit_ts</> under the data directory.  Conversely, a safe
+      value for the newest transaction ID for which the commit time can be
+      retrieved (second part) can be determined by looking for the numerically
+      greatest file name in the same directory.  The file names are in
+      hexadecimal.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><option>-e</option> <replaceable class="parameter">xid_epoch</replaceable></term>
+    <listitem>
+     <para>
+      Manually set the next transaction ID's epoch.
+     </para>
+
+     <para>
+      The transaction ID epoch is not actually stored anywhere in the database
+      except in the field that is set by <command>pg_resetwal</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</> and
+      <application>Skytools</> work correctly &mdash;
+      if so, an appropriate value should be obtainable from the state of
+      the downstream replicated database.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><option>-l</option> <replaceable class="parameter">walfile</replaceable></term>
+    <listitem>
+     <para>
+      Manually set the WAL starting address.
+     </para>
+
+     <para>
+      The WAL starting address should be
+      larger than any WAL segment file name currently existing in
+      the directory <filename>pg_wal</> under the data directory.
+      These names are also in hexadecimal and have three parts.  The first
+      part is the <quote>timeline ID</> and should usually be kept the same.
+      For example, if <filename>00000001000000320000004A</> is the
+      largest entry in <filename>pg_wal</>, use <literal>-l 00000001000000320000004B</> or higher.
+     </para>
+
+     <note>
+      <para>
+       <command>pg_resetwal</command> itself looks at the files in
+       <filename>pg_wal</> and chooses a default <option>-l</> setting
+       beyond the last existing file name.  Therefore, manual adjustment of
+       <option>-l</> should only be needed if you are aware of WAL segment
+       files that are not currently present in <filename>pg_wal</>, such as
+       entries in an offline archive; or if the contents of
+       <filename>pg_wal</> have been lost entirely.
+      </para>
+     </note>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><option>-m</option> <replaceable class="parameter">mxid</replaceable>,<replaceable class="parameter">mxid</replaceable></term>
+    <listitem>
+     <para>
+      Manually set the next and oldest multitransaction ID.
+     </para>
+
+     <para>
+      A safe value for the next multitransaction ID (first part) can be
+      determined by looking for the numerically largest file name in the
+      directory <filename>pg_multixact/offsets</> under the data directory,
+      adding one, and then multiplying by 65536 (0x10000).  Conversely, a safe
+      value for the oldest multitransaction ID (second part of
+      <option>-m</>) can be determined by looking for the numerically smallest
+      file name in the same directory and multiplying by 65536.  The file
+      names are in hexadecimal, so the easiest way to do this is to specify
+      the option value in hexadecimal and append four zeroes.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><option>-o</option> <replaceable class="parameter">oid</replaceable></term>
+    <listitem>
+     <para>
+      Manually set the next OID.
+     </para>
+
+     <para>
+      There is no comparably easy way to determine a next OID that's beyond
+      the largest one in the database, but fortunately it is not critical to
+      get the next-OID setting right.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><option>-O</option> <replaceable class="parameter">mxoff</replaceable></term>
+    <listitem>
+     <para>
+      Manually set the next multitransaction offset.
+     </para>
+
+     <para>
+      A safe value can be determined by looking for the numerically largest
+      file name in the directory <filename>pg_multixact/members</> under the
+      data directory, adding one, and then multiplying by 52352 (0xCC80).
+      The file names are in hexadecimal.  There is no simple recipe such as
+      the ones for other options of appending zeroes.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><option>-x</option> <replaceable class="parameter">xid</replaceable></term>
+    <listitem>
+     <para>
+      Manually set the next transaction ID.
+     </para>
+
+     <para>
+      A safe value can be determined by looking for the numerically largest
+      file name in the directory <filename>pg_clog</> under the data directory,
+      adding one,
+      and then multiplying by 1048576 (0x100000).  Note that the file names are in
+      hexadecimal.  It is usually easiest to specify the option value in
+      hexadecimal too. For example, if <filename>0011</> is the largest entry
+      in <filename>pg_clog</>, <literal>-x 0x1200000</> will work (five
+      trailing zeroes provide the proper multiplier).
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+ <refsect1>
+  <title>Notes</title>
+
+  <para>
+   This command must not be used when the server is
+   running.  <command>pg_resetwal</command> will refuse to start up if
+   it finds a server lock file in the data directory.  If the
+   server crashed then a lock file might have been left
+   behind; in that case you can remove the lock file to allow
+   <command>pg_resetwal</command> to run.  But before you do
+   so, make doubly certain that there is no server process still alive.
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="app-pgcontroldata"></member>
+  </simplelist>
+ </refsect1>
+</refentry>