From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Wed, 9 Apr 2025 14:38:17 +0000 (+0100)
Subject: docs: document multiple statements limitations
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=5c14dd44caaa8758c901de52a62918b611bbb2e7;p=thirdparty%2Fpsycopg.git

docs: document multiple statements limitations

Close #1020.
---

diff --git a/docs/advanced/pipeline.rst b/docs/advanced/pipeline.rst
index cf71e2509..2c7f89247 100644
--- a/docs/advanced/pipeline.rst
+++ b/docs/advanced/pipeline.rst
@@ -200,8 +200,10 @@ synchronization point.
 
     - COPY is not supported in pipeline mode by PostgreSQL.
     - `Cursor.stream()` doesn't make sense in pipeline mode (its job is the
-      opposite of batching!)
+      opposite of batching!).
     - `ServerCursor` are currently not implemented in pipeline mode.
+    - You cannot execute :ref:`multiple statements in the same query
+      <multi-statements>`.
 
 .. note::
 
diff --git a/docs/basic/from_pg2.rst b/docs/basic/from_pg2.rst
index 7fb94d92f..466a6a1fd 100644
--- a/docs/basic/from_pg2.rst
+++ b/docs/basic/from_pg2.rst
@@ -154,6 +154,14 @@ or a :ref:`client-side binding cursor <client-side-binding-cursors>`::
     ...     "INSERT INTO foo VALUES (%s); INSERT INTO foo VALUES (%s)",
     ...     (10, 20))
 
+.. warning::
+
+    You cannot executeA multiple statements in the same query:
+
+    - when retrieving a :ref:`binary result <binary-data>` (such as using
+      ``.execute(..., binary=True)``;
+    - when using the :ref:`pipeline mode <pipeline-mode>`.
+
 .. warning::
 
     If a statement must be executed outside a transaction (such as
diff --git a/docs/basic/params.rst b/docs/basic/params.rst
index a733f0739..0158337f4 100644
--- a/docs/basic/params.rst
+++ b/docs/basic/params.rst
@@ -240,3 +240,8 @@ in the database, such as images::
     cur.execute(
         "SELECT image_data FROM images WHERE id = %s", [image_id], binary=True)
     data = cur.fetchone()[0]
+
+.. warning::
+
+    You cannot execute :ref:`multiple statements in the same query
+    <multi-statements>` when requesting a binary result.