From d1f3c3a295b842fbf6a3a9a040cfbd33e52d7333 Mon Sep 17 00:00:00 2001
From: Bharath Rupireddy <bharath.rupireddyforpostgres@gmail.com>
Date: Fri, 25 Feb 2022 07:30:49 +0000
Subject: [PATCH v5] pg_walinspect docs

---
 doc/src/sgml/contrib.sgml      |   1 +
 doc/src/sgml/filelist.sgml     |   1 +
 doc/src/sgml/pgwalinspect.sgml | 165 +++++++++++++++++++++++++++++++++
 3 files changed, 167 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..fa9f1d9b6c
--- /dev/null
+++ b/doc/src/sgml/pgwalinspect.sgml
@@ -0,0 +1,165 @@
+<!-- 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 and analytical
+  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>
+
+ <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 will not wait if
+      the future WAL LSN is provided, instead emits a warning and returns an
+      empty row.
+     </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 will not wait if the future WAL LSN is provided, instead emits
+      a warning and returns an empty row.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term>
+     <function>pg_get_first_and_last_valid_wal_record_lsn(wal_file_name text, first_valid_lsn OUT pg_lsn, last_valid_lsn OUT pg_lsn)</function>
+    </term>
+
+    <listitem>
+     <para>
+      Gets first and last valid WAL record LSNs of the given WAL file.
+     </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 will not
+      wait if the future WAL LSN is provided, instead emits a warning and
+      returns an empty row.
+     </para>
+    </listitem>
+   </varlistentry>
+
+    <varlistentry>
+    <term>
+     <function>pg_get_wal_records_info(start_lsn pg_lsn, end_lsn pg_lsn, wait_for_wal boolean DEFAULT false, 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 will wait if the future WAL LSN is provided when
+      <replaceable>wait_for_wal</replaceable> is passed as <literal>true</literal>.
+      If <replaceable>wait_for_wal</replaceable> is <literal>false</literal>
+      (default value), it will not wait for the future WAL, instead emits a
+      warning and returns rows for whatever available WAL records.
+     </para>
+    </listitem>
+   </varlistentry>
+
+    <varlistentry>
+    <term>
+     <function>pg_get_wal_records_info_till_end_of_wal(start_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 information of all the valid WAL records from
+      <replaceable>start_lsn</replaceable> till end of WAL. This function is
+      similar to <literal>pg_get_wal_records_info</literal> except that it
+      doesn't have <replaceable>end_lsn</replaceable> as input and it doesn't
+      wait for the future WAL.
+     </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 will wait if the
+      future WAL LSN is provided when <replaceable>wait_for_wal</replaceable>
+      is passed as <literal>true</literal>. If <replaceable>wait_for_wal</replaceable>
+      is <literal>false</literal> (default value), it will not wait for the
+      future WAL, instead emits a warning and returns rows for whatever
+      available WAL records.
+     </para>
+    </listitem>
+   </varlistentry>
+
+    <varlistentry>
+    <term>
+     <function>pg_get_wal_stats_till_end_of_wal(start_lsn pg_lsn, end_lsn pg_lsn, 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 from
+      <replaceable>start_lsn</replaceable> till end of WAL. This function is
+      similar to <literal>pg_get_wal_stats</literal> except that it doesn't
+      have <replaceable>end_lsn</replaceable> as input and it doesn't wait for
+      the future WAL.
+     </para>
+    </listitem>
+   </varlistentry>
+
+  </variablelist>
+ </sect2>
+
+</sect1>
-- 
2.25.1

