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.

diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml
index 385691e21ed08aa428a22ec7f9749f24c9754b38..5128982e07dde6fbfd4cde08de50754651080291 100644 (file)
--- 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
      
     
    
-
-   
-    
-     Support for the Serializable transaction isolation level has not yet
-     been added to Hot Standby replication targets (described in
-     ).  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.
-    
-   
   
  
 
@@ -1667,6 +1653,38 @@ SELECT pg_advisory_lock(q.id) FROM
    
   
 
+  
+   Caveats
+
+   
+    Some DDL commands, currently only  and the
+    table-rewriting forms of , 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 — any transaction that has done so
+    would hold at least an ACCESS SHARE 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.
+   
+
+   
+    Support for the Serializable transaction isolation level has not yet
+    been added to Hot Standby replication targets (described in
+    ).  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.
+   
+  
+
   
    Locking and Indexes
 

diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index ad985cd73110037328aba9bc29097d48d3ea58e3..92e9ce864f5aa8447d5c1593c82eb072757937f5 100644 (file)
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -652,7 +652,7 @@ ALTER TABLE ALL IN TABLESPACE name
       This form changes the information which is written to the write-ahead log
       to identify rows which are updated or deleted.  This option has no effect
       except when logical replication is in use.  DEFAULT
-      (the default for non-system tables) records the 
+      (the default for non-system tables) records the
       old values of the columns of the primary key, if any.  USING INDEX
       records the old values of the columns covered by the named index, which
       must be unique, not partial, not deferrable, and include only columns marked
@@ -954,7 +954,8 @@ ALTER TABLE ALL IN TABLESPACE name
 
    
     Adding a CHECK or NOT NULL constraint requires
-    scanning the table to verify that existing rows meet the constraint.
+    scanning the table to verify that existing rows meet the constraint,
+    but does not require a table rewrite.
    
 
    
@@ -976,11 +977,17 @@ ALTER TABLE ALL IN TABLESPACE name
    
 
    
-    To force an immediate rewrite of the table, you can use
-    VACUUM FULL, 
-    or one of the forms of ALTER TABLE that forces a rewrite.  This results in
-    no semantically-visible change in the table, but gets rid of
-    no-longer-useful data.
+    To force immediate reclamation of space occupied by a dropped column,
+    you can execute one of the forms of ALTER TABLE that
+    performs a rewrite of the whole table.  This results in reconstructing
+    each row with the dropped column replaced by a null value.
+   
+
+   
+    The rewriting forms of ALTER TABLE are not MVCC-safe.
+    After a table rewrite, the table will appear empty to concurrent
+    transactions, if they are using a snapshot taken before the rewrite
+    occurred.  See  for more details.
    
 
    

diff --git a/doc/src/sgml/ref/truncate.sgml b/doc/src/sgml/ref/truncate.sgml
index 10c4fdd359abbee3622edd123f4e3fcd7f53a267..a78e47c0952b5c6c3b82cd9402f3a059cccf0e12 100644 (file)
--- a/doc/src/sgml/ref/truncate.sgml
+++ b/doc/src/sgml/ref/truncate.sgml
@@ -140,23 +140,12 @@ TRUNCATE [ TABLE ] [ ONLY ] name [
    that were added due to cascading).
   
 
-  
-   
-    TRUNCATE is not MVCC-safe (see 
-     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 — any
-     transaction that has done so would hold at least an
-     ACCESS SHARE lock, which would block
-     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.
-   
-  
+  
+   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  for more details.
+  
 
   
    TRUNCATE is transaction-safe with respect to the data