From fb59b82c35af874400ff478639d31f9dfca23384 Mon Sep 17 00:00:00 2001 From: steve-chavez Date: Wed, 7 Jun 2023 13:43:23 -0500 Subject: [PATCH] references: updated automatic recovery * use bullets were possible and join paragraphs. * add bug fixes to the unreleased page --- docs/references/connection_pool.rst | 47 ++++++++++++++--------------- docs/releases/unreleased.rst | 6 ++-- postgrest.dict | 2 ++ 3 files changed, 28 insertions(+), 27 deletions(-) diff --git a/docs/references/connection_pool.rst b/docs/references/connection_pool.rst index fbccccaa7..a196ee689 100644 --- a/docs/references/connection_pool.rst +++ b/docs/references/connection_pool.rst @@ -3,22 +3,20 @@ Connection Pool =============== -Every request to an :doc:`API resource ` borrows a connection from the connection pool to start a :doc:`transaction `. - -A connection pool is a cache of reusable database connections. It allows serving many HTTP requests using few database connections. +A connection pool is a cache of reusable database connections. It allows serving many HTTP requests using few database connections. Every request to an :doc:`API resource ` borrows a connection from the pool to start a :doc:`transaction `. 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: Dynamic Connection Pool ----------------------- -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. +To conserve 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. -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. +- If all the connections are being used, a new connection is added. 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 released. Connection lifetime ------------------- @@ -27,8 +25,7 @@ Long-lived PostgreSQL connections can consume considerable memory(see `here `. + - Reduce write requests. Do :ref:`bulk_insert` (or :ref:`upsert`) instead of inserting rows one by one. + - Reduce read requests. Use :ref:`resource_embedding`. Combine unrelated data into a single request using custom database views or functions. + - Use :ref:`s_procs` for combining read and write logic into a single request. - - Not a panacea since connections can't grow infinitely. Try the previous recommendations before this. + - Increase the :ref:`db-pool` size. + + - Not a panacea since connections can't grow infinitely. Try the previous recommendations before this. .. _automatic_recovery: Automatic Recovery ------------------ -If the pool loses the connection to the database, it will retry reconnecting using exponential backoff. With 32 seconds being the maximum backoff time between retries. +The server will retry reconnecting to the database if connection loss happens. -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` 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. +- It will retry forever with exponential backoff. 32 seconds being the maximum backoff time between retries. Each of these attempts are :ref:`logged `. +- It will only stop retrying if the server deems the error to be fatal. This can be a password authentication failure or an internal error. +- 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. +- To ensure a valid state, 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. .. _external_connection_poolers: diff --git a/docs/releases/unreleased.rst b/docs/releases/unreleased.rst index 48e4ed895..1044e92d8 100644 --- a/docs/releases/unreleased.rst +++ b/docs/releases/unreleased.rst @@ -14,12 +14,12 @@ Configuration - New :ref:`in_db_config`. It no longer requires high privileges and can be used on cloud-hosted databases. -Documentation improvements -~~~~~~~~~~~~~~~~~~~~~~~~~~ - Bug fixes --------- +- Fix dropping schema cache reload notifications. +- Stop automatic recovery when the error is "no password supplied". + Thanks ------ diff --git a/postgrest.dict b/postgrest.dict index fa04fbd50..35bdccaf9 100644 --- a/postgrest.dict +++ b/postgrest.dict @@ -66,6 +66,8 @@ Ibarluzea Inlining inlined Integrations +idletime +IDLETIME ilike imatch io