From 1bfe97e5a89fea0994a9c5d428b08cd7c3d63c3b Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Sat, 17 May 2008 23:36:27 +0000
Subject: [PATCH] Rewrite the warning about non-transaction-safety of TRUNCATE
... RESTART IDENTITY to be more explicit about the possible hazards. Per
gripe from Neil and subsequent discussion. Eventually we may be able to get
rid of this warning, but for now it had better be there.
---
doc/src/sgml/ref/truncate.sgml | 27 +++++++++++++++++++++------
1 file changed, 21 insertions(+), 6 deletions(-)
diff --git a/doc/src/sgml/ref/truncate.sgml b/doc/src/sgml/ref/truncate.sgml
index effe903b099..152b6640d8f 100644
--- a/doc/src/sgml/ref/truncate.sgml
+++ b/doc/src/sgml/ref/truncate.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/truncate.sgml,v 1.26 2008/05/16 23:36:04 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/truncate.sgml,v 1.27 2008/05/17 23:36:27 tgl Exp $
PostgreSQL documentation
-->
@@ -151,11 +151,26 @@ TRUNCATE [ TABLE ] <replaceable class="PARAMETER">name</replaceable> [, ... ]
<para>
Any <command>ALTER SEQUENCE RESTART</> operations performed as a
consequence of using the <literal>RESTART IDENTITY</> option are
- nontransactional and will not be rolled back. To minimize risk,
- these operations are performed only after all the rest of
- <command>TRUNCATE</>'s work is done. In practice this will only
- be an issue if <command>TRUNCATE</> is performed inside a
- transaction block that is aborted afterwards.
+ nontransactional and will not be rolled back on failure. To minimize
+ the risk, these operations are performed only after all the rest of
+ <command>TRUNCATE</>'s work is done. However, there is still a risk
+ if <command>TRUNCATE</> is performed inside a transaction block that is
+ aborted afterwards. For example, consider
+
+<programlisting>
+BEGIN;
+TRUNCATE TABLE foo RESTART IDENTITY;
+COPY foo FROM ...;
+COMMIT;
+</programlisting>
+
+ If the <command>COPY</> fails partway through, the table data
+ rolls back correctly, but the sequences will be left with values
+ that are probably smaller than they had before, possibly leading
+ to duplicate-key failures or other problems in later transactions.
+ If this is likely to be a problem, it's best to avoid using
+ <literal>RESTART IDENTITY</>, and accept that the new contents of
+ the table will have higher serial numbers than the old.
</para>
</warning>
</refsect1>
--
GitLab