Distributed Caching
Multi-instance Redis, consistent hashing, and Redis Cluster
Skills taught: redis.distributed
Why Distribute Redis?
A single Redis node can handle millions of ops/sec and terabytes of RAM on large hardware. But for datasets that don't fit in one machine, or for extreme throughput, you need to distribute across nodes. Redis offers two approaches: Redis Cluster (built-in) and client-side sharding.
Redis Cluster Basics
Redis Cluster automatically shards data across nodes using 16384 hash slots. Each key is assigned a slot via CRC16(key) % 16384, and each node owns a range of slots.
# Start 6 Redis instances (3 primary + 3 replica)
redis-server --port 7000 --cluster-enabled yes --cluster-config-file nodes-7000.conf &
redis-server --port 7001 --cluster-enabled yes --cluster-config-file nodes-7001.conf &
redis-server --port 7002 --cluster-enabled yes --cluster-config-file nodes-7002.conf &
redis-server --port 7003 --cluster-enabled yes --cluster-config-file nodes-7003.conf &
redis-server --port 7004 --cluster-enabled yes --cluster-config-file nodes-7004.conf &
redis-server --port 7005 --cluster-enabled yes --cluster-config-file nodes-7005.conf &
# Create cluster with 1 replica per primary
redis-cli --cluster create \
127.0.0.1:7000 127.0.0.1:7001 127.0.0.1:7002 \
127.0.0.1:7003 127.0.0.1:7004 127.0.0.1:7005 \
--cluster-replicas 1
# Check cluster health
redis-cli -p 7000 cluster info
redis-cli -p 7000 cluster nodes
Connecting from Node.js
import { createCluster } from 'redis';
const cluster = createCluster({
rootNodes: [
{ url: 'redis://localhost:7000' },
{ url: 'redis://localhost:7001' },
{ url: 'redis://localhost:7002' },
],
});
await cluster.connect();
// Commands route to correct node automatically
await cluster.set('user:1', 'Alice'); // goes to node holding slot for 'user:1'
await cluster.get('user:1'); // goes to same node
// MGET works only if all keys are on same node
// Use hash tags to co-locate keys
await cluster.set('{user:1}.name', 'Alice');
await cluster.set('{user:1}.email', 'alice@ex.com');
await cluster.mGet(['{user:1}.name', '{user:1}.email']); // same slot, works!
- Hash Tag
- A substring in {} in a key that Redis uses as the hash input instead of the whole key. Keys sharing the same hash tag always map to the same hash slot, enabling multi-key commands in a cluster.
High Availability with Sentinel
For single-node deployments that need failover (but not sharding), Redis Sentinel is simpler than Cluster. It monitors a primary/replica pair and auto-promotes on failure.
# sentinel.conf
sentinel monitor mymaster 127.0.0.1 6379 2
sentinel down-after-milliseconds mymaster 5000
sentinel failover-timeout mymaster 60000
sentinel parallel-syncs mymaster 1
Redis Cluster vs Sentinel
- Redis Cluster: Sharding + HA in one
- Redis Sentinel: HA only, no sharding
Tip: Redis Cluster uses 16384 hash slots distributed across shards. Use hash tags like {user:1}.name and {user:1}.email to ensure related keys land on the same shard, enabling multi-key operations.
Frequently Asked Questions
Can I use pipelining with Redis Cluster?
Yes, but all keys in a pipeline must map to the same hash slot. Use hash tags {tag} in your key names to force related keys to the same slot.
What happens when a node fails in Redis Cluster?
Cluster detects the failure via gossip protocol, waits for CLUSTER_NODE_TIMEOUT (default 15s), then elects a replica to become the new primary via a Raft-like election.
What is the minimum nodes for Redis Cluster?
3 primary nodes minimum. Each needs at least 1 replica for high availability, so 6 nodes total for a minimal HA cluster.