Redis Cluster
Redis Cluster splits your data across multiple Redis nodes automatically. Instead of one server holding all keys, the cluster divides them into 16,384 slots and assigns groups of slots to different nodes. This lets your data and write capacity grow beyond what a single server can handle.
The Post Office Sorting Analogy
A single post office sorts all letters for a city. As the city grows, one office cannot keep up. The city opens multiple offices, each responsible for specific zip codes. Letters for zip codes 1–3000 go to Office A, 3001–6000 to Office B, and so on. Redis Cluster works the same way — instead of zip codes, it uses hash slots.
Without Cluster (single node):
┌──────────────────────────────────────┐
│ One Redis server │
│ All 100 million keys │
│ Maximum RAM: 64 GB │
│ Bottleneck for all writes │
└──────────────────────────────────────┘
With Cluster (6 nodes — 3 primaries + 3 replicas):
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Primary A │ │ Primary B │ │ Primary C │
│ Slots 0 │ │ Slots 5461 │ │ Slots 10923│
│ to 5460 │ │ to 10922 │ │ to 16383 │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
│ Replica A │ │ Replica B │ │ Replica C │
└─────────────┘ └─────────────┘ └─────────────┘
Hash Slots – How Keys Get Distributed
Redis Cluster does not distribute keys randomly. It runs a CRC16 checksum on the key name and takes the result modulo 16384 to determine the slot number. That slot number determines which node holds the key.
Key: "user:1001"
CRC16("user:1001") = 40291
40291 mod 16384 = 7523
Slot 7523 is assigned to Primary B
→ user:1001 lives on Primary B
Key: "session:abc"
CRC16("session:abc") = 15820
15820 mod 16384 = 15820
Slot 15820 is assigned to Primary C
→ session:abc lives on Primary C
Your app does not need to calculate this.
Redis client libraries do it automatically.
Hash Tags – Grouping Keys on the Same Node
Sometimes you want multiple keys to land on the same node — for example, to use MULTI/EXEC across related keys. Wrap the shared part of the key in curly braces. Redis uses only the text inside the braces for slot calculation.
Without hash tags (may end up on different nodes):
order:1001:items → slot 2200 → Node A
order:1001:total → slot 9100 → Node B
MULTI across them would fail (different nodes)
With hash tags (guaranteed same node):
{order:1001}:items → slot based on "order:1001" → Node B
{order:1001}:total → slot based on "order:1001" → Node B
Both keys → same node → MULTI works fine
MOVED – When a Key Lives on a Different Node
If you connect to the wrong node and ask for a key, that node tells you where the key actually lives by returning a MOVED redirect.
Client connects to Node A and runs: GET user:1001 Node A calculates: slot 7523 → Primary B Node A replies: (error) MOVED 7523 192.168.1.12:6379 Client reconnects to Node B (192.168.1.12) and retries GET. Smart client libraries (like redis-py, Jedis, ioredis) handle MOVED automatically — your app code never sees it.
Cluster Failover – Automatic Recovery
Each primary has a replica. If a primary fails, its replica detects the failure and promotes itself to primary automatically. The cluster continues without human intervention.
Normal state: Primary B (healthy) ────▶ Replica B (follower) Primary B crashes: Primary B (down) Replica B waits for 15 seconds (default cluster-node-timeout) Other primaries vote to promote Replica B After promotion: New Primary B (was Replica B) ──── handles slots 5461–10922 Cluster is healthy again. When the old Primary B comes back online: It rejoins as a replica of the new Primary B.
Adding and Removing Nodes
Add a new node: redis-cli --cluster add-node new_ip:6379 existing_node_ip:6379 Rebalance slots to include the new node: redis-cli --cluster rebalance existing_node_ip:6379 This moves some hash slots (and their keys) from existing nodes to the new node without downtime. Remove a node (migrate its slots first): redis-cli --cluster reshard existing_node_ip:6379 redis-cli --cluster del-node existing_node_ip:6379
Cluster Limitations
┌─────────────────────────────────────────────────────────────────┐ │ Limitation │ ├─────────────────────────────────────────────────────────────────┤ │ Multi-key commands (MSET, MGET, SUNION) work only if all keys │ │ are in the same slot (use hash tags to enforce this). │ │ │ │ MULTI/EXEC transactions work only within one node. │ │ │ │ Database 0 is the only database in cluster mode. │ │ (Redis normally supports 16 databases: SELECT 0–15) │ │ │ │ Lua scripts must only access keys on the same node. │ └─────────────────────────────────────────────────────────────────┘
When to Use Cluster vs Single Node
┌────────────────────────────────────┬──────────────────────────┐ │ Use Single Node When │ Use Cluster When │ ├────────────────────────────────────┼──────────────────────────┤ │ Data fits in one server's RAM │ Data exceeds one server │ │ Write throughput is manageable │ Writes need horizontal │ │ Simplicity matters │ scale across nodes │ │ You use multi-key commands widely │ You need geographic │ │ │ distribution │ └────────────────────────────────────┴──────────────────────────┘
Key Points
- Redis Cluster divides data into 16,384 hash slots spread across multiple primary nodes.
- Each key maps to a slot via CRC16. Client libraries handle routing automatically.
- Use hash tags (curly braces) to force related keys onto the same node when you need multi-key operations.
- A MOVED response tells the client which node actually holds the requested slot.
- Each primary has at least one replica. If the primary fails, the replica auto-promotes and the cluster continues.
- Multi-key commands and MULTI/EXEC work only when all keys live on the same node.