Set up a cluster
KiviDB can run as a Redis-compatible cluster node. Cluster mode shards data across 16,384 hash slots and supports automatic failover.
Set up a KiviDB Cluster
KiviDB can run as a Redis-compatible cluster node. Cluster mode shards data across 16,384 hash slots and supports automatic failover.
Required flags
| Flag | Default | What it does |
|---|---|---|
--cluster-enabled <yes|no> | no | Enables cluster mode and opens the cluster bus on port + 10000. |
--cluster-node-timeout <ms> | 15000 | Failure detection timeout (lower for faster failover testing). |
--dir <path> | the current directory | Where the node keeps nodes.conf, dump.kdb and appendonly.aof. |
Each node needs its own directory. A node takes a lock (kividb.lock) on its directory, so a second node started in the same one waits for the lock and never accepts connections. Give every node its own --dir.
Single-node cluster (quick sanity check)
mkdir -p 7000
kividb --port 7000 --cluster-enabled yes --dir ./7000 &
# Claim all slots so the cluster reports healthy
redis-cli -p 7000 CLUSTER ADDSLOTSRANGE 0 16383
redis-cli -p 7000 CLUSTER INFO | grep cluster_state
Three-node local cluster
Start three nodes, each in its own directory:
mkdir -p 7000 7001 7002
kividb --port 7000 --cluster-enabled yes --dir ./7000 &
kividb --port 7001 --cluster-enabled yes --dir ./7001 &
kividb --port 7002 --cluster-enabled yes --dir ./7002 &
Form the cluster and split the slots:
redis-cli -p 7000 CLUSTER MEET 127.0.0.1 7001
redis-cli -p 7000 CLUSTER MEET 127.0.0.1 7002
redis-cli -p 7000 CLUSTER ADDSLOTSRANGE 0 5460
redis-cli -p 7001 CLUSTER ADDSLOTSRANGE 5461 10922
redis-cli -p 7002 CLUSTER ADDSLOTSRANGE 10923 16383
Or let redis-cli introduce the nodes and split the slots in one step (answer yes when it asks):
redis-cli --cluster create 127.0.0.1:7000 127.0.0.1:7001 127.0.0.1:7002 --cluster-replicas 0
Use a cluster-aware client:
redis-cli -c -p 7000 SET user:42 alice
redis-cli -c -p 7000 GET user:42
Cluster bus port
With --cluster-enabled yes, each node listens on:
- Client port:
--port(RESP commands) - Cluster bus port:
--port + 10000(gossip, heartbeat, elections)
Files written
Cluster mode writes nodes.conf in the node's --dir (the directory it was started in, without one) to persist the topology across restarts. Delete the directories to start over.