path: root/doc/src/sgml/man1/pg_waldump.1

'\" t
.\"     Title: pg_waldump
.\"    Author: The PostgreSQL Global Development Group
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 2024
.\"    Manual: PostgreSQL 16.2 Documentation
.\"    Source: PostgreSQL 16.2
.\"  Language: English
.\"
.TH "PG_WALDUMP" "1" "2024" "PostgreSQL 16.2" "PostgreSQL 16.2 Documentation"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
pg_waldump \- display a human\-readable rendering of the write\-ahead log of a PostgreSQL database cluster
.SH "SYNOPSIS"
.HP \w'\fBpg_waldump\fR\ 'u
\fBpg_waldump\fR [\fBoption\fR...] [\fBstartseg\fR\ [\fBendseg\fR]]
.SH "DESCRIPTION"
.PP
\fBpg_waldump\fR
displays the write\-ahead log (WAL) and is mainly useful for debugging or educational purposes\&.
.PP
This utility can only be run by the user who installed the server, because it requires read\-only access to the data directory\&.
.SH "OPTIONS"
.PP
The following command\-line options control the location and format of the output:
.PP
\fIstartseg\fR
.RS 4
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\&.
.RE
.PP
\fIendseg\fR
.RS 4
Stop after reading the specified WAL segment file\&.
.RE
.PP
\fB\-b\fR
.br
\fB\-\-bkp\-details\fR
.RS 4
Output detailed information about backup blocks\&.
.RE
.PP
\fB\-B \fR\fB\fIblock\fR\fR
.br
\fB\-\-block=\fR\fB\fIblock\fR\fR
.RS 4
Only display records that modify the given block\&. The relation must also be provided with
\fB\-\-relation\fR
or
\fB\-R\fR\&.
.RE
.PP
\fB\-e \fR\fB\fIend\fR\fR
.br
\fB\-\-end=\fR\fB\fIend\fR\fR
.RS 4
Stop reading at the specified WAL location, instead of reading to the end of the log stream\&.
.RE
.PP
\fB\-f\fR
.br
\fB\-\-follow\fR
.RS 4
After reaching the end of valid WAL, keep polling once per second for new WAL to appear\&.
.RE
.PP
\fB\-F \fR\fB\fIfork\fR\fR
.br
\fB\-\-fork=\fR\fB\fIfork\fR\fR
.RS 4
If provided, only display records that modify blocks in the given fork\&. The valid values are
main
for the main fork,
fsm
for the free space map,
vm
for the visibility map, and
init
for the init fork\&.
.RE
.PP
\fB\-n \fR\fB\fIlimit\fR\fR
.br
\fB\-\-limit=\fR\fB\fIlimit\fR\fR
.RS 4
Display the specified number of records, then stop\&.
.RE
.PP
\fB\-p \fR\fB\fIpath\fR\fR
.br
\fB\-\-path=\fR\fB\fIpath\fR\fR
.RS 4
Specifies a directory to search for WAL segment files or a directory with a
pg_wal
subdirectory that contains such files\&. The default is to search in the current directory, the
pg_wal
subdirectory of the current directory, and the
pg_wal
subdirectory of
\fBPGDATA\fR\&.
.RE
.PP
\fB\-q\fR
.br
\fB\-\-quiet\fR
.RS 4
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\&.
.RE
.PP
\fB\-r \fR\fB\fIrmgr\fR\fR
.br
\fB\-\-rmgr=\fR\fB\fIrmgr\fR\fR
.RS 4
Only display records generated by the specified resource manager\&. You can specify the option multiple times to select multiple resource managers\&. If
list
is passed as name, print a list of valid resource manager names, and exit\&.
.sp
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
custom###
where "###" is the three\-digit resource manager ID\&. Names of this form will always be considered valid\&.
.RE
.PP
\fB\-R \fR\fB\fItblspc\fR\fR\fB/\fR\fB\fIdb\fR\fR\fB/\fR\fB\fIrel\fR\fR
.br
\fB\-\-relation=\fR\fB\fItblspc\fR\fR\fB/\fR\fB\fIdb\fR\fR\fB/\fR\fB\fIrel\fR\fR
.RS 4
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
1234/12345/12345\&. This is the same format used for relations in the program\*(Aqs output\&.
.RE
.PP
\fB\-s \fR\fB\fIstart\fR\fR
.br
\fB\-\-start=\fR\fB\fIstart\fR\fR
.RS 4
WAL location at which to start reading\&. The default is to start reading the first valid WAL record found in the earliest file found\&.
.RE
.PP
\fB\-t \fR\fB\fItimeline\fR\fR
.br
\fB\-\-timeline=\fR\fB\fItimeline\fR\fR
.RS 4
Timeline from which to read WAL records\&. The default is to use the value in
\fIstartseg\fR, if that is specified; otherwise, the default is 1\&. The value can be specified in decimal or hexadecimal, for example
17
or
0x11\&.
.RE
.PP
\fB\-V\fR
.br
\fB\-\-version\fR
.RS 4
Print the
pg_waldump
version and exit\&.
.RE
.PP
\fB\-w\fR
.br
\fB\-\-fullpage\fR
.RS 4
Only display records that include full page images\&.
.RE
.PP
\fB\-x \fR\fB\fIxid\fR\fR
.br
\fB\-\-xid=\fR\fB\fIxid\fR\fR
.RS 4
Only display records marked with the given transaction ID\&.
.RE
.PP
\fB\-z\fR
.br
\fB\-\-stats[=record]\fR
.RS 4
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\&.
.sp
If
pg_waldump
is terminated by signal
SIGINT
(Control+C), the summary of the statistics computed is displayed up to the termination point\&. This operation is not supported on
Windows\&.
.RE
.PP
\fB\-\-save\-fullpage=\fR\fB\fIsave_path\fR\fR
.RS 4
Save full page images found in the WAL records to the
\fIsave_path\fR
directory\&. The images saved are subject to the same filtering and limiting criteria as the records displayed\&.
.sp
The full page images are saved with the following file name format:
\fITIMELINE\fR\-\fILSN\fR\&.\fIRELTABLESPACE\fR\&.\fIDATOID\fR\&.\fIRELNODE\fR\&.\fIBLKNO\fR\fIFORK\fR
The file names are composed of the following parts:
.TS
allbox tab(:);
lB lB.
T{
Component
T}:T{
Description
T}
.T&
l l
l l
l l
l l
l l
l l
l l.
T{
TIMELINE
T}:T{
The timeline of the WAL segment file where the record
             is located formatted as one 8\-character hexadecimal number
             %08X
T}
T{
LSN
T}:T{
The LSN of the record with this image,
             formatted as two 8\-character hexadecimal numbers
             %08X\-%08X
T}
T{
RELTABLESPACE
T}:T{
tablespace OID of the block
T}
T{
DATOID
T}:T{
database OID of the block
T}
T{
RELNODE
T}:T{
filenode of the block
T}
T{
BLKNO
T}:T{
block number of the block
T}
T{
FORK
T}:T{
The name of the fork the full page image came from, such as
             _main, _fsm,
             _vm, or _init\&.
T}
.TE
.sp 1
.RE
.PP
\fB\-?\fR
.br
\fB\-\-help\fR
.RS 4
Show help about
pg_waldump
command line arguments, and exit\&.
.RE
.SH "ENVIRONMENT"
.PP
\fBPGDATA\fR
.RS 4
Data directory; see also the
\fB\-p\fR
option\&.
.RE
.PP
\fBPG_COLOR\fR
.RS 4
Specifies whether to use color in diagnostic messages\&. Possible values are
always,
auto
and
never\&.
.RE
.SH "NOTES"
.PP
Can give wrong results when the server is running\&.
.PP
Only the specified timeline is displayed (or the default, if none is specified)\&. Records in other timelines are ignored\&.
.PP
pg_waldump
cannot read WAL files with suffix
\&.partial\&. If those files need to be read,
\&.partial
suffix needs to be removed from the file name\&.
.SH "SEE ALSO"
Section\ \&30.6