<!--
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>
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
<application>pg_waldump</application> 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
<replaceable>###</replaceable> 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>