docs: document multiple statements limitations

Close #1020.

diff --git a/docs/advanced/pipeline.rst b/docs/advanced/pipeline.rst
index cf71e25091651ce310591a3efcc10a2ea2ab565b..2c7f89247042db65480c5b45d925fddb5a6a9a7a 100644 (file)
--- 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 7fb94d92f540631f8eb865b748019548edf477b9..466a6a1fd8c201af8c7d82c22669554178e4bcd0 100644 (file)
--- 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 a733f0739c804ce7a6ea5d64dd35218e461357e1..0158337f4ca1a8b0f235100ae9f4c3eb69e85cd0 100644 (file)
--- 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.