How Undermoon Enables Simple, Fast Redis Cluster Slot Migration

Undermoon is a self‑managed Redis Cluster system that implements slot migration using the Redis commands SCAN, DUMP, PTTL, RESTORE and DEL.

Project address: https://github.com/doyoubi/undermoon

Migration Overview

The SCAN command guarantees that all keys created before the first SCAN will eventually be returned, although duplicates may appear. Migration is performed in three phases:

Wait for the source Redis instance to finish all pending commands.

Redirect all read/write operations to the target Redis. If a key does not exist on the target, the target Redis DUMP s the key’s data from the source before processing the command.

Start scanning and forward the data to the peer Redis.

Detailed Steps

migrating proxy

runs a PreCheck to verify that the importing proxy has also received the migration task. migrating proxy blocks newly added commands into a Queue and waits for existing commands to finish. migrating proxy sends a TmpSwitch command to the importing proxy, which then begins processing the import of slots within the key range.

When the TmpSwitch reply arrives, migrating proxy releases the Queue and redirects its commands to the importing proxy. migrating proxy uses SCAN, PTTL, DUMP, RESTORE and DEL to forward all data in the slot range to the peer importing Redis. The RESTORE command is issued without the REPLACE flag. importing proxy processes each command as follows:

If EXISTS on the local importing Redis returns true, the command is forwarded to that Redis.

If EXISTS returns false, the proxy issues DUMP and PTTL to the migrating Redis, restores the data with RESTORE, and then forwards the original command.

For commands that do not delete a key, the operation is idempotent; multiple RESTORE calls on the same key are safe.

For delete‑prone commands such as DEL, EXPIRE or KPOP, the proxy first obtains a key lock, sends a UMSYNC to the migrating proxy, and then uses DUMP, PTTL, RESTORE and DEL to transfer the key, ensuring ordered handling.

After the scan completes, migrating proxy sends a CommitSwitch to the importing proxy, which then processes remaining commands locally.

The coordinator is notified and waits for the final UMCTL SETCLUSTER commit.

Design Rationale

The migration relies exclusively on the five commands listed above. Only the RESTORE command is sent to the importing server proxy, which improves performance because the heavy scanning and data transfer occur on the migrating proxy. Since both scanning and transfer consume significant CPU on the Redis instances, the design keeps most workload on the migrating proxy while moving slots early to the importing proxy.

For commands that may delete a key, pulling data only from the importing proxy could cause inconsistencies; therefore a lock and explicit data transfer are used. Idempotent commands are safe to restore multiple times without the REPLACE flag.

Performance

During migration, the migrating proxy consumes about 130% CPU, while the importing proxy uses roughly 80% CPU. Migrating 1 GB of data takes less than one minute.

Benchmarking while migrating shows throughput dropping from 50 k ops/s to 28 k ops/s, then rising to 40 k ops/s as keys are transferred. This drop is caused by the heavy SCAN, DUMP and RESTORE operations on the Redis nodes. Once a key is migrated, only an EXISTS check is needed, and after migration completes, throughput roughly doubles.