Connection

1. Single Instances
2. Connection Strings
3. Secure Connections
4. Clusters
5. Sentinel
6. Replication
7. Relay
8. Valkey, KeyDB, Dragonfly

#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' => '...',
    'path' => '/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:[email protected]: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 connection 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 primary 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',
    ],
    'cluster_failover' => 'error',
]);

For failover, see the cluster_failover configuration option.

#Sentinel

To use Redis Sentinel, provide the Sentinel nodes using the sentinels configuration option as well as the service name. The primaries and replicas will be automatically discovered. Keep your timeouts short (a few hundreds of milliseconds), to allow for fast failovers and reconnections.

Predis, PhpRedis and Relay all handle Sentinel authentication differently. When using PhpRedis as the client the Sentinel nodes must use the same password as the primaries and replicas.

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

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

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

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

#Replication

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

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

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

define('WP_REDIS_CONFIG', [
    'token' => '...',
    'servers' => [
        'tcp://10.0.0.1:6379/?role=primary',
        '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 primary. To change this behavior see the replication_strategy configuration option.

#Relay

For even better performance Object Cache Pro can use the Relay PHP extension, which is tightly integrated.

#Valkey, KeyDB, Dragonfly

Object Cache Pro is fully compatible with popular Redis forks, like Valkey, Dragonfly and KeyDB.

• Dragonfly does not support async_flush