diff --git a/psycopg3/docs/_sources/advanced/prepare.rst.txt b/psycopg3/docs/_sources/advanced/prepare.rst.txt index e41bcae2..25f98a51 100644 --- a/psycopg3/docs/_sources/advanced/prepare.rst.txt +++ b/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`. diff --git a/psycopg3/docs/_sources/api/connections.rst.txt b/psycopg3/docs/_sources/api/connections.rst.txt index 898a8470..11f29a8b 100644 --- a/psycopg3/docs/_sources/api/connections.rst.txt +++ b/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 `. + .. __: 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 diff --git a/psycopg3/docs/_sources/news.rst.txt b/psycopg3/docs/_sources/news.rst.txt index 59c326cd..42ca9eca 100644 --- a/psycopg3/docs/_sources/news.rst.txt +++ b/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 `. + (: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 diff --git a/psycopg3/docs/advanced/index.html b/psycopg3/docs/advanced/index.html index 8b8fe130..07b0d96e 100644 --- a/psycopg3/docs/advanced/index.html +++ b/psycopg3/docs/advanced/index.html @@ -303,7 +303,10 @@
  • Dumpers and loaders life cycle
    • -
  • Prepared statements
    • +
  • Prepared statements +
  • Pipeline mode support
    • Client-server messages flow
    • Pipeline mode usage
      • diff --git a/psycopg3/docs/advanced/prepare.html b/psycopg3/docs/advanced/prepare.html index 009a8b33..cf2fc4ab 100644 --- a/psycopg3/docs/advanced/prepare.html +++ b/psycopg3/docs/advanced/prepare.html @@ -145,7 +145,7 @@ -