From 71d05a2c7b82379bb1013a0e338906349c54ed85 Mon Sep 17 00:00:00 2001
From: Robert Haas <rhaas@postgresql.org>
Date: Fri, 17 Jun 2016 17:37:30 -0400
Subject: pg_visibility: Add pg_truncate_visibility_map function.

This requires some core changes as well so that we can properly
WAL-log the truncation.  Specifically, it changes the format of the
XLOG_SMGR_TRUNCATE WAL record, so bump XLOG_PAGE_MAGIC.

Patch by me, reviewed but not fully endorsed by Andres Freund.
---
 doc/src/sgml/pgvisibility.sgml | 30 ++++++++++++++++++++++++------
 1 file changed, 24 insertions(+), 6 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/pgvisibility.sgml b/doc/src/sgml/pgvisibility.sgml
index 4cdca7dada9..44e83de7289 100644
--- a/doc/src/sgml/pgvisibility.sgml
+++ b/doc/src/sgml/pgvisibility.sgml
@@ -9,14 +9,16 @@
 
  <para>
   The <filename>pg_visibility</> module provides a means for examining the
-  visibility map (VM) and page-level visibility information.
+  visibility map (VM) and page-level visibility information.  It also
+  provides functions to check the integrity of the visibility map and to
+  force it to be rebuilt.
  </para>
 
  <para>
-  These routines return information about three different bits.  The
-  all-visible bit in the visibility map indicates that every tuple on
-  a given page of a relation is visible to every current transaction.  The
-  all-frozen bit in the visibility map indicates that every tuple on the
+  Three different bits are used to store information about page-level
+  visibility.  The all-visible bit in the visibility map indicates that every
+  tuple on a given page of a relation is visible to every current transaction.
+  The all-frozen bit in the visibility map indicates that every tuple on 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-level <literal>PD_ALL_VISIBLE</literal> bit has the
@@ -25,7 +27,8 @@
   will normally agree, but the page-level bit can sometimes be set while the
   visibility map bit is clear after a crash recovery; or they can disagree
   because of a change which occurs after <literal>pg_visibility</> examines
-  the visibility map and before it examines the data page.
+  the visibility map and before it examines the data page.  Any event which
+  causes data corruption can also cause these bits to disagree.
  </para>
 
  <para>
@@ -118,6 +121,21 @@
      </para>
     </listitem>
    </varlistentry>
+
+   <varlistentry>
+    <term><function>pg_truncate_visibility_map(regclass) returns void</function></term>
+
+    <listitem>
+     <para>
+      Truncates the visibility map for the given relation.  This function
+      is only expected to be useful if you suspect that the visibility map
+      for the indicated relation is corrupt and wish to rebuild it.  The first
+      <command>VACUUM</> executed on the given relation after this function
+      is executed will scan every page in the relation and rebuild the
+      visibility map.
+     </para>
+    </listitem>
+   </varlistentry>
   </variablelist>
 
   <para>
-- 
cgit v1.2.3