From 293913568e6a7a86fd1479e1cff8e2ecb58d6568 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 13 Apr 2024 15:44:03 +0200 Subject: Adding upstream version 16.2. Signed-off-by: Daniel Baumann --- doc/src/sgml/man1/pg_waldump.1 | 312 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 312 insertions(+) create mode 100644 doc/src/sgml/man1/pg_waldump.1 (limited to 'doc/src/sgml/man1/pg_waldump.1') diff --git a/doc/src/sgml/man1/pg_waldump.1 b/doc/src/sgml/man1/pg_waldump.1 new file mode 100644 index 0000000..1ffdfc0 --- /dev/null +++ b/doc/src/sgml/man1/pg_waldump.1 @@ -0,0 +1,312 @@ +'\" t +.\" Title: pg_waldump +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot +.\" 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 -- cgit v1.2.3