REDIS Module

The redis module handles connections to a redis database, and the %redis( …) dynamic expansion.

See also https://redis.io/documentation for documentation on the Redis database.

Configuration Settings

This module connects to a Redis database. Other modules (e.g. redis_ippool) perform task-specific functions using Redis.

server: The server to connect to.

If using Redis cluster, multiple 'bootstrap' servers may be listed here (as separate config items). These will be contacted in turn until one provides us with a valid map for the cluster.

Server strings may contain unique ports e.g.:

server = '127.0.0.1:30001'
server = '[::1]:30002'

Instantiation failure behaviour is controlled by pool.start as with every other module, but with clustering, the pool { … } section determines limits for each node in the cluster, not the cluster as a whole.

database: Select the Redis logical database having the specified zero-based numeric index.
port: Port to connect to The default port is 6379.
password: The password used to authenticate to the server.

We recommend using a strong password.

use_tls: Use TLS (requires hiredis 1.0+)

TLS parameters can be specified in the optional adjacent tls {} section

use_cluster_map: Use cluster map

Build cluster map during initialization.

The cluster client can operate, albeit inefficiently, without a cluster map by following '-ASK' and '-MOVE' redirects.

Disabling cluster map can be required for stunnel-based deployments. Alternatively, cluster map is not built during initialization when pool.start == 0

lua { … }: Configuration options which control the execution of lua scripts on redis nodes.
function <name> { … }: Every function section listed here will be registered as an expansion with a name in the format <inst>.<name>.

For example the function below would be callable as %redis.hello_world(…).

expansion functions take the same arguments as the redis EVALSHA command, i.e. <numkeys> [<key> [<key> …]] [<arg> [<arg> …]].

numkeys specifies how many of the proceeding arguments should be treated as keys.

The redis module will use the first key to determine which cluster node the function should called on.

The redis module pre-calcualtes the SHA1 hash of all lua functions on startup. When an expansion function is called, it uses the EVALSHA command to attempt to call lua function on a remote redis node. If EVALSHA fails with an error indicating no script could be found with the calculated SHA1 hash, the lua function will be loaded transparently using SCRIPT LOAD.

body: Lua code to send to redis nodes with SCRIPT LOAD
pool { … }: Information for the connection pool. The configuration items below are the same for all modules which use the new connection pool.
start: Connections to create during module instantiation.

If the server cannot create specified number of connections during instantiation it will exit. Set to 0 to allow the server to start without the external service being available.

min: Minimum number of connections to keep open.
max: Maximum number of connections.

If these connections are all in use and a new one is requested, the request will NOT get a connection.

Setting max to LESS than the number of threads means that some threads may starve, and you will see errors like No connections available and at max connection limit.

Setting max to MORE than the number of threads means that there are more connections than necessary.

If max is not specified, then it defaults to the number of workers configured.

spare: Spare connections to be left idle.

Idle connections WILL be closed if idle_timeout is set. This should be less than or equal to max above.

uses: Number of uses before the connection is closed.

0 means "infinite".

retry_delay: The number of seconds to wait after the server tries to open a connection, and fails.

During this time, no new connections will be opened.

lifetime: The lifetime (in seconds) of the connection.

0 means "infinite".

cleanup_interval: The pool is checked for free connections every cleanup_interval.

If there are free connections, then one of them is closed.

idle_timeout: The idle timeout (in seconds).

A connection which is unused for this length of time will be closed.

0 means "infinite".

connect_timeout: Connection timeout (in seconds).

The maximum amount of time to wait for a new connection to be established.

All configuration settings are enforced. If a connection is closed because of idle_timeout, uses, or lifetime, then the total number of connections MAY fall below min.

When that happens, it will open a new connection. It will also log a WARNING message.

The solution is to either lower the "min" connections, or increase lifetime/idle_timeout.

Default Configuration

redis {
	server = 127.0.0.1
#	database = 0
	port = 6379
#	password = thisisreallysecretandhardtoguess
#	use_tls = no
#	tls { }
#	use_cluster_map = yes
	lua {
		function hello_world {
			body = 'return "hello world"'
		}
	}
	pool {
		start = 0
		min = 0
#		max =
		spare = 1
		uses = 0
		retry_delay = 30
		lifetime = 86400
		cleanup_interval = 300
		idle_timeout = 600
		connect_timeout = 3.0
	}
}