From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Mon, 9 May 2022 23:21:47 +0000 (+0200)
Subject: docs: suggest to use commit to maintain atomic sanity in pipeline mode
X-Git-Tag: 3.1~113^2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F297%2Fhead;p=thirdparty%2Fpsycopg.git

docs: suggest to use commit to maintain atomic sanity in pipeline mode
---

diff --git a/docs/advanced/pipeline.rst b/docs/advanced/pipeline.rst
index 54bc7f0df..12a7eb187 100644
--- a/docs/advanced/pipeline.rst
+++ b/docs/advanced/pipeline.rst
@@ -251,7 +251,7 @@ only committed when the Sync is received. As such, a failure in a group of
 statements will probably invalidate the effect of statements executed after
 the previous Sync, and will propagate to the following Sync.
 
-For example, the following block:
+For example, in the following block:
 
 .. code:: python
 
@@ -266,8 +266,9 @@ For example, the following block:
     ...             pass
     ...         cur.execute("INSERT INTO mytable (data) VALUES (%s)", ["four"])
 
-fails with the error ``relation "no_such_table" does not exist`` and, at the
-end of the block, the table will contain:
+there will be an error in the block, ``relation "no_such_table" does not
+exist`` caused by the insert ``two``, but probably raised by the `!sync()`
+call. At at the end of the block, the table will contain:
 
 .. code:: text
 
@@ -290,15 +291,15 @@ because:
 
 .. 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.
+    The exact Python statement where an exception caused by a server error is
+    raised is somewhat arbitrary: it depends on when the server flushes its
+    buffered result.
 
-    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.
+    If you want to make sure that a group of statements is applied atomically
+    by the server, do make use of transaction methods such as
+    `~Connection.commit()` or `~Connection.transaction()`: these methods will
+    also sync the pipeline and raise an exception if there was any error in
+    the commands executed so far.
 
 
 The fine prints