pg_waldump
Prev | Up | PostgreSQL Server Applications | Home | Next

## pg_waldump

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``

  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.

`-K`
`--encryption-key-command=`command``

  If the cluster is encrypted, run this command to retrieve the encryption key. See Chapter 33 for details.

`-n `limit``
`--limit=`limit``

  Display the specified number of records, then stop.

`-p `path``
`--path=`path``

  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 `PGDATA`.

`-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`.

## 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 30.6

Prev | Up | Next
pg_upgrade | Home | postgres