Add pg_xlogdump contrib program

This program relies on rm_desc backend routines and the xlogreader
infrastructure to emit human-readable rendering of WAL records.

Author: Andres Freund, with many reworks by Álvaro
Reviewed (in a much earlier version) by Peter Eisentraut

4 files changed, 208 insertions, 1 deletions

diff --git a/doc/src/sgml/contrib.sgml b/doc/src/sgml/contrib.sgml
index 39e9827fca7..dd8e09ed291 100644
--- a/doc/src/sgml/contrib.sgml
+++ b/doc/src/sgml/contrib.sgml
@@ -207,5 +207,6 @@ pages.
  &pgtestfsync;
  &pgtesttiming;
  &pgupgrade;
+ &pgxlogdump;
  </sect1>
 </appendix>
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 5d55ef357b0..b623f58b1a9 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -134,6 +134,7 @@
 <!ENTITY pgtesttiming    SYSTEM "pgtesttiming.sgml">
 <!ENTITY pgtrgm          SYSTEM "pgtrgm.sgml">
 <!ENTITY pgupgrade       SYSTEM "pgupgrade.sgml">
+<!ENTITY pgxlogdump      SYSTEM "pg_xlogdump.sgml">
 <!ENTITY postgres-fdw    SYSTEM "postgres-fdw.sgml">
 <!ENTITY seg             SYSTEM "seg.sgml">
 <!ENTITY contrib-spi     SYSTEM "contrib-spi.sgml">
diff --git a/doc/src/sgml/pg_xlogdump.sgml b/doc/src/sgml/pg_xlogdump.sgml
new file mode 100644
index 00000000000..15bdfbb46c7
--- /dev/null
+++ b/doc/src/sgml/pg_xlogdump.sgml
@@ -0,0 +1,205 @@
+<!--
+doc/src/sgml/ref/pg_xlogdump.sgml
+PostgreSQL documentation
+-->
+
+<refentry id="pg_xlogdump">
+ <refmeta>
+  <refentrytitle><application>pg_xlogdump</application></refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo>Application</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+  <refname>pg_xlogdump</refname>
+  <refpurpose>Display a human-readable rendering of the write-ahead log of a <productname>PostgreSQL</productname> database cluster</refpurpose>
+ </refnamediv>
+
+ <indexterm zone="pg_xlogdump">
+  <primary>pg_xlogdump</primary>
+ </indexterm>
+
+ <refsynopsisdiv>
+  <cmdsynopsis>
+   <command>pg_xlogdump</command>
+   <arg rep="repeat" choice="opt"><option>option</option></arg>
+   <arg choice="opt"><option>startseg</option>
+    <arg choice="opt"><option>endseg</option></arg>
+   </arg>
+  </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-APP-PGXLOGDUMP-1">
+  <title>Description</title>
+  <para>
+   <command>pg_xlogdump</command> display the write-ahead log (WAL) and is mainly
+   useful for debugging or educational purposes.
+  </para>
+
+  <para>
+   This utility can only be run by the user who installed the server, because
+   it requires read-only access to the data directory.
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>Options</title>
+
+   <para>
+    The following command-line options control the location and format of the
+    output:
+
+    <variablelist>
+
+     <varlistentry>
+      <term><replaceable class="parameter">startseg</replaceable></term>
+      <listitem>
+       <para>
+        Start reading at the specified log segment file.  This implicitly determines
+        the path in which files will be searched for, and the timeline to use.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><replaceable class="parameter">endseg</replaceable></term>
+      <listitem>
+       <para>
+        Stop after reading the specified log segment file.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-b</option></term>
+      <term><option>--bkp-details</option></term>
+      <listitem>
+       <para>
+        Output detailed information about backup blocks.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-e <replaceable>end</replaceable></option></term>
+      <term><option>--end=<replaceable>end</replaceable></option></term>
+      <listitem>
+       <para>
+        Stop reading at the specified log position, instead of reading to the
+        end of the log stream.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-n <replaceable>limit</replaceable></option></term>
+      <term><option>--limit=<replaceable>limit</replaceable></option></term>
+      <listitem>
+       <para>
+        Display the specified number of records, then stop.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-p <replaceable>path</replaceable></option></term>
+      <term><option>--path=<replaceable>path</replaceable></option></term>
+      <listitem>
+       <para>
+        Directory in which to find log segment files.  The default is to search
+        for them in the <literal>pg_xlog</literal> subdirectory of the current
+        directory.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-r <replaceable>rmgr</replaceable></option></term>
+      <term><option>--rmgr=<replaceable>rmgr</replaceable></option></term>
+      <listitem>
+       <para>
+        Only display records generated by the specified resource manager.
+        If <literal>list</> is passed as name, print a list of valid resource manager
+        names, and exit.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-s <replaceable>start</replaceable></option></term>
+      <term><option>--start=<replaceable>start</replaceable></option></term>
+      <listitem>
+       <para>
+        Log position at which to start reading. The default is to start reading
+        the first valid log record found in the earliest file found.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-t <replaceable>timeline</replaceable></option></term>
+      <term><option>--timelime=<replaceable>timeline</replaceable></option></term>
+      <listitem>
+       <para>
+        Timeline from which to read log records. The default is to use the
+        value in <literal>startseg</>, if that is specified; otherwise, the
+        default is 1.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+       <term><option>-V</></term>
+       <term><option>--version</></term>
+       <listitem>
+       <para>
+       Print the <application>pg_xlogdump</application> version and exit.
+       </para>
+       </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-x <replaceable>xid</replaceable></option></term>
+      <term><option>--xid=<replaceable>xid</replaceable></option></term>
+      <listitem>
+       <para>
+        Only display records marked with the given TransactionId.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-?</></term>
+      <term><option>--help</></term>
+       <listitem>
+        <para>
+         Show help about <application>pg_xlogdump</application> command line
+         arguments, and exit.
+        </para>
+       </listitem>
+      </varlistentry>
+    </variablelist>
+   </para>
+ </refsect1>
+
+ <refsect1>
+  <title>Notes</title>
+  <para>
+    Can give wrong results when the server is running.
+  </para>
+
+  <para>
+    Only the specified timeline is displayed (or the default, if none is
+    specified). Records in other timelines are ignored.
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="wal"></member>
+  </simplelist>
+ </rfsect1>
+
+</refentry>
diff --git a/doc/src/sgml/ref/pg_isready.sgml b/doc/src/sgml/ref/pg_isready.sgml
index 407d73ba5bd..19ff1d4935d 100644
--- a/doc/src/sgml/ref/pg_isready.sgml
+++ b/doc/src/sgml/ref/pg_isready.sgml
@@ -12,7 +12,7 @@ PostgreSQL documentation
 
  <refnamediv>
   <refname>pg_isready</refname>
-  <refpurpose>checks the connection status of a <productname>PostgreSQL</productname> server</refpurpose>
+  <refpurpose>check the connection status of a <productname>PostgreSQL</productname> server</refpurpose>
  </refnamediv>
 
  <indexterm zone="app-pg-isready">