PGMONETA-WALINFO(1)

📦
version 0.21.0 · 2 versions
, in nixos 26.05

💅 pgmoneta-walinfo — the manual, but make it make sense

okay so bestie, welcome to pgmoneta-walinfo, section 1 of the manual 🎀 this is the page for the little command line icon that reads WAL files and tells you what's in them. grab a snack, we're going in 🍓

✨ NAME ✨

pgmoneta-walinfo — the command line utility that reads and displays Write-Ahead Log (WAL) files. that's it, that's the whole vibe. no cap. 💜

(it lives in manual section 1, for the record 🧚)

🌈 SYNOPSIS 🌈

pgmoneta-walinfo <file|directory|tar_archive>

🦋 DESCRIPTION 🦋

pgmoneta-walinfo is a command line utility that reads and displays information about PostgreSQL Write-Ahead Log (WAL) files. she's flexible, okay?? she handles:

  • individual WAL files
  • directories containing WAL files
  • TAR archives (optionally compressed with .gz, .lz4, .zstd, or .bz2)
  • encrypted files (.aes)

and she'll give you the deets on the WAL file in either raw or JSON format ✨

and like, on top of the standard WAL files, pgmoneta-walinfo also supports:

  • Encrypted WAL files (.aes)
  • Compressed WAL files: .zstd, .gz, .lz4, and .bz2
  • TAR archives containing WAL files (.tar)
  • Directories containing WAL files

she's versatile. main character energy, honestly 👑

✨ OPTIONS ✨

  • -I, --interactive — interactive mode for WAL files with ncurses (peep the INTERACTIVE MODE section below, iykyk)
  • -c, --config CONFIG_FILE — set the path to the pgmoneta.conf file
  • -u, --users USERS_FILE — set the path to the pgmoneta_users.conf file
  • -o, --output FILE — output file
  • -F, --format raw|json — set the output format. default is raw
  • -L, --logfile FILE — set the log file
  • -q, --quiet — no output, only result 🤫
  • --color — use colors (on, off)
  • -v, --verbose — output result
  • -S, --summary — show a summary of WAL record counts grouped by resource manager
  • -V, --version — display version information
  • -t, --translate — translate the OIDs in the XLOG records to the corresponding object (database/tablespace/relation) names 🫶
  • -m, --mapping — the JSON file that contains the mapping of the OIDs to the corresponding object names
  • -RT, --tablespaces — filter on tablespaces
  • -RD, --databases — filter on databases
  • -RT, --relations — filter on relations
  • -R, --filter — combination of -RT, -RD, -RR
  • -?, --help — display help and usage information
ngl bestie, yes, -RT really does show up twice up there, and yes -R mentions -RR. that's literally what the page says. I'm not gonna gaslight you, I'm just reporting 🫡

🌸 ARGUMENTS 🌸

  • <file|directory|tar_archive> — the path to the WAL file, directory containing WAL files, or TAR archive to be analyzed. that's your one job, bestie 🎀

💅 INTERACTIVE MODE 💅

with -I (--interactive), pgmoneta-walinfo runs a full-screen ncurses viewer 🔥 you can browse WAL records in a table, search, filter, mark rows, and export XIDs for pgmoneta-walfilter. it's giving control room. it's giving main character.

  • Up / Down — move to previous/next record (at file boundaries, moves to adjacent WAL files in the same directory when applicable)
  • PgUp / PgDn — scroll by page
  • Home / End — first / last record in the current list
  • Enter — open detailed view for the current record

📁 File browser

  • press l to open the file browser
  • Up / Down moves between directory entries
  • PgUp / PgDn jumps by one visible page in the file browser list
  • Enter opens a directory or loads the selected WAL file
  • q closes the file browser without loading a file (no accidental commitments 💀)

👀 Display

  • t — Text mode (human-readable columns)
  • b — Binary mode (hex dump)

🔍 Search (separate from filtering, ok??)

  • s — open the search dialog (resource manager, LSN fields, XID, description). Tab cycles through known values for RMGR, Start LSN, and End LSN fields
  • n / p (or Right / Left when search is active) — next / previous search match; Right / Left can cycle multiple matches in a field
  • Esc — clear search highlights and results (does not clear filters, they're separate, keep up 💖)

🎯 Filtering

  • f — open the filter dialog. criteria you set restrict which rows remain in the list. the dialog is pre-filled with the current rules so you can edit or remove them. Tab cycles through known values for RMGR, Start LSN, and End LSN fields
  • u — clear all filters and reload the full record list from the WAL file
  • Ctrl+U (in the filter dialog only) — clear all filter fields

🧠 Filter semantics

  • AND across fields: every non-empty field you set must match (RMGR, Start LSN range, End LSN range, XID, Relation)
  • OR within a field: for RMGR, XID, and Relation, you may enter comma-separated values; a record matches if it matches any token in that field
  • Start LSN and End LSN in the filter dialog define a range together: the record's start LSN must be greater than or equal to the filter start (if set) and the record's end LSN must be less than or equal to the filter end (if set). if only one bound is set, only that bound applies

🫥 Visibility

  • while filters are active, the header shows a short summary of the rules; the status line shows how many records are shown versus the total loaded (e.g. filtered vs full file)

🔖 Marks and YAML export

  • m — mark or unmark the current row (for export)
  • g — write a walfilter YAML file listing XIDs from marked rows (for use with pgmoneta-walfilter) ⭐

🎀 Other

  • v — verify records (stub in current viewer)
  • l — load a different WAL file or browse directories
  • ? — help overlay listing shortcuts
  • q — quit (sad, but necessary 😭)

🌟 USAGE 🌟

to display information about a WAL file in raw format:

pgmoneta-walinfo /path/to/walfile

to display information about a WAL file in interactive mode using ncurses:

pgmoneta-walinfo -I /path/to/walfile

to display information in JSON format:

pgmoneta-walinfo -F json /path/to/walfile

to analyze WAL files from a TAR archive:

pgmoneta-walinfo /path/to/wal_backup.tar.gz

to display information and translate the OIDs to the corresponding object names:

pgmoneta-walinfo -c pgmoneta_walinfo.conf -t -m /path/to/mapping.json /path/to/walfile or pgmoneta-walinfo -c pgmoneta_walinfo.conf -t -u /path/to/pgmoneta_users.conf /path/to/walfile

💜 OID TRANSLATION 💜

the -t flag enables translation of WAL record OIDs to object names. use either:

  • -u /path/to/pgmoneta_users.conf to resolve names from a live PostgreSQL server
  • -m /path/to/mapping.json to resolve names from a local JSON mapping file

the mapping JSON file must contain tablespaces, databases, and relations sections with object names mapped to OIDs 🧚

⚠️ and listen — if both mappings and server credentials are supplied, the mapping file takes precedence. so don't come crying when the JSON wins, bestie 🙈

🛠 CREATING THE MAPPING FILE 🛠

the mapping file can be created manually or generated from a PostgreSQL database ✨

each section is an array of objects where the key is the object name and the value is the OID as a string. yes, a string. don't @ me.

Generating from PostgreSQL:

Tablespaces:

SELECT '{' || string_agg('"' || spcname || '": "' || oid || '"', ', ') || '}' FROM pg_tablespace;

Databases:

SELECT '{' || string_agg('"' || datname || '": "' || oid || '"', ', ') || '}' FROM pg_database WHERE datname NOT IN ('template0', 'template1');

Relations:

SELECT '{' || string_agg('"' || nspname || '.' || relname || '": "' || c.oid || '"', ', ') || '}' FROM pg_class c JOIN pg_namespace n ON c.relnamespace = n.oid WHERE c.relkind IN ('r', 'p', 'v', 'm', 'f') AND n.nspname NOT IN ('pg_catalog', 'information_schema');

combine into a JSON file with "tablespaces", "databases", and "relations" arrays. slay 💅

🐛 REPORTING BUGS 🐛

pgmoneta is maintained on GitHub at https://github.com/pgmoneta/pgmoneta — that's where the bugs live, go tell on them (lovingly) 🫶

pgmoneta-walinfo is licensed under the 3-clause BSD License. iconic, legally speaking.

🔗 SEE ALSO 🔗

pgmoneta.conf(5), pgmoneta(1), pgmoneta-admin(1)

and that's the whole page bestie 🎀 the footer just signs it pgmoneta-walinfo() like a little autograph — pgmoneta manual, section 1, that's the source and the version vibe. now go read some WAL files, you absolute queen 💖✨🦋

📦 where this page comes from