Cluster Mode
Architecture#
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Shard 0 │ │ Shard 1 │ │ Shard 2 │
│ slots 0-5460│ │ 5461-10922 │ │ 10923-16383 │
│ Primary + R │ │ Primary + R │ │ Primary + R │
└──────────────┘ └──────────────┘ └──────────────┘
↕ ↕ ↕
┌────────────────────────────────────────────────┐
│ cachly Smart Router (Proxy) │
└────────────────────────────────────────────────┘
↕
Your Application
Each shard holds a subset of the 16384 hash slots. cachly's smart proxy routes commands to the correct shard automatically — your application connects to a single endpoint.
Features#
| Feature | What it does |
|---|---|
| Linear Scaling | Add shards to increase throughput and memory linearly, with no single-node bottleneck |
| Automatic Failover | If a primary fails, its replica is promoted within seconds, with zero manual intervention |
| Smart Routing | cachly's proxy handles MOVED/ASK redirections transparently; your app sees one endpoint |
| Hash Tags | Use {tag} notation to colocate related keys on the same shard for multi-key operations |
| Per-Shard Metrics | Memory, ops/sec, and latency metrics broken down by shard in Grafana |
| Multi-Region Ready | Deploy replicas in different regions for read-local latency |
Enabling Cluster Mode#
Cluster Mode is available on the Pro and Enterprise tiers. Enable it when creating an instance:
POST /api/v1/instances
{
"name": "prod-cluster",
"engine": "valkey",
"tier": "pro",
"cluster": {
"enabled": true,
"shards": 3,
"replicas_per_shard": 1
}
}
Terraform example#
resource "cachly_instance" "cluster" {
name = "prod-cluster"
engine = "valkey"
tier = "pro"
cluster {
enabled = true
shards = 3
replicas_per_shard = 1
}
}See the Terraform Provider docs for the full provider reference.
Hash tags for key colocation#
By default, keys are distributed across shards by hashing the full key. Use {tag} notation to ensure related keys land on the same shard:
SET {user:42}:profile "..."
SET {user:42}:sessions "..."
SET {user:42}:prefs "..."
# All three keys colocate on the same shard → MULTI/EXEC works
Related#
Cluster Mode runs on the Valkey engine covered in Cache Engines. Provision clusters as code with the Terraform Provider.