docs: improve docs about query protocols and PgBouncer

diff --git a/docs/advanced/cursors.rst b/docs/advanced/cursors.rst
index fd4191c80203c6ecc07676e3eb15ea1eb911d2e5..40e4a4222ad3945c22884e8a3e4c1bc4757ba044 100644 (file)
--- a/docs/advanced/cursors.rst
+++ b/docs/advanced/cursors.rst
@@ -126,22 +126,6 @@ as argument.
     cur = psycopg.ClientCursor(conn)
 
 
-You can also use `~ClientCursor` with autocommit mode to disable Extended
-Query Protocol and use Simple Query Protocol instead. This is useful for
-example when issuing `SHOW STATS` to a `pgbouncer` for example, since the
-`Pgbouncer Admin Console  <https://www.pgbouncer.org/usage.html#admin-console>`_
-only support Simple Query Protocol.
-
-.. code:: python
-
-    from psycopg import connect, ClientCursor
-
-    conn = psycopg.connect(DSN, cursor_factory=ClientCursor, autocommit=True)
-    cur = conn.cursor()
-    cur.execute("SHOW STATS")
-    cur.fetchall()
-
-
 .. warning::
 
     Client-side cursors don't support :ref:`binary parameters and return
@@ -159,6 +143,51 @@ only support Simple Query Protocol.
     to parametrize tables and fields names too, or entirely generic SQL
     snippets.
 
+
+.. index::
+    single: PgBouncer
+    double: Query protocol; simple
+
+.. _simple-query-protocol:
+
+Simple query protocol
+^^^^^^^^^^^^^^^^^^^^^
+
+Using the `!ClientCursor` should ensure that psycopg will always use the
+`simple query protocol`__ for querying. In most cases, the choice of the
+fronted/backend protocol used is transparent on PostgreSQL. However, in some
+case using the simple query protocol is mandatory. This is the case querying
+the `PgBouncer admin console`__ for instance, which doesn't support the
+extended query protocol.
+
+.. __: https://www.postgresql.org/docs/current/protocol-flow.html#PROTOCOL-FLOW-SIMPLE-QUERY
+.. __: https://www.pgbouncer.org/usage.html#admin-console
+
+.. code:: python
+
+    from psycopg import connect, ClientCursor
+
+    conn = psycopg.connect(ADMIN_DSN, cursor_factory=ClientCursor)
+    cur = conn.cursor()
+    cur.execute("SHOW STATS")
+    cur.fetchall()
+
+.. versionchanged:: 3.1.20
+    While querying using the `!ClientCursor` works well with PgBouncer, the
+    connection's COMMIT and ROLLBACK commands are only ensured to be executed
+    using the simple query protocol starting from Psycopg 3.1.20.
+
+    In previous versions you should use an autocommit connection in order to
+    query the PgBouncer admin console:
+
+    .. code:: python
+
+        from psycopg import connect, ClientCursor
+
+        conn = psycopg.connect(ADMIN_DSN, cursor_factory=ClientCursor, autocommit=True)
+        ...
+
+
 .. index::
     double: Cursor; Server-side
     single: Portal

diff --git a/docs/basic/from_pg2.rst b/docs/basic/from_pg2.rst
index c449c10319b73f251bed05882e5aa117c1079f18..6f5e375afc908926502847836e3405a976c169a2 100644 (file)
--- a/docs/basic/from_pg2.rst
+++ b/docs/basic/from_pg2.rst
@@ -98,6 +98,27 @@ use the `psycopg.sql` module::
     ...     .format(sql.Identifier(username), password))
 
 
+.. index::
+    single: PgBouncer
+    double: Query protocol; advanced
+
+.. _advanced-query-protocol:
+
+Extended query Protocol
+-----------------------
+
+In order to use :ref:`server-side-binding`, psycopg normally uses the
+`extended query protocol`__ to communicate with the backend.
+
+In certain context outside pure PostgreSQL, the extended query protocol is not
+supported, for instance to query the `PgBouncer admin console`__. In this case
+you should probably use a `ClientCursor`. See :ref:`simple-query-protocol` for
+details.
+
+.. __: https://www.postgresql.org/docs/current/protocol-flow.html#PROTOCOL-FLOW-EXT-QUERY
+.. __: https://www.pgbouncer.org/usage.html#admin-console
+
+
 .. _multi-statements:
 
 Multiple statements in the same query