| 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. |