Upstream Replica

Redis can increase availability and read throughput by using replication. Lettuce provides dedicated Master/Replica support since 4.2 for topologies and ReadFrom-Settings.

Redis Master/Replica can be run standalone or together with Redis Sentinel, which provides automated failover and master promotion. Failover and master promotion is supported in Lettuce already since version 3.1 for master connections.

Connections can be obtained from the MasterReplica connection provider by supplying the client, Codec, and one or multiple RedisURIs.

Redis Sentinel

Master/Replica using Redis Sentinel uses Redis Sentinel as registry and notification source for topology events. Details about the master and its replicas are obtained from Redis Sentinel. Lettuce subscribes to Redis Sentinel events for notifications to all supplied Sentinels.

Standalone Master/Replica

Running a Standalone Master/Replica setup requires one seed address to establish a Redis connection. Providing one RedisURI will discover other nodes which belong to the Master/Replica setup and use the discovered addresses for connections. The initial URI can point either to a master or a replica node.

Static Master/Replica with predefined node addresses

In some cases, topology discovery shouldn’t be enabled, or the discovered Redis addresses are not suited for connections. AWS ElastiCache falls into this category. Lettuce allows to specify one or more Redis addresses as List and predefine the node topology. Master/Replica URIs will be treated in this case as static topology, and no additional hosts are discovered in such case. Redis Standalone Master/Replica will discover the roles of the supplied RedisURIs and issue commands to the appropriate node.

Topology discovery

Master-Replica topologies are either static or semi-static. Redis Standalone instances with attached replicas provide no failover/HA mechanism. Redis Sentinel managed instances are controlled by Redis Sentinel and allow failover (which include master promotion). The MasterReplica API supports both mechanisms. The topology is provided by a TopologyProvider:

• MasterReplicaTopologyProvider: Dynamic topology lookup using the INFO REPLICATION output. Replicas are listed as replicaN=…​ entries. The initial connection can either point to a master or a replica, and the topology provider will discover nodes. The connection needs to be re-established outside of Lettuce in a case of a Master/Replica failover or topology changes.

• StaticMasterReplicaTopologyProvider: Topology is defined by the list of URIs and the ROLE output. MasterReplica uses only the supplied nodes and won’t discover additional nodes in the setup. The connection needs to be re-established outside of Lettuce in case of a Master/Replica failover or topology changes.

• SentinelTopologyProvider: Dynamic topology lookup using the Redis Sentinel API. In particular, SENTINEL MASTER and SENTINEL SLAVES output. Master/Replica failover is handled by Lettuce.

Topology Updates

• Standalone Master/Replica: Performs a one-time topology lookup which remains static afterward

• Redis Sentinel: Subscribes to all Sentinels and listens for Pub/Sub messages to trigger topology refreshing

Transactions

Since version 5.1, transactions and commands during a transaction are routed to the master node to ensure atomic transaction execution on a single node. Transactions can contain read- and write-operations so the driver cannot decide upfront which node can be used to run the actual transaction.

Examples

Example 1. Redis Standalone Master/Replica

RedisClient redisClient = RedisClient.create();

StatefulRedisMasterSlaveConnection<String, String> connection = MasterReplica.connect(redisClient, StringCodec.UTF8,
        RedisURI.create("redis://localhost"));
connection.setReadFrom(ReadFrom.UPSTREAM_PREFERRED);

System.out.println("Connected to Redis");

connection.close();
redisClient.shutdown();

Example 2. Redis Sentinel

RedisClient redisClient = RedisClient.create();

StatefulRedisMasterReplicaConnection<String, String> connection = MasterReplica.connect(redisClient, StringCodec.UTF8,
        RedisURI.create("redis-sentinel://localhost:26379,localhost:26380/0#mymaster"));
connection.setReadFrom(ReadFrom.UPSTREAM_PREFERRED);

System.out.println("Connected to Redis");

connection.close();
redisClient.shutdown();

Example 3. AWS ElastiCache Cluster

RedisClient redisClient = RedisClient.create();

List<RedisURI> nodes = Arrays.asList(RedisURI.create("redis://host1"),
        RedisURI.create("redis://host2"),
        RedisURI.create("redis://host3"));

StatefulRedisMasterSlaveConnection<String, String> connection = MasterReplica
        .connect(redisClient, StringCodec.UTF8, nodes);
connection.setReadFrom(ReadFrom.UPSTREAM_PREFERRED);

System.out.println("Connected to Redis");

connection.close();
redisClient.shutdown();