path: root/doc/src/sgml/ref/pg_waldump.sgml

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

<refentry id="pgwaldump">
 <indexterm zone="pgwaldump">
  <primary>pg_waldump</primary>
 </indexterm>

 <refmeta>
  <refentrytitle><application>pg_waldump</application></refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo>Application</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>pg_waldump</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_waldump</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-pgwaldump-1">
  <title>Description</title>
  <para>
   <command>pg_waldump</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 WAL 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 WAL 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>-B <replaceable>block</replaceable></option></term>
      <term><option>--block=<replaceable>block</replaceable></option></term>
      <listitem>
       <para>
        Only display records that modify the given block.  The relation must
        also be provided with <option>--relation</option> or
        <option>-R</option>.
       </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 WAL location, 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>-F <replaceable>fork</replaceable></option></term>
      <term><option>--fork=<replaceable>fork</replaceable></option></term>
      <listitem>
       <para>
        If provided, only display records that modify blocks in the given fork.
        The valid values are <literal>main</literal> for the main fork,
        <literal>fsm</literal> for the free space map,
        <literal>vm</literal> for the visibility map,
        and <literal>init</literal> for the init fork.
       </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>
        Specifies a directory to search for WAL segment files or a
        directory with a <literal>pg_wal</literal> subdirectory that
        contains such files.  The default is to search in the current
        directory, the <literal>pg_wal</literal> subdirectory of the
        current directory, and the <literal>pg_wal</literal> subdirectory
        of <envar>PGDATA</envar>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-q</option></term>
      <term><option>--quiet</option></term>
      <listitem>
       <para>
        Do not print any output, except for errors. This option can be useful
        when you want to know whether a range of WAL records can be
        successfully parsed but don't care about the record contents.
       </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. You can
        specify the option multiple times to select multiple resource managers.
        If <literal>list</literal> is passed as name, print a list of valid resource manager
        names, and exit.
       </para>
       <para>
        Extensions may define custom resource managers, but pg_waldump does
        not load the extension module and therefore does not recognize custom
        resource managers by name. Instead, you can specify the custom
        resource managers as <literal>custom###</literal> where
        "<literal>###</literal>" is the three-digit resource manager ID. Names
        of this form will always be considered valid.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-R <replaceable>tblspc</replaceable>/<replaceable>db</replaceable>/<replaceable>rel</replaceable></option></term>
      <term><option>--relation=<replaceable>tblspc</replaceable>/<replaceable>db</replaceable>/<replaceable>rel</replaceable></option></term>
      <listitem>
       <para>
        Only display records that modify blocks in the given relation.  The
        relation is specified with tablespace OID, database OID, and relfilenode
        separated by slashes, for example <literal>1234/12345/12345</literal>.
        This is the same format used for relations in the program's output.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-s <replaceable>start</replaceable></option></term>
      <term><option>--start=<replaceable>start</replaceable></option></term>
      <listitem>
       <para>
        WAL location at which to start reading. The default is to start reading
        the first valid WAL 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 WAL records. The default is to use the
        value in <replaceable>startseg</replaceable>, if that is specified; otherwise, the
        default is 1.  The value can be specified in decimal or hexadecimal,
        for example <literal>17</literal> or <literal>0x11</literal>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
       <term><option>-V</option></term>
       <term><option>--version</option></term>
       <listitem>
       <para>
       Print the <application>pg_waldump</application> version and exit.
       </para>
       </listitem>
     </varlistentry>

     <varlistentry>
       <term><option>-w</option></term>
       <term><option>--fullpage</option></term>
       <listitem>
       <para>
        Only display records that include full page images.
       </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>

       <para>
        If <application>pg_waldump</application> is terminated by signal
        <systemitem>SIGINT</systemitem>
        (<keycombo action="simul"><keycap>Control</keycap><keycap>C</keycap></keycombo>),
        the summary of the statistics computed is displayed up to the
        termination point. This operation is not supported on
        <productname>Windows</productname>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
       <term><option>--save-fullpage=<replaceable>save_path</replaceable></option></term>
       <listitem>
       <para>
        Save full page images found in the WAL records to the
        <replaceable>save_path</replaceable> directory. The images saved
        are subject to the same filtering and limiting criteria as the
        records displayed.
       </para>
       <para>
        The full page images are saved with the following file name format:
        <literal><replaceable>TIMELINE</replaceable>-<replaceable>LSN</replaceable>.<replaceable>RELTABLESPACE</replaceable>.<replaceable>DATOID</replaceable>.<replaceable>RELNODE</replaceable>.<replaceable>BLKNO</replaceable><replaceable>FORK</replaceable></literal>

        The file names are composed of the following parts:
        <informaltable>
         <tgroup cols="2">
          <thead>
           <row>
            <entry>Component</entry>
            <entry>Description</entry>
           </row>
          </thead>

          <tbody>
           <row>
            <entry>TIMELINE</entry>
            <entry>The timeline of the WAL segment file where the record
             is located formatted as one 8-character hexadecimal number
             <literal>%08X</literal></entry>
           </row>

           <row>
            <entry>LSN</entry>
            <entry>The <acronym>LSN</acronym> of the record with this image,
             formatted as two 8-character hexadecimal numbers
             <literal>%08X-%08X</literal></entry>
           </row>

           <row>
            <entry>RELTABLESPACE</entry>
            <entry>tablespace OID of the block</entry>
           </row>

           <row>
            <entry>DATOID</entry>
            <entry>database OID of the block</entry>
           </row>

           <row>
            <entry>RELNODE</entry>
            <entry>filenode of the block</entry>
           </row>

           <row>
            <entry>BLKNO</entry>
            <entry>block number of the block</entry>
           </row>

           <row>
            <entry>FORK</entry>
            <entry>
             The name of the fork the full page image came from, such as
             <literal>_main</literal>, <literal>_fsm</literal>,
             <literal>_vm</literal>, or <literal>_init</literal>.
            </entry>
           </row>
          </tbody>
         </tgroup>
        </informaltable>
       </para>
       </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-?</option></term>
      <term><option>--help</option></term>
       <listitem>
        <para>
         Show help about <application>pg_waldump</application> command line
         arguments, and exit.
        </para>
       </listitem>
      </varlistentry>
    </variablelist>
   </para>
 </refsect1>

 <refsect1>
  <title>Environment</title>

  <variablelist>
   <varlistentry>
    <term><envar>PGDATA</envar></term>
    <listitem>
     <para>
      Data directory; see also the <option>-p</option> option.
     </para>
    </listitem>
   </varlistentry>

   <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>
    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_waldump</application> cannot read WAL files with suffix
    <literal>.partial</literal>. If those files need to be read, <literal>.partial</literal>
    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>