From c62d24c993dcd286377f35f4aa02c47b8a811c85 Mon Sep 17 00:00:00 2001 From: steve-chavez Date: Wed, 7 Jun 2023 12:12:38 -0500 Subject: [PATCH] references: add dynamic pool --- docs/references/configuration.rst | 10 ++++++++++ docs/references/connection_pool.rst | 24 +++++++++++++----------- docs/releases/unreleased.rst | 5 +++++ 3 files changed, 28 insertions(+), 11 deletions(-) diff --git a/docs/references/configuration.rst b/docs/references/configuration.rst index bdd382e9e..9b44ac3ab 100644 --- a/docs/references/configuration.rst +++ b/docs/references/configuration.rst @@ -158,6 +158,7 @@ db-extra-search-path String public Y PGRST_DB_EXTRA_ db-max-rows Int ∞ Y PGRST_DB_MAX_ROWS pgrst.db_max_rows db-plan-enabled Boolean False Y PGRST_DB_PLAN_ENABLED pgrst.db_plan_enabled db-pool Int 10 PGRST_DB_POOL +db-pool-max-idletime Int 30 PGRST_DB_POOL_MAX_IDLETIME db-pool-acquisition-timeout Int 10 PGRST_DB_POOL_ACQUISITION_TIMEOUT db-pool-max-lifetime Int 1800 PGRST_DB_POOL_MAX_LIFETIME db-pre-request String Y PGRST_DB_PRE_REQUEST pgrst.db_pre_request @@ -294,6 +295,15 @@ db-pool Number of maximum connections to keep open in PostgREST's database pool. +.. _db-pool-max-idletime: + +db-pool-max-idletime +-------------------- + + *For backwards compatibility, this config parameter is also available as “db-pool-timeout”.* + + Time in seconds to close idle pool connections. + .. _db-pool-acquisition-timeout: db-pool-acquisition-timeout diff --git a/docs/references/connection_pool.rst b/docs/references/connection_pool.rst index 48683b90a..fbccccaa7 100644 --- a/docs/references/connection_pool.rst +++ b/docs/references/connection_pool.rst @@ -9,29 +9,31 @@ A connection pool is a cache of reusable database connections. It allows serving Minimizing connections it’s paramount to performance. Each PostgreSQL connection creates a process, having too many can exhaust available resources. -.. _pool_growth_limit: +.. _dyn_conn_pool: -Growth Limit ------------- +Dynamic Connection Pool +----------------------- -If all the connections are being used, a new connection is added to the pool. The pool can grow until it reaches the :ref:`db-pool` size. +To converve system resources, PostgREST uses a dynamic connection pool. This enables the number of connections in the pool to increase and decrease depending on request traffic. -Note it’s pointless to set this higher than the ``max_connections`` setting in your database. +If all the connections are being used, a new connection is added to the pool. The pool can grow until it reaches the :ref:`db-pool` size. Note it’s pointless to set this higher than the ``max_connections`` setting in your database. + +If a connection is unused for a period of time(determined by :ref:`db-pool-max-idletime`, 30 seconds by default), it will be closed. Connection lifetime ------------------- -After a period of time, connections from the pool will be released and news ones will be created. This time is specified by :ref:`db-pool-max-lifetime`. +Long-lived PostgreSQL connections can consume considerable memory(see `here `_ for more details). +Under a busy system, the :ref:`db-pool-max-idletime` won't be reached and the connection pool can have many long-lived connections. -The lifetime doesn't affect running requests. Only unused connections will be released. +To avoid this problem and save resources, a connection max lifetime(determined by :ref:`db-pool-max-lifetime`, 30 minutes by default) is enforced. -For knowing why a connection lifetime is necessary, see the following discussion: -https://www.postgresql.org/message-id/flat/CA%2Bmi_8bnvpxHZtb6EgHSHY-xn29W8VJMzjPU3fiCOv1bfjrNuA%40mail.gmail.com. +After the max lifetime is reached, connections from the pool will be released and news ones will be created. This doesn't affect running requests. Only unused connections will be released. Acquisition Timeout ------------------- -If all the available connections in the pool are busy, an HTTP request will wait until reaching a timeout. You can configure this timeout with :ref:`db-pool-acquisition-timeout`. +If all the available connections in the pool are busy, an HTTP request will wait until reaching a timeout(determined by :ref:`db-pool-acquisition-timeout`, 10 seconds by default). If the request reaches the timeout, it will be aborted with the following response: @@ -69,7 +71,7 @@ If the pool loses the connection to the database, it will retry reconnecting usi The retries happen immediately after a connection loss, if :ref:`db-channel-enabled` is set to true(the default). Otherwise they'll happen once a request arrives. -The server reloads the :ref:`schema_cache` when recovering. +The server reloads the :ref:`schema_cache` and :ref:`configuration` when recovering. To notify the client of the next retry, the server sends a ``503 Service Unavailable`` status with the ``Retry-After: x`` header. Where ``x`` is the number of seconds programmed for the next retry. diff --git a/docs/releases/unreleased.rst b/docs/releases/unreleased.rst index 8b88fa9ca..48e4ed895 100644 --- a/docs/releases/unreleased.rst +++ b/docs/releases/unreleased.rst @@ -4,6 +4,11 @@ Unreleased Features -------- +Connection Pool +~~~~~~~~~~~~~~~ + +- New :ref:`db-pool-max-idletime`. It enables a :ref:`dyn_conn_pool`. + Configuration ~~~~~~~~~~~~~