Class MasterReplica
- java.lang.Object
-
- io.lettuce.core.masterreplica.MasterReplica
-
public class MasterReplica extends Object
Master-Replica connection API.This API allows connections to Redis Master/Replica setups which run either in a static Master/Replica setup or are managed by Redis Sentinel. Master-Replica connections can discover topologies and select a source for read operations using
ReadFrom
.Connections can be obtained by providing the
RedisClient
, aRedisURI
and aRedisCodec
.RedisClient client = RedisClient.create(); StatefulRedisMasterReplicaConnection<String, String> connection = MasterReplica.connect(client, RedisURI.create("redis://localhost"), StringCodec.UTF8); // ... connection.close(); client.shutdown();
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). TheMasterReplica
API supports both mechanisms. The topology is provided by aTopologyProvider
:ReplicaTopologyProvider
: Dynamic topology lookup using theINFO REPLICATION
output. Replicas are listed asreplicaN=...
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 Master/Replica failover or topology changes.StaticMasterReplicaTopologyProvider
: Topology is defined by the list ofURIs
and theROLE
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 a case of Master/Replica failover or topology changes.SentinelTopologyProvider
: Dynamic topology lookup using the Redis Sentinel API. In particular,SENTINEL MASTER
andSENTINEL 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
Connection Fault-Tolerance
Connecting to Master/Replica bears the possibility that individual nodes are not reachable.MasterReplica
can still connect to a partially-available set of nodes.- Redis Sentinel: At least one Sentinel must be reachable, the masterId must be registered and at least one host must be available (master or replica). Allows for runtime-recovery based on Sentinel Events.
- Static Setup (auto-discovery): The initial endpoint must be reachable. No recovery/reconfiguration during runtime.
- Static Setup (provided hosts): All endpoints must be reachable. No recovery/reconfiguration during runtime.
- Since:
- 5.2
- Author:
- Mark Paluch
-
-
Constructor Summary
Constructors Constructor Description MasterReplica()
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static <K,V>
StatefulRedisMasterReplicaConnection<K,V>connect(RedisClient redisClient, RedisCodec<K,V> codec, RedisURI redisURI)
static <K,V>
StatefulRedisMasterReplicaConnection<K,V>connect(RedisClient redisClient, RedisCodec<K,V> codec, Iterable<RedisURI> redisURIs)
static <K,V>
CompletableFuture<StatefulRedisMasterReplicaConnection<K,V>>connectAsync(RedisClient redisClient, RedisCodec<K,V> codec, RedisURI redisURI)
static <K,V>
CompletableFuture<StatefulRedisMasterReplicaConnection<K,V>>connectAsync(RedisClient redisClient, RedisCodec<K,V> codec, Iterable<RedisURI> redisURIs)
-
-
-
Method Detail
-
connect
public static <K,V> StatefulRedisMasterReplicaConnection<K,V> connect(RedisClient redisClient, RedisCodec<K,V> codec, RedisURI redisURI)
Open a new connection to a Redis Master-Replica server/servers using the suppliedRedisURI
and the suppliedcodec
to encode/decode keys.This
MasterReplica
performs auto-discovery of nodes using either Redis Sentinel or Master/Replica. ARedisURI
can point to either a master or a replica host.- Type Parameters:
K
- Key type.V
- Value type.- Parameters:
redisClient
- the Redis client.codec
- Use this codec to encode/decode keys and values, must not benull
.redisURI
- the Redis server to connect to, must not benull
.- Returns:
- a new connection.
-
connectAsync
public static <K,V> CompletableFuture<StatefulRedisMasterReplicaConnection<K,V>> connectAsync(RedisClient redisClient, RedisCodec<K,V> codec, RedisURI redisURI)
Open asynchronously a new connection to a Redis Master-Replica server/servers using the suppliedRedisURI
and the suppliedcodec
to encode/decode keys.This
MasterReplica
performs auto-discovery of nodes using either Redis Sentinel or Master/Replica. ARedisURI
can point to either a master or a replica host.- Type Parameters:
K
- Key type.V
- Value type.- Parameters:
redisClient
- the Redis client.codec
- Use this codec to encode/decode keys and values, must not benull
.redisURI
- the Redis server to connect to, must not benull
.- Returns:
CompletableFuture
that is notified once the connect is finished.- Since:
- 6.0
-
connect
public static <K,V> StatefulRedisMasterReplicaConnection<K,V> connect(RedisClient redisClient, RedisCodec<K,V> codec, Iterable<RedisURI> redisURIs)
Open a new connection to a Redis Master-Replica server/servers using the suppliedRedisURI
and the suppliedcodec
to encode/decode keys.This
MasterReplica
performs auto-discovery of nodes if the URI is a Redis Sentinel URI. Master/Replica URIs will be treated as static topology and no additional hosts are discovered in such case. Redis Standalone Master/Replica will discover the roles of the suppliedURIs
and issue commands to the appropriate node.When using Redis Sentinel, ensure that
redisURIs
contains only a single entry as only the first URI is considered.RedisURI
pointing to multiple Sentinels can be configured throughRedisURI.Builder.withSentinel(java.lang.String)
.- Type Parameters:
K
- Key type.V
- Value type.- Parameters:
redisClient
- the Redis client.codec
- Use this codec to encode/decode keys and values, must not benull
.redisURIs
- the Redis server(s) to connect to, must not benull
.- Returns:
- a new connection.
- Since:
- 6.0
-
connectAsync
public static <K,V> CompletableFuture<StatefulRedisMasterReplicaConnection<K,V>> connectAsync(RedisClient redisClient, RedisCodec<K,V> codec, Iterable<RedisURI> redisURIs)
Open asynchronously a new connection to a Redis Master-Replica server/servers using the suppliedRedisURI
and the suppliedcodec
to encode/decode keys.This
MasterReplica
performs auto-discovery of nodes if the URI is a Redis Sentinel URI. Master/Replica URIs will be treated as static topology and no additional hosts are discovered in such case. Redis Standalone Master/Replica will discover the roles of the suppliedURIs
and issue commands to the appropriate node.When using Redis Sentinel, ensure that
redisURIs
contains only a single entry as only the first URI is considered.RedisURI
pointing to multiple Sentinels can be configured throughRedisURI.Builder.withSentinel(java.lang.String)
.- Type Parameters:
K
- Key type.V
- Value type.- Parameters:
redisClient
- the Redis client.codec
- Use this codec to encode/decode keys and values, must not benull
.redisURIs
- the Redis server(s) to connect to, must not benull
.- Returns:
CompletableFuture
that is notified once the connect is finished.- Since:
- 6.0
-
-