v8-0001-pg_walinspect-docs.patch
application/octet-stream
Filename: v8-0001-pg_walinspect-docs.patch
Type: application/octet-stream
Part: 2
Patch
Format: format-patch
Series: patch v8-0001
Subject: pg_walinspect docs
| File | + | − |
|---|---|---|
| doc/src/sgml/contrib.sgml | 1 | 0 |
| doc/src/sgml/filelist.sgml | 1 | 0 |
| doc/src/sgml/pgwalinspect.sgml | 173 | 0 |
From 157777bbf29f21f26d2f969aad2acae05aeb500d Mon Sep 17 00:00:00 2001
From: Bharath Rupireddy <bharath.rupireddyforpostgres@gmail.com>
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 <replaceable>module_name</replaceable>;
&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 @@
<!ENTITY pgsurgery SYSTEM "pgsurgery.sgml">
<!ENTITY pgtrgm SYSTEM "pgtrgm.sgml">
<!ENTITY pgvisibility SYSTEM "pgvisibility.sgml">
+<!ENTITY pgwalinspect SYSTEM "pgwalinspect.sgml">
<!ENTITY postgres-fdw SYSTEM "postgres-fdw.sgml">
<!ENTITY seg SYSTEM "seg.sgml">
<!ENTITY contrib-spi SYSTEM "contrib-spi.sgml">
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 @@
+<!-- doc/src/sgml/pgwalinspect.sgml -->
+
+<sect1 id="pgwalinspect" xreflabel="pg_walinspect">
+ <title>pg_walinspect</title>
+
+ <indexterm zone="pgwalinspect">
+ <primary>pg_walinspect</primary>
+ </indexterm>
+
+ <para>
+ The <filename>pg_walinspect</filename> module provides functions that allow
+ you to inspect the contents of write-ahead log of <productname>PostgreSQL</productname>
+ database cluster at a low level, which is useful for debugging or analytical
+ or reporting or educational purposes.
+ </para>
+
+ <para>
+ By default, use of these functions is restricted to superusers and members of
+ the <literal>pg_monitor</literal> role. Access may be granted to others using
+ <command>GRANT</command>.
+ </para>
+
+ <para>
+ All the functions of this module will provide the WAL information using the
+ current server's timeline ID.
+ </para>
+
+ <sect2>
+ <title>General Functions</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <function>pg_get_raw_wal_record(in_lsn pg_lsn, lsn OUT pg_lsn, record OUT bytea)</function>
+ </term>
+
+ <listitem>
+ <para>
+ 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)
+ <replaceable>in_lsn</replaceable> is specified.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>pg_get_first_valid_wal_record_lsn(in_lsn pg_lsn, lsn OUT pg_lsn, prev_lsn OUT pg_lsn)</function>
+ </term>
+
+ <listitem>
+ <para>
+ 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) <replaceable>in_lsn</replaceable> is specified.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>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)</function>
+ </term>
+
+ <listitem>
+ <para>
+ 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)
+ <replaceable>in_lsn</replaceable> is specified.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>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)</function>
+ </term>
+
+ <listitem>
+ <para>
+ Gets information of all the valid WAL records between
+ <replaceable>start_lsn</replaceable> and <replaceable>end_lsn</replaceable>.
+ Returns one row per each valid WAL record. Issues a warning if the given
+ <replaceable>start_lsn</replaceable> 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 <replaceable>end_lsn</replaceable> if it's
+ not specified, that means, it returns information up to the end of WAL.
+ Default value of <replaceable>end_lsn</replaceable> is <literal>NULL</literal>.
+ This function emits an error if a future (the LSN database system doesn't
+ know about) <replaceable>start_lsn</replaceable> or <replaceable>end_lsn</replaceable>
+ is specified. For example:
+<screen>
+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)
+</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>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)</function>
+ </term>
+
+ <listitem>
+ <para>
+ Gets statistics of all the valid WAL records between
+ <replaceable>start_lsn</replaceable> and <replaceable>end_lsn</replaceable>.
+ Returns one row per each <replaceable>resource_manager</replaceable>
+ type. Issues a warning if the given <replaceable>start_lsn</replaceable>
+ 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
+ <replaceable>end_lsn</replaceable> if it's not specified, that means, it
+ returns information up to the end of WAL. Default value of
+ <replaceable>end_lsn</replaceable> is <literal>NULL</literal>. This
+ function emits an error if a future (the LSN database system doesn't know
+ about) <replaceable>start_lsn</replaceable> or <replaceable>end_lsn</replaceable>
+ is specified. For example:
+<screen>
+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)
+</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect2>
+
+</sect1>
--
2.25.1