From 157777bbf29f21f26d2f969aad2acae05aeb500d Mon Sep 17 00:00:00 2001 From: Bharath Rupireddy Date: Thu, 10 Mar 2022 16:43:15 +0000 Subject: [PATCH v8] pg_walinspect docs --- doc/src/sgml/contrib.sgml | 1 + doc/src/sgml/filelist.sgml | 1 + doc/src/sgml/pgwalinspect.sgml | 173 +++++++++++++++++++++++++++++++++ 3 files changed, 175 insertions(+) create mode 100644 doc/src/sgml/pgwalinspect.sgml diff --git a/doc/src/sgml/contrib.sgml b/doc/src/sgml/contrib.sgml index be9711c6f2..19614a42e1 100644 --- a/doc/src/sgml/contrib.sgml +++ b/doc/src/sgml/contrib.sgml @@ -130,6 +130,7 @@ CREATE EXTENSION module_name; &pgsurgery; &pgtrgm; &pgvisibility; + &pgwalinspect; &postgres-fdw; &seg; &sepgsql; diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index 328cd1f378..a2e8fd4a08 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -146,6 +146,7 @@ + diff --git a/doc/src/sgml/pgwalinspect.sgml b/doc/src/sgml/pgwalinspect.sgml new file mode 100644 index 0000000000..9c61de1838 --- /dev/null +++ b/doc/src/sgml/pgwalinspect.sgml @@ -0,0 +1,173 @@ + + + + pg_walinspect + + + pg_walinspect + + + + The pg_walinspect module provides functions that allow + you to inspect the contents of write-ahead log of PostgreSQL + database cluster at a low level, which is useful for debugging or analytical + or reporting or educational purposes. + + + + By default, use of these functions is restricted to superusers and members of + the pg_monitor role. Access may be granted to others using + GRANT. + + + + All the functions of this module will provide the WAL information using the + current server's timeline ID. + + + + General Functions + + + + + pg_get_raw_wal_record(in_lsn pg_lsn, lsn OUT pg_lsn, record OUT bytea) + + + + + Gets raw WAL record data of a given LSN. Issues a warning if the given + LSN wasn't a pointer to the start of a record and also wasn't a pointer + to the beginning of a WAL segment file. This function emits an error if + a future (the LSN database system doesn't know about) + in_lsn is specified. + + + + + + + pg_get_first_valid_wal_record_lsn(in_lsn pg_lsn, lsn OUT pg_lsn, prev_lsn OUT pg_lsn) + + + + + Gets first and previous valid WAL record LSNs of the given LSN. Issues + a warning if the given LSN wasn't a pointer to the start of a record and + also wasn't a pointer to the beginning of a WAL segment file. This + function emits an error if a future (the LSN database system doesn't know + about) in_lsn is specified. + + + + + + + pg_get_wal_record_info(in_lsn pg_lsn, lsn OUT pg_lsn, prev_lsn OUT pg_lsn, xid OUT xid, resource_manager OUT text, length OUT int4, total_length OUT int4, description OUT text, block_ref OUT text, data OUT bytea, data_len OUT int4) + + + + + Gets WAL record information of the given LSN. Issues a warning if the + given LSN wasn't a pointer to the start of a record and also wasn't a + pointer to the beginning of a WAL segment file. This function emits an + error if a future (the LSN database system doesn't know about) + in_lsn is specified. + + + + + + + pg_get_wal_records_info(start_lsn pg_lsn, end_lsn pg_lsn DEFAULT NULL, lsn OUT pg_lsn, prev_lsn OUT pg_lsn, xid OUT xid, resource_manager OUT text, length OUT int4, total_length OUT int4, description OUT text, block_ref OUT text, data OUT bytea, data_len OUT int4) + + + + + Gets information of all the valid WAL records between + start_lsn and end_lsn. + Returns one row per each valid WAL record. Issues a warning if the given + start_lsn wasn't a pointer to the start of a + record and also wasn't a pointer to the beginning of a WAL segment file. + This function figures out the end_lsn if it's + not specified, that means, it returns information up to the end of WAL. + Default value of end_lsn is NULL. + This function emits an error if a future (the LSN database system doesn't + know about) start_lsn or end_lsn + is specified. For example: + +postgres=# select prev_lsn, xid, resource_manager, length, total_length, block_ref from pg_get_wal_records_info('0/158A7F0', '0/1591400'); + prev_lsn | xid | resource_manager | length | total_length | block_ref +-----------+-----+------------------+--------+--------------+-------------------------------------------------------------------------- + 0/158A7B8 | 735 | Heap | 54 | 7838 | blkref #0: rel 1663/5/2619 blk 18 (FPW); hole: offset: 88, length: 408 + 0/158A7F0 | 735 | Btree | 53 | 8133 | blkref #0: rel 1663/5/2696 blk 1 (FPW); hole: offset: 1632, length: 112 + 0/158C6A8 | 735 | Heap | 53 | 873 | blkref #0: rel 1663/5/1259 blk 0 (FPW); hole: offset: 212, length: 7372 + 0/158E688 | 735 | Transaction | 114 | 114 | + 0/158E9F8 | 0 | Standby | 50 | 50 | + 0/158EA70 | 0 | Heap2 | 59 | 6755 | blkref #0: rel 1663/5/1255 blk 92 (FPW); hole: offset: 120, length: 1496 + 0/158EAA8 | 0 | Standby | 50 | 50 | + 0/1590528 | 736 | Heap | 54 | 3570 | blkref #0: rel 1663/5/16411 blk 4 (FPW); hole: offset: 412, length: 4676 + 0/1590560 | 736 | Heap | 59 | 59 | blkref #0: rel 1663/5/16411 blk 4 + 0/1591358 | 736 | Heap | 59 | 59 | blkref #0: rel 1663/5/16411 blk 4 + 0/1591398 | 736 | Transaction | 34 | 34 | +(11 rows) + + + + + + + + pg_get_wal_stats(start_lsn pg_lsn, end_lsn pg_lsn, wait_for_wal boolean DEFAULT false, resource_manager OUT text, count OUT int8, count_percentage OUT float4, record_size OUT int8, record_size_percentage OUT float4, fpi_size OUT int8, fpi_size_percentage OUT float4, combined_size OUT int8, combined_size_percentage OUT float4) + + + + + Gets statistics of all the valid WAL records between + start_lsn and end_lsn. + Returns one row per each resource_manager + type. Issues a warning if the given start_lsn + wasn't a pointer to the start of a record and also wasn't a pointer to + the beginning of a WAL segment file. This function figures out the + end_lsn if it's not specified, that means, it + returns information up to the end of WAL. Default value of + end_lsn is NULL. This + function emits an error if a future (the LSN database system doesn't know + about) start_lsn or end_lsn + is specified. For example: + +postgres=# select * from pg_get_wal_stats('0/158A7F0', '0/1591400'); + resource_manager | count | count_percentage | record_size | record_size_percentage | fpi_size | fpi_size_percentage | combined_size | combined_size_percentage +-------------------+-------+------------------+-------------+------------------------+----------+---------------------+---------------+-------------------------- + XLOG | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 + Transaction | 2 | 18.181818 | 148 | 23.16119 | 0 | 0 | 148 | 0.53749776 + Storage | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 + CLOG | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 + Database | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 + Tablespace | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 + MultiXact | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 + RelMap | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 + Standby | 2 | 18.181818 | 100 | 15.649452 | 0 | 0 | 100 | 0.36317414 + Heap2 | 1 | 9.090909 | 59 | 9.233177 | 6696 | 24.895895 | 6755 | 24.532413 + Heap | 5 | 45.454544 | 279 | 43.661972 | 12120 | 45.06246 | 12399 | 45.02996 + Btree | 1 | 9.090909 | 53 | 8.2942095 | 8080 | 30.041641 | 8133 | 29.536953 + Hash | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 + Gin | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 + Gist | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 + Sequence | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 + SPGist | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 + BRIN | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 + CommitTs | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 + ReplicationOrigin | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 + Generic | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 + LogicalMessage | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 +(22 rows) + + + + + + + + + -- 2.25.1