Client-side cluster support in Redis - Deep Dive

Overview - Client-side cluster support

What is it?

Client-side cluster support in Redis means that the client application understands how data is split across multiple Redis servers (nodes) and can directly send commands to the right node. Instead of relying on a single server, Redis data is divided into parts called slots, and each node handles some slots. The client keeps track of this division and routes requests accordingly.

Why it matters

Without client-side cluster support, clients would have to send all requests to one server, which limits scalability and fault tolerance. By knowing how data is distributed, clients can efficiently access the right server, improving speed and reliability. This makes Redis suitable for large-scale applications where data grows beyond one machine's capacity.

Where it fits

Before learning client-side cluster support, you should understand basic Redis commands and the concept of Redis clusters. After this, you can explore advanced topics like cluster rebalancing, failover handling, and client libraries that implement cluster support.

Mental Model

Core Idea

Client-side cluster support means the client knows how Redis data is split across servers and sends commands directly to the correct server without extra hops.

Think of it like...

Imagine a library where books are spread across different rooms by topic. Instead of asking a librarian to find a book for you every time, you have a map that shows which room holds which topics, so you go straight to the right room yourself.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Redis Node 1  │       │ Redis Node 2  │       │ Redis Node 3  │
│ Slots 0-5460  │       │ Slots 5461-10922│     │ Slots 10923-16383│
└──────┬────────┘       └──────┬────────┘       └──────┬────────┘
       │                       │                       │
       │                       │                       │
       ▼                       ▼                       ▼
┌─────────────────────────────────────────────────────────┐
│                   Redis Client                           │
│  Knows slot ranges and sends commands directly to nodes │
└─────────────────────────────────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Redis Clusters Basics

Concept: Redis clusters split data into 16384 slots distributed across multiple nodes.

Redis divides all keys into 16384 hash slots. Each node in the cluster owns a subset of these slots. When you add or remove nodes, slots move between nodes to balance the load.

Result

You get a cluster of Redis servers, each responsible for a part of the data.

Understanding slot distribution is key to knowing why clients need to route commands correctly.

2

Foundation

Role of the Redis Client in Clusters

Concept: The client must know which node owns which slots to send commands directly.

Instead of sending all commands to one server, the client asks the cluster for the slot map and uses it to send commands to the right node. This avoids extra redirections and improves performance.

Result

Clients can communicate efficiently with the cluster by targeting the correct node.

Knowing the client's role helps understand why client-side cluster support is necessary.

3

Intermediate

How Clients Discover Cluster Topology

🤔Before reading on: do you think clients learn cluster layout by asking a central server or by querying any node? Commit to your answer.

Concept: Clients discover cluster layout by querying any node, which returns the full slot-to-node mapping.

When a client connects, it sends a CLUSTER SLOTS command to any node. The node replies with the slot ranges and the nodes responsible. The client caches this info to route commands.

Result

The client has a map of slots to nodes and can send commands directly without asking again until topology changes.

Understanding discovery prevents confusion about how clients keep updated about cluster changes.

4

Intermediate

Handling MOVED and ASK Redirections

🤔Before reading on: do you think clients always know the correct node, or do they sometimes get redirected? Commit to your answer.

Concept: Clients may get redirected if the cluster topology changes and must update their slot map accordingly.

If a client sends a command to the wrong node, the node replies with MOVED or ASK errors indicating the correct node. The client then updates its slot map or temporarily redirects the command.

Result

Clients stay in sync with cluster changes and maintain correct routing.

Knowing how clients handle redirections explains how they remain reliable despite cluster changes.

5

Intermediate

Key Hashing and Slot Calculation

Concept: Clients calculate the slot for a key using a hash function to decide which node to contact.

Clients use a CRC16 hash on the key (or part of it if using hash tags) and then take modulo 16384 to find the slot number. This calculation must match Redis's internal logic.

Result

Clients can determine the slot for any key locally without asking the server.

Understanding hashing ensures clients route commands correctly and consistently.

6

Advanced

Cluster Topology Updates and Failover Handling

🤔Before reading on: do you think clients automatically detect node failures or require manual intervention? Commit to your answer.

Concept: Clients periodically refresh cluster topology to handle node failures and failovers automatically.

Clients refresh their slot cache by reissuing CLUSTER SLOTS commands at intervals or after errors. This allows them to detect new masters after failover and update routing without downtime.

Result

Clients maintain high availability and resilience by adapting to cluster changes.

Knowing automatic topology refresh is crucial for building robust client applications.

7

Expert

Optimizing Client-Side Cluster Performance

🤔Before reading on: do you think clients always query nodes sequentially or can they pipeline commands smartly? Commit to your answer.

Concept: Advanced clients pipeline commands to multiple nodes in parallel and cache topology aggressively to reduce latency.

Clients can batch commands to different nodes simultaneously, reducing wait times. They also handle partial failures gracefully and optimize slot cache updates to avoid unnecessary network calls.

Result

Applications achieve faster response times and better throughput in large Redis clusters.

Understanding these optimizations reveals how client-side cluster support scales in real-world systems.

Under the Hood

Internally, Redis clusters assign each key to a slot using a CRC16 hash. Each node owns a range of slots. The client maintains a slot-to-node map by querying the cluster. When sending a command, the client hashes the key, finds the slot, and routes the command to the node owning that slot. If the cluster topology changes, nodes send MOVED or ASK errors to inform clients, prompting them to update their maps. Clients also periodically refresh the slot map to stay current.

Why designed this way?

This design distributes data and load across multiple servers, enabling horizontal scaling and fault tolerance. Client-side routing reduces the need for extra network hops and server-side redirections, improving performance. Alternatives like proxy-based routing add latency and complexity. The client-side approach balances efficiency and simplicity.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Redis Node 1  │◄──────┤               │──────►│ Redis Node 2  │
│ Slots 0-5460  │       │ Redis Client  │       │ Slots 5461-10922│
└──────┬────────┘       │ Maintains slot│       └──────┬────────┘
       │                │ to node map   │              │
       │                └──────┬────────┘              │
       ▼                       │                       ▼
┌───────────────┐              │              ┌───────────────┐
│ Redis Node 3  │◄─────────────┴─────────────►│ Redis Node 4  │
│ Slots 10923-16383│                            │ Slots 16384-...│
└───────────────┘                            └───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do clients always send commands to a single Redis node regardless of cluster setup? Commit yes or no.

Common Belief: Clients just send all commands to one Redis node and the cluster handles routing internally.

Reality: Clients must know the cluster layout and send commands directly to the correct node owning the key's slot.

Why it matters: Assuming the server routes commands causes inefficient clients that get many redirections, increasing latency and load.

Quick: Do you think clients never need to update their slot map after initial discovery? Commit yes or no.

Common Belief: Once clients get the cluster slot map, it never changes during the connection lifetime.

Reality: Cluster topology can change due to failover or scaling, so clients must refresh their slot map regularly or after errors.

Why it matters: Ignoring updates leads to stale routing, causing errors and failed commands.

Quick: Do you think clients can route commands for multi-key operations if keys belong to different slots? Commit yes or no.

Common Belief: Clients can send multi-key commands across different slots to any nodes without issues.

Reality: Multi-key commands must target keys in the same slot; otherwise, Redis returns an error.

Why it matters: Misunderstanding this causes failed multi-key operations and confusion in application logic.

Quick: Do you think client-side cluster support is only about performance? Commit yes or no.

Common Belief: Client-side cluster support exists mainly to speed up Redis commands.

Reality: It also ensures correctness, fault tolerance, and scalability by handling cluster topology and failover.

Why it matters: Focusing only on speed misses the importance of reliability and data consistency in distributed systems.

Expert Zone

1

Clients must handle partial cluster failures gracefully, retrying commands on failover nodes without user intervention.

2

Hash tags allow grouping multiple keys into the same slot for atomic multi-key operations, a subtle but powerful feature.

3

Aggressive caching of slot maps improves performance but risks stale data; balancing cache freshness and overhead is a key design choice.

When NOT to use

Client-side cluster support is not suitable for very simple applications or when using Redis in standalone mode. For proxy-based cluster setups, server-side routing is used instead. Also, if multi-key operations across slots are frequent, consider redesigning data or using Redis modules that support cross-slot transactions.

Production Patterns

In production, clients implement automatic topology refresh, handle MOVED/ASK redirections transparently, and pipeline commands to multiple nodes for efficiency. They also use hash tags to group related keys and avoid cross-slot errors. Monitoring cluster health and client cache freshness is standard practice.

Connections

Distributed Hash Tables (DHT)

Client-side cluster support uses a similar concept of hashing keys to nodes as DHTs in distributed systems.

Understanding DHTs helps grasp how Redis clients map keys to nodes and handle dynamic membership changes.

Load Balancing in Web Servers

Both involve directing requests to the correct server based on a key or session to optimize resource use.

Knowing load balancing strategies clarifies why client-side routing improves performance by avoiding unnecessary hops.

Human Memory Retrieval

Like a client remembering where data lives, human memory stores information in organized locations for quick access.

This analogy highlights the importance of caching and updating knowledge to avoid errors and delays.

Common Pitfalls

#1 Sending commands to a random node without slot calculation.

Wrong approach:

client.sendCommand('GET', 'mykey') to any node without slot mapping

Correct approach:

Calculate slot for 'mykey' and send GET command directly to node owning that slot

Root cause:

Not understanding that Redis cluster requires clients to route commands based on key slots.

#2 Ignoring MOVED redirection errors and not updating slot cache.

Wrong approach:

On MOVED error, client retries same node without refreshing slot map

Correct approach:

On MOVED error, client updates slot map and retries command on correct node

Root cause:

Misunderstanding cluster topology changes and client responsibility to adapt.

#3 Using multi-key commands with keys in different slots.

Wrong approach:

client.sendCommand('MGET', 'key1', 'key2') where keys hash to different slots

Correct approach:

Use hash tags to ensure keys are in the same slot or avoid multi-key commands across slots

Root cause:

Not knowing Redis cluster limitation on multi-key commands across slots.

Key Takeaways

Client-side cluster support means the client knows how Redis data is split and sends commands directly to the right node.

Redis clusters divide keys into 16384 slots distributed across nodes; clients calculate slots to route commands.

Clients discover cluster topology by querying nodes and must handle redirections and topology changes dynamically.

Multi-key commands must target keys in the same slot; hash tags help group keys for this purpose.

Advanced clients optimize performance by pipelining commands and caching slot maps while handling failover automatically.