postgresql/doc/src/sgml/ref/pg_xlogdump.sgml

<!--
doc/src/sgml/ref/pg_xlogdump.sgml
PostgreSQL documentation
-->

<refentry id="pgxlogdump">
 <indexterm zone="pgxlogdump">
  <primary>pg_xlogdump</primary>
 </indexterm>

 <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>

 <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> displays 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>-f</option></term>
      <term><option>--follow</option></term>
      <listitem>
       <para>
        After reaching the end of valid WAL, keep polling once per second for
        new WAL to appear.
       </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>--timeline=<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 transaction ID.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-z</option></term>
      <term><option>--stats[=record]</option></term>
      <listitem>
       <para>
        Display summary statistics (number and size of records and
        full-page images) instead of individual records. Optionally
        generate statistics per-record instead of per-rmgr.
       </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>

  <para>
    <application>pg_xlogdump</> cannot read WAL files with suffix
    <literal>.partial</>. If those files need to be read, <literal>.partial</>
    suffix needs to be removed from the file name.
  </para>
 </refsect1>

 <refsect1>
  <title>See Also</title>

  <simplelist type="inline">
   <member><xref linkend="wal-internals"></member>
  </simplelist>
 </refsect1>

</refentry>