summaryrefslogtreecommitdiffstats
path: root/doc/src/sgml/pgwalinspect.sgml
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-16 19:46:48 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-16 19:46:48 +0000
commit311bcfc6b3acdd6fd152798c7f287ddf74fa2a98 (patch)
tree0ec307299b1dada3701e42f4ca6eda57d708261e /doc/src/sgml/pgwalinspect.sgml
parentInitial commit. (diff)
downloadpostgresql-15-311bcfc6b3acdd6fd152798c7f287ddf74fa2a98.tar.xz
postgresql-15-311bcfc6b3acdd6fd152798c7f287ddf74fa2a98.zip
Adding upstream version 15.4.upstream/15.4upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/src/sgml/pgwalinspect.sgml')
-rw-r--r--doc/src/sgml/pgwalinspect.sgml203
1 files changed, 203 insertions, 0 deletions
diff --git a/doc/src/sgml/pgwalinspect.sgml b/doc/src/sgml/pgwalinspect.sgml
new file mode 100644
index 0000000..51592a5
--- /dev/null
+++ b/doc/src/sgml/pgwalinspect.sgml
@@ -0,0 +1,203 @@
+<!-- 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 SQL functions that
+ allow you to inspect the contents of write-ahead log of
+ a running <productname>PostgreSQL</productname> database cluster at a low
+ level, which is useful for debugging, analytical, reporting or
+ educational purposes. It is similar to <xref linkend="pgwaldump"/>, but
+ accessible through SQL rather than a separate utility.
+ </para>
+
+ <para>
+ All the functions of this module will provide the WAL information using the
+ current server's timeline ID.
+ </para>
+
+ <para>
+ All the functions of this module will try to find the first valid WAL record
+ that is at or after the given <replaceable>in_lsn</replaceable> or
+ <replaceable>start_lsn</replaceable> and will emit error if no such record
+ is available. Similarly, the <replaceable>end_lsn</replaceable> must be
+ available, and if it falls in the middle of a record, the entire record must
+ be available.
+ </para>
+
+ <note>
+ <para>
+ Some functions, such as <function><link
+ linkend="pg-logical-emit-message">pg_logical_emit_message</link></function>,
+ return the LSN <emphasis>after</emphasis> the record just
+ inserted. Therefore, if you pass that LSN as
+ <replaceable>in_lsn</replaceable> or <replaceable>start_lsn</replaceable>
+ to one of these functions, it will return the <emphasis>next</emphasis>
+ record.
+ </para>
+ </note>
+ <para>
+ By default, use of these functions is restricted to superusers and members of
+ the <literal>pg_read_server_files</literal> role. Access may be granted by
+ superusers to others using <command>GRANT</command>.
+ </para>
+
+ <sect2>
+ <title>General Functions</title>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <function>pg_get_wal_record_info(in_lsn pg_lsn) returns record</function>
+ </term>
+
+ <listitem>
+ <para>
+ Gets WAL record information of a given LSN. If the given LSN isn't
+ at the start of a WAL record, it gives the information of the next
+ available valid WAL record; or an error if no such record is found.
+ For example, usage of the function is as
+ follows:
+<screen>
+postgres=# SELECT * FROM pg_get_wal_record_info('0/1E826E98');
+-[ RECORD 1 ]----+----------------------------------------------------
+start_lsn | 0/1E826F20
+end_lsn | 0/1E826F60
+prev_lsn | 0/1E826C80
+xid | 0
+resource_manager | Heap2
+record_type | PRUNE
+record_length | 58
+main_data_length | 8
+fpi_length | 0
+description | snapshotConflictHorizon 33748 nredirected 0 ndead 2
+block_ref | blkref #0: rel 1663/5/60221 fork main blk 2
+</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>
+ pg_get_wal_records_info(start_lsn pg_lsn, end_lsn pg_lsn)
+ returns setof record
+ </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 WAL record. If <replaceable>start_lsn</replaceable>
+ or <replaceable>end_lsn</replaceable> are not yet available, the
+ function will raise an error. For example:
+<screen>
+postgres=# SELECT * FROM pg_get_wal_records_info('0/1E913618', '0/1E913740') LIMIT 1;
+-[ RECORD 1 ]----+--------------------------------------------------------------
+start_lsn | 0/1E913618
+end_lsn | 0/1E913650
+prev_lsn | 0/1E9135A0
+xid | 0
+resource_manager | Standby
+record_type | RUNNING_XACTS
+record_length | 50
+main_data_length | 24
+fpi_length | 0
+description | nextXid 33775 latestCompletedXid 33774 oldestRunningXid 33775
+block_ref |
+</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>
+ pg_get_wal_records_info_till_end_of_wal(start_lsn pg_lsn)
+ returns setof record
+ </function>
+ </term>
+
+ <listitem>
+ <para>
+ This function is the same as <function>pg_get_wal_records_info()</function>,
+ except that it gets information of all the valid WAL records from
+ <replaceable>start_lsn</replaceable> till the end of WAL.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>
+ pg_get_wal_stats(start_lsn pg_lsn, end_lsn pg_lsn, per_record boolean DEFAULT false)
+ returns setof record
+ </function>
+ </term>
+
+ <listitem>
+ <para>
+ Gets statistics of all the valid WAL records between
+ <replaceable>start_lsn</replaceable> and
+ <replaceable>end_lsn</replaceable>. By default, it returns one row per
+ <replaceable>resource_manager</replaceable> type. When
+ <replaceable>per_record</replaceable> is set to <literal>true</literal>,
+ it returns one row per <replaceable>record_type</replaceable>.
+ If <replaceable>start_lsn</replaceable>
+ or <replaceable>end_lsn</replaceable> are not yet available, the
+ function will raise an error. For example:
+<screen>
+postgres=# SELECT * FROM pg_get_wal_stats('0/1E847D00', '0/1E84F500')
+ WHERE count > 0 AND
+ "resource_manager/record_type" = 'Transaction'
+ LIMIT 1;
+-[ RECORD 1 ]----------------+-------------------
+resource_manager/record_type | Transaction
+count | 2
+count_percentage | 8
+record_size | 875
+record_size_percentage | 41.23468426013195
+fpi_size | 0
+fpi_size_percentage | 0
+combined_size | 875
+combined_size_percentage | 2.8634072910530795
+</screen>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <function>
+ pg_get_wal_stats_till_end_of_wal(start_lsn pg_lsn, per_record boolean DEFAULT false)
+ returns setof record
+ </function>
+ </term>
+
+ <listitem>
+ <para>
+ This function is the same as <function>pg_get_wal_stats()</function>,
+ except that it gets statistics of all the valid WAL records from
+ <replaceable>start_lsn</replaceable> till end of WAL.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </sect2>
+
+ <sect2>
+ <title>Author</title>
+
+ <para>
+ Bharath Rupireddy <email>bharath.rupireddyforpostgres@gmail.com</email>
+ </para>
+ </sect2>
+
+</sect1>