v7-0001-pg_walinspect-docs.patch

From 1efcb8fc07cf5f5b1b2987339321dd803c96275a Mon Sep 17 00:00:00 2001
From: Bharath Rupireddy <bharath.rupireddyforpostgres@gmail.com>
Date: Fri, 4 Mar 2022 09:15:21 +0000
Subject: [PATCH v7] pg_walinspect docs

---
 doc/src/sgml/contrib.sgml      |   1 +
 doc/src/sgml/filelist.sgml     |   1 +
 doc/src/sgml/pgwalinspect.sgml | 128 +++++++++++++++++++++++++++++++++
 3 files changed, 130 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..5bc79c80ae
--- /dev/null
+++ b/doc/src/sgml/pgwalinspect.sgml
@@ -0,0 +1,128 @@
+<!-- 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.
+     </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.
+     </para>
+    </listitem>
+   </varlistentry>
+
+  </variablelist>
+ </sect2>
+
+</sect1>
-- 
2.25.1