PG_WALDUMP(1)

💖 PG_WALDUMP(1) 💖

okay bestie, pull up a chair, because this is pg_waldump from the PostgreSQL 18.6 manual — it lives in section 1 of the manual pages, and it's literally the little tool that lets you stare directly into the write-ahead log of a PostgreSQL database cluster. no cap. let's get into it 🫶

---

✨ NAME ✨

pg_waldump — displays a human-readable rendering of the write-ahead log of a PostgreSQL database cluster. it's giving "here's what your WAL was actually doing" 💅

---

🌸 SYNOPSIS 🌸

pg_waldump [option...] [startseg [endseg]]

---

🦋 DESCRIPTION 🦋

So pg_waldump shows you the write-ahead log, aka the WAL, and honestly? it's mainly there for debugging or educational purposes. like, this is the tool you use when you're being a nerd on purpose and you want to know what's in there 🔍

bestie, important: this utility can only be run by the user who installed the server. why? because it needs read-only access to the data directory. that's the vibe check, and you have to pass it 🙈

---

✨ OPTIONS ✨

These are the command-line options that control where the output comes from and what shape it takes, okay?

• startseg — start reading at this specific WAL segment file. sneaky detail: this also implicitly decides the path where files get searched for, and the timeline to use. so it's doing two jobs, main character energy fr.
• endseg — stop after reading this specified WAL segment file. that's the finish line 🏁

---

• -b, --bkp-details — output detailed info about backup blocks.
• -B block, --block=block — only show records that modify the given block. and heads up: you **also have to provide the relation, using --relation or -R. it's a package deal 💖
• *-e *end, --end=end — stop reading at the specified WAL location, instead of reading all the way to the end of the log stream.
• -f, --follow — after it reaches the end of valid WAL, it just keeps polling once per second waiting for new WAL to show up. obsessed with the dedication honestly.
• *-F *fork, --fork=fork — only display records that modify blocks in the given fork. 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 — show exactly this many records, then stop. boundaries, we love them ✋
• *-p *path, --path=path — tells it which directory to search for WAL segment files, or a directory that has a pg_wal subdirectory containing 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 — print literally no output except errors. ngl this one's lowkey iconic: it's useful when you just wanna know whether a range of WAL records can be successfully parsed and you do not care about the record contents.
• *-r *rmgr, --rmgr=rmgr — only display records generated by the specified resource manager. you can pass this option multiple times to select multiple resource managers. and if you pass list as the name, it prints a list of valid resource manager names and exits. slay.
  • Extensions may define custom resource managers, but pg_waldump does not load the extension module, so it doesn't 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 are always considered valid. good to know iykyk 💀
• *-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. consistency queen 👑
• *-s *start, --start=start — the 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 — the timeline from which to read WAL records. default is to use the value in startseg, if that's specified; otherwise the default is 1. and you can write the value in decimal or hexadecimal, for example 17 or 0x11. flexible 💅
• -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 (the number and size of records and full-page images) instead of individual records. optionally, generate statistics per-record instead of per-rmgr. and listen: if pg_waldump gets terminated by signal SIGINT (that's Control+C for you and me), the summary of the statistics computed is displayed up to the termination point. but this operation is not supported on Windows — sorry Windows besties 😭
• --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 — so your filters apply to the files too, no sneaking around it.
  • 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 these parts:
    • 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. when in doubt 🎀

---

🌈 ENVIRONMENT 🌈

• PGDATA — the data directory; see also the -p option. (they're besties, they work together 🫶)
• PG_COLOR — specifies whether to use color in diagnostic messages. possible values are always, auto and never. yes, we do care about aesthetics in our diagnostics 🌸

---

⭐ NOTES ⭐

Can give wrong results when the server is running. not me warning you twice, but... yeah. be careful bestie.

• Only the specified timeline is displayed (or the default, if none is specified). records in other timelines are ignored, periodt.
• pg_waldump cannot read WAL files with the suffix .partial. if those files need to be read, the .partial suffix needs to be removed from the file name. like, physically renamed. it's not being dramatic, it just refuses 💀

---

🎀 SEE ALSO 🎀

Section 28.6 💜

---

and that's the whole page, bestie! this was PG_WALDUMP(1) from PostgreSQL 18.6, dated 2026 — go forth and read your WAL responsibly 🦋✨💖