From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Wed, 26 Oct 2022 23:58:04 +0000 (+0200)
Subject: docs: add section about returning multiple results
X-Git-Tag: pool-3.1.4~15
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=6750363451166291b08f717c353b7ef87836d5e5;p=thirdparty%2Fpsycopg.git

docs: add section about returning multiple results

Close #417.
---

diff --git a/docs/basic/from_pg2.rst b/docs/basic/from_pg2.rst
index a029a7529..306cec4d7 100644
--- a/docs/basic/from_pg2.rst
+++ b/docs/basic/from_pg2.rst
@@ -147,6 +147,39 @@ split the queries on semicolons and send them separately). This is not new in
 Psycopg 3: the same limitation is present in `!psycopg2` too.
 
 
+.. _multi-results:
+
+Multiple results returned from multiple statements
+--------------------------------------------------
+
+If more than one statement returning results is executed in psycopg2, only the
+result of the last statement is returned::
+
+    >>> cur_pg2.execute("SELECT 1; SELECT 2")
+    >>> cur_pg2.fetchone()
+    (2,)
+
+In Psycopg 3 instead, all the results are available. After running the query,
+the first result will be readily available in the cursor and can be consumed
+using the usual ``fetch*()`` methods. In order to access the following
+results, you can use the `Cursor.nextset()` method::
+
+    >>> cur_pg3.execute("SELECT 1; SELECT 2")
+    >>> cur_pg3.fetchone()
+    (1,)
+
+    >>> cur_pg3.nextset()
+    True
+    >>> cur_pg3.fetchone()
+    (2,)
+
+    >>> cur_pg3.nextset()
+    None  # no more results
+
+Remember though that you cannot use server-side bindings to :ref:`execute more
+than one statement in the same query <multi-statements>`.
+
+
 .. _difference-cast-rules:
 
 Different cast rules