<!-- doc/src/sgml/pgwalinspect.sgml -->

<sect1 id="pgwalinspect" xreflabel="pg_walinspect">
 <title>pg_walinspect &mdash; low-level WAL inspection</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
  server's current timeline ID.
 </para>

 <note>
  <para>
   The <filename>pg_walinspect</filename> functions are often called
   using an LSN argument that specifies the location at which a known
   WAL record of interest <emphasis>begins</emphasis>.  However, 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 that was just
   inserted.
  </para>
 </note>
 <tip>
  <para>
   All of the <filename>pg_walinspect</filename> functions that show
   information about records that fall within a certain LSN range are
   permissive about accepting <replaceable>end_lsn</replaceable>
   arguments that are after the server's current LSN.  Using an
   <replaceable>end_lsn</replaceable> <quote>from the future</quote>
   will not raise an error.
  </para>
  <para>
   It may be convenient to provide the value
   <literal>FFFFFFFF/FFFFFFFF</literal> (the maximum valid
   <type>pg_lsn</type> value) as an <replaceable>end_lsn</replaceable>
   argument.  This is equivalent to providing an
   <replaceable>end_lsn</replaceable> argument matching the server's
   current LSN.
  </para>
 </tip>
 <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 id="pgwalinspect-funcs">
  <title>General Functions</title>

  <variablelist>
   <varlistentry id="pgwalinspect-funcs-pg-get-wal-record-info">
    <term>
     <function>pg_get_wal_record_info(in_lsn pg_lsn) returns record</function>
    </term>

    <listitem>
     <para>
      Gets WAL record information about a record that is located at or
      after the <replaceable>in_lsn</replaceable> argument.  For
      example:
<screen>
postgres=# SELECT * FROM pg_get_wal_record_info('0/E419E28');
-[ RECORD 1 ]----+-------------------------------------------------
start_lsn        | 0/E419E28
end_lsn          | 0/E419E68
prev_lsn         | 0/E419D78
xid              | 0
resource_manager | Heap2
record_type      | VACUUM
record_length    | 58
main_data_length | 2
fpi_length       | 0
description      | nunused: 5, unused: [1, 2, 3, 4, 5]
block_ref        | blkref #0: rel 1663/16385/1249 fork main blk 364
</screen>
     </para>
     <para>
      If <replaceable>in_lsn</replaceable> isn't at the start of a WAL
      record, information about the next valid WAL record is shown
      instead.  If there is no next valid WAL record, the function
      raises an error.
     </para>
    </listitem>
   </varlistentry>

    <varlistentry id="pgwalinspect-funcs-pg-get-wal-records-info">
    <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.  For example:
<screen>
postgres=# SELECT * FROM pg_get_wal_records_info('0/1E913618', '0/1E913740') LIMIT 1;
-[ RECORD 1 ]----+--------------------------------------------------------------