diff --git a/admin.rst b/admin.rst index 03b7579c1..4a1c7ab26 100644 --- a/admin.rst +++ b/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 ` 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 ========= diff --git a/configuration.rst b/configuration.rst index b6b9db3d6..066b117be 100644 --- a/configuration.rst +++ b/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 ` for more information. + .. _db-tx-end: db-tx-end diff --git a/postgrest.dict b/postgrest.dict index 6d86f45b2..7c3644939 100644 --- a/postgrest.dict +++ b/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 diff --git a/releases/upcoming.rst b/releases/upcoming.rst index 4a8f35688..d35310ceb 100644 --- a/releases/upcoming.rst +++ b/releases/upcoming.rst @@ -16,12 +16,18 @@ Added * Allow :ref:`s_procs_variadic`. |br| -- `@wolfgangwalther `_ +* Allow :ref:`connection_poolers` such as PgBouncer in transaction pooling mode. + |br| -- `@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 `_ * Config option for logging level. See :ref:`log-level`. |br| -- `@steve-chavez `_ +* Config option for enabling or disabling prepared statements. See :ref:`db-prepared-statements`. + |br| -- `@steve-chavez `_ + * Config option for specifying how to terminate the transactions (allowing rollbacks, useful for testing). See :ref:`db-tx-end`. |br| -- `@wolfgangwalther `_