Adding upstream version 16.2.upstream/16.2

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 386 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 0000000..fd539f5
--- /dev/null
+++ b/doc/src/sgml/ref/pg_resetwal.sgml
@@ -0,0 +1,386 @@
+<!--
+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>
+   <group choice="opt">
+    <arg choice="plain"><option>-f</option></arg>
+    <arg choice="plain"><option>--force</option></arg>
+   </group>
+   <group choice="opt">
+    <arg choice="plain"><option>-n</option></arg>
+    <arg choice="plain"><option>--dry-run</option></arg>
+   </group>
+   <arg rep="repeat"><replaceable>option</replaceable></arg>
+   <group choice="plain">
+    <group choice="opt">
+     <arg choice="plain"><option>-D</option></arg>
+     <arg choice="plain"><option>--pgdata</option></arg>
+    </group>
+    <replaceable class="parameter">datadir</replaceable>
+   </group>
+  </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</filename> 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</command>, and restore.  After restore, 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</envar>.
+  </para>
+
+  <para>
+   If <command>pg_resetwal</command> complains that it cannot determine
+   valid data for <filename>pg_control</filename>, you can force it to proceed anyway
+   by specifying the <option>-f</option> (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 location 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</option> can still be used, but
+   the recovered database must be treated with even more suspicion than
+   usual: an immediate dump and restore is imperative.  <emphasis>Do not</emphasis>
+   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>
+    <term><option>--force</option></term>
+    <listitem>
+     <para>
+      Force <command>pg_resetwal</command> to proceed even if it cannot determine
+      valid data for <filename>pg_control</filename>, as explained above.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><option>-n</option></term>
+    <term><option>--dry-run</option></term>
+    <listitem>
+     <para>
+      The <option>-n</option>/<option>--dry-run</option> option instructs
+      <command>pg_resetwal</command> to print the values reconstructed from
+      <filename>pg_control</filename> 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</filename>.  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 <replaceable class="parameter">xid</replaceable>,<replaceable class="parameter">xid</replaceable></option></term>
+    <term><option>--commit-timestamp-ids=<replaceable class="parameter">xid</replaceable>,<replaceable class="parameter">xid</replaceable></option></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</filename> 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 <replaceable class="parameter">xid_epoch</replaceable></option></term>
+    <term><option>--epoch=<replaceable class="parameter">xid_epoch</replaceable></option></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</application> and
+      <application>Skytools</application> 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 <replaceable class="parameter">walfile</replaceable></option></term>
+    <term><option>--next-wal-file=<replaceable class="parameter">walfile</replaceable></option></term>
+    <listitem>
+     <para>
+      Manually set the WAL starting location by specifying the name of the
+      next WAL segment file.
+     </para>
+
+     <para>
+      The name of next WAL segment file should be
+      larger than any WAL segment file name currently existing in
+      the directory <filename>pg_wal</filename> under the data directory.
+      These names are also in hexadecimal and have three parts.  The first
+      part is the <quote>timeline ID</quote> and should usually be kept the same.
+      For example, if <filename>00000001000000320000004A</filename> is the
+      largest entry in <filename>pg_wal</filename>, use <literal>-l 00000001000000320000004B</literal> or higher.
+     </para>
+
+     <para>
+      Note that when using nondefault WAL segment sizes, the numbers in the WAL
+      file names are different from the LSNs that are reported by system
+      functions and system views.  This option takes a WAL file name, not an
+      LSN.
+     </para>
+
+     <note>
+      <para>
+       <command>pg_resetwal</command> itself looks at the files in
+       <filename>pg_wal</filename> and chooses a default <option>-l</option> setting
+       beyond the last existing file name.  Therefore, manual adjustment of
+       <option>-l</option> should only be needed if you are aware of WAL segment
+       files that are not currently present in <filename>pg_wal</filename>, such as
+       entries in an offline archive; or if the contents of
+       <filename>pg_wal</filename> have been lost entirely.
+      </para>
+     </note>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><option>-m <replaceable class="parameter">mxid</replaceable>,<replaceable class="parameter">mxid</replaceable></option></term>
+    <term><option>--multixact-ids=<replaceable class="parameter">mxid</replaceable>,<replaceable class="parameter">mxid</replaceable></option></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</filename> 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</option>) 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 <replaceable class="parameter">oid</replaceable></option></term>
+    <term><option>--next-oid=<replaceable class="parameter">oid</replaceable></option></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 <replaceable class="parameter">mxoff</replaceable></option></term>
+    <term><option>--multixact-offset=<replaceable class="parameter">mxoff</replaceable></option></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</filename> 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>--wal-segsize=<replaceable class="parameter">wal_segment_size</replaceable></option></term>
+    <listitem>
+     <para>
+      Set the new WAL segment size, in megabytes.  The value must be set to a
+      power of 2 between 1 and 1024 (megabytes).  See the same option of <xref
+      linkend="app-initdb"/> for more information.
+     </para>
+
+     <note>
+      <para>
+       While <command>pg_resetwal</command> will set the WAL starting address
+       beyond the latest existing WAL segment file, some segment size changes
+       can cause previous WAL file names to be reused.  It is recommended to
+       use <option>-l</option> together with this option to manually set the
+       WAL starting address if WAL file name overlap will cause problems with
+       your archiving strategy.
+      </para>
+     </note>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><option>-u <replaceable class="parameter">xid</replaceable></option></term>
+    <term><option>--oldest-transaction-id=<replaceable class="parameter">xid</replaceable></option></term>
+    <listitem>
+     <para>
+      Manually set the oldest unfrozen transaction ID.
+     </para>
+
+     <para>
+      A safe value can be determined by looking for the numerically smallest
+      file name in the directory <filename>pg_xact</filename> under the data directory
+      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>0007</filename> is the smallest entry
+      in <filename>pg_xact</filename>, <literal>-u 0x700000</literal> will work (five
+      trailing zeroes provide the proper multiplier).
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><option>-x <replaceable class="parameter">xid</replaceable></option></term>
+    <term><option>--next-transaction-id=<replaceable class="parameter">xid</replaceable></option></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_xact</filename> 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</filename> is the largest entry
+      in <filename>pg_xact</filename>, <literal>-x 0x1200000</literal> will work (five
+      trailing zeroes provide the proper multiplier).
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+ <refsect1>
+  <title>Environment</title>
+
+  <variablelist>
+   <varlistentry>
+    <term><envar>PG_COLOR</envar></term>
+    <listitem>
+     <para>
+      Specifies whether to use color in diagnostic messages. Possible values
+      are <literal>always</literal>, <literal>auto</literal> and
+      <literal>never</literal>.
+     </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>
+
+  <para>
+   <command>pg_resetwal</command> works only with servers of the same
+   major version.
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="app-pgcontroldata"/></member>
+  </simplelist>
+ </refsect1>
+</refentry>