Cluster Commands

CLUSTER-INFO

Redis Cluster distributes data across multiple nodes. 16384 hash slots spread across masters, with replicas for failover. Essential for scaling beyond a single server.

You'll Learn

  • How Redis Cluster works
  • CLUSTER INFO for health checks
  • CLUSTER NODES topology
  • Slot management basics
Free Download

See Your Data, Not Terminal Text

Redimo visualizes every Redis data type beautifully. Edit inline, undo mistakes, stay safe in production.

1. How Redis Cluster Works

Redis Cluster automatically shards data across multiple nodes. Each key maps to one of 16384 hash slots, and each slot is assigned to a master node.

Slot Calculation

# Key → Slot (CRC16 hash mod 16384)
mykey → CRC16("mykey") % 16384 → slot 5798

# Hash tags force keys to same slot
{user:1001}:profile → CRC16("user:1001") % 16384
{user:1001}:settings → CRC16("user:1001") % 16384
# Both go to same slot, enabling multi-key operations

Cluster Topology

┌─────────────────────────────────────────────────────┐
│                   Clients                            │
└───────────┬─────────────┬─────────────┬─────────────┘
            │             │             │
   ┌────────▼────────┐ ┌──▼──────────┐ ┌▼────────────┐
   │   Master A      │ │  Master B   │ │  Master C   │
   │  Slots 0-5460   │ │ 5461-10922  │ │ 10923-16383 │
   └────────┬────────┘ └──┬──────────┘ └┬────────────┘
            │             │             │
   ┌────────▼────────┐ ┌──▼──────────┐ ┌▼────────────┐
   │   Replica A1    │ │ Replica B1  │ │ Replica C1  │
   └─────────────────┘ └─────────────┘ └─────────────┘

2. CLUSTER INFO: Health Check

CLUSTER INFO gives you a quick health overview. The most important field is cluster_state.

CLUSTER INFO

127.0.0.1:6379> CLUSTER INFO
cluster_state:ok
cluster_slots_assigned:16384
cluster_slots_ok:16384
cluster_slots_pfail:0
cluster_slots_fail:0
cluster_known_nodes:6
cluster_size:3
cluster_current_epoch:6
cluster_my_epoch:2
cluster_stats_messages_sent:1234567
cluster_stats_messages_received:1234567

Key Fields

  • cluster_state - ok/fail
  • cluster_slots_assigned - Should be 16384
  • cluster_slots_ok - Healthy slots
  • cluster_size - Number of masters

Warning Signs

  • cluster_state:fail - Critical!
  • cluster_slots_pfail > 0 - Node may be down
  • cluster_slots_fail > 0 - Slots unavailable

3. CLUSTER NODES: Topology

CLUSTER NODES shows all nodes, their roles, slot assignments, and replication relationships.

CLUSTER NODES

127.0.0.1:6379> CLUSTER NODES
a1b2c3d4... 192.168.1.1:6379@16379 myself,master - 0 0 1 connected 0-5460
e5f6g7h8... 192.168.1.2:6379@16379 master - 0 1234567890 2 connected 5461-10922
i9j0k1l2... 192.168.1.3:6379@16379 master - 0 1234567891 3 connected 10923-16383
m3n4o5p6... 192.168.1.4:6379@16379 slave a1b2c3d4... 0 1234567892 1 connected
q7r8s9t0... 192.168.1.5:6379@16379 slave e5f6g7h8... 0 1234567893 2 connected
u1v2w3x4... 192.168.1.6:6379@16379 slave i9j0k1l2... 0 1234567894 3 connected

Field Breakdown

  • a1b2c3d4... - Node ID
  • 192.168.1.1:6379@16379 - Address (client@cluster bus)
  • myself,master - Flags (role, state)
  • 0-5460 - Slot range owned
  • slave a1b2c3d4... - Replica of node ID

4. CLUSTER SLOTS: Slot Map

CLUSTER SLOTS returns the slot-to-node mapping in a more structured format.

CLUSTER SLOTS

127.0.0.1:6379> CLUSTER SLOTS
1) 1) (integer) 0        # Start slot
   2) (integer) 5460     # End slot
   3) 1) "192.168.1.1"   # Master IP
      2) (integer) 6379  # Master port
      3) "a1b2c3d4..."   # Master node ID
   4) 1) "192.168.1.4"   # Replica IP
      2) (integer) 6379  # Replica port
      3) "m3n4o5p6..."   # Replica node ID
2) 1) (integer) 5461
   2) (integer) 10922
   ...

5. Key Operations in Cluster

Not all commands work the same in cluster mode. Multi-key operations require keys on the same node.

Which Slot for a Key?

# Find which slot a key belongs to
CLUSTER KEYSLOT mykey
(integer) 5798

# Find which slot for a hash tag
CLUSTER KEYSLOT {user:1001}:profile
(integer) 7568

# Count keys in a slot (on the node owning it)
CLUSTER COUNTKEYSINSLOT 5798
(integer) 42

CROSSSLOT Error

Commands like MGET, MSET, and transactions fail with CROSSSLOT error if keys are on different slots. Use hash tags to ensure related keys stay together: {user:1001}:profile and {user:1001}:settings.

6. Failover and Replicas

Replica Information

# See replicas of current node
CLUSTER REPLICAS <node-id>

# Manual failover (on replica)
CLUSTER FAILOVER
# Promotes this replica to master

# Force failover (when master is unreachable)
CLUSTER FAILOVER FORCE

# Check replication lag
INFO replication
# role:slave
# master_link_status:up
# master_last_io_seconds_ago:0
# slave_repl_offset:123456

7. Adding/Removing Nodes

Cluster Management

# Add a new node to cluster
CLUSTER MEET 192.168.1.7 6379

# Add node as replica of specific master
CLUSTER REPLICATE <master-node-id>

# Remove a node (after migrating its slots)
CLUSTER FORGET <node-id>

# Rebalance slots (redis-cli)
redis-cli --cluster rebalance 192.168.1.1:6379

Slot Migration

Moving slots is a careful process: CLUSTER SETSLOT commands migrate keys between nodes. Use redis-cli --cluster reshard for safe migrations.

8. Monitoring Cluster Health

Health Check Commands

# Overall health
CLUSTER INFO | grep cluster_state
cluster_state:ok

# Node states
CLUSTER NODES | grep -E "(fail|pfail)"
# Should return nothing if healthy

# Check specific node
CLUSTER INFO <node-id>

# Memory per node (run on each)
INFO memory | grep used_memory_human

Monitoring Checklist

  • • cluster_state is "ok"
  • • All 16384 slots assigned and healthy
  • • No nodes in fail/pfail state
  • • Replicas connected and synced
  • • Memory balanced across nodes
  • • No excessive redirections (MOVED/ASK)

9. CLI vs Redimo

CLI Challenges

  • • CLUSTER NODES output is hard to parse
  • • Need to connect to each node separately
  • • Manual tracking of which node has which keys
  • • No visual cluster topology

Redimo Benefits

  • • Single connection handles cluster routing
  • • See keys regardless of which node owns them
  • • Status bar shows cluster mode
  • • Automatic redirect handling

Quick Reference

CommandPurpose
CLUSTER INFOOverall cluster health
CLUSTER NODESAll nodes and their state
CLUSTER SLOTSSlot-to-node mapping
CLUSTER KEYSLOT keyWhich slot for a key
CLUSTER FAILOVERPromote replica to master
CLUSTER MEETAdd node to cluster

Manage Your Cluster

Cluster mode brings scalability and complexity. See your distributed data clearly with Redimo.

Download Redimo - It's Free

Continue Learning

Beginner

GET & SET

Store and retrieve string values - the foundation of Redis

Beginner

HSET & HGET

Store objects as field-value pairs without JSON serialization

Beginner

LPUSH & RPUSH

Ordered collections for queues, stacks, and activity feeds

Beginner

SADD & SMEMBERS

Unique collections with powerful set operations

Free Download

Stop Fighting with CLI.
Visualize Your Data.

Redimo makes every Valkey and Redis command easier. Visual data, inline editing, Safe Mode for production.