Inspect PostgreSQL WAL Safely with pg_waldump

You will use pg_waldump to read PostgreSQL write-ahead log (WAL) records, limit the output to a useful slice, and produce a summary when individual records are too noisy. The examples target PostgreSQL 16.15 on Ubuntu 24.04. Allow about 15 minutes if you already know the data directory and the WAL segment you want to inspect.

This is a diagnostic reader. It does not repair WAL, replay it, or change the database. It does require read-only access to the data directory, so the command must normally run as the operating-system user that installed the PostgreSQL server. Use an account with the necessary access, but do not turn a read-only investigation into a permissions change.

1. Check the installed command

First confirm the binary and version. On this machine the PostgreSQL client package installs the executable outside the ordinary shell PATH:

$ /usr/lib/postgresql/16/bin/pg_waldump --version
pg_waldump (PostgreSQL) 16.15 (Ubuntu 16.15-0ubuntu0.24.04.1)
$ dpkg-query -W -f='${Package} ${Version}\n' postgresql-client-16
postgresql-client-16 16.15-0ubuntu0.24.04.1

Your package path may differ. Set a shell variable once you have checked it:

$ WALDUMP=/usr/lib/postgresql/16/bin/pg_waldump
$ "$WALDUMP" --help

2. Identify the WAL directory and access account

Use the PostgreSQL cluster configuration or your service definition to identify PGDATA. The directory passed to --path can be the directory containing WAL segments or a directory containing a pg_wal subdirectory. The default search is the current directory, its pg_wal subdirectory, and PGDATA/pg_wal.

For a typical Debian or Ubuntu cluster, the WAL directory is below the cluster data directory. Do not guess the path from the version number. Check it before running a read:

$ PGDATA=/var/lib/postgresql/16/main
$ find "$PGDATA/pg_wal" -maxdepth 1 -type f -name '[0-9A-F]*' -printf '%f\n' | head
000000010000000000000001
000000010000000000000002

The segment names on your host will differ. If this check fails, stop and correct the path or account first. A failed read is usually a path or permission problem, not evidence that the WAL is damaged.

3. Read a small range of records

Start with a limit so that a busy cluster does not flood your terminal. This ordinary command is read-only, but it may expose transaction and relation details, so treat its output as operational data:

$ "$WALDUMP" --path "$PGDATA" --limit=20
rmgr: Heap        len (rec/tot):     59/    59, tx:          0, lsn: 0/014C2A28, prev 0/014C29F0, desc: INSERT off 1 flags 0x00, blkref #0: rel 1663/16384/16385 blk 0
rmgr: Transaction len (rec/tot):     34/    34, tx:        742, lsn: 0/014C2A68, prev 0/014C2A28, desc: commit: 2026-09-26 10:20:00.123456 BST
...

The exact records, timestamps and LSNs depend on the cluster. The useful fields are the resource manager, record length, transaction ID, LSN and description. The command stops after the requested number of records. Without --limit, it continues through the available WAL.

4. Narrow the investigation with filters

Use the filters together when you have a concrete question. --rmgr=list prints the valid resource manager names. The installed command reports names including Heap, Btree, Transaction and LogicalMessage:

$ "$WALDUMP" --rmgr=list
XLOG
Transaction
Storage
CLOG
Database
Tablespace
MultiXact
RelMap
Standby
Heap2
Heap
Btree
...

To inspect only records generated by one manager, repeat --rmgr for multiple managers:

$ "$WALDUMP" --path "$PGDATA" --rmgr=Heap --rmgr=Btree --limit=50

For a relation-specific question, supply tablespace OID, database OID and relfilenode with --relation. To restrict that relation to one block, add --block:

$ "$WALDUMP" --path "$PGDATA" --relation=1663/16384/16385 --block=0 --limit=20

These identifiers are not table names. Obtain them from PostgreSQL metadata or the existing pg_waldump output before filtering. A guessed triple can return no records and send the investigation in the wrong direction.

5. Produce statistics instead of a record dump

Use --stats when you need counts and sizes by resource manager rather than every record. The optional record argument changes the grouping to per-record statistics:

$ "$WALDUMP" --path "$PGDATA" --stats
WAL statistics
                                         count             size
                          XLOG             12              840
                   Transaction             38             1420
                           Heap            114             9016
                           TOTAL            164            11276

The values above are illustrative output shape, not expected totals. On a live system, press Control+C to stop a long statistics run and ask for the partial summary. Do not confuse --stats with a database health check: it describes the WAL files read, not whether the cluster can recover from every possible failure.

6. Handle live clusters and partial segments carefully

The PostgreSQL documentation warns that results can be wrong while the server is running. For a consistent forensic capture, work from a suitable stopped-cluster copy or an archived WAL set, following your normal backup and incident procedures. Stopping a production database is service-disrupting and outside this guide. Do not stop it merely to make a first test convenient.

Only one timeline is read: the value supplied with --timeline, the timeline encoded by STARTSEG, or timeline 1 by default. After a promotion or recovery, select the timeline deliberately rather than assuming the default is correct.

pg_waldump does not read files ending in .partial. Never rename a live WAL file just to satisfy the tool. If an archived copy must be inspected, make a separate working copy, remove the suffix on that copy only, and preserve the original for recovery and audit purposes. Removing or overwriting the original is destructive and has no undo inside pg_waldump.

7. Save full-page images only when needed

--save-fullpage=DIR writes extracted full-page images to the directory you specify, subject to the same filters and limits as the displayed records. Create a new, empty working directory and check its contents afterwards:

$ mkdir -p /tmp/waldump-images
$ "$WALDUMP" --path "$PGDATA" --fullpage --limit=20 --save-fullpage=/tmp/waldump-images
$ find /tmp/waldump-images -maxdepth 1 -type f -printf '%f\n'

This is the only state-changing example here: it creates files under /tmp. Remove those files when the investigation is complete with an explicit path, after checking that the directory contains only disposable output. The filenames include timeline, LSN, relation identifiers, block number and fork, which makes them useful for correlating with the record dump.