Add db-prepared-statements config option

admin.rst

@@ -120,6 +120,19 @@ The burst argument tells Nginx to start dropping requests if more than five queu
 
 Nginx rate limiting is general and indiscriminate. To rate limit each authenticated request individually you will need to add logic in a :ref:`Custom Validation <custom_validation>` function.
 
+.. _connection_poolers:
+
+Using Connection Poolers
+------------------------
+
+In order to increase performance, PostgREST uses prepared statements by default. However, this setting is incompatible with connection poolers such as PgBouncer working in transaction pooling mode. In this case, you need to set the :ref:`db-prepared-statements` config option to ``false``. On the other hand, session pooling is fully compatible with PostgREST, while statement pooling is not compatible at all.
+
+.. note::
+
+  If prepared statements are enabled, PostgREST will quit after detecting that transaction or statement pooling is being used.
+
+You should also set the ``db-channel-enabled`` config option to ``false``, due to the ``LISTEN`` command not being compatible with transaction pooling, although it should not give any errors if it's left enabled by default.
+
 Debugging
 =========
 

configuration.rst

@@ -39,6 +39,7 @@ db-anon-role             String                    Y
 db-pool                  Int     10
 db-pool-timeout          Int     10
 db-extra-search-path     String  public
+db-prepared-statements   Boolean True
 db-tx-end                String  commit
 server-host              String  !4
 server-port              Int     3000
@@ -134,6 +135,17 @@ db-extra-search-path
 
   Multiple schemas can be added in a comma-separated string, e.g. ``public, extensions``.
 
+.. _db-prepared-statements:
+
+db-prepared-statements
+----------------------
+
+  Enables or disables prepared statements.
+
+  When disabled, the generated queries will be parameterized (invulnerable to SQL injection) but they will not be prepared (cached in the database session). Not using prepared statements will noticeably decrease performance, so it's recommended to always have this setting enabled.
+
+  You should only set this to ``false`` when using PostgresSQL behind a connection pooler such as PgBouncer working in transaction pooling mode. See :ref:`this section <connection_poolers>` for more information.
+
 .. _db-tx-end:
 
 db-tx-end

postgrest.dict

@@ -88,6 +88,7 @@ ov
 passphrase
 Pelletier
 Petr
+PgBouncer
 pgcrypto
 pgjwt
 pgSQL
@@ -95,6 +96,7 @@ phfts
 phraseto
 plainto
 plfts
+poolers
 PostGIS
 PostgreSQL
 PostgreSQL's

releases/upcoming.rst

@@ -16,12 +16,18 @@ Added
 * Allow :ref:`s_procs_variadic`.
   |br| -- `@wolfgangwalther <https://github.com/wolfgangwalther>`_
 
+* Allow :ref:`connection_poolers` such as PgBouncer in transaction pooling mode.
+  |br| -- `@laurenceisla <https://github.com/laurenceisla>`_
+
 * Config options for showing a full OpenAPI output regardless of the JWT role privileges and for disabling it altogether. See :ref:`openapi-mode`.
   |br| -- `@steve-chavez <https://github.com/steve-chavez>`_
 
 * Config option for logging level. See :ref:`log-level`.
   |br| -- `@steve-chavez <https://github.com/steve-chavez>`_
 
+* Config option for enabling or disabling prepared statements. See :ref:`db-prepared-statements`.
+  |br| -- `@steve-chavez <https://github.com/steve-chavez>`_
+
 * Config option for specifying how to terminate the transactions (allowing rollbacks, useful for testing). See :ref:`db-tx-end`.
   |br| -- `@wolfgangwalther <https://github.com/wolfgangwalther>`_