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

FlagDefaultWhat it does
--cluster-enabled <yes|no>noEnables cluster mode and opens the cluster bus on port + 10000.
--cluster-node-timeout <ms>15000Failure detection timeout (lower for faster failover testing).
--dir <path>the current directoryWhere 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.