Connection pools

Synopsis

Connection pools are used by multiple modules in the server. A connection pool manages connections to an external databases. The management includes setting minimum and maximum numbers for "live" connections, timeouts, etc.

A connection pool is not a module, and cannot be listed in any processing sections. Connection pools do not register any dynamic expansions.

A connection pool is indicated by the use of a sub-section, called pool.

The pool sub-section contains information for the connection pool. The configuration directives below are the same for all modules that use connection pools.

Note

All configuration settings are enforced. If a connection is closed because a idle_timeout, uses, or lifetime limit has been reached, then the total number of connections MAY fall below min. When that happens, a new connection will be opened. A WARNING message may also be logged. The solution is to either lower the value of min, or to increase the value of uses, lifetime and/or idle_timeout.

Example pool configuration

pool {
    start = 1
    min   = 1
    max   = 10
    spare = 2
}

Directives

cleanup_delay

Syntax: cleanup_interval = integer
Default: 30
Description: How often the connection pool is examined for spare connections. If there are any spare connections, only one is deleted. The time for the next sweep of the pool is set to half of cleanup_interval, and the process is repeated. The minimum interval between sweeps is one (1) second.

If a new connection is opened, the sweep interval is reset to cleanup_interval;.

Limits: If cleanup_interval > idle_timeout, the server sets cleanup_interval = idle_timeout.

idle_timeout

Syntax: idle_timeout = integer
Default: 600
Description: How long connections can be idle before they are closed. A connection which is unused (i.e. idle) for idle_timeout seconds will be closed. The special value 0 means never close idle connections.
Limits: If idle_timeout > lifetime, the connections will never be closed due to idle_timeout. In that situation, the server resets idle_timeout = 0.

lifetime

Syntax: lifetime = integer
Default: 86400
Description: How long a connection will live before it is closed. A connection which was created lifetime seconds in the past will be closed. The special value 0 means never close the connections.

max

Syntax: max = integer
Default: ${thread[pool].max_servers}
Description: The maximum number of connections which can be open at the same time.

Setting max to less than the number of threads means that some threads may starve, and the server will produce errors such asNo connections available and at max connection limit+.

Setting max to more than the number of threads means that the server is using more connections than necessary.

Limits: The maximum number of connections is limited to 1024.

min

Syntax: min = integer
Default: 1
Description: The minimum number of connections which will be open at the same time. Connections may be closed for a number of reasons, such as error, or idle_timeout or lifetime limits being reached. However, whenever the numver of open connections falls below min, the server will open one or more new connections.
Limits: The minimum number of connections cannot be greater than the maximum number of connections.

spare

Syntax: spare = integer
Default: 0
Description: The number of spare (i.e. idle) connections to keep open.

Connections may take some time to open. Having spare connections allows the server to respond quickly to sudden increases in traffic.

Limits: The value for spare can be no more than max - min. If spare is set to be larger than this value, it is capped at that value.

start

Syntax: start = integer

Default 1

Description: When the server begins, it creates start number of connections. If it cannot create these connections, pool cannot be initialized, the module using the pool fails to be initialized, and the server refuses to start.
: It is sometimes useful to have the server start even when the back-end database is down or unreachable. Setting start = 0 will tell the server to initialize the pool with no connections. The pool and module initialization will then succeed, and the server will start.
: Any requests received by the server will likely fail, as the back-end database is down. The typical solution is to use the module in a redundant block.
Limits: If start > max, it is capped at max.

uses

Syntax: uses = integer
Default: 0
Description: Allow no more than uses queries through a connection. Once that limit is reached, the connection will be closed, and a new one opened.