begriffs open source - ai-pg/blob - full-docs/man1/pg_waldump.1

   1 '\" t
   2 .\"     Title: pg_waldump
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "PG_WALDUMP" "1" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 pg_waldump \- display a human\-readable rendering of the write\-ahead log of a PostgreSQL database cluster
  32 .SH "SYNOPSIS"
  33 .HP \w'\fBpg_waldump\fR\ 'u
  34 \fBpg_waldump\fR [\fBoption\fR...] [\fBstartseg\fR\ [\fBendseg\fR]]
  35 .SH "DESCRIPTION"
  36 .PP
  37 \fBpg_waldump\fR
  38 displays the write\-ahead log (WAL) and is mainly useful for debugging or educational purposes\&.
  39 .PP
  40 This utility can only be run by the user who installed the server, because it requires read\-only access to the data directory\&.
  41 .SH "OPTIONS"
  42 .PP
  43 The following command\-line options control the location and format of the output:
  44 .PP
  45 \fIstartseg\fR
  46 .RS 4
  47 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\&.
  48 .RE
  49 .PP
  50 \fIendseg\fR
  51 .RS 4
  52 Stop after reading the specified WAL segment file\&.
  53 .RE
  54 .PP
  55 \fB\-b\fR
  56 .br
  57 \fB\-\-bkp\-details\fR
  58 .RS 4
  59 Output detailed information about backup blocks\&.
  60 .RE
  61 .PP
  62 \fB\-B \fR\fB\fIblock\fR\fR
  63 .br
  64 \fB\-\-block=\fR\fB\fIblock\fR\fR
  65 .RS 4
  66 Only display records that modify the given block\&. The relation must also be provided with
  67 \fB\-\-relation\fR
  68 or
  69 \fB\-R\fR\&.
  70 .RE
  71 .PP
  72 \fB\-e \fR\fB\fIend\fR\fR
  73 .br
  74 \fB\-\-end=\fR\fB\fIend\fR\fR
  75 .RS 4
  76 Stop reading at the specified WAL location, instead of reading to the end of the log stream\&.
  77 .RE
  78 .PP
  79 \fB\-f\fR
  80 .br
  81 \fB\-\-follow\fR
  82 .RS 4
  83 After reaching the end of valid WAL, keep polling once per second for new WAL to appear\&.
  84 .RE
  85 .PP
  86 \fB\-F \fR\fB\fIfork\fR\fR
  87 .br
  88 \fB\-\-fork=\fR\fB\fIfork\fR\fR
  89 .RS 4
  90 Only display records that modify blocks in the given fork\&. The valid values are
  91 main
  92 for the main fork,
  93 fsm
  94 for the free space map,
  95 vm
  96 for the visibility map, and
  97 init
  98 for the init fork\&.
  99 .RE
 100 .PP
 101 \fB\-n \fR\fB\fIlimit\fR\fR
 102 .br
 103 \fB\-\-limit=\fR\fB\fIlimit\fR\fR
 104 .RS 4
 105 Display the specified number of records, then stop\&.
 106 .RE
 107 .PP
 108 \fB\-p \fR\fB\fIpath\fR\fR
 109 .br
 110 \fB\-\-path=\fR\fB\fIpath\fR\fR
 111 .RS 4
 112 Specifies a directory to search for WAL segment files or a directory with a
 113 pg_wal
 114 subdirectory that contains such files\&. The default is to search in the current directory, the
 115 pg_wal
 116 subdirectory of the current directory, and the
 117 pg_wal
 118 subdirectory of
 119 \fBPGDATA\fR\&.
 120 .RE
 121 .PP
 122 \fB\-q\fR
 123 .br
 124 \fB\-\-quiet\fR
 125 .RS 4
 126 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\*(Aqt care about the record contents\&.
 127 .RE
 128 .PP
 129 \fB\-r \fR\fB\fIrmgr\fR\fR
 130 .br
 131 \fB\-\-rmgr=\fR\fB\fIrmgr\fR\fR
 132 .RS 4
 133 Only display records generated by the specified resource manager\&. You can specify the option multiple times to select multiple resource managers\&. If
 134 list
 135 is passed as name, print a list of valid resource manager names, and exit\&.
 136 .sp
 137 Extensions may define custom resource managers, but
 138 pg_waldump
 139 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
 140 custom###
 141 where
 142 \fI###\fR
 143 is the three\-digit resource manager ID\&. Names of this form will always be considered valid\&.
 144 .RE
 145 .PP
 146 \fB\-R \fR\fB\fItblspc\fR\fR\fB/\fR\fB\fIdb\fR\fR\fB/\fR\fB\fIrel\fR\fR
 147 .br
 148 \fB\-\-relation=\fR\fB\fItblspc\fR\fR\fB/\fR\fB\fIdb\fR\fR\fB/\fR\fB\fIrel\fR\fR
 149 .RS 4
 150 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
 151 1234/12345/12345\&. This is the same format used for relations in the program\*(Aqs output\&.
 152 .RE
 153 .PP
 154 \fB\-s \fR\fB\fIstart\fR\fR
 155 .br
 156 \fB\-\-start=\fR\fB\fIstart\fR\fR
 157 .RS 4
 158 WAL location at which to start reading\&. The default is to start reading the first valid WAL record found in the earliest file found\&.
 159 .RE
 160 .PP
 161 \fB\-t \fR\fB\fItimeline\fR\fR
 162 .br
 163 \fB\-\-timeline=\fR\fB\fItimeline\fR\fR
 164 .RS 4
 165 Timeline from which to read WAL records\&. The default is to use the value in
 166 \fIstartseg\fR, if that is specified; otherwise, the default is 1\&. The value can be specified in decimal or hexadecimal, for example
 167 17
 168 or
 169 0x11\&.
 170 .RE
 171 .PP
 172 \fB\-V\fR
 173 .br
 174 \fB\-\-version\fR
 175 .RS 4
 176 Print the
 177 pg_waldump
 178 version and exit\&.
 179 .RE
 180 .PP
 181 \fB\-w\fR
 182 .br
 183 \fB\-\-fullpage\fR
 184 .RS 4
 185 Only display records that include full page images\&.
 186 .RE
 187 .PP
 188 \fB\-x \fR\fB\fIxid\fR\fR
 189 .br
 190 \fB\-\-xid=\fR\fB\fIxid\fR\fR
 191 .RS 4
 192 Only display records marked with the given transaction ID\&.
 193 .RE
 194 .PP
 195 \fB\-z\fR
 196 .br
 197 \fB\-\-stats[=record]\fR
 198 .RS 4
 199 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\&.
 200 .sp
 201 If
 202 pg_waldump
 203 is terminated by signal
 204 SIGINT
 205 (Control+C), the summary of the statistics computed is displayed up to the termination point\&. This operation is not supported on
 206 Windows\&.
 207 .RE
 208 .PP
 209 \fB\-\-save\-fullpage=\fR\fB\fIsave_path\fR\fR
 210 .RS 4
 211 Save full page images found in the WAL records to the
 212 \fIsave_path\fR
 213 directory\&. The images saved are subject to the same filtering and limiting criteria as the records displayed\&.
 214 .sp
 215 The full page images are saved with the following file name format:
 216 \fITIMELINE\fR\-\fILSN\fR\&.\fIRELTABLESPACE\fR\&.\fIDATOID\fR\&.\fIRELNODE\fR\&.\fIBLKNO\fR_\fIFORK\fR
 217 The file names are composed of the following parts:
 218 .TS
 219 allbox tab(:);
 220 lB lB.
 221 T{
 222 Component
 223 T}:T{
 224 Description
 225 T}
 226 .T&
 227 l l
 228 l l
 229 l l
 230 l l
 231 l l
 232 l l
 233 l l.
 234 T{
 235 TIMELINE
 236 T}:T{
 237 The timeline of the WAL segment file where the record
 238              is located formatted as one 8\-character hexadecimal number
 239              %08X
 240 T}
 241 T{
 242 LSN
 243 T}:T{
 244 The LSN of the record with this image,
 245              formatted as two 8\-character hexadecimal numbers
 246              %08X\-%08X
 247 T}
 248 T{
 249 RELTABLESPACE
 250 T}:T{
 251 tablespace OID of the block
 252 T}
 253 T{
 254 DATOID
 255 T}:T{
 256 database OID of the block
 257 T}
 258 T{
 259 RELNODE
 260 T}:T{
 261 filenode of the block
 262 T}
 263 T{
 264 BLKNO
 265 T}:T{
 266 block number of the block
 267 T}
 268 T{
 269 FORK
 270 T}:T{
 271 The name of the fork the full page image came from, such as
 272              main, fsm,
 273              vm, or init\&.
 274 T}
 275 .TE
 276 .sp 1
 277 .RE
 278 .PP
 279 \fB\-?\fR
 280 .br
 281 \fB\-\-help\fR
 282 .RS 4
 283 Show help about
 284 pg_waldump
 285 command line arguments, and exit\&.
 286 .RE
 287 .SH "ENVIRONMENT"
 288 .PP
 289 \fBPGDATA\fR
 290 .RS 4
 291 Data directory; see also the
 292 \fB\-p\fR
 293 option\&.
 294 .RE
 295 .PP
 296 \fBPG_COLOR\fR
 297 .RS 4
 298 Specifies whether to use color in diagnostic messages\&. Possible values are
 299 always,
 300 auto
 301 and
 302 never\&.
 303 .RE
 304 .SH "NOTES"
 305 .PP
 306 Can give wrong results when the server is running\&.
 307 .PP
 308 Only the specified timeline is displayed (or the default, if none is specified)\&. Records in other timelines are ignored\&.
 309 .PP
 310 pg_waldump
 311 cannot read WAL files with suffix
 312 \&.partial\&. If those files need to be read,
 313 \&.partial
 314 suffix needs to be removed from the file name\&.
 315 .SH "SEE ALSO"
 316 Section\ \&28.6