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 a8d2a4ee6eda33a736e7152427df329bc7d88a03..dfa5c3f21b3309a2563f1bcecc381473cbd85352 100644 (file)
--- 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