Upstream Replica

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

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

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

Redis Sentinel

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

Standalone Upstream/Replica

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

Static Upstream/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. Upstream/Replica URIs will be treated in this case as static topology, and no additional hosts are discovered in such case. Redis Standalone Upstream/Replica will discover the roles of the supplied RedisURIs and issue commands to the appropriate node.

Topology discovery

Upstream-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 upstream promotion). The MasteReplica API supports both mechanisms. The topology is provided by a TopologyProvider:

• UpstreamReplicaTopologyProvider: Dynamic topology lookup using the INFO REPLICATION output. Replicas are listed as replicaN=…​ entries. The initial connection can either point to a upstream 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 Upstream/Replica failover or topology changes.

• StaticUpstreamReplicaTopologyProvider: 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 Upstream/Replica failover or topology changes.

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

Topology Updates

• Standalone Upstream/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 upstream 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 = MasteReplica.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 = MasteReplica.connect(redisClient, StringCodec.UTF8,
        RedisURI.create("redis-sentinel://localhost:26379,localhost:26380/0#myupstream"));
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 = MasteReplica
        .connect(redisClient, new Utf8StringCodec(), nodes);
connection.setReadFrom(ReadFrom.UPSTREAM_PREFERRED);

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

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