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, 6 insertions, 17 deletions

diff --git a/doc/src/sgml/ref/truncate.sgml b/doc/src/sgml/ref/truncate.sgml
index 10c4fdd359a..a78e47c0952 100644
--- a/doc/src/sgml/ref/truncate.sgml
+++ b/doc/src/sgml/ref/truncate.sgml
@@ -140,23 +140,12 @@ TRUNCATE [ TABLE ] [ ONLY ] <replaceable class="PARAMETER">name</replaceable> [
    that were added due to cascading).
   </para>
 
-  <warning>
-   <para>
-    <command>TRUNCATE</> is not MVCC-safe (see <xref linkend="mvcc">
-     for general information about MVCC).  After truncation, the table
-     will appear empty to all concurrent transactions, even if they
-     are using a snapshot taken before the truncation occurred.  This
-     will only be an issue for a transaction that did not access the
-     truncated table before the truncation happened &mdash; any
-     transaction that has done so would hold at least an
-     <literal>ACCESS SHARE</literal> lock, which would block
-     <command>TRUNCATE</> until that transaction completes.  So
-     truncation will not cause any apparent inconsistency in the table
-     contents for successive queries on the same table, but it could
-     cause visible inconsistency between the contents of the truncated
-     table and other tables in the database.
-   </para>
-  </warning>
+  <para>
+   <command>TRUNCATE</> is not MVCC-safe.  After truncation, the table will
+   appear empty to concurrent transactions, if they are using a snapshot
+   taken before the truncation occurred.
+   See <xref linkend="mvcc-caveats"> for more details.
+  </para>
 
   <para>
    <command>TRUNCATE</> is transaction-safe with respect to the data