docs: add warning about error messages raised randomly in pipeline mode

Close #266

diff --git a/docs/advanced/pipeline.rst b/docs/advanced/pipeline.rst
index b151557a22af80fa79daf893b14ad9ef2bd66075..b1a0b0e33086e73eba85dd7387788d34dc44eb18 100644 (file)
--- a/docs/advanced/pipeline.rst
+++ b/docs/advanced/pipeline.rst
@@ -285,6 +285,18 @@ because:
 - the statement ``four`` is executed with
   success after the Sync has terminated the failed transaction.
 
+.. warning::
+
+    The exact Python statement where the exception is raised is somewhat
+    arbitrary: it depends on when the server returns the error message. In the
+    above example, the `!execute()` of the statement ``two`` is not the one
+    expected to raise the exception. The exception might be raised by the
+    `!sync()`, or when leaving the `!Pipeline` block.
+
+    Do not rely on expectations of a precise point where the exception is
+    raised; make sure to use transactions if you want to guarantee that a set
+    of statements is handled atomically by the server.
+
 
 The fine prints
 ---------------