Improve documentation about MVCC-unsafe utility commands.

The table-rewriting forms of ALTER TABLE are MVCC-unsafe, in much the same
way as TRUNCATE, because they replace all rows of the table with newly-made
rows with a new xmin.  (Ideally, concurrent transactions with old snapshots
would continue to see the old table contents, but the data is not there
anymore --- and if it were there, it would be inconsistent with the table's
updated rowtype, so there would be serious implementation problems to fix.)
This was nowhere documented though, and the problem was only documented for
TRUNCATE in a note in the TRUNCATE reference page.  Create a new "Caveats"
section in the MVCC chapter that can be home to this and other limitations
on serializable consistency.

In passing, fix a mistaken statement that VACUUM and CLUSTER would reclaim
space occupied by a dropped column.  They don't reconstruct existing tuples
so they couldn't do that.

Back-patch to all supported branches.

1 files changed, 32 insertions, 14 deletions

diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml
index 385691e21e..5128982e07 100644
--- a/doc/src/sgml/mvcc.sgml
+++ b/doc/src/sgml/mvcc.sgml
@@ -757,20 +757,6 @@ ERROR:  could not serialize access due to read/write dependencies among transact
      </listitem>
     </itemizedlist>
    </para>
-
-   <warning>
-    <para>
-     Support for the Serializable transaction isolation level has not yet
-     been added to Hot Standby replication targets (described in
-     <xref linkend="hot-standby">).  The strictest isolation level currently
-     supported in hot standby mode is Repeatable Read.  While performing all
-     permanent database writes within Serializable transactions on the
-     master will ensure that all standbys will eventually reach a consistent
-     state, a Repeatable Read transaction run on the standby can sometimes
-     see a transient state which is inconsistent with any serial execution
-     of serializable transactions on the master.
-    </para>
-   </warning>
   </sect2>
  </sect1>
 
@@ -1667,6 +1653,38 @@ SELECT pg_advisory_lock(q.id) FROM
    </sect2>
   </sect1>
 
+  <sect1 id="mvcc-caveats">
+   <title>Caveats</title>
+
+   <para>
+    Some DDL commands, currently only <xref linkend="sql-truncate"> and the
+    table-rewriting forms of <xref linkend="sql-altertable">, are not
+    MVCC-safe.  This means that after the truncation or rewrite commits, the
+    table will appear empty to concurrent transactions, if they are using a
+    snapshot taken before the DDL command committed.  This will only be an
+    issue for a transaction that did not access the table in question
+    before the DDL command started &mdash; any transaction that has done so
+    would hold at least an <literal>ACCESS SHARE</literal> table lock,
+    which would block the DDL command until that transaction completes.
+    So these commands will not cause any apparent inconsistency in the
+    table contents for successive queries on the target table, but they
+    could cause visible inconsistency between the contents of the target
+    table and other tables in the database.
+   </para>
+
+   <para>
+    Support for the Serializable transaction isolation level has not yet
+    been added to Hot Standby replication targets (described in
+    <xref linkend="hot-standby">).  The strictest isolation level currently
+    supported in hot standby mode is Repeatable Read.  While performing all
+    permanent database writes within Serializable transactions on the
+    master will ensure that all standbys will eventually reach a consistent
+    state, a Repeatable Read transaction run on the standby can sometimes
+    see a transient state that is inconsistent with any serial execution
+    of the transactions on the master.
+   </para>
+  </sect1>
+
   <sect1 id="locking-indexes">
    <title>Locking and Indexes</title>