references: add dynamic pool

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

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 <https://www.postgresql.org/message-id/CAFj8pRCQN2B2vrVMH1-bd-8xtzjytWR%2BAjZ%2BMCj9J2wPxKPa9Q%40mail.gmail.com>`_ 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:
+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.
-https://www.postgresql.org/message-id/flat/CA%2Bmi_8bnvpxHZtb6EgHSHY-xn29W8VJMzjPU3fiCOv1bfjrNuA%40mail.gmail.com.
 
 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.
 

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
 ~~~~~~~~~~~~~