doc/src/sgml/pglogicalinspect.sgml

   1 <!-- doc/src/sgml/pglogicalinspect.sgml -->
   2
   3 <sect1 id="pglogicalinspect" xreflabel="pg_logicalinspect">
   4  <title>pg_logicalinspect &mdash; logical decoding components inspection</title>
   5
   6  <indexterm zone="pglogicalinspect">
   7   <primary>pg_logicalinspect</primary>
   8  </indexterm>
   9
  10  <para>
  11   The <filename>pg_logicalinspect</filename> module provides SQL functions
  12   that allow you to inspect the contents of logical decoding components. It
  13   allows the inspection of serialized logical snapshots of a running
  14   <productname>PostgreSQL</productname> database cluster, which is useful
  15   for debugging or educational purposes.
  16  </para>
  17
  18  <para>
  19   By default, use of these functions is restricted to superusers and members of
  20   the <literal>pg_read_server_files</literal> role. Access may be granted by
  21   superusers to others using <command>GRANT</command>.
  22  </para>
  23
  24  <sect2 id="pglogicalinspect-funcs">
  25   <title>Functions</title>
  26
  27   <variablelist>
  28    <varlistentry id="pglogicalinspect-funcs-pg-get-logical-snapshot-meta">
  29     <term>
  30      <function>pg_get_logical_snapshot_meta(filename text) returns record</function>
  31     </term>
  32
  33     <listitem>
  34      <para>
  35       Gets logical snapshot metadata about a snapshot file that is located in
  36       the server's <filename>pg_logical/snapshots</filename> directory.
  37       The <replaceable>filename</replaceable> argument represents the snapshot
  38       file name.
  39       For example:
  40 <screen>
  41 postgres=# SELECT * FROM pg_ls_logicalsnapdir();
  42 -[ RECORD 1 ]+-----------------------
  43 name         | 0-40796E18.snap
  44 size         | 152
  45 modification | 2024-08-14 16:36:32+00
  46
  47 postgres=# SELECT * FROM pg_get_logical_snapshot_meta('0-40796E18.snap');
  48 -[ RECORD 1 ]--------
  49 magic    | 1369563137
  50 checksum | 1028045905
  51 version  | 6
  52
  53 postgres=# SELECT ss.name, meta.* FROM pg_ls_logicalsnapdir() AS ss,
  54 pg_get_logical_snapshot_meta(ss.name) AS meta;
  55 -[ RECORD 1 ]-------------
  56 name     | 0-40796E18.snap
  57 magic    | 1369563137
  58 checksum | 1028045905
  59 version  | 6
  60 </screen>
  61      </para>
  62      <para>
  63       If <replaceable>filename</replaceable> does not match a snapshot file, the
  64       function raises an error.
  65      </para>
  66     </listitem>
  67    </varlistentry>
  68
  69    <varlistentry id="pglogicalinspect-funcs-pg-get-logical-snapshot-info">
  70     <term>
  71      <function>pg_get_logical_snapshot_info(filename text) returns record</function>
  72     </term>
  73
  74     <listitem>
  75      <para>
  76       Gets logical snapshot information about a snapshot file that is located in
  77       the server's <filename>pg_logical/snapshots</filename> directory.
  78       The <replaceable>filename</replaceable> argument represents the snapshot
  79       file name.
  80       For example:
  81 <screen>
  82 postgres=# SELECT * FROM pg_ls_logicalsnapdir();
  83 -[ RECORD 1 ]+-----------------------
  84 name         | 0-40796E18.snap
  85 size         | 152
  86 modification | 2024-08-14 16:36:32+00
  87
  88 postgres=# SELECT * FROM pg_get_logical_snapshot_info('0-40796E18.snap');
  89 -[ RECORD 1 ]------------+-----------
  90 state                    | consistent
  91 xmin                     | 751
  92 xmax                     | 751
  93 start_decoding_at        | 0/40796AF8
  94 two_phase_at             | 0/40796AF8
  95 initial_xmin_horizon     | 0
  96 building_full_snapshot   | f
  97 in_slot_creation         | f
  98 last_serialized_snapshot | 0/0
  99 next_phase_at            | 0
 100 committed_count          | 0
 101 committed_xip            |
 102 catchange_count          | 2
 103 catchange_xip            | {751,752}
 104
 105 postgres=# SELECT ss.name, info.* FROM pg_ls_logicalsnapdir() AS ss,
 106 pg_get_logical_snapshot_info(ss.name) AS info;
 107 -[ RECORD 1 ]------------+----------------
 108 name                     | 0-40796E18.snap
 109 state                    | consistent
 110 xmin                     | 751
 111 xmax                     | 751
 112 start_decoding_at        | 0/40796AF8
 113 two_phase_at             | 0/40796AF8
 114 initial_xmin_horizon     | 0
 115 building_full_snapshot   | f
 116 in_slot_creation         | f
 117 last_serialized_snapshot | 0/0
 118 next_phase_at            | 0
 119 committed_count          | 0
 120 committed_xip            |
 121 catchange_count          | 2
 122 catchange_xip            | {751,752}
 123 </screen>
 124      </para>
 125      <para>
 126       If <replaceable>filename</replaceable> does not match a snapshot file, the
 127       function raises an error.
 128      </para>
 129     </listitem>
 130    </varlistentry>
 131
 132   </variablelist>
 133  </sect2>
 134
 135  <sect2 id="pglogicalinspect-author">
 136   <title>Author</title>
 137
 138   <para>
 139    Bertrand Drouvot <email>bertranddrouvot.pg@gmail.com</email>
 140   </para>
 141  </sect2>
 142
 143 </sect1>