Module lettuce.core
Package io.lettuce.core.masterreplica

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, a RedisURI and a RedisCodec. 

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

  • ReplicaTopologyProvider: 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 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 a case of 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

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 Details

    • MasterReplica

      public MasterReplica()

  • Method Details

    • 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 supplied RedisURI and the supplied codec to encode/decode keys.

      This MasterReplica performs auto-discovery of nodes using either Redis Sentinel or Master/Replica. A RedisURI 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 be null.
      redisURI - the Redis server to connect to, must not be null.
      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 supplied RedisURI and the supplied codec to encode/decode keys.

      This MasterReplica performs auto-discovery of nodes using either Redis Sentinel or Master/Replica. A RedisURI 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 be null.
      redisURI - the Redis server to connect to, must not be null.
      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 supplied RedisURI and the supplied codec 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 supplied URIs 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 through RedisURI.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 be null.
      redisURIs - the Redis server(s) to connect to, must not be null.
      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 supplied RedisURI and the supplied codec 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 supplied URIs 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 through RedisURI.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 be null.
      redisURIs - the Redis server(s) to connect to, must not be null.
      Returns:
      CompletableFuture that is notified once the connect is finished.
      Since:
      6.0