ReadFrom Settings

The ReadFrom setting describes how Lettuce routes read operations to replica nodes.

By default, Lettuce routes its read operations in multi-node connections to the master node. Reading from the master returns the most recent version of the data because write operations are issued to the single master node. Reading from masters guarantees strong consistency.

You can reduce latency or improve read throughput by distributing reads to replica members for applications that do not require fully up-to-date data.

Be careful if using other ReadFrom settings than MASTER. Settings other than MASTER may return stale data because the replication is asynchronous. Data in the replicas may not hold the most recent data.

Redis Cluster

Redis Cluster is a multi-node operated Redis setup that uses one or more master nodes and allows to setup replica nodes. Redis Cluster connections allow to set a ReadFrom setting on connection level. This setting applies for all read operations on this connection.

Example 1. Enable Replica reads with ReadFrom.REPLICA

RedisClusterClient client = RedisClusterClient.create(RedisURI.create("host", 7379));
StatefulRedisClusterConnection<String, String> connection = client.connect();
connection.setReadFrom(ReadFrom.REPLICA);

RedisAdvancedClusterCommands<String, String> sync = connection.sync();
sync.set(key, "value");

sync.get(key); // replica read

connection.close();
client.shutdown();

Master/Replica connections ("Master/Slave")

Redis nodes can be operated in a Master/Replica setup to achieve availability and performance. Master/Replica setups can be run either Standalone or managed using Redis Sentinel. Lettuce allows to use replica nodes for read operations by using the MasterReplica API that supports both Master/Replica setups:

1. Redis Standalone Master/Replica (no failover)

2. Redis Sentinel Master/Replica (Sentinel-managed failover)

The resulting connection uses in any case the primary connection-point to dispatch non-read operations.

Redis Sentinel

Master/Replica with Redis Sentinel is very similar to regular Redis Sentinel operations. When the master fails over, a replica is promoted by Redis Sentinel to the new master and the client obtains the new topology from Redis Sentinel.

Connections to Master/Replica require one or more Redis Sentinel connection points and a master name. The primary connection point is the Sentinel monitored master node.

Example 2. Using ReadFrom with Master/Replica and Redis Sentinel

RedisURI sentinelUri = RedisURI.Builder.sentinel("sentinel-host", 26379, "master-name").build();
RedisClient client = RedisClient.create();

StatefulRedisMasterReplicaConnection<String, String> connection = MasterReplica.connect(
            client,
            StringCodec.UTF8
            sentinelUri);

connection.setReadFrom(ReadFrom.REPLICA);

connection.sync().get("key"); // Replica read

connection.close();
client.shutdown();

Redis Standalone

Master/Replica with Redis Standalone is very similar to regular Redis Standalone operations. A Redis Standalone Master/Replica setup is static and provides no built-in failover. Replicas are read from the Redis master node’s INFO command.

Connecting to Redis Standalone Master/Replica nodes requires connections to use the Redis master for the RedisURI. The node used within the RedisURI is the primary connection point.

Example 3. Using ReadFrom with Master/Replica and Redis Standalone (Master and Replica)

RedisURI masterUri = RedisURI.Builder.redis("master-host", 6379).build();
RedisClient client = RedisClient.create();

StatefulRedisMasterReplicaConnection<String, String> connection = MasterReplica.connect(
            client,
            StringCodec.UTF8,
            masterUri);

connection.setReadFrom(ReadFrom.REPLICA);

connection.sync().get("key"); // Replica read

connection.close();
client.shutdown();

Use Cases for non-master reads

The following use cases are common for using non-master read settings and encourage eventual consistency:

• Providing local reads for geographically distributed applications. If you have Redis and application servers in multiple data centers, you may consider having a geographically distributed cluster. Using the LOWEST_LATENCY setting allows the client to read from the lowest-latency members, rather than always reading from the master node.

• Maintaining availability during a failover. Use MASTER_PREFERRED if you want an application to read from the master by default, but to allow stale reads from replicas when the master node is unavailable. MASTER_PREFERRED allows a "read-only mode" for your application during a failover.

• Increase read throughput by allowing stale reads If you want to increase your read throughput by adding additional replica nodes to your cluster Use REPLICA to read explicitly from replicas and reduce read load on the master node. Using replica reads can highly lead to stale reads.

Read from settings

All ReadFrom settings except MASTER may return stale data because replicas replication is asynchronous and requires some delay. You need to ensure that your application can tolerate stale data.

Setting	Description
MASTER	Default mode. Read from the current master node.
MASTER_PREFERRED	Read from the master, but if it is unavailable, read from replica nodes.
REPLICA	Read from replica nodes.
REPLICA_PREFERRED	Read from the replica nodes, but if none is unavailable, read from the master.
LOWEST_LATENCY	Read from any node of the cluster with the lowest latency.
ANY	Read from any node of the cluster.
ANY_REPLICA	Read from any replica of the cluster.

Tip	The latency of the nodes is determined upon the cluster topology refresh. If the topology view is never refreshed, values from the initial cluster nodes read are used.

Custom read settings can be implemented by extending the io.lettuce.core.ReadFrom class.