Redis Cluster (3.x)

❗️Documentation page for lettuce 3.x. Find the recent documentation for lettuce 4.x here: Redis Cluster

---

lettuce has a dedicated client for Redis Cluster (since 3.0)

The clustering support covers:

• Support of all CLUSTER commands
• Command routing based on the hash slot of the commands' key
• MOVED and ASK redirection handling
• Obtaining direct connections to cluster nodes by slot and host/port (since 3.3)
• Node authentication
• Regular cluster topology updates

Connecting to a Redis Cluster requires one or more initial nodes. The initial cluster topology view (partitions) is obtained on the first connection. Lettuce holds multiple connections, which are opened on demand. You are free to operate on these connections. Connections can be bound to specific hosts or nodeIds. Connections bound to a nodeId will always stick to the nodeId, even if the nodeId is handled by a different host. Requests to unknown nodeId's or host/ports that are not part of the cluster are rejected. Do not close the connections. Otherwise, unpredictable behavior will occur. Keep also in mind that the node connections are used by the cluster connection itself to perform cluster operations: If you block one connection all other users of the cluster connection might be affected.

Command routing

The concept of Redis Cluster bases on sharding. Every master node within the cluster handles one or more slots. Slots are the unit of sharding and calculated from the commands' key using CRC16 MOD 16384. Hash slots can also be specified using hash tags such as {user:1000}.foo.

Every request, which incorporates at least one key is routed based on its hash slot to the corresponding node. Commands without a key are executed on the default connection that points most likely to the first provided RedisURI. The same rule applies to commands operating on multiple keys but with the limitation that all keys have to be on the same slot. Commands operating on multiple slots will be terminated with a CROSSSLOT error.

Refreshing the cluster topology view

The Redis Cluster configuration may change at runtime. New nodes can be added, the master for a specific slot can change. Lettuce handles MOVED and ASK redirects transparently but in case too many commands run into redirects, you should refresh the cluster topology view. The topology is bound to a RedisClusterClient instance. All cluster connections that are created by one RedisClusterClient instance share the same cluster topology view. The view can be updated in two ways:

1. Either by calling RedisClusterClient.reloadPartitions
2. Regular updates in the background.

By default, commands are executed up to 5 times (up to 4 redirects) until the command execution is considered to be failed.

Client-options

See Cluster-specific Client options

Examples

Connecting to a Redis Cluster

RedisURI redisUri = RedisURI.Builder.redis("localhost").withPassword("authentication").build();

RedisClusterClient clusterClient = new RedisClusterClient(rediUri);
RedisAdvancedClusterAsyncConnection<String, String> connection = clusterClient.connectClusterAsync();


...

connection.close();
clusterClient.shutdown();

Enabling regular cluster topology view updates

RedisClusterClient clusterClient = new RedisClusterClient(RedisURI.Builder.redis("localhost").build());
clusterClient.setOptions(new ClusterClientOptions.Builder()
                                           .refreshClusterView(true)
                                           .refreshPeriod(1, TimeUnit.MINUTES)
                                           .build());

RedisClusterConnection<String, String> connection = clusterClient.connectCluster();

...

connection.close();
clusterClient.shutdown();

Obtaining a node connection

RedisURI redisUri = RedisURI.Builder.redis("localhost").withPassword("authentication").build();

RedisClusterClient clusterClient = new RedisClusterClient(rediUri);
RedisAdvancedClusterConnection<String, String> connection = clusterClient.connectCluster();
RedisClusterConnection<String, String> node1 = connection.getConnection("host", 7379);

...

// do not close node1
connection.close();
clusterClient.shutdown();

Internals

Redis connections are pooled to maintain a connection to each cluster node. The cluster topology can change during runtime. As soon as a redirect (MOVED) is replied, the client itself either looks up the connection to the host (distinguished by host and port) or creates a new connection, even if the host was not part of the initial cluster nodes. Note lettuce validates by default that the connection point is part of the Redis Cluster. If a connection point (identified by nodeId or host and port) is not within the cluster topology view (Partitions), the connection attempt is rejected, and the command fails. The validation can be disabled within the ClusterClientOptions.

The connection returned to the caller of connectClusterAsync() is considered as control and router connection. Requests without key (such as PING) are dispatched without routing. This means that that control connection is mostly a dispatcher. The control connection does not use itself for requests, which could fit into the node's responsibility because of the changing topology.The control connection creates a second connection (because of the command's hash) to the same host and dispatches the command to the same node but over a different connection.