Deploying to master from @ psycopg/psycopg-website@5b007f0 🚀

psycopg3/docs/_sources/advanced/prepare.rst.txt

@@ -48,10 +48,34 @@ Statement preparation can be controlled in several ways:
 
     .. __: https://www.postgresql.org/docs/current/sql-prepare.html
 
+
+.. _pgbouncer:
+
+Using prepared statements with PgBouncer
+----------------------------------------
+
 .. warning::
 
-    Using external connection poolers, such as PgBouncer, is not compatible
-    with prepared statements, because the same client connection may change
-    the server session it refers to. If such middleware is used you should
-    disable prepared statements, by setting the `Connection.prepare_threshold`
-    attribute to `!None`.
+    Unless a connection pooling middleware explicitly declares otherwise, they
+    are not compatible with prepared statements, because the same client
+    connection may change the server session it refers to. If such middleware
+    is used you should disable prepared statements, by setting the
+    `Connection.prepare_threshold` attribute to `!None`.
+
+Starting from 3.2, Psycopg supports prepared statements when using the
+PgBouncer__ middleware, using the following caveats:
+
+- PgBouncer version must be at least version `1.22`__.
+- PgBouncer `max_prepared_statements`__ must be greater than 0.
+- The libpq version on the client must be from PostgreSQL 17 or higher.
+
+.. __: https://www.pgbouncer.org/
+.. __: https://www.pgbouncer.org/2024/01/pgbouncer-1-22-0
+.. __: https://www.pgbouncer.org/config.html#max_prepared_statements
+
+.. hint::
+
+    If libpq 17 is not available on your client, but PgBouncer is 1.22 or
+    higher, you can still use Psycopg *as long as you disable deallocation*.
+
+    You can do so by setting `Connection.prepared_max` to `!None`.

psycopg3/docs/_sources/api/connections.rst.txt

@@ -273,8 +273,15 @@ The `!Connection` class
 
         If more queries need to be prepared, old ones are deallocated__.
 
+        Specifying `!None` can be useful for middleware that don't support
+        deallocation; see :ref:`prepared statements notes <pgbouncer>`.
+
         .. __: https://www.postgresql.org/docs/current/sql-deallocate.html
 
+        .. versionchanged:: 3.2
+
+            Added support for the `!None` value.
+
 
     .. rubric:: Methods you can use to do something cool
 

psycopg3/docs/_sources/news.rst.txt

@@ -20,6 +20,8 @@ Psycopg 3.2 (unreleased)
 - Add :ref:`raw-query-cursors` to execute queries using placeholders in
   PostgreSQL format (`$1`, `$2`...) (:ticket:`#560`).
 - Add `~rows.scalar_row` to return scalar values from a query (:ticket:`#723`).
+- Prepared statements are now :ref:`compatible with PgBouncer <pgbouncer>`.
+  (:ticket:`#589`).
 - Add `~Connection.set_autocommit()` on sync connections, and similar
   transaction control methods available on the async connections.
 - Add support for libpq functions to close prepared statements and portals

psycopg3/docs/advanced/index.html

@@ -303,7 +303,10 @@
 <li class="toctree-l2"><a class="reference internal" href="adapt.html#dumpers-and-loaders-life-cycle">Dumpers and loaders life cycle</a></li>
 </ul>
 </li>
-<li class="toctree-l1"><a class="reference internal" href="prepare.html">Prepared statements</a></li>
+<li class="toctree-l1"><a class="reference internal" href="prepare.html">Prepared statements</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="prepare.html#using-prepared-statements-with-pgbouncer">Using prepared statements with PgBouncer</a></li>
+</ul>
+</li>
 <li class="toctree-l1"><a class="reference internal" href="pipeline.html">Pipeline mode support</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="pipeline.html#client-server-messages-flow">Client-server messages flow</a></li>
 <li class="toctree-l2"><a class="reference internal" href="pipeline.html#pipeline-mode-usage">Pipeline mode usage</a></li>

psycopg3/docs/advanced/prepare.html

@@ -145,7 +145,7 @@
           <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
         </button>
       </div>
-      <label class="toc-overlay-icon toc-header-icon no-toc" for="__toc">
+      <label class="toc-overlay-icon toc-header-icon" for="__toc">
         <div class="visually-hidden">Toggle table of contents sidebar</div>
         <i class="icon"><svg><use href="#svg-toc"></use></svg></i>
       </label>
@@ -242,7 +242,7 @@
               <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
             </button>
           </div>
-          <label class="toc-overlay-icon toc-content-icon no-toc" for="__toc">
+          <label class="toc-overlay-icon toc-content-icon" for="__toc">
             <div class="visually-hidden">Toggle table of contents sidebar</div>
             <i class="icon"><svg><use href="#svg-toc"></use></svg></i>
           </label>
@@ -283,14 +283,30 @@
 <code class="sql docutils literal notranslate"><span class="pre">PREPARE</span></code> and <code class="sql docutils literal notranslate"><span class="pre">EXECUTE</span></code>, but protocol level commands such as the
 ones exposed by <code class="docutils literal notranslate"><a class="reference external" href="https://www.postgresql.org/docs/14/libpq-async.html#LIBPQ-PQSENDPREPARE"><span class="pre">PQsendPrepare</span></a></code>, <code class="docutils literal notranslate"><a class="reference external" href="https://www.postgresql.org/docs/14/libpq-async.html#LIBPQ-PQSENDQUERYPREPARED"><span class="pre">PQsendQueryPrepared</span></a></code>.</p>
 </div>
+<section id="using-prepared-statements-with-pgbouncer">
+<span id="pgbouncer"></span><h2>Using prepared statements with PgBouncer<a class="headerlink" href="#using-prepared-statements-with-pgbouncer" title="Permalink to this heading">#</a></h2>
 <div class="admonition warning">
 <p class="admonition-title">Warning</p>
-<p>Using external connection poolers, such as PgBouncer, is not compatible
-with prepared statements, because the same client connection may change
-the server session it refers to. If such middleware is used you should
-disable prepared statements, by setting the <a class="reference internal" href="../api/connections.html#psycopg.Connection.prepare_threshold" title="psycopg.Connection.prepare_threshold"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Connection.prepare_threshold</span></code></a>
-attribute to <code class="xref py py-obj docutils literal notranslate"><span class="pre">None</span></code>.</p>
+<p>Unless a connection pooling middleware explicitly declares otherwise, they
+are not compatible with prepared statements, because the same client
+connection may change the server session it refers to. If such middleware
+is used you should disable prepared statements, by setting the
+<a class="reference internal" href="../api/connections.html#psycopg.Connection.prepare_threshold" title="psycopg.Connection.prepare_threshold"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Connection.prepare_threshold</span></code></a> attribute to <code class="xref py py-obj docutils literal notranslate"><span class="pre">None</span></code>.</p>
 </div>
+<p>Starting from 3.2, Psycopg supports prepared statements when using the
+<a class="reference external" href="https://www.pgbouncer.org/">PgBouncer</a> middleware, using the following caveats:</p>
+<ul class="simple">
+<li><p>PgBouncer version must be at least version <a class="reference external" href="https://www.pgbouncer.org/2024/01/pgbouncer-1-22-0">1.22</a>.</p></li>
+<li><p>PgBouncer <a class="reference external" href="https://www.pgbouncer.org/config.html#max_prepared_statements">max_prepared_statements</a> must be greater than 0.</p></li>
+<li><p>The libpq version on the client must be from PostgreSQL 17 or higher.</p></li>
+</ul>
+<div class="admonition hint">
+<p class="admonition-title">Hint</p>
+<p>If libpq 17 is not available on your client, but PgBouncer is 1.22 or
+higher, you can still use Psycopg <em>as long as you disable deallocation</em>.</p>
+<p>You can do so by setting <a class="reference internal" href="../api/connections.html#psycopg.Connection.prepared_max" title="psycopg.Connection.prepared_max"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Connection.prepared_max</span></code></a> to <code class="xref py py-obj docutils literal notranslate"><span class="pre">None</span></code>.</p>
+</div>
+</section>
 </section>
 
         </article>
@@ -337,9 +353,28 @@
 
       </footer>
     </div>
-    <aside class="toc-drawer no-toc">
+    <aside class="toc-drawer">
 
 
+      <div class="toc-sticky toc-scroll">
+        <div class="toc-title-container">
+          <span class="toc-title">
+            Contents
+          </span>
+        </div>
+        <div class="toc-tree-container">
+          <div class="toc-tree">
+            <ul>
+<li><a class="reference internal" href="#">Prepared statements</a><ul>
+<li><a class="reference internal" href="#using-prepared-statements-with-pgbouncer">Using prepared statements with PgBouncer</a></li>
+</ul>
+</li>
+</ul>
+
+          </div>
+        </div>
+      </div>
+
 
     </aside>
   </div>

psycopg3/docs/api/connections.html

@@ -612,8 +612,14 @@ <h2>The <code class="xref py py-obj docutils literal notranslate"><span class="p
 <dt class="sig sig-object py" id="psycopg.Connection.prepared_max">
 <span class="sig-name descname"><span class="pre">prepared_max</span></span><a class="headerlink" href="#psycopg.Connection.prepared_max" title="Permalink to this definition">#</a></dt>
 <dd><p>Maximum number of prepared statements on the connection.</p>
-<p>Default value: 100</p>
+<p><code class="xref py py-obj docutils literal notranslate"><span class="pre">None</span></code> means no max number of prepared statements. The default value
+is 100.</p>
 <p>If more queries need to be prepared, old ones are <a class="reference external" href="https://www.postgresql.org/docs/current/sql-deallocate.html">deallocated</a>.</p>
+<p>Specifying <code class="xref py py-obj docutils literal notranslate"><span class="pre">None</span></code> can be useful for middleware that don’t support
+deallocation; see <a class="reference internal" href="../advanced/prepare.html#pgbouncer"><span class="std std-ref">prepared statements notes</span></a>.</p>
+<div class="versionchanged">
+<p><span class="versionmodified changed">Changed in version 3.2: </span>Added support for the <code class="xref py py-obj docutils literal notranslate"><span class="pre">None</span></code> value.</p>
+</div>
 </dd></dl>
 
 <p class="rubric">Methods you can use to do something cool</p>

psycopg3/docs/news.html

@@ -262,6 +262,8 @@ <h3>Psycopg 3.2 (unreleased)<a class="headerlink" href="#psycopg-3-2-unreleased"
 <li><p>Add <a class="reference internal" href="advanced/cursors.html#raw-query-cursors"><span class="std std-ref">Raw query cursors</span></a> to execute queries using placeholders in
 PostgreSQL format (<code class="xref py py-obj docutils literal notranslate"><span class="pre">$1</span></code>, <code class="xref py py-obj docutils literal notranslate"><span class="pre">$2</span></code>…) (ticket <a class="reference external" href="https://github.com/psycopg/psycopg/issues/560">#560</a>).</p></li>
 <li><p>Add <a class="reference internal" href="api/rows.html#psycopg.rows.scalar_row" title="psycopg.rows.scalar_row"><code class="xref py py-obj docutils literal notranslate"><span class="pre">scalar_row</span></code></a> to return scalar values from a query (ticket <a class="reference external" href="https://github.com/psycopg/psycopg/issues/723">#723</a>).</p></li>
+<li><p>Prepared statements are now <a class="reference internal" href="advanced/prepare.html#pgbouncer"><span class="std std-ref">compatible with PgBouncer</span></a>.
+(ticket <a class="reference external" href="https://github.com/psycopg/psycopg/issues/589">#589</a>).</p></li>
 <li><p>Add <a class="reference internal" href="api/connections.html#psycopg.Connection.set_autocommit" title="psycopg.Connection.set_autocommit"><code class="xref py py-obj docutils literal notranslate"><span class="pre">set_autocommit()</span></code></a> on sync connections, and similar
 transaction control methods available on the async connections.</p></li>
 <li><p>Add support for libpq functions to close prepared statements and portals