summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorTom Lane2015-08-15 17:30:16 +0000
committerTom Lane2015-08-15 17:30:16 +0000
commitec2bc39e8910d05e27794e5095b7b8daed981406 (patch)
tree193aec3b4834ef26527e4dc54cf081f72fe077cd
parent9d6af7367e7b079c021c285f03128bad531b667e (diff)
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.
-rw-r--r--doc/src/sgml/mvcc.sgml20
-rw-r--r--doc/src/sgml/ref/alter_table.sgml10
-rw-r--r--doc/src/sgml/ref/truncate.sgml23
3 files changed, 35 insertions, 18 deletions
diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml
index 341351e46ff..040b29c1453 100644
--- a/doc/src/sgml/mvcc.sgml
+++ b/doc/src/sgml/mvcc.sgml
@@ -1181,6 +1181,26 @@ SELECT pg_advisory_lock(q.id) FROM
</para>
</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>
+ </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 94343f88f6e..91f26f0d584 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -699,7 +699,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>
@@ -736,6 +737,13 @@ ALTER TABLE table ALTER COLUMN anycol TYPE anytype;
</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>
The <literal>USING</literal> option of <literal>SET DATA TYPE</> can actually
specify any expression involving the old values of the row; that is, it
can refer to other columns as well as the one being converted. This allows
diff --git a/doc/src/sgml/ref/truncate.sgml b/doc/src/sgml/ref/truncate.sgml
index 99202de5b49..2f1fafc6547 100644
--- a/doc/src/sgml/ref/truncate.sgml
+++ b/doc/src/sgml/ref/truncate.sgml
@@ -137,23 +137,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