doc/src/sgml/ref/pg_waldump.sgml

   1 <!--
   2 doc/src/sgml/ref/pg_waldump.sgml
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="pgwaldump">
   7  <indexterm zone="pgwaldump">
   8   <primary>pg_waldump</primary>
   9  </indexterm>
  10
  11  <refmeta>
  12   <refentrytitle><application>pg_waldump</application></refentrytitle>
  13   <manvolnum>1</manvolnum>
  14   <refmiscinfo>Application</refmiscinfo>
  15  </refmeta>
  16
  17  <refnamediv>
  18   <refname>pg_waldump</refname>
  19   <refpurpose>display a human-readable rendering of the write-ahead log of a <productname>PostgreSQL</productname> database cluster</refpurpose>
  20  </refnamediv>
  21
  22  <refsynopsisdiv>
  23   <cmdsynopsis>
  24    <command>pg_waldump</command>
  25    <arg rep="repeat" choice="opt"><option>option</option></arg>
  26    <arg choice="opt"><option>startseg</option><arg choice="opt"><option>endseg</option></arg></arg>
  27   </cmdsynopsis>
  28  </refsynopsisdiv>
  29
  30  <refsect1 id="r1-app-pgwaldump-1">
  31   <title>Description</title>
  32   <para>
  33    <command>pg_waldump</command> displays the write-ahead log (WAL) and is mainly
  34    useful for debugging or educational purposes.
  35   </para>
  36
  37   <para>
  38    This utility can only be run by the user who installed the server, because
  39    it requires read-only access to the data directory.
  40   </para>
  41  </refsect1>
  42
  43  <refsect1>
  44   <title>Options</title>
  45
  46    <para>
  47     The following command-line options control the location and format of the
  48     output:
  49
  50     <variablelist>
  51
  52      <varlistentry>
  53       <term><replaceable class="parameter">startseg</replaceable></term>
  54       <listitem>
  55        <para>
  56         Start reading at the specified WAL segment file.  This implicitly determines
  57         the path in which files will be searched for, and the timeline to use.
  58        </para>
  59       </listitem>
  60      </varlistentry>
  61
  62      <varlistentry>
  63       <term><replaceable class="parameter">endseg</replaceable></term>
  64       <listitem>
  65        <para>
  66         Stop after reading the specified WAL segment file.
  67        </para>
  68       </listitem>
  69      </varlistentry>
  70
  71      <varlistentry>
  72       <term><option>-b</option></term>
  73       <term><option>--bkp-details</option></term>
  74       <listitem>
  75        <para>
  76         Output detailed information about backup blocks.
  77        </para>
  78       </listitem>
  79      </varlistentry>
  80
  81      <varlistentry>
  82       <term><option>-B <replaceable>block</replaceable></option></term>
  83       <term><option>--block=<replaceable>block</replaceable></option></term>
  84       <listitem>
  85        <para>
  86         Only display records that modify the given block.  The relation must
  87         also be provided with <option>--relation</option> or
  88         <option>-R</option>.
  89        </para>
  90       </listitem>
  91      </varlistentry>
  92
  93      <varlistentry>
  94       <term><option>-e <replaceable>end</replaceable></option></term>
  95       <term><option>--end=<replaceable>end</replaceable></option></term>
  96       <listitem>
  97        <para>
  98         Stop reading at the specified WAL location, instead of reading to the
  99         end of the log stream.
 100        </para>
 101       </listitem>
 102      </varlistentry>
 103
 104      <varlistentry>
 105       <term><option>-f</option></term>
 106       <term><option>--follow</option></term>
 107       <listitem>
 108        <para>
 109         After reaching the end of valid WAL, keep polling once per second for
 110         new WAL to appear.
 111        </para>
 112       </listitem>
 113      </varlistentry>
 114
 115      <varlistentry>
 116       <term><option>-F <replaceable>fork</replaceable></option></term>
 117       <term><option>--fork=<replaceable>fork</replaceable></option></term>
 118       <listitem>
 119        <para>
 120         Only display records that modify blocks in the given fork.
 121         The valid values are <literal>main</literal> for the main fork,
 122         <literal>fsm</literal> for the free space map,
 123         <literal>vm</literal> for the visibility map,
 124         and <literal>init</literal> for the init fork.
 125        </para>
 126       </listitem>
 127      </varlistentry>
 128
 129      <varlistentry>
 130       <term><option>-n <replaceable>limit</replaceable></option></term>
 131       <term><option>--limit=<replaceable>limit</replaceable></option></term>
 132       <listitem>
 133        <para>
 134         Display the specified number of records, then stop.
 135        </para>
 136       </listitem>
 137      </varlistentry>
 138
 139      <varlistentry>
 140       <term><option>-p <replaceable>path</replaceable></option></term>
 141       <term><option>--path=<replaceable>path</replaceable></option></term>
 142       <listitem>
 143        <para>
 144         Specifies a directory to search for WAL segment files or a
 145         directory with a <literal>pg_wal</literal> subdirectory that
 146         contains such files.  The default is to search in the current
 147         directory, the <literal>pg_wal</literal> subdirectory of the
 148         current directory, and the <literal>pg_wal</literal> subdirectory
 149         of <envar>PGDATA</envar>.
 150        </para>
 151       </listitem>
 152      </varlistentry>
 153
 154      <varlistentry>
 155       <term><option>-q</option></term>
 156       <term><option>--quiet</option></term>
 157       <listitem>
 158        <para>
 159         Do not print any output, except for errors. This option can be useful
 160         when you want to know whether a range of WAL records can be
 161         successfully parsed but don't care about the record contents.
 162        </para>
 163       </listitem>
 164      </varlistentry>
 165
 166      <varlistentry>
 167       <term><option>-r <replaceable>rmgr</replaceable></option></term>
 168       <term><option>--rmgr=<replaceable>rmgr</replaceable></option></term>
 169       <listitem>
 170        <para>
 171         Only display records generated by the specified resource manager. You can
 172         specify the option multiple times to select multiple resource managers.
 173         If <literal>list</literal> is passed as name, print a list of valid resource manager
 174         names, and exit.
 175        </para>
 176        <para>
 177         Extensions may define custom resource managers, but
 178         <application>pg_waldump</application> does
 179         not load the extension module and therefore does not recognize custom
 180         resource managers by name. Instead, you can specify the custom
 181         resource managers as <literal>custom###</literal> where
 182         <replaceable>###</replaceable> is the three-digit resource manager ID.
 183         Names of this form will always be considered valid.
 184        </para>
 185       </listitem>
 186      </varlistentry>
 187
 188      <varlistentry>
 189       <term><option>-R <replaceable>tblspc</replaceable>/<replaceable>db</replaceable>/<replaceable>rel</replaceable></option></term>
 190       <term><option>--relation=<replaceable>tblspc</replaceable>/<replaceable>db</replaceable>/<replaceable>rel</replaceable></option></term>
 191       <listitem>
 192        <para>
 193         Only display records that modify blocks in the given relation.  The
 194         relation is specified with tablespace OID, database OID, and relfilenode
 195         separated by slashes, for example <literal>1234/12345/12345</literal>.
 196         This is the same format used for relations in the program's output.
 197        </para>
 198       </listitem>
 199      </varlistentry>
 200
 201      <varlistentry>
 202       <term><option>-s <replaceable>start</replaceable></option></term>
 203       <term><option>--start=<replaceable>start</replaceable></option></term>
 204       <listitem>
 205        <para>
 206         WAL location at which to start reading. The default is to start reading
 207         the first valid WAL record found in the earliest file found.
 208        </para>
 209       </listitem>
 210      </varlistentry>
 211
 212      <varlistentry>
 213       <term><option>-t <replaceable>timeline</replaceable></option></term>
 214       <term><option>--timeline=<replaceable>timeline</replaceable></option></term>
 215       <listitem>
 216        <para>
 217         Timeline from which to read WAL records. The default is to use the
 218         value in <replaceable>startseg</replaceable>, if that is specified; otherwise, the
 219         default is 1.  The value can be specified in decimal or hexadecimal,
 220         for example <literal>17</literal> or <literal>0x11</literal>.
 221        </para>
 222       </listitem>
 223      </varlistentry>
 224
 225      <varlistentry>
 226        <term><option>-V</option></term>
 227        <term><option>--version</option></term>
 228        <listitem>
 229        <para>
 230        Print the <application>pg_waldump</application> version and exit.
 231        </para>
 232        </listitem>
 233      </varlistentry>
 234
 235      <varlistentry>
 236        <term><option>-w</option></term>
 237        <term><option>--fullpage</option></term>
 238        <listitem>
 239        <para>
 240         Only display records that include full page images.
 241        </para>
 242        </listitem>
 243      </varlistentry>
 244
 245      <varlistentry>
 246       <term><option>-x <replaceable>xid</replaceable></option></term>
 247       <term><option>--xid=<replaceable>xid</replaceable></option></term>
 248       <listitem>
 249        <para>
 250         Only display records marked with the given transaction ID.
 251        </para>
 252       </listitem>
 253      </varlistentry>
 254
 255      <varlistentry>
 256       <term><option>-z</option></term>
 257       <term><option>--stats[=record]</option></term>
 258       <listitem>
 259        <para>
 260         Display summary statistics (number and size of records and
 261         full-page images) instead of individual records. Optionally
 262         generate statistics per-record instead of per-rmgr.
 263        </para>
 264
 265        <para>
 266         If <application>pg_waldump</application> is terminated by signal
 267         <systemitem>SIGINT</systemitem>
 268         (<keycombo action="simul"><keycap>Control</keycap><keycap>C</keycap></keycombo>),
 269         the summary of the statistics computed is displayed up to the
 270         termination point. This operation is not supported on
 271         <productname>Windows</productname>.
 272        </para>
 273       </listitem>
 274      </varlistentry>
 275
 276      <varlistentry>
 277        <term><option>--save-fullpage=<replaceable>save_path</replaceable></option></term>
 278        <listitem>
 279        <para>
 280         Save full page images found in the WAL records to the
 281         <replaceable>save_path</replaceable> directory. The images saved
 282         are subject to the same filtering and limiting criteria as the
 283         records displayed.
 284        </para>
 285        <para>
 286         The full page images are saved with the following file name format:
 287         <literal><replaceable>TIMELINE</replaceable>-<replaceable>LSN</replaceable>.<replaceable>RELTABLESPACE</replaceable>.<replaceable>DATOID</replaceable>.<replaceable>RELNODE</replaceable>.<replaceable>BLKNO</replaceable>_<replaceable>FORK</replaceable></literal>
 288
 289         The file names are composed of the following parts:
 290         <informaltable>
 291          <tgroup cols="2">
 292           <thead>
 293            <row>
 294             <entry>Component</entry>
 295             <entry>Description</entry>
 296            </row>
 297           </thead>
 298
 299           <tbody>
 300            <row>
 301             <entry>TIMELINE</entry>
 302             <entry>The timeline of the WAL segment file where the record
 303              is located formatted as one 8-character hexadecimal number
 304              <literal>%08X</literal></entry>
 305            </row>
 306
 307            <row>
 308             <entry>LSN</entry>
 309             <entry>The <acronym>LSN</acronym> of the record with this image,
 310              formatted as two 8-character hexadecimal numbers
 311              <literal>%08X-%08X</literal></entry>
 312            </row>
 313
 314            <row>
 315             <entry>RELTABLESPACE</entry>
 316             <entry>tablespace OID of the block</entry>
 317            </row>
 318
 319            <row>
 320             <entry>DATOID</entry>
 321             <entry>database OID of the block</entry>
 322            </row>
 323
 324            <row>
 325             <entry>RELNODE</entry>
 326             <entry>filenode of the block</entry>
 327            </row>
 328
 329            <row>
 330             <entry>BLKNO</entry>
 331             <entry>block number of the block</entry>
 332            </row>
 333
 334            <row>
 335             <entry>FORK</entry>
 336             <entry>
 337              The name of the fork the full page image came from, such as
 338              <literal>main</literal>, <literal>fsm</literal>,
 339              <literal>vm</literal>, or <literal>init</literal>.
 340             </entry>
 341            </row>
 342           </tbody>
 343          </tgroup>
 344         </informaltable>
 345        </para>
 346        </listitem>
 347      </varlistentry>
 348
 349      <varlistentry>
 350       <term><option>-?</option></term>
 351       <term><option>--help</option></term>
 352        <listitem>
 353         <para>
 354          Show help about <application>pg_waldump</application> command line
 355          arguments, and exit.
 356         </para>
 357        </listitem>
 358       </varlistentry>
 359     </variablelist>
 360    </para>
 361  </refsect1>
 362
 363  <refsect1>
 364   <title>Environment</title>
 365
 366   <variablelist>
 367    <varlistentry>
 368     <term><envar>PGDATA</envar></term>
 369     <listitem>
 370      <para>
 371       Data directory; see also the <option>-p</option> option.
 372      </para>
 373     </listitem>
 374    </varlistentry>
 375
 376    <varlistentry>
 377     <term><envar>PG_COLOR</envar></term>
 378     <listitem>
 379      <para>
 380       Specifies whether to use color in diagnostic messages. Possible values
 381       are <literal>always</literal>, <literal>auto</literal> and
 382       <literal>never</literal>.
 383      </para>
 384     </listitem>
 385    </varlistentry>
 386   </variablelist>
 387  </refsect1>
 388
 389  <refsect1>
 390   <title>Notes</title>
 391   <para>
 392     Can give wrong results when the server is running.
 393   </para>
 394
 395   <para>
 396     Only the specified timeline is displayed (or the default, if none is
 397     specified). Records in other timelines are ignored.
 398   </para>
 399
 400   <para>
 401     <application>pg_waldump</application> cannot read WAL files with suffix
 402     <literal>.partial</literal>. If those files need to be read, <literal>.partial</literal>
 403     suffix needs to be removed from the file name.
 404   </para>
 405  </refsect1>
 406
 407  <refsect1>
 408   <title>See Also</title>
 409
 410   <simplelist type="inline">
 411    <member><xref linkend="wal-internals"/></member>
 412   </simplelist>
 413  </refsect1>
 414
 415 </refentry>