From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Wed, 21 Sep 2022 11:46:07 +0000 (+0100)
Subject: docs: add link to document how to recover the stream from ACTIVE state
X-Git-Tag: 3.1.3~14
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=027b18cdd14b7844fe1b3159bf2d9890fdabd5cb;p=thirdparty%2Fpsycopg.git

docs: add link to document how to recover the stream from ACTIVE state

See #382.
---

diff --git a/docs/api/cursors.rst b/docs/api/cursors.rst
index a8d2a4ee6..dfa5c3f21 100644
--- a/docs/api/cursors.rst
+++ b/docs/api/cursors.rst
@@ -148,6 +148,21 @@ The `!Cursor` class
 
         The parameters are the same of `execute()`.
 
+        .. warning::
+
+            Failing to consume the iterator entirely will result in a
+            connection left in `~psycopg.ConnectionInfo.transaction_status`
+            `~pq.TransactionStatus.ACTIVE` state: this connection will refuse
+            to receive further commands (with a messge such as *another
+            command is already in progress*).
+
+            You can restore the connection to a working state by consuming
+            the generator entirely: see `this comment`__ to get a few ideas
+            about how to do it.
+
+            .. __: https://github.com/psycopg/psycopg/issues/382#issuecomment-1253582340
+
+
     .. attribute:: format
 
         The format of the data returned by the queries. It can be selected