1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>pg_waldump</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="pgupgrade.html" title="pg_upgrade" /><link rel="next" href="app-pgwalsummary.html" title="pg_walsummary" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">pg_waldump</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="pgupgrade.html" title="pg_upgrade">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><th width="60%" align="center">PostgreSQL Server Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-pgwalsummary.html" title="pg_walsummary">Next</a></td></tr></table><hr /></div><div class="refentry" id="PGWALDUMP"><div class="titlepage"></div><a id="id-1.9.5.14.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">pg_waldump</span></span></h2><p>pg_waldump — display a human-readable rendering of the write-ahead log of a <span class="productname">PostgreSQL</span> database cluster</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.5.14.4.1"><code class="command">pg_waldump</code> [<code class="option">option</code>...] [<code class="option">startseg</code> [<code class="option">endseg</code>]]</p></div></div><div class="refsect1" id="R1-APP-PGWALDUMP-1"><h2>Description</h2><p>
3 <code class="command">pg_waldump</code> displays the write-ahead log (WAL) and is mainly
4 useful for debugging or educational purposes.
6 This utility can only be run by the user who installed the server, because
7 it requires read-only access to the data directory.
8 </p></div><div class="refsect1" id="id-1.9.5.14.6"><h2>Options</h2><p>
9 The following command-line options control the location and format of the
12 </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>startseg</code></em></span></dt><dd><p>
13 Start reading at the specified WAL segment file. This implicitly determines
14 the path in which files will be searched for, and the timeline to use.
15 </p></dd><dt><span class="term"><em class="replaceable"><code>endseg</code></em></span></dt><dd><p>
16 Stop after reading the specified WAL segment file.
17 </p></dd><dt><span class="term"><code class="option">-b</code><br /></span><span class="term"><code class="option">--bkp-details</code></span></dt><dd><p>
18 Output detailed information about backup blocks.
19 </p></dd><dt><span class="term"><code class="option">-B <em class="replaceable"><code>block</code></em></code><br /></span><span class="term"><code class="option">--block=<em class="replaceable"><code>block</code></em></code></span></dt><dd><p>
20 Only display records that modify the given block. The relation must
21 also be provided with <code class="option">--relation</code> or
22 <code class="option">-R</code>.
23 </p></dd><dt><span class="term"><code class="option">-e <em class="replaceable"><code>end</code></em></code><br /></span><span class="term"><code class="option">--end=<em class="replaceable"><code>end</code></em></code></span></dt><dd><p>
24 Stop reading at the specified WAL location, instead of reading to the
25 end of the log stream.
26 </p></dd><dt><span class="term"><code class="option">-f</code><br /></span><span class="term"><code class="option">--follow</code></span></dt><dd><p>
27 After reaching the end of valid WAL, keep polling once per second for
29 </p></dd><dt><span class="term"><code class="option">-F <em class="replaceable"><code>fork</code></em></code><br /></span><span class="term"><code class="option">--fork=<em class="replaceable"><code>fork</code></em></code></span></dt><dd><p>
30 Only display records that modify blocks in the given fork.
31 The valid values are <code class="literal">main</code> for the main fork,
32 <code class="literal">fsm</code> for the free space map,
33 <code class="literal">vm</code> for the visibility map,
34 and <code class="literal">init</code> for the init fork.
35 </p></dd><dt><span class="term"><code class="option">-n <em class="replaceable"><code>limit</code></em></code><br /></span><span class="term"><code class="option">--limit=<em class="replaceable"><code>limit</code></em></code></span></dt><dd><p>
36 Display the specified number of records, then stop.
37 </p></dd><dt><span class="term"><code class="option">-p <em class="replaceable"><code>path</code></em></code><br /></span><span class="term"><code class="option">--path=<em class="replaceable"><code>path</code></em></code></span></dt><dd><p>
38 Specifies a directory to search for WAL segment files or a
39 directory with a <code class="literal">pg_wal</code> subdirectory that
40 contains such files. The default is to search in the current
41 directory, the <code class="literal">pg_wal</code> subdirectory of the
42 current directory, and the <code class="literal">pg_wal</code> subdirectory
43 of <code class="envar">PGDATA</code>.
44 </p></dd><dt><span class="term"><code class="option">-q</code><br /></span><span class="term"><code class="option">--quiet</code></span></dt><dd><p>
45 Do not print any output, except for errors. This option can be useful
46 when you want to know whether a range of WAL records can be
47 successfully parsed but don't care about the record contents.
48 </p></dd><dt><span class="term"><code class="option">-r <em class="replaceable"><code>rmgr</code></em></code><br /></span><span class="term"><code class="option">--rmgr=<em class="replaceable"><code>rmgr</code></em></code></span></dt><dd><p>
49 Only display records generated by the specified resource manager. You can
50 specify the option multiple times to select multiple resource managers.
51 If <code class="literal">list</code> is passed as name, print a list of valid resource manager
54 Extensions may define custom resource managers, but
55 <span class="application">pg_waldump</span> does
56 not load the extension module and therefore does not recognize custom
57 resource managers by name. Instead, you can specify the custom
58 resource managers as <code class="literal">custom###</code> where
59 <em class="replaceable"><code>###</code></em> is the three-digit resource manager ID.
60 Names of this form will always be considered valid.
61 </p></dd><dt><span class="term"><code class="option">-R <em class="replaceable"><code>tblspc</code></em>/<em class="replaceable"><code>db</code></em>/<em class="replaceable"><code>rel</code></em></code><br /></span><span class="term"><code class="option">--relation=<em class="replaceable"><code>tblspc</code></em>/<em class="replaceable"><code>db</code></em>/<em class="replaceable"><code>rel</code></em></code></span></dt><dd><p>
62 Only display records that modify blocks in the given relation. The
63 relation is specified with tablespace OID, database OID, and relfilenode
64 separated by slashes, for example <code class="literal">1234/12345/12345</code>.
65 This is the same format used for relations in the program's output.
66 </p></dd><dt><span class="term"><code class="option">-s <em class="replaceable"><code>start</code></em></code><br /></span><span class="term"><code class="option">--start=<em class="replaceable"><code>start</code></em></code></span></dt><dd><p>
67 WAL location at which to start reading. The default is to start reading
68 the first valid WAL record found in the earliest file found.
69 </p></dd><dt><span class="term"><code class="option">-t <em class="replaceable"><code>timeline</code></em></code><br /></span><span class="term"><code class="option">--timeline=<em class="replaceable"><code>timeline</code></em></code></span></dt><dd><p>
70 Timeline from which to read WAL records. The default is to use the
71 value in <em class="replaceable"><code>startseg</code></em>, if that is specified; otherwise, the
72 default is 1. The value can be specified in decimal or hexadecimal,
73 for example <code class="literal">17</code> or <code class="literal">0x11</code>.
74 </p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
75 Print the <span class="application">pg_waldump</span> version and exit.
76 </p></dd><dt><span class="term"><code class="option">-w</code><br /></span><span class="term"><code class="option">--fullpage</code></span></dt><dd><p>
77 Only display records that include full page images.
78 </p></dd><dt><span class="term"><code class="option">-x <em class="replaceable"><code>xid</code></em></code><br /></span><span class="term"><code class="option">--xid=<em class="replaceable"><code>xid</code></em></code></span></dt><dd><p>
79 Only display records marked with the given transaction ID.
80 </p></dd><dt><span class="term"><code class="option">-z</code><br /></span><span class="term"><code class="option">--stats[=record]</code></span></dt><dd><p>
81 Display summary statistics (number and size of records and
82 full-page images) instead of individual records. Optionally
83 generate statistics per-record instead of per-rmgr.
85 If <span class="application">pg_waldump</span> is terminated by signal
86 <span class="systemitem">SIGINT</span>
87 (<span class="keycap"><strong>Control</strong></span>+<span class="keycap"><strong>C</strong></span>),
88 the summary of the statistics computed is displayed up to the
89 termination point. This operation is not supported on
90 <span class="productname">Windows</span>.
91 </p></dd><dt><span class="term"><code class="option">--save-fullpage=<em class="replaceable"><code>save_path</code></em></code></span></dt><dd><p>
92 Save full page images found in the WAL records to the
93 <em class="replaceable"><code>save_path</code></em> directory. The images saved
94 are subject to the same filtering and limiting criteria as the
97 The full page images are saved with the following file name format:
98 <code class="literal"><em class="replaceable"><code>TIMELINE</code></em>-<em class="replaceable"><code>LSN</code></em>.<em class="replaceable"><code>RELTABLESPACE</code></em>.<em class="replaceable"><code>DATOID</code></em>.<em class="replaceable"><code>RELNODE</code></em>.<em class="replaceable"><code>BLKNO</code></em>_<em class="replaceable"><code>FORK</code></em></code>
100 The file names are composed of the following parts:
101 </p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Component</th><th>Description</th></tr></thead><tbody><tr><td>TIMELINE</td><td>The timeline of the WAL segment file where the record
102 is located formatted as one 8-character hexadecimal number
103 <code class="literal">%08X</code></td></tr><tr><td>LSN</td><td>The <acronym class="acronym">LSN</acronym> of the record with this image,
104 formatted as two 8-character hexadecimal numbers
105 <code class="literal">%08X-%08X</code></td></tr><tr><td>RELTABLESPACE</td><td>tablespace OID of the block</td></tr><tr><td>DATOID</td><td>database OID of the block</td></tr><tr><td>RELNODE</td><td>filenode of the block</td></tr><tr><td>BLKNO</td><td>block number of the block</td></tr><tr><td>FORK</td><td>
106 The name of the fork the full page image came from, such as
107 <code class="literal">main</code>, <code class="literal">fsm</code>,
108 <code class="literal">vm</code>, or <code class="literal">init</code>.
109 </td></tr></tbody></table></div><p>
110 </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
111 Show help about <span class="application">pg_waldump</span> command line
113 </p></dd></dl></div><p>
114 </p></div><div class="refsect1" id="id-1.9.5.14.7"><h2>Environment</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">PGDATA</code></span></dt><dd><p>
115 Data directory; see also the <code class="option">-p</code> option.
116 </p></dd><dt><span class="term"><code class="envar">PG_COLOR</code></span></dt><dd><p>
117 Specifies whether to use color in diagnostic messages. Possible values
118 are <code class="literal">always</code>, <code class="literal">auto</code> and
119 <code class="literal">never</code>.
120 </p></dd></dl></div></div><div class="refsect1" id="id-1.9.5.14.8"><h2>Notes</h2><p>
121 Can give wrong results when the server is running.
123 Only the specified timeline is displayed (or the default, if none is
124 specified). Records in other timelines are ignored.
126 <span class="application">pg_waldump</span> cannot read WAL files with suffix
127 <code class="literal">.partial</code>. If those files need to be read, <code class="literal">.partial</code>
128 suffix needs to be removed from the file name.
129 </p></div><div class="refsect1" id="id-1.9.5.14.9"><h2>See Also</h2><span class="simplelist"><a class="xref" href="wal-internals.html" title="28.6. WAL Internals">Section 28.6</a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pgupgrade.html" title="pg_upgrade">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-server.html" title="PostgreSQL Server Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-pgwalsummary.html" title="pg_walsummary">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">pg_upgrade</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">pg_walsummary</span></td></tr></table></div></body></html>
begriffs.com / projects / ai-pg / blob