[PATCH 1 of 3 cubicweb] [doc] document connections pooler

Laurent Peuch cortex at worlddomination.be
Thu Jan 9 00:25:05 CET 2020


# HG changeset patch
# User Laurent Peuch <cortex at worlddomination.be>
# Date 1578522048 -3600
#      Wed Jan 08 23:20:48 2020 +0100
# Node ID bae338fe4e76b1af369590b44bb6d67c66fd8f6a
# Parent  d2c1622e898b763459e895af0f6db6dfd0954140
# Available At https://hg.logilab.org/users/lpeuch/cubicweb
#              hg pull https://hg.logilab.org/users/lpeuch/cubicweb -r bae338fe4e76
[doc] document connections pooler

diff --git a/doc/book/devrepo/connections_pooler.rst b/doc/book/devrepo/connections_pooler.rst
new file mode 100644
--- /dev/null
+++ b/doc/book/devrepo/connections_pooler.rst
@@ -0,0 +1,62 @@
+.. -*- coding: utf-8 -*-
+
+.. _connection_poller:
+
+Source connections pooler
+=========================
+
+*CubicWeb* comes with a connections pool for it's datasource (typically sqlite
+or postgresql), it is a min-max pool meaning that:
+
+* it will keep a minimum number of connections open
+* when load increase it will open new connections until the max number is reached
+* when the load has decreased since some time it will close unused open connections progressively
+* if no connection are available after some time the connections pool will
+  raise, you want to increase the value of `connections-pool-size` if that ever
+  happens, a minimum of 5 is recommended (you'll get a warning otherwise)
+
+Note that the connections pool won't be activated in some "quick start" situations
+like database dump/restore.
+
+Configuration
+-------------
+
+The values used by the connections pool are fully configurable *in your instance
+configuration file* (usually the `all-in-one.conf`), here is the list:
+
+* **connections-pooler-enabled**: enable the connections pooler, default: true
+* **connections-pool-size**: max size of the connections pool. Each source
+  supporting multiple connections will have this maximum number of opened
+  connections, default: 5
+* **min-connections-pool-size**: min size of the connections pool. Each source
+  supporting multiple connections will have this minimum number of opened
+  connections, default: 3
+* **max-connections-pool-timeout**: the delay, in seconds, before failing to get
+  a database connection fails, default: 5.0
+* **min-connections-pool-timeout**: the delay, in seconds, before failing to get
+  a database connection result in opening a new connection if the max number of
+  connections (connections-pool-size) hasn't been reached yet, default: 0.1
+* **connections-pool-low-load-delay**: the delay, in seconds, of low load before
+  the connections pool will start to close open database connections if there
+  are more than the minimum numbers, default: 30
+* **connections-pool-close-delay**: the delay, in seconds, between each
+  connection close when the load is low and there are more open unused
+  connections than the minimum number of open connections
+  (min-connections-pool-size), default: 5
+
+Recommended configuration
+-------------------------
+
+The default configuration of the 3.28 release should be fine for most situation
+but if you have the default configuration for before 3.27 ensure that the
+settings `connections-pool-size` is at least 5 to avoid some deadlock situations.
+
+Here is the default configuration for reference:
+
+* **connections-pooler-enabled**: true
+* **connections-pool-size**: 5
+* **min-connections-pool-size**: 3
+* **max-connections-pool-timeout**: 5.0
+* **min-connections-pool-timeout**: 0.1
+* **connections-pool-low-load-delay**: 30
+* **connections-pool-close-delay**: 5
diff --git a/doc/book/devrepo/index.rst b/doc/book/devrepo/index.rst
--- a/doc/book/devrepo/index.rst
+++ b/doc/book/devrepo/index.rst
@@ -24,3 +24,4 @@ separate layer and has its own whole cha
    fti.rst
    dataimport
    debug_channels
+   connections_pooler



More information about the cubicweb-devel mailing list