diff options
Diffstat (limited to 'doc/src/sgml/ref/pg_waldump.sgml')
| -rw-r--r-- | doc/src/sgml/ref/pg_waldump.sgml | 414 |
1 files changed, 414 insertions, 0 deletions
diff --git a/doc/src/sgml/ref/pg_waldump.sgml b/doc/src/sgml/ref/pg_waldump.sgml new file mode 100644 index 0000000..4592d60 --- /dev/null +++ b/doc/src/sgml/ref/pg_waldump.sgml @@ -0,0 +1,414 @@ +<!-- +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> |