VALKEY-ATOMIC-SLOT-MIGRATION(7)

💅 VALKEY-ATOMIC-SLOT-MIGRATION ✨

okay bestie, so this is the Valkey Manual page for valkey-atomic-slot-migration and it's literally about atomic slot migration and it's so good, you're gonna be obsessed 🫶

---

🌸 NAME 🌸

valkey-atomic-slot-migration — Atomic slot migration 💖

---

✨ DESCRIPTION ✨

So in valkey-cluster-spec(7) Valkey Cluster, there's this whole process called slot migration that you use to scale your cluster in or out. And during slot migration, one or more of the 16384 hash slots get moved from a source node to a target node. Classic.

Then Valkey 9.0 pulled up with a new option for migrating hash slots called atomic slot migration, and it's faster, more reliable, and has less impact on client applications than the legacy CLUSTER SETSLOT-based migration. it's giving glow-up, fr fr 💅

---

🎀 Performing an atomic slot migration using CLUSTER MIGRATESLOTS 🎀

Valkey 9.0 did not get rid of the legacy slot migration option — it just introduced atomic slot migration as a second option. Both can coexist, no drama. 😌

So to do an atomic slot migration, an operator does these steps:

1. Send <source> CLUSTER MIGRATESLOTS SLOTSRANGE <start-slot> <end-slot> NODE <target>
2. Poll <source> for progress using CLUSTER GETSLOTMIGRATIONS

CLUSTER MIGRATESLOTS kicks off a migration of the designated slot range to the specified target node. And then the slot migration process is performed asynchronously — so it goes off and does its thing, main character energy, no need to babysit it. ✨

For more details on CLUSTER MIGRATESLOTS see the cluster-migrateslots(3valkey).

---

🦋 Polling atomic slot migrations 🦋

The CLUSTER GETSLOTMIGRATIONS command is how you poll the status of your migration. You can run CLUSTER GETSLOTMIGRATIONS on either the source node or the target node — flexible, we love that. 💖

In-progress migrations will always be shown, and recently completed migrations will be visible up to a configurable threshold. And if something fails? The slot migration will also include a short description of the failure so you can make good decisions about whether to retry. no guessing, periodt 💀

For more details on CLUSTER GETSLOTMIGRATIONS see the cluster-getslotmigrations(3valkey).

---

🧚 Canceling atomic slot migrations 🧚

Need to cancel a slot migration after it already started? Been there. 🙈 Valkey gives you the CLUSTER CANCELSLOTMIGRATIONS command to cancel all active atomic slot migrations for which that node is the source node. And you can send this command to the whole cluster to cancel all slot migrations everywhere. one command, whole cluster, iconic 👑

For more details on CLUSTER CANCELSLOTMIGRATIONS see the cluster-cancelslotmigrations(3valkey).

---

💀 Behind the scenes of atomic slot migration 💀

Atomic slot migration uses a completely different process than CLUSTER SETSLOT-based migrations. Like, not even related. Here's the tea, step by step:

1. Immediately after CLUSTER MIGRATESLOTS is received by the source node, it initiates a connection to the target node and performs authentication, similar to how a replication link is initialized.
2. Once established, the source node uses a new internal command — CLUSTER SYNCSLOTS — to inform the target of the migration.
3. The source node then forks a child process to do a one-time snapshot of the slot contents. The fork iterates all hash slots and serializes their contents over the slot migration link. The contents are subsequently replicated to any replicas of the target node.
4. While the child process is doing the snapshot, the parent process tracks all mutations performed on the migrating hash slots.
5. Once the child process snapshot finishes, the parent process sends all accumulated mutations. Any new mutations received during this step are also sent.
6. Once the amount of in-flight mutations goes below a configured threshold, the parent process pauses write commands temporarily to allow final synchronization of the hash slots.
7. Once the target node is completely caught up, it takes over the hash slots and broadcasts ownership to the cluster.
8. When the source node finds out about the migration, it deletes the keys in the hash slot and unpauses write commands. Clients will now get MOVED redirections to the target node, which now owns the hash slots. The slot migration is completed. 🎉

ok that's a whole glow-up arc, from fork to takeover. ate and left no crumbs 💅

---

🌈 Isolation of importing hash slots from clients 🌈

Since slot ownership is not moved until the very end of the migration, commands targeting migrating hash slots on the target node will receive MOVED redirections per the cluster specification. That's just how it is.

But there are some commands that operate on the entire database, and those are the troublemakers:

1. KEYS/SCAN: These commands allow a client to list out all keys on a shard.
2. DBSIZE/INFO: These commands provide statistical information about how many keys are on a shard.
3. FLUSHDB/FLUSHALL: These commands allow a client to drop all data in a database, or on all databases, on a node.

To handle this, all importing hash slots are marked specially and hidden from read operations on both the target primary and the target replica. sneaky but make it correct ✨

FLUSHDB and FLUSHALL present a special case where we fail the slot migration when being executed on both the source and target node. ⚠️ It is expected that operators would retry the migration after flushing, which should now succeed almost instantly due to an empty database. lowkey a free win honestly 🍓

---

💜 Configuring atomic slot migration 💜

Some configurations may be worth tuning based on your workload. vibe check your cluster first, bestie:

• client-output-buffer-limit: Since atomic slot migration uses the replication process to migrate the slots, the amount of accumulated mutations while snapshotting could exceed that of the configured replication output buffer limit. Both the hard and soft limits of the replica client output buffer should be configured large enough to accumulate the accumulated mutations.
• slot-migration-max-failover-repl-bytes: By default, atomic slot migration will only proceed to pausing mutations on the source node once all in-flight mutations have been sent to the target node. However, for workloads with persistently high write throughput, atomic slot migration can be configured to do the pause so long as all in-flight mutations are under a given threshold.
• cluster-slot-migration-log-max-len: atomic slot migration keeps track of all in progress migrations and recently completed or failed migrations. These can be viewed with CLUSTER GETSLOTMIGRATIONS. The number of recently completed migrations stored can be increased using this configuration.

---

okay that's the whole page!! 💖

This one's from Valkey version 9.0.0, dated 2025-10-21, and it lives in the VALKEY-ATOMIC-SLOT-MIGRATION(7) manual. go migrate some slots bestie, you got this 🫶✨👑