Deploying to master from @ psycopg/psycopg-website@bc1ad59 🚀

psycopg · May 17, 2024 · 2504d9e · 2504d9e
1 parent 0f3af36
commit 2504d9e
Show file tree

Hide file tree

Showing 8 changed files with 150 additions and 44 deletions.
diff --git a/psycopg3/docs/_sources/advanced/cursors.rst.txt b/psycopg3/docs/_sources/advanced/cursors.rst.txt
@@ -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/psycopg3/docs/_sources/basic/from_pg2.rst.txt b/psycopg3/docs/_sources/basic/from_pg2.rst.txt
@@ -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

diff --git a/psycopg3/docs/advanced/cursors.html b/psycopg3/docs/advanced/cursors.html
@@ -369,19 +369,6 @@
 <span class="n">cur</span> <span class="o">=</span> <span class="n">psycopg</span><span class="o">.</span><span class="n">ClientCursor</span><span class="p">(</span><span class="n">conn</span><span class="p">)</span>
 </pre></div>
 </div>
-<p>You can also use <a class="reference internal" href="../api/cursors.html#psycopg.ClientCursor" title="psycopg.ClientCursor"><code class="xref py py-obj docutils literal notranslate"><span class="pre">ClientCursor</span></code></a> with autocommit mode to disable Extended
-Query Protocol and use Simple Query Protocol instead. This is useful for
-example when issuing <code class="xref py py-obj docutils literal notranslate"><span class="pre">SHOW</span> <span class="pre">STATS</span></code> to a <code class="xref py py-obj docutils literal notranslate"><span class="pre">pgbouncer</span></code> for example, since the
-<a class="reference external" href="https://www.pgbouncer.org/usage.html#admin-console">Pgbouncer Admin Console</a>
-only support Simple Query Protocol.</p>
-<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">psycopg</span> <span class="kn">import</span> <span class="n">connect</span><span class="p">,</span> <span class="n">ClientCursor</span>
-
-<span class="n">conn</span> <span class="o">=</span> <span class="n">psycopg</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="n">DSN</span><span class="p">,</span> <span class="n">cursor_factory</span><span class="o">=</span><span class="n">ClientCursor</span><span class="p">,</span> <span class="n">autocommit</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
-<span class="n">cur</span> <span class="o">=</span> <span class="n">conn</span><span class="o">.</span><span class="n">cursor</span><span class="p">()</span>
-<span class="n">cur</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s2">&quot;SHOW STATS&quot;</span><span class="p">)</span>
-<span class="n">cur</span><span class="o">.</span><span class="n">fetchall</span><span class="p">()</span>
-</pre></div>
-</div>
 <div class="admonition warning">
 <p class="admonition-title">Warning</p>
 <p>Client-side cursors don’t support <a class="reference internal" href="../basic/params.html#binary-data"><span class="std std-ref">binary parameters and return
@@ -397,9 +384,39 @@
 to parametrize tables and fields names too, or entirely generic SQL
 snippets.</p>
 </div>
+<section id="simple-query-protocol">
+<span id="index-3"></span><span id="id4"></span><h3>Simple query protocol<a class="headerlink" href="#simple-query-protocol" title="Permalink to this heading">#</a></h3>
+<p>Using the <code class="xref py py-obj docutils literal notranslate"><span class="pre">ClientCursor</span></code> should ensure that psycopg will always use the
+<a class="reference external" href="https://www.postgresql.org/docs/current/protocol-flow.html#PROTOCOL-FLOW-SIMPLE-QUERY">simple query protocol</a> 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 <a class="reference external" href="https://www.pgbouncer.org/usage.html#admin-console">PgBouncer admin console</a> for instance, which doesn’t support the
+extended query protocol.</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">psycopg</span> <span class="kn">import</span> <span class="n">connect</span><span class="p">,</span> <span class="n">ClientCursor</span>
+
+<span class="n">conn</span> <span class="o">=</span> <span class="n">psycopg</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="n">ADMIN_DSN</span><span class="p">,</span> <span class="n">cursor_factory</span><span class="o">=</span><span class="n">ClientCursor</span><span class="p">)</span>
+<span class="n">cur</span> <span class="o">=</span> <span class="n">conn</span><span class="o">.</span><span class="n">cursor</span><span class="p">()</span>
+<span class="n">cur</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s2">&quot;SHOW STATS&quot;</span><span class="p">)</span>
+<span class="n">cur</span><span class="o">.</span><span class="n">fetchall</span><span class="p">()</span>
+</pre></div>
+</div>
+<div class="versionchanged">
+<p><span class="versionmodified changed">Changed in version 3.1.20: </span>While querying using the <code class="xref py py-obj docutils literal notranslate"><span class="pre">ClientCursor</span></code> 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.</p>
+<p>In previous versions you should use an autocommit connection in order to
+query the PgBouncer admin console:</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">psycopg</span> <span class="kn">import</span> <span class="n">connect</span><span class="p">,</span> <span class="n">ClientCursor</span>
+
+<span class="n">conn</span> <span class="o">=</span> <span class="n">psycopg</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="n">ADMIN_DSN</span><span class="p">,</span> <span class="n">cursor_factory</span><span class="o">=</span><span class="n">ClientCursor</span><span class="p">,</span> <span class="n">autocommit</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
+<span class="o">...</span>
+</pre></div>
+</div>
+</div>
+</section>
 </section>
 <section id="server-side-cursors">
-<span id="index-3"></span><span id="id4"></span><h2>Server-side cursors<a class="headerlink" href="#server-side-cursors" title="Permalink to this heading">#</a></h2>
+<span id="index-4"></span><span id="id7"></span><h2>Server-side cursors<a class="headerlink" href="#server-side-cursors" title="Permalink to this heading">#</a></h2>
 <p>PostgreSQL has its own concept of <em>cursor</em> too (sometimes also called
 <em>portal</em>). When a database cursor is created, the query is not necessarily
 completely processed: the server might be able to produce results only as they
@@ -457,7 +474,7 @@
 </section>
 </section>
 <section id="raw-query-cursors">
-<span id="id6"></span><h2>Raw query cursors<a class="headerlink" href="#raw-query-cursors" title="Permalink to this heading">#</a></h2>
+<span id="id9"></span><h2>Raw query cursors<a class="headerlink" href="#raw-query-cursors" title="Permalink to this heading">#</a></h2>
 <div class="versionadded">
 <p><span class="versionmodified added">New in version 3.2.</span></p>
 </div>
@@ -554,7 +571,10 @@
             <ul>
 <li><a class="reference internal" href="#">Cursor types</a><ul>
 <li><a class="reference internal" href="#client-side-cursors">Client-side cursors</a></li>
-<li><a class="reference internal" href="#client-side-binding-cursors">Client-side-binding cursors</a></li>
+<li><a class="reference internal" href="#client-side-binding-cursors">Client-side-binding cursors</a><ul>
+<li><a class="reference internal" href="#simple-query-protocol">Simple query protocol</a></li>
+</ul>
+</li>
 <li><a class="reference internal" href="#server-side-cursors">Server-side cursors</a><ul>
 <li><a class="reference internal" href="#stealing-an-existing-cursor">“Stealing” an existing cursor</a></li>
 </ul>

diff --git a/psycopg3/docs/basic/from_pg2.html b/psycopg3/docs/basic/from_pg2.html
@@ -328,6 +328,15 @@
 </pre></div>
 </div>
 </section>
+<section id="extended-query-protocol">
+<span id="advanced-query-protocol"></span><span id="index-1"></span><h2>Extended query Protocol<a class="headerlink" href="#extended-query-protocol" title="Permalink to this heading">#</a></h2>
+<p>In order to use <a class="reference internal" href="#server-side-binding"><span class="std std-ref">Server-side binding</span></a>, psycopg normally uses the
+<a class="reference external" href="https://www.postgresql.org/docs/current/protocol-flow.html#PROTOCOL-FLOW-EXT-QUERY">extended query protocol</a> to communicate with the backend.</p>
+<p>In certain context outside pure PostgreSQL, the extended query protocol is not
+supported, for instance to query the <a class="reference external" href="https://www.pgbouncer.org/usage.html#admin-console">PgBouncer admin console</a>. In this case
+you should probably use a <a class="reference internal" href="../api/cursors.html#psycopg.ClientCursor" title="psycopg.ClientCursor"><code class="xref py py-obj docutils literal notranslate"><span class="pre">ClientCursor</span></code></a>. See <a class="reference internal" href="../advanced/cursors.html#simple-query-protocol"><span class="std std-ref">Simple query protocol</span></a> for
+details.</p>
+</section>
 <section id="multiple-statements-in-the-same-query">
 <span id="multi-statements"></span><h2>Multiple statements in the same query<a class="headerlink" href="#multiple-statements-in-the-same-query" title="Permalink to this heading">#</a></h2>
 <p>As a consequence of using <a class="reference internal" href="#server-side-binding"><span class="std std-ref">server-side bindings</span></a>,
@@ -665,6 +674,7 @@
             <ul>
 <li><a class="reference internal" href="#">Differences from <code class="xref py py-obj docutils literal notranslate"><span class="pre">psycopg2</span></code></a><ul>
 <li><a class="reference internal" href="#server-side-binding">Server-side binding</a></li>
+<li><a class="reference internal" href="#extended-query-protocol">Extended query Protocol</a></li>
 <li><a class="reference internal" href="#multiple-statements-in-the-same-query">Multiple statements in the same query</a></li>
 <li><a class="reference internal" href="#multiple-results-returned-from-multiple-statements">Multiple results returned from multiple statements</a></li>
 <li><a class="reference internal" href="#different-cast-rules">Different cast rules</a></li>

diff --git a/psycopg3/docs/basic/index.html b/psycopg3/docs/basic/index.html
@@ -321,6 +321,7 @@
 </li>
 <li class="toctree-l1"><a class="reference internal" href="from_pg2.html">Differences from <code class="xref py py-obj docutils literal notranslate"><span class="pre">psycopg2</span></code></a><ul>
 <li class="toctree-l2"><a class="reference internal" href="from_pg2.html#server-side-binding">Server-side binding</a></li>
+<li class="toctree-l2"><a class="reference internal" href="from_pg2.html#extended-query-protocol">Extended query Protocol</a></li>
 <li class="toctree-l2"><a class="reference internal" href="from_pg2.html#multiple-statements-in-the-same-query">Multiple statements in the same query</a></li>
 <li class="toctree-l2"><a class="reference internal" href="from_pg2.html#multiple-results-returned-from-multiple-statements">Multiple results returned from multiple statements</a></li>
 <li class="toctree-l2"><a class="reference internal" href="from_pg2.html#different-cast-rules">Different cast rules</a></li>

diff --git a/psycopg3/docs/genindex.html b/psycopg3/docs/genindex.html
@@ -338,14 +338,21 @@ <h2>A</h2>
 </li>
         <li><a href="api/connections.html#psycopg.Connection.add_notify_handler">add_notify_handler() (psycopg.Connection method)</a>
 </li>
+        <li>
+    advanced
+
+        <ul>
+          <li><a href="basic/from_pg2.html#index-1">Query protocol</a>
+</li>
+        </ul></li>
         <li><a href="api/pq.html#psycopg.pq.ConnStatus.ALLOCATED">ALLOCATED (psycopg.pq.ConnStatus attribute)</a>
 </li>
         <li><a href="api/rows.html#psycopg.rows.args_row">args_row() (in module psycopg.rows)</a>
-</li>
-        <li><a href="api/sql.html#psycopg.sql.Composable.as_bytes">as_bytes() (psycopg.sql.Composable method)</a>
 </li>
     </ul></td>
     <td style="width: 33%; vertical-align: top;"><ul>
+        <li><a href="api/sql.html#psycopg.sql.Composable.as_bytes">as_bytes() (psycopg.sql.Composable method)</a>
+</li>
         <li><a href="api/sql.html#psycopg.sql.Composable.as_string">as_string() (psycopg.sql.Composable method)</a>
 </li>
         <li><a href="api/cursors.html#psycopg.AsyncClientCursor">AsyncClientCursor (class in psycopg)</a>
@@ -674,9 +681,9 @@ <h2>C</h2>
 </li>
           <li><a href="advanced/cursors.html#index-1">Client-side</a>
 </li>
-          <li><a href="advanced/cursors.html#index-3">Named</a>
+          <li><a href="advanced/cursors.html#index-4">Named</a>
 </li>
-          <li><a href="advanced/cursors.html#index-3">Server-side</a>
+          <li><a href="advanced/cursors.html#index-4">Server-side</a>
 </li>
         </ul></li>
         <li><a href="api/cursors.html#psycopg.Cursor">Cursor (class in psycopg)</a>
@@ -1270,7 +1277,7 @@ <h2>N</h2>
     Named
 
         <ul>
-          <li><a href="advanced/cursors.html#index-3">Cursor</a>
+          <li><a href="advanced/cursors.html#index-4">Cursor</a>
 </li>
         </ul></li>
         <li>
@@ -1391,6 +1398,8 @@ <h2>P</h2>
         <li><a href="basic/install.html#index-0">PATH</a>
 </li>
         <li><a href="api/objects.html#psycopg.Notify.payload">payload (psycopg.Notify attribute)</a>
+</li>
+        <li><a href="advanced/cursors.html#index-3">PgBouncer</a>, <a href="basic/from_pg2.html#index-1">[1]</a>
 </li>
         <li><a href="api/pq.html#psycopg.pq.PGcancel">PGcancel (class in psycopg.pq)</a>
 </li>
@@ -1457,7 +1466,7 @@ <h2>P</h2>
 </li>
         <li><a href="api/objects.html#psycopg.ConnectionInfo.port">port (psycopg.ConnectionInfo attribute)</a>
 </li>
-        <li><a href="advanced/cursors.html#index-3">Portal</a>
+        <li><a href="advanced/cursors.html#index-4">Portal</a>
 </li>
         <li>
     PostGIS
@@ -1467,11 +1476,11 @@ <h2>P</h2>
 </li>
         </ul></li>
         <li><a href="api/objects.html#psycopg.Column.precision">precision (psycopg.Column attribute)</a>
-</li>
-        <li><a href="api/connections.html#psycopg.Connection.prepare_threshold">prepare_threshold (psycopg.Connection attribute)</a>
 </li>
     </ul></td>
     <td style="width: 33%; vertical-align: top;"><ul>
+        <li><a href="api/connections.html#psycopg.Connection.prepare_threshold">prepare_threshold (psycopg.Connection attribute)</a>
+</li>
         <li><a href="api/objects.html#psycopg.Xid.prepared">prepared (psycopg.Xid attribute)</a>
 </li>
         <li><a href="advanced/prepare.html#index-0">Prepared statements</a>
@@ -1609,6 +1618,15 @@ <h2>Q</h2>
 
         <ul>
           <li><a href="basic/params.html#index-0">Parameters</a>
+</li>
+        </ul></li>
+        <li>
+    Query protocol
+
+        <ul>
+          <li><a href="basic/from_pg2.html#index-1">advanced</a>
+</li>
+          <li><a href="advanced/cursors.html#index-3">simple</a>
 </li>
         </ul></li>
     </ul></td>
@@ -1787,7 +1805,7 @@ <h2>S</h2>
     Server-side
 
         <ul>
-          <li><a href="advanced/cursors.html#index-3">Cursor</a>
+          <li><a href="advanced/cursors.html#index-4">Cursor</a>
 </li>
         </ul></li>
         <li><a href="api/connections.html#psycopg.AsyncConnection.server_cursor_factory">server_cursor_factory (psycopg.AsyncConnection attribute)</a>
@@ -1838,14 +1856,21 @@ <h2>S</h2>
 </li>
         <li><a href="api/errors.html#psycopg.errors.Diagnostic.severity">severity (psycopg.errors.Diagnostic attribute)</a>
 </li>
-    </ul></td>
-    <td style="width: 33%; vertical-align: top;"><ul>
         <li><a href="api/pq.html#psycopg.pq.DiagnosticField.SEVERITY">SEVERITY (psycopg.pq.DiagnosticField attribute)</a>
 </li>
+    </ul></td>
+    <td style="width: 33%; vertical-align: top;"><ul>
         <li><a href="api/errors.html#psycopg.errors.Diagnostic.severity_nonlocalized">severity_nonlocalized (psycopg.errors.Diagnostic attribute)</a>
 </li>
         <li><a href="api/pq.html#psycopg.pq.DiagnosticField.SEVERITY_NONLOCALIZED">SEVERITY_NONLOCALIZED (psycopg.pq.DiagnosticField attribute)</a>
 </li>
+        <li>
+    simple
+
+        <ul>
+          <li><a href="advanced/cursors.html#index-3">Query protocol</a>
+</li>
+        </ul></li>
         <li><a href="api/pq.html#psycopg.pq.ExecStatus.SINGLE_TUPLE">SINGLE_TUPLE (psycopg.pq.ExecStatus attribute)</a>
 </li>
         <li><a href="api/errors.html#psycopg.errors.Diagnostic.source_file">source_file (psycopg.errors.Diagnostic attribute)</a>

diff --git a/psycopg3/docs/objects.inv b/psycopg3/docs/objects.inv
diff --git a/psycopg3/docs/searchindex.js b/psycopg3/docs/searchindex.js