pg\_waldump

pg\_waldump

1

Application

pg\_waldump

display a human-readable rendering of the write-ahead log of a

PostgreSQL

database cluster

pg\_waldump

option

startseg

endseg

Description {#r1-app-pgwaldump-1}
===========

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

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

:   Display the specified number of records, then stop.

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

:   Specifies a directory to search for log 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 log record found in the earliest file found.

`-t timeline`; `--timeline=timeline`

:   Timeline from which to read log records. The default is to use the
    value in startseg, if that is specified; otherwise, the default
    is 1.

`-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]{.keycombo}, the summary of the statistics computed is
    displayed up to the termination point. This operation is not
    supported on Windows.

`-?`; `--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
========
