Debian Codegraph @

src/backend/access/rmgrdesc/README

raw
1 src/backend/access/rmgrdesc/README
2
3 WAL resource manager description functions
4 ==========================================
5
6 For debugging purposes, there is a "description function", or rmgrdesc
7 function, for each WAL resource manager. The rmgrdesc function parses the WAL
8 record and prints the contents of the WAL record in a somewhat human-readable
9 format.
10
11 The rmgrdesc functions for all resource managers are gathered in this
12 directory, because they are also used in the stand-alone pg_waldump program.
13 They could potentially be used by out-of-tree debugging tools too, although
14 neither the description functions nor the output format should be considered
15 part of a stable API
16
17 Guidelines for rmgrdesc output format
18 -------------------------------------
19
20 The goal of these guidelines is to avoid gratuitous inconsistencies across
21 each rmgr, and to allow users to parse desc output strings without too much
22 difficulty. This is not an API specification or an interchange format.
23 (Only heapam and nbtree desc routines follow these guidelines at present, in
24 any case.)
25
26 Record descriptions are similar to JSON style key/value objects. However,
27 there is no explicit "string" type/string escaping. Top-level { } brackets
28 should be omitted. For example:
29
30 snapshotConflictHorizon: 0, flags: 0x03
31
32 Record descriptions may contain variable-length arrays. For example:
33
34 nunused: 5, unused: [1, 2, 3, 4, 5]
35
36 Nested objects are supported via { } brackets. They generally appear inside
37 variable-length arrays. For example:
38
39 ndeleted: 0, nupdated: 1, deleted: [], updated: [{ off: 45, nptids: 1, ptids: [0] }]
40
41 Try to output things in an order that faithfully represents the order of
42 fields from the underlying physical WAL record struct. Key names should be
43 unique (at the same nesting level) to make parsing easy. It's a good idea if
44 the number of items in the array appears before the array.
45
46 It's okay for individual WAL record types to invent their own conventions.
47 For example, Heap2's PRUNE record descriptions use a custom array format for
48 the record's "redirected" field:
49
50 ... redirected: [1->4, 5->9], dead: [10, 11], unused: [3, 7, 8]
51
52 Arguably the desc routine should be using object notation for this instead.
53 However, there is value in using a custom format when it conveys useful
54 information about the underlying physical data structures.
55
56 This ad-hoc format has the advantage of being close to the format used for
57 the "dead" and "unused" arrays (which follow the standard desc convention for
58 page offset number arrays). It suggests that the "redirected" elements shown
59 are just pairs of page offset numbers (which is how it really works).
60
61 rmgrdesc_utils.c contains some helper functions to print data in this format.