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.

diff --git a/doc/src/sgml/ref/truncate.sgml b/doc/src/sgml/ref/truncate.sgml
index 73a6cee6a3bd6555ad676c3cb4c80f971fc7fa97..4675a1c2864e6a01cad67ea53c8ef567b620c853 100644 (file)
--- a/doc/src/sgml/ref/truncate.sgml
+++ b/doc/src/sgml/ref/truncate.sgml
@@ -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>