redis-clustering

Original：🇺🇸 English

Translated

Redis Cluster and replication guidance covering hash tags for multi-key operations, avoiding CROSSSLOT errors, and reading from replicas to scale read-heavy workloads. Use when designing keys for a sharded Redis Cluster, debugging CROSSSLOT errors on MGET / SDIFF / pipelines, configuring a multi-key transaction in a cluster, or routing reads to replicas for caches, analytics, or dashboards.

6installs

Sourceredis/agent-skills

Added on2026-05-27

NPX Install

npx skill4agent add redis/agent-skills redis-clustering

SKILL.md Content

View Translation Comparison →

Redis Clustering

Guidance for designing keys and routing reads in a sharded Redis Cluster (and in standalone primary/replica replication). Covers the two failure modes that bite most new cluster users:

CROSSSLOT

errors on multi-key operations, and overloading primaries with read traffic.

When to apply

Designing keys for a Redis Cluster deployment.
Debugging a
```
CROSSSLOT
```
error on
```
MGET
```
,
```
SDIFF
```
, transactions, or pipelines.
Implementing transactions / Lua scripts that touch multiple keys.
Scaling out read traffic without adding shards.

1. Hash tags for multi-key operations

Redis Cluster distributes keys across 16,384 slots by hashing the key name. Any command that touches multiple keys (

MGET

,

SDIFF

,

SUNIONSTORE

, transactions, pipelines, Lua scripts with multiple

KEYS[]

) requires all keys to live on the same slot — otherwise the server returns a

CROSSSLOT

error.

Hash tags force this: the part between

and

is the only thing hashed for slot assignment, so two keys sharing a hash tag always land together.

python

# Same slot — multi-key ops work
redis.set("{user:1001}:profile",  "...")
redis.set("{user:1001}:settings", "...")
redis.lmove("{user:1001}:pending", "{user:1001}:processed", "LEFT", "RIGHT")

python

# Different keys, no hash tag — CROSSSLOT on multi-key commands in cluster mode
redis.set("user:1001:profile",  "...")
redis.set("user:1001:settings", "...")
pipe = redis.pipeline()
pipe.get("user:1001:profile")
pipe.get("user:1001:settings")
pipe.execute()  # CROSSSLOT error in cluster

Rules of thumb:

Use a tag scoped to the meaningful entity, e.g.
```
{user:1001}
```
. Avoid bare
```
{1001}
```
— unrelated namespaces (
```
purchase:{1001}
```
,
```
employee:{1001}
```
) would all collide on the same slot.
Only tag where you actually need multi-key ops. Tagging everything creates hotspots and defeats the point of sharding.
A single-key command on a hash-tagged key works fine, so adding tags later is incremental — but renaming keys in production is painful, so plan tagging up front for entities you'll group.

See references/hash-tags.md.

2. Read replicas for read-heavy workloads

If reads dominate writes, route them to replicas to free primary capacity. Works both in Redis Cluster (each shard has 1+ replica) and in standalone primary/replica replication.

python

# Redis Cluster: enable replica reads on the client
from redis.cluster import RedisCluster

rc = RedisCluster(host="localhost", port=6379, read_from_replicas=True)
rc.set("key", "value")     # → primary
value = rc.get("key")       # → may be served by a replica

For non-cluster setups, point two clients at the right nodes:

python

primary = Redis(host="primary-host", port=6379)
replica = Redis(host="replica-host", port=6379)
primary.set("key", "value")
value = replica.get("key")

The trade-off is consistency: replicas are eventually consistent. Don't read your own writes from a replica; don't use replica reads for anything that requires strict freshness (financial balances, idempotency state). Good fits: cache layers, analytics, dashboards, recommendation feeds.

See references/read-replicas.md.

redis-clustering

NPX Install

Tags

SKILL.md Content

Redis Clustering

When to apply

1. Hash tags for multi-key operations

2. Read replicas for read-heavy workloads

References