begriffs open source - ai-pg/blob - full-docs/txt/pgwalinspect.txt

   1
   2 F.37. pg_walinspect — low-level WAL inspection #
   3
   4    F.37.1. General Functions
   5    F.37.2. Author
   6
   7    The pg_walinspect module provides SQL functions that allow you to
   8    inspect the contents of write-ahead log of a running PostgreSQL
   9    database cluster at a low level, which is useful for debugging,
  10    analytical, reporting or educational purposes. It is similar to
  11    pg_waldump, but accessible through SQL rather than a separate utility.
  12
  13    All the functions of this module will provide the WAL information using
  14    the server's current timeline ID.
  15
  16 Note
  17
  18    The pg_walinspect functions are often called using an LSN argument that
  19    specifies the location at which a known WAL record of interest begins.
  20    However, some functions, such as pg_logical_emit_message, return the
  21    LSN after the record that was just inserted.
  22
  23 Tip
  24
  25    All of the pg_walinspect functions that show information about records
  26    that fall within a certain LSN range are permissive about accepting
  27    end_lsn arguments that are after the server's current LSN. Using an
  28    end_lsn “from the future” will not raise an error.
  29
  30    It may be convenient to provide the value FFFFFFFF/FFFFFFFF (the
  31    maximum valid pg_lsn value) as an end_lsn argument. This is equivalent
  32    to providing an end_lsn argument matching the server's current LSN.
  33
  34    By default, use of these functions is restricted to superusers and
  35    members of the pg_read_server_files role. Access may be granted by
  36    superusers to others using GRANT.
  37
  38 F.37.1. General Functions #
  39
  40    pg_get_wal_record_info(in_lsn pg_lsn) returns record #
  41           Gets WAL record information about a record that is located at or
  42           after the in_lsn argument. For example:
  43
  44 postgres=# SELECT * FROM pg_get_wal_record_info('0/E419E28');
  45 -[ RECORD 1 ]----+-------------------------------------------------
  46 start_lsn        | 0/E419E28
  47 end_lsn          | 0/E419E68
  48 prev_lsn         | 0/E419D78
  49 xid              | 0
  50 resource_manager | Heap2
  51 record_type      | VACUUM
  52 record_length    | 58
  53 main_data_length | 2
  54 fpi_length       | 0
  55 description      | nunused: 5, unused: [1, 2, 3, 4, 5]
  56 block_ref        | blkref #0: rel 1663/16385/1249 fork main blk 364
  57
  58           If in_lsn isn't at the start of a WAL record, information about
  59           the next valid WAL record is shown instead. If there is no next
  60           valid WAL record, the function raises an error.
  61
  62    pg_get_wal_records_info(start_lsn pg_lsn, end_lsn pg_lsn) returns setof
  63           record #
  64           Gets information of all the valid WAL records between start_lsn
  65           and end_lsn. Returns one row per WAL record. For example:
  66
  67 postgres=# SELECT * FROM pg_get_wal_records_info('0/1E913618', '0/1E913740') LIM
  68 IT 1;
  69 -[ RECORD 1 ]----+--------------------------------------------------------------
  70 start_lsn        | 0/1E913618
  71 end_lsn          | 0/1E913650
  72 prev_lsn         | 0/1E9135A0
  73 xid              | 0
  74 resource_manager | Standby
  75 record_type      | RUNNING_XACTS
  76 record_length    | 50
  77 main_data_length | 24
  78 fpi_length       | 0
  79 description      | nextXid 33775 latestCompletedXid 33774 oldestRunningXid 33775
  80 block_ref        |
  81
  82           The function raises an error if start_lsn is not available.
  83
  84    pg_get_wal_block_info(start_lsn pg_lsn, end_lsn pg_lsn, show_data
  85           boolean DEFAULT true) returns setof record #
  86           Gets information about each block reference from all the valid
  87           WAL records between start_lsn and end_lsn with one or more block
  88           references. Returns one row per block reference per WAL record.
  89           For example:
  90
  91 postgres=# SELECT * FROM pg_get_wal_block_info('0/1230278', '0/12302B8');
  92 -[ RECORD 1 ]-----+-----------------------------------
  93 start_lsn         | 0/1230278
  94 end_lsn           | 0/12302B8
  95 prev_lsn          | 0/122FD40
  96 block_id          | 0
  97 reltablespace     | 1663
  98 reldatabase       | 1
  99 relfilenode       | 2658
 100 relforknumber     | 0
 101 relblocknumber    | 11
 102 xid               | 341
 103 resource_manager  | Btree
 104 record_type       | INSERT_LEAF
 105 record_length     | 64
 106 main_data_length  | 2
 107 block_data_length | 16
 108 block_fpi_length  | 0
 109 block_fpi_info    |
 110 description       | off: 46
 111 block_data        | \x00002a00070010402630000070696400
 112 block_fpi_data    |
 113
 114           This example involves a WAL record that only contains one block
 115           reference, but many WAL records contain several block
 116           references. Rows output by pg_get_wal_block_info are guaranteed
 117           to have a unique combination of start_lsn and block_id values.
 118
 119           Much of the information shown here matches the output that
 120           pg_get_wal_records_info would show, given the same arguments.
 121           However, pg_get_wal_block_info unnests the information from each
 122           WAL record into an expanded form by outputting one row per block
 123           reference, so certain details are tracked at the block reference
 124           level rather than at the whole-record level. This structure is
 125           useful with queries that track how individual blocks changed
 126           over time. Note that records with no block references (e.g.,
 127           COMMIT WAL records) will have no rows returned, so
 128           pg_get_wal_block_info may actually return fewer rows than
 129           pg_get_wal_records_info.
 130
 131           The reltablespace, reldatabase, and relfilenode parameters
 132           reference pg_tablespace.oid, pg_database.oid, and
 133           pg_class.relfilenode respectively. The relforknumber field is
 134           the fork number within the relation for the block reference; see
 135           common/relpath.h for details.
 136
 137 Tip
 138
 139           The pg_filenode_relation function (see Table 9.103) can help you
 140           to determine which relation was modified during original
 141           execution.
 142
 143           It is possible for clients to avoid the overhead of
 144           materializing block data. This may make function execution
 145           significantly faster. When show_data is set to false, block_data
 146           and block_fpi_data values are omitted (that is, the block_data
 147           and block_fpi_data OUT arguments are NULL for all rows
 148           returned). Obviously, this optimization is only feasible with
 149           queries where block data isn't truly required.
 150
 151           The function raises an error if start_lsn is not available.
 152
 153    pg_get_wal_stats(start_lsn pg_lsn, end_lsn pg_lsn, per_record boolean
 154           DEFAULT false) returns setof record #
 155           Gets statistics of all the valid WAL records between start_lsn
 156           and end_lsn. By default, it returns one row per resource_manager
 157           type. When per_record is set to true, it returns one row per
 158           record_type. For example:
 159
 160 postgres=# SELECT * FROM pg_get_wal_stats('0/1E847D00', '0/1E84F500')
 161            WHERE count > 0 AND
 162                  "resource_manager/record_type" = 'Transaction'
 163            LIMIT 1;
 164 -[ RECORD 1 ]----------------+-------------------
 165 resource_manager/record_type | Transaction
 166 count                        | 2
 167 count_percentage             | 8
 168 record_size                  | 875
 169 record_size_percentage       | 41.23468426013195
 170 fpi_size                     | 0
 171 fpi_size_percentage          | 0
 172 combined_size                | 875
 173 combined_size_percentage     | 2.8634072910530795
 174
 175           The function raises an error if start_lsn is not available.
 176
 177 F.37.2. Author #
 178
 179    Bharath Rupireddy <bharath.rupireddyforpostgres@gmail.com>