CLUSTER-REPLICATE(3valkey)

📦
version 9.0.6 · 2 versions
, in fedora 44

💅 CLUSTER-REPLICATE — valkey command manual, but make it make sense

okay bestie, sit down, we're doing cluster surgery today 🩺✨

✨ NAME ✨

cluster-replicate — the glow-up (or the un-glow-up) command: it makes a node become a replica of a primary node, or detaches a replica from its primary. it's giving "you're with me now" energy. 🫶

🌸 SYNOPSIS 🌸

CLUSTER REPLICATE node-id
CLUSTER REPLICATE NO ONE

two moods, one command. pick your fighter. 💅

💖 DESCRIPTION 💖

so basically, this command reconfigures a node as a replica of the primary you specified. and here's the little plot twist: if the node receiving the command is an empty primary, then as a side effect of the command, that node's role gets changed from primary to replica. not me casually demoting myself 😭

once a node has been turned into the replica of another primary node, there is genuinely no need to go tell all the other cluster nodes about it — the heartbeat packets that nodes exchange between each other will propagate the new configuration automatically. no group chat announcement needed, the gossip handles it. periodt. 🦋

a replica will always accept the command, assuming that:

  1. The specified node ID exists in its nodes table.
  2. The specified node ID does not identify the instance we are sending the command to.
  3. The specified node ID is a primary.

(so like… the node ID has to be real, it can't be you, and it has to be a primary. three boxes, check them all bestie ✅)

now, if the node receiving the command is not already a replica but is a primary, then the command will only succeed — and the node will only get converted into a replica — if these additional conditions are also met:

  1. The node is not serving any hash slots.
  2. The node is empty, no keys are stored at all in the key space.
⚠️ okay this is the important part, lowkey highkey: a primary with slots or with keys in it will NOT be converted. it's empty-or-nothing. no cap. 💀

if the command succeeds, the new replica will immediately try to contact its primary in order to replicate from it. bestie is already on the phone, calling its new primary. 📞✨

🎀 REPLY 🎀

valkey-protocol(7) Simple string reply: OK if the command was successful. otherwise, an error is returned. that's it, that's the vibe check. 💖

🔥 COMPLEXITY 🔥

O(1) — constant time, queen. no scrolling required. 👑

🌈 ACL CATEGORIES 🌈

@admin @dangerous @slow

🚨 read that again: @admin, @dangerous, @slow. this is main character energy but also main character responsibility. be careful who you hand this power to.

⭐ HISTORY ⭐

  • Available since: 3.0.0
  • Changed in 9.0.0: Added support of NO ONE arg instead of resulting into detaching replica from primary node.

(it literally grew up. glow-up era. 🧚)

👑 SEE ALSO 👑

asking(3valkey), cluster(3valkey), cluster-addslots(3valkey), cluster-addslotsrange(3valkey), cluster-bumpepoch(3valkey), cluster-cancelslotmigrations(3valkey), cluster-count-failure-reports(3valkey), cluster-countkeysinslot(3valkey), cluster-delslots(3valkey), cluster-delslotsrange(3valkey), cluster-failover(3valkey), cluster-flushslots(3valkey), cluster-forget(3valkey), cluster-getkeysinslot(3valkey), cluster-getslotmigrations(3valkey), cluster-help(3valkey), cluster-info(3valkey), cluster-keyslot(3valkey), cluster-links(3valkey), cluster-meet(3valkey), cluster-migrateslots(3valkey), cluster-myid(3valkey), cluster-myshardid(3valkey), cluster-nodes(3valkey), cluster-replicas(3valkey), cluster-reset(3valkey), cluster-saveconfig(3valkey), cluster-set-config-epoch(3valkey), cluster-setslot(3valkey), cluster-shards(3valkey), cluster-slot-stats(3valkey), cluster-slots(3valkey), cluster-syncslots(3valkey), readonly(3valkey), readwrite(3valkey)

and that's the whole page bestie 💜 this little diva is from 9.0.0, dated 2025-10-21 — CLUSTER-REPLICATE(3valkey), the valkey command manual. now go forth and replicate responsibly, iykyk 🫶✨

📦 where this page comes from