diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml
index dfece8a9f713dfb95a9691a8d214751472793c14..2c7a03d092593bf5ed590bc06a9ca2131bccad9f 100644
--- a/doc/src/sgml/mvcc.sgml
+++ b/doc/src/sgml/mvcc.sgml
@@ -708,20 +708,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>
@@ -1618,6 +1604,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 — 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>
diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 0e7b99c934cc68db1a7251959ce2d3b9a9e08076..8ef0cabe77ecd129839e1da0884b6bf4c7792e0d 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -623,7 +623,7 @@ ALTER TABLE ALL IN TABLESPACE <replaceable class="PARAMETER">name</replaceable>
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. <literal>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. <literal>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
@@ -915,7 +915,8 @@ ALTER TABLE ALL IN TABLESPACE <replaceable class="PARAMETER">name</replaceable>
<para>
Adding a <literal>CHECK</> or <literal>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.
</para>
<para>
@@ -937,11 +938,17 @@ ALTER TABLE ALL IN TABLESPACE <replaceable class="PARAMETER">name</replaceable>
</para>
<para>
- To force an immediate rewrite of the table, you can use
- <link linkend="SQL-VACUUM">VACUUM FULL</>, <xref linkend="SQL-CLUSTER">
- 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 <command>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.
+ </para>
+
+ <para>
+ The rewriting forms of <command>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 <xref linkend="mvcc-caveats"> for more details.
</para>
<para>
diff --git a/doc/src/sgml/ref/truncate.sgml b/doc/src/sgml/ref/truncate.sgml
index 87516c9cc365dc6054cd9e36b4226d37c433fa6e..b06ed78990269edf861631de7090dbf98f6165c3 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 — 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