Object Cache Pro

Connection

Single Instances

To connect to a standard Redis instance, use the host and port combination:

define('WP_REDIS_CONFIG', [
'token' => '...',
'host' => '127.0.0.1',
'port' => 6379,
]);

To connect to a unix socket omit the port:

define('WP_REDIS_CONFIG', [
'token' => '...',
'host' => '/var/run/redis/redis-server.sock',
]);

Connection Strings

Heroku, DigitalOcean and other platforms may give you an environment variable with your Redis connection credentials:

REDIS_URL=redis://h:password@127.0.0.1:6379?database=0

You can use the url configuration option to set your host, port and other options:

define('WP_REDIS_CONFIG', [
'token' => '...',
'url' => getenv('REDIS_URL'),
]);

Secure Connections

To establish a secure connecting using TLS, you must use PhpRedis 5.3.0 or newer and can simply prefix the url with tls://.

define('WP_REDIS_CONFIG', [
'token' => '...',
'url' => 'tls://10.0.0.3:6379',
'timeout' => 2.5,
'tls_options' => [
'verify_peer' => true,
],
]);

Ensure that the timeout of the client is set to at least 1.0. Setting the timeout too low can lead to numerous timeouts when the server load is high.

To customize the TLS socket, you may use the tls_options configuration option.

Clusters

To connect to a cluster, provide an array of master nodes using the cluster option:

define('WP_REDIS_CONFIG', [
'token' => '...',
'password' => 'secret',
'cluster' => [
'tcp://172.17.0.1:6379',
'tcp://172.17.0.2:6379',
'tcp://172.17.0.3:6379',
],
]);

For cluster failover / distribution, see the cluster_failover configuration option.

Sentinel

To use a Redis Sentinel, provide the Sentinel nodes using the sentinels configuration option as well as the service name. The masters and replicas will be automatically discovered.

Keep your timeouts short (in the order of a few hundreds of milliseconds), to allow for fast failovers and reconnections.

define('WP_REDIS_CONFIG', [
'token' => '...',

'service' => 'wp-sentinel',
'sentinels' => [
'tcp://10.0.0.1:26379',
'tcp://10.0.0.2:26379',
],

'timeout' => 0.2,
'read_timeout' => 0.2,
'retry_interval' => 50,
]);

By default, read requests are distributed across all replicas as well as the master. To change this behavior see the replication_strategy configuration option.

Replication

To use a replicated master with read-only replicas, provide the master using the servers configuration option to have the replicas automatically discovered:

define('WP_REDIS_CONFIG', [
'token' => '...',
'servers' => [
'tcp://127.0.0.1:7000?role=master',
],
]);

Alternatively, especially when not using autoscaling, provide a list of replicas:

define('WP_REDIS_CONFIG', [
'token' => '...',
'servers' => [
'tcp://10.0.0.1:6379/?role=master',
'tcp://10.0.0.2:6380/?role=replica',
'tcp://10.0.0.3:6381/?role=replica',
],
]);

By default, read requests are distributed across all replicas as well as the master. To change this behavior see the replication_strategy configuration option.

Relay

If the Relay PHP extension is installed on your system, using Object Cache Pro's tight integration is easy.

Twemproxy

To use the built-in Twemproxy support, set the connector configuration option to twemproxy.

define('WP_REDIS_CONFIG', [
'token' => '...',
'host' => '127.0.0.1',
'port' => 6379,
'connector' => 'twemproxy',
]);