From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Sat, 6 Apr 2024 20:54:21 +0000 (+0000)
Subject: docs(prepare): add notes about the PgBouncer and prepared statements
X-Git-Tag: 3.2.0~55^2~2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b78dc55356ee0d11abc7c6ed8ae1f86c7e03ce78;p=thirdparty%2Fpsycopg.git

docs(prepare): add notes about the PgBouncer and prepared statements
---

diff --git a/docs/advanced/prepare.rst b/docs/advanced/prepare.rst
index e41bcae23..752dd0f4d 100644
--- a/docs/advanced/prepare.rst
+++ b/docs/advanced/prepare.rst
@@ -50,8 +50,30 @@ Statement preparation can be controlled in several ways:
 
 .. 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`.
+
+
+.. _pgbouncer:
+
+Using prepared statements with PgBouncer
+----------------------------------------
+
+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`__.
+- 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
+
+.. 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 `!sys.maxsize`.
diff --git a/docs/news.rst b/docs/news.rst
index 59c326cd8..42ca9ecaf 100644
--- a/docs/news.rst
+++ b/docs/news.rst
@@ -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