diff options
| -rw-r--r-- | doc/src/sgml/mvcc.sgml | 46 | ||||
| -rw-r--r-- | doc/src/sgml/ref/alter_table.sgml | 19 | ||||
| -rw-r--r-- | doc/src/sgml/ref/truncate.sgml | 23 |
3 files changed, 51 insertions, 37 deletions
diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml index 18b7c6bdd56..5ec5f922a48 100644 --- a/doc/src/sgml/mvcc.sgml +++ b/doc/src/sgml/mvcc.sgml @@ -680,20 +680,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> @@ -1455,6 +1441,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 4e082eaa637..e3e81ba9d76 100644 --- a/doc/src/sgml/ref/alter_table.sgml +++ b/doc/src/sgml/ref/alter_table.sgml @@ -822,7 +822,8 @@ ALTER TABLE <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> @@ -844,11 +845,17 @@ ALTER TABLE <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 7b9c2f30128..5d77e5daec9 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 |