src/backend/access/rmgrdesc/README

WAL resource manager description functions

==========================================

For debugging purposes, there is a "description function", or rmgrdesc

function, for each WAL resource manager. The rmgrdesc function parses the WAL

record and prints the contents of the WAL record in a somewhat human-readable

format.

The rmgrdesc functions for all resource managers are gathered in this

directory, because they are also used in the stand-alone pg_waldump program.

They could potentially be used by out-of-tree debugging tools too, although

neither the description functions nor the output format should be considered

part of a stable API

Guidelines for rmgrdesc output format

-------------------------------------

The goal of these guidelines is to avoid gratuitous inconsistencies across

each rmgr, and to allow users to parse desc output strings without too much

difficulty. This is not an API specification or an interchange format.

(Only heapam and nbtree desc routines follow these guidelines at present, in

any case.)

Record descriptions are similar to JSON style key/value objects. However,

there is no explicit "string" type/string escaping. Top-level { } brackets

should be omitted. For example:

snapshotConflictHorizon: 0, flags: 0x03

Record descriptions may contain variable-length arrays. For example:

nunused: 5, unused: [1, 2, 3, 4, 5]

Nested objects are supported via { } brackets. They generally appear inside

variable-length arrays. For example:

ndeleted: 0, nupdated: 1, deleted: [], updated: [{ off: 45, nptids: 1, ptids: [0] }]

Try to output things in an order that faithfully represents the order of

fields from the underlying physical WAL record struct. Key names should be

unique (at the same nesting level) to make parsing easy. It's a good idea if

the number of items in the array appears before the array.

It's okay for individual WAL record types to invent their own conventions.

For example, Heap2's PRUNE record descriptions use a custom array format for

the record's "redirected" field:

... redirected: [1->4, 5->9], dead: [10, 11], unused: [3, 7, 8]

Arguably the desc routine should be using object notation for this instead.

However, there is value in using a custom format when it conveys useful

information about the underlying physical data structures.

This ad-hoc format has the advantage of being close to the format used for

the "dead" and "unused" arrays (which follow the standard desc convention for

page offset number arrays). It suggests that the "redirected" elements shown

are just pairs of page offset numbers (which is how it really works).

rmgrdesc_utils.c contains some helper functions to print data in this format.