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.