Adding upstream version 15.4.upstream/15.4upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 158 insertions, 0 deletions

diff --git a/doc/src/sgml/pgvisibility.sgml b/doc/src/sgml/pgvisibility.sgml
new file mode 100644
index 0000000..8090aa5
--- /dev/null
+++ b/doc/src/sgml/pgvisibility.sgml
@@ -0,0 +1,158 @@
+<!-- doc/src/sgml/pgvisibility.sgml -->
+
+<sect1 id="pgvisibility" xreflabel="pg_visibility">
+ <title>pg_visibility</title>
+
+ <indexterm zone="pgvisibility">
+  <primary>pg_visibility</primary>
+ </indexterm>
+
+ <para>
+  The <filename>pg_visibility</filename> module provides a means for examining the
+  visibility map (VM) and page-level visibility information of a table.
+  It also provides functions to check the integrity of a visibility map and to
+  force it to be rebuilt.
+ </para>
+
+ <para>
+  Three different bits are used to store information about page-level
+  visibility.  The all-visible bit in the visibility map indicates that every
+  tuple in the corresponding page of the relation is visible to every current
+  and future transaction.  The all-frozen bit in the visibility map indicates
+  that every tuple in the page is frozen; that is, no future vacuum will need
+  to modify the page until such time as a tuple is inserted, updated, deleted,
+  or locked on that page.
+  The page header's <literal>PD_ALL_VISIBLE</literal> bit has the
+  same meaning as the all-visible bit in the visibility map, but is stored
+  within the data page itself rather than in a separate data structure.
+  These two bits will normally agree, but the page's all-visible bit can
+  sometimes be set while the visibility map bit is clear after a crash
+  recovery.  The reported values can also disagree because of a change that
+  occurs after <literal>pg_visibility</literal> examines the visibility map and
+  before it examines the data page.  Any event that causes data corruption
+  can also cause these bits to disagree.
+ </para>
+
+ <para>
+  Functions that display information about <literal>PD_ALL_VISIBLE</literal> bits
+  are much more costly than those that only consult the visibility map,
+  because they must read the relation's data blocks rather than only the
+  (much smaller) visibility map.  Functions that check the relation's
+  data blocks are similarly expensive.
+ </para>
+
+ <sect2>
+  <title>Functions</title>
+
+  <variablelist>
+   <varlistentry>
+    <term><function>pg_visibility_map(relation regclass, blkno bigint, all_visible OUT boolean, all_frozen OUT boolean) returns record</function></term>
+    <listitem>
+     <para>
+      Returns the all-visible and all-frozen bits in the visibility map for
+      the given block of the given relation.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><function>pg_visibility(relation regclass, blkno bigint, all_visible OUT boolean, all_frozen OUT boolean, pd_all_visible OUT boolean) returns record</function></term>
+    <listitem>
+     <para>
+      Returns the all-visible and all-frozen bits in the visibility map for
+      the given block of the given relation, plus the
+      <literal>PD_ALL_VISIBLE</literal> bit of that block.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><function>pg_visibility_map(relation regclass, blkno OUT bigint, all_visible OUT boolean, all_frozen OUT boolean) returns setof record</function></term>
+    <listitem>
+     <para>
+      Returns the all-visible and all-frozen bits in the visibility map for
+      each block of the given relation.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><function>pg_visibility(relation regclass, blkno OUT bigint, all_visible OUT boolean, all_frozen OUT boolean, pd_all_visible OUT boolean) returns setof record</function></term>
+
+    <listitem>
+     <para>
+      Returns the all-visible and all-frozen bits in the visibility map for
+      each block of the given relation, plus the <literal>PD_ALL_VISIBLE</literal>
+      bit of each block.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><function>pg_visibility_map_summary(relation regclass, all_visible OUT bigint, all_frozen OUT bigint) returns record</function></term>
+
+    <listitem>
+     <para>
+      Returns the number of all-visible pages and the number of all-frozen
+      pages in the relation according to the visibility map.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><function>pg_check_frozen(relation regclass, t_ctid OUT tid) returns setof tid</function></term>
+
+    <listitem>
+     <para>
+      Returns the TIDs of non-frozen tuples stored in pages marked all-frozen
+      in the visibility map.  If this function returns a non-empty set of
+      TIDs, the visibility map is corrupt.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><function>pg_check_visible(relation regclass, t_ctid OUT tid) returns setof tid</function></term>
+
+    <listitem>
+     <para>
+      Returns the TIDs of non-all-visible tuples stored in pages marked
+      all-visible in the visibility map.  If this function returns a non-empty
+      set of TIDs, the visibility map is corrupt.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><function>pg_truncate_visibility_map(relation regclass) returns void</function></term>
+
+    <listitem>
+     <para>
+      Truncates the visibility map for the given relation.  This function is
+      useful if you believe that the visibility map for the relation is
+      corrupt and wish to force rebuilding it.  The first <command>VACUUM</command>
+      executed on the given relation after this function is executed will scan
+      every page in the relation and rebuild the visibility map.  (Until that
+      is done, queries will treat the visibility map as containing all zeroes.)
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+
+  <para>
+   By default, these functions are executable only by superusers and roles with privileges
+   of the <literal>pg_stat_scan_tables</literal> role, with the exception of
+   <function>pg_truncate_visibility_map(relation regclass)</function> which can only
+   be executed by superusers.
+  </para>
+ </sect2>
+
+ <sect2>
+  <title>Author</title>
+
+  <para>
+   Robert Haas <email>rhaas@postgresql.org</email>
+  </para>
+ </sect2>
+
+</sect1>