--- title: "pg_waldump" id: pgwaldump pg_version: "20devel" --- # pg_waldump — display a human-readable rendering of the write-ahead log of a PostgreSQL database cluster ## Synopsis ``` pg_waldump [option...] [startseg[endseg] ] ``` ## Description `pg_waldump` displays the write-ahead log (WAL) and is mainly useful for debugging or educational purposes. This utility can only be run by the user who installed the server, because it requires read-only access to the data directory. ## Options The following command-line options control the location and format of the output: **`startseg`** 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. **`endseg`** Stop after reading the specified WAL segment file. **`-b`**, **`--bkp-details`** Output detailed information about backup blocks. **`-B block`**, **`--block=block`** Only display records that modify the given block. The relation must also be provided with `--relation` or `-R`. **`-e end`**, **`--end=end`** Stop reading at the specified WAL location, instead of reading to the end of the log stream. **`-f`**, **`--follow`** After reaching the end of valid WAL, keep polling once per second for new WAL to appear. **`-F fork`**, **`--fork=fork`** 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. **`-n limit`**, **`--limit=limit`** Display the specified number of records, then stop. **`-p path`**, **`--path=path`** Specifies a tar archive or 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 PGDATA. If a tar archive is provided and its WAL segment files are not in sequential order, those files will be written to a temporary directory named starting with `waldump_tmp`. This directory will be created inside the directory specified by the TMPDIR environment variable if it is set; otherwise, it will be created within the same directory as the tar archive. **`-q`**, **`--quiet`** 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't care about the record contents. **`-r rmgr`**, **`--rmgr=rmgr`** 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. 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. **`-R tblspc/db/rel`**, **`--relation=tblspc/db/rel`** 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's output. **`-s start`**, **`--start=start`** WAL location at which to start reading. The default is to start reading the first valid WAL record found in the earliest file found. **`-t timeline`**, **`--timeline=timeline`** Timeline from which to read WAL records. The default is to use the value in `startseg`, if that is specified; otherwise, the default is 1. The value can be specified in decimal or hexadecimal, for example `17` or `0x11`. **`-V`**, **`--version`** Print the pg_waldump version and exit. **`-w`**, **`--fullpage`** Only display records that include full page images. **`-x xid`**, **`--xid=xid`** Only display records marked with the given transaction ID. **`-z`**, **`--stats[=record]`** 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. 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. **`--save-fullpage=save_path`** Save full page images found in the WAL records to the `save_path` directory. The images saved are subject to the same filtering and limiting criteria as the records displayed. The full page images are saved with the following file name format: `TIMELINE-LSN.RELTABLESPACE.DATOID.RELNODE.BLKNO_FORK` The file names are composed of the following parts: | Component | Description | | --- | --- | | TIMELINE | The timeline of the WAL segment file where the record is located formatted as one 8-character hexadecimal number `%08X` | | LSN | The LSN of the record with this image, formatted as two 8-character hexadecimal numbers `%08X-%08X` | | RELTABLESPACE | tablespace OID of the block | | DATOID | database OID of the block | | RELNODE | filenode of the block | | BLKNO | block number of the block | | FORK | The name of the fork the full page image came from, such as `main`, `fsm`, `vm`, or `init`. | **`-?`**, **`--help`** Show help about pg_waldump command line arguments, and exit. ## Environment **PGDATA** Data directory; see also the `-p` option. **PG_COLOR** Specifies whether to use color in diagnostic messages. Possible values are `always`, `auto` and `never`. **TMPDIR** Directory in which to create temporary files when reading WAL from a tar archive with out-of-order segment files. If not set, the temporary directory is created within the same directory as the tar archive. ## Notes Can give wrong results when the server is running. Only the specified timeline is displayed (or the default, if none is specified). Records in other timelines are ignored. 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. ## See Also [Section 28.6](wal-internals.md)