Replication, Sentinel & Cluster

REPLICAOF host port (the modern name for the deprecated SLAVEOF) makes the target instance a replica of the given master; REPLICAOF NO ONE promotes it back to a standalone master without discarding its dataset. Issuing REPLICAOF against a different host/port while already replicating discards the current dataset and restarts sync against the new master from scratch.

See REPLICAOF.

When a replica connects, the master and replica negotiate via PSYNC whether a partial or a full resynchronization is possible:

INFO replication reports master_repl_offset on the master and each replica’s own offset, the numbers a partial resync compares to decide what is still coverable by the backlog.

See Redis replication.

By default a master accepts writes with any number of connected replicas, including zero — a lost replica does not, by itself, block writes. min-replicas-to-write N (paired with min-replicas-max-lag seconds, default 10) makes the master refuse writes once fewer than N replicas are connected and caught up within the lag threshold, trading availability for a stronger guarantee that an accepted write has somewhere else to survive a master crash. Neither setting makes Redis synchronous by default: replication itself stays asynchronous, so a write can still be lost if the master crashes before it reached any replica; WAIT numreplicas timeout is the per-command way to block until a specific write has actually propagated.

See Redis replication.

replica-read-only yes (the default) makes a replica reject write commands from ordinary clients, since any write it accepted locally would only be overwritten by the next command streamed from the master. Setting it to no allows local writes on the replica, but they are never propagated anywhere and are silently lost on the next full resync — a footgun almost never worth taking outside of a throwaway local write cache.

See Redis replication.

By default (repl-diskless-sync yes) the master streams the RDB snapshot for a full resync directly over the replica socket rather than writing it to disk first and letting the replica fetch the file — useful when disk I/O, not network bandwidth, is the bottleneck, or when the master’s disk is slow or on network storage. repl-diskless-sync-delay seconds (default 5) waits briefly before starting a diskless transfer so that several replicas that reconnect close together can share one snapshot generation instead of forking once per replica; repl-diskless-load similarly controls whether the replica streams the incoming snapshot straight into memory instead of writing it to a temp file first.

See Redis replication.

Each Sentinel independently pings the master; once enough of them agree it is unreachable, they proceed to an election and a failover. sentinel monitor mymaster host port quorum sets the master to watch and how many Sentinels must agree the master is down before it is marked objectively down (ODOWN) — distinct from any single Sentinel’s own subjectively down (SDOWN) opinion, which on its own triggers nothing. Reaching ODOWN does not itself perform the failover: the Sentinels then hold a leader election (a majority of the configured Sentinels, not just quorum, must agree on a leader) and only the elected leader Sentinel drives the actual promotion. Because of that majority requirement, running Sentinel with fewer than three instances — or an even count, which cannot break a tie — undermines the whole mechanism; three is the practical minimum.

See High availability with Redis Sentinel.

A Sentinel process is started with its own config file rather than sharing the monitored Redis instance’s redis.conf:

down-after-milliseconds sets how long a master must be unreachable before this Sentinel marks it SDOWN; failover-timeout bounds how long a failover attempt (including waiting for the promoted replica to be ready and for the remaining replicas to be reconfigured) is allowed to take before Sentinel retries or gives up; and parallel-syncs caps how many of the other replicas are reconfigured to follow the new master simultaneously, trading failover speed against how much resync load the new master takes on at once. Sentinel rewrites this file in place as the deployment’s state changes (a new master address after a failover, for example), so it must be writable at runtime, not just at startup.

See High availability with Redis Sentinel.

Neither Lettuce nor Jedis is told the master’s address directly in a Sentinel deployment — both are pointed at the Sentinels instead and ask them for the current master on every connection attempt:

Both clients need the set of Sentinel addresses, not a single one, since any individual Sentinel can be down when the client needs to look up the current master.

See High availability with Redis Sentinel.

A network partition can leave the old master reachable by some clients (on its side of the partition) while Sentinels on the other side promote a replica — briefly leaving two masters accepting writes from different clients at once. min-replicas-to-write (above) narrows this window by making the old master refuse writes once it can no longer see enough replicas, rather than continuing to accept writes it can never reconcile once the partition heals; it does not eliminate the risk on its own, since a write can still land in the brief window before the master notices its replicas are gone. Sentinel’s failover-timeout and quorum sizing are the other lever — a low quorum against too few Sentinels is more prone to promoting prematurely on a partition that would otherwise have healed.

See High availability with Redis Sentinel and Redis replication for min-replicas-to-write.

The keyspace is divided into 16384 fixed hash slots, and every key is deterministically mapped to exactly one: CRC16(key) mod 16384. If a key contains a hash tag — a substring between the first \{ and the first non-empty \} — only that substring is hashed instead of the whole key, so several related keys can be pinned to the same slot on purpose (see "Multi-key command limits" below for why that matters). Every primary in the cluster owns a subset of the 16384 slots, and that assignment — not node identity — is what determines which node a key belongs to.

See Redis cluster specification.

redis-cli --cluster create bootstraps a cluster from a list of already-running, empty Redis instances started with cluster-enabled yes, assigning slots evenly across the primaries and, with --cluster-replicas N, attaching N replicas to each primary (placed on different nodes than their primary, where the node list allows it):

See Scale with Redis Cluster.

A client can connect to any cluster node and ask for any key; a node that does not own the requested key’s slot does not proxy the request, it redirects the client instead:

See Redis cluster specification and CLUSTER SETSLOT.

Wrapping the part of a key that should determine its slot in \{ \} — for example \{bookshop:cart:42\} — lets every key that shares that tag land on the same slot regardless of the rest of the key name. This is how the Bookshop cart, which stores a hash under bookshop:cart:<userId> but might also want a per-cart set or stream alongside it (bookshop:cart:42:events, say), keeps every per-cart structure on one slot so they can be read or written together in a single multi-key command or a Lua script.

See Redis cluster specification and CLUSTER KEYSLOT.

MGET/MSET, a MULTI/EXEC transaction, and a Lua script’s key arguments must all resolve to the same slot in Cluster mode — Redis has no cross-node coordination for a single command or transaction, so mixing keys from different slots fails outright with a CROSSSLOT error rather than silently doing part of the work on each node. This is the reason hash tags exist: any keys an application needs to touch together in one command or transaction must be tagged onto the same slot deliberately, since Cluster mode gives that no other way to happen.

See Redis cluster specification.

Resharding moves a range of slots (and the keys mapped to them) from one primary to another, needed both when scaling a cluster out or in and when rebalancing load away from an overloaded shard. Before Redis 8.4, this moved keys one at a time (CLUSTER SETSLOT slot IMPORTING\|MIGRATING, then CLUSTER GETKEYSINSLOT/MIGRATE per batch, finalized with CLUSTER SETSLOT slot NODE), which was slow and, mid-migration, forced clients through the ASK redirect dance above for every key that had not yet moved.

Redis 8.4 introduces atomic slot migration (ASM) via a new CLUSTER MIGRATION command: the destination node issues CLUSTER MIGRATION IMPORT start-slot end-slot [start-slot end-slot …​], which replicates the whole slot range (an initial snapshot plus the live write stream, much like ordinary replication) to the destination and only then performs a single atomic handoff of slot ownership — clients keep being served by the source node throughout the copy and see, at most, an ordinary MOVED once ownership actually switches, instead of a stream of ASK redirects for keys moved one by one. CLUSTER MIGRATION STATUS ID id\|ALL reports progress on a running migration, and CLUSTER MIGRATION CANCEL ID id\|ALL (sent to the destination) aborts one. redis-cli --cluster reshard/--cluster rebalance remain the operator-facing entry points and use ASM automatically on a Redis 8.4+ cluster.

See Atomic slot migration with Redis 8.4 and Scale with Redis Cluster.

CLUSTER SLOT-STATS <SLOTSRANGE start-slot end-slot \| ORDERBY metric [LIMIT limit] [ASC\|DESC]> reports per-slot usage on the current node — KEY-COUNT always, and, once cluster-slot-stats-enabled yes is set, also CPU-USEC, NETWORK-BYTES-IN, NETWORK-BYTES-OUT and MEMORY-BYTES — the tool for spotting a hot or cold slot before deciding what to reshard, rather than guessing from overall node-level metrics.

See CLUSTER SLOT-STATS.

By default (cluster-require-full-coverage yes) a cluster stops serving any query the moment even a single slot has no owner — typically while a primary and all its replicas are down at once — since Redis cannot tell whether that slot’s data is truly gone or just temporarily unreachable, and refuses to guess. Setting it to no lets the cluster keep serving the slots that are still covered, sacrificing full consistency guarantees (queries for keys in the uncovered slots simply fail) for partial availability during an outage that would otherwise take the whole cluster down.

See Redis cluster specification.

A cluster-aware client keeps its own cached map of slot-to-node ownership and updates it both reactively (on a MOVED/ASK reply) and, usually, on a periodic timer — since a resharding operation can move slots the client has not queried recently, and a reactive-only client would only discover that on the next miss. Lettuce configures this explicitly through ClusterTopologyRefreshOptions, combining a periodic interval with adaptive triggers that refresh immediately on events such as a MOVED redirect or a node becoming unreachable (see the Lettuce example below); Jedis’s cluster client refreshes its slot cache reactively on MOVED by default and, in recent versions, also supports a configurable periodic refresh.

See Redis cluster specification.

A minimal sketch of six redis:8 containers wired for cluster mode — creating the cluster itself is still a separate, one-off redis-cli --cluster create step against the running containers, not something Compose expresses:

Each node’s cluster bus port (17000-17005, always the client port + 10000) also needs to be reachable between the nodes themselves, not just from the host — omitted above for brevity but required in practice.

This derives from CLUSTER KEYSLOT.

Periodic refresh catches a resharding that happened without this client observing a MOVED/ASK reply; adaptive triggers refresh immediately on events such as a redirect or a node disconnect, instead of waiting for the next periodic tick. This derives from Redis cluster specification.