Skip to content
HotKVDocs

Ask the HotKV docs

Answers come only from these docs and can be wrong; check the linked pages before you rely on them.

CLUSTER GETSLOTMIGRATIONS

Last updated 
CLUSTER GETSLOTMIGRATIONS
Group
Cluster
Complexity
O(N) where N is the number of migrations listed
Arity
2 (exactly, counting the command name)
HotKV Cloud
Not available
On-Premise
no license needed

CLUSTER GETSLOTMIGRATIONS shows the atomic slot migrations this node has taken part in, as the source (an export) or as the target (an import), whether they were started with CLUSTER MIGRATESLOTS, with CLUSTER MIGRATION IMPORT or by redis-cli and valkey-cli. Use it to see how far a move has got, why one stopped, and which node to ask next. Both ends list the same migration under the same name, so ask the source and the target.

The newest migration comes first. A node keeps finished migrations too, up to cluster-slot-migration-log-max-len (default 1000).

Return value

Section titled “Return value”

An array with one entry per migration. Each entry is a map in RESP3 and a flat array of field and value pairs in RESP2. With no migrations the array is empty.

Field Type Meaning
name Bulk string The migration’s ID, 40 hexadecimal characters. A migration started with CLUSTER MIGRATION IMPORT carries that task ID.
operation Bulk string EXPORT on the source, IMPORT on the target
slot_ranges Bulk string The slots, as ranges separated by spaces, such as 100-149 200-249
target_node Bulk string The target’s node ID. A replica that only follows an import does not list it.
source_node Bulk string The source’s node ID. A replica that only follows an import does not list it.
create_time Integer When the migration was created, Unix time in seconds
last_update_time Integer Time of the last update, Unix time in seconds
last_ack_time Integer Time of the last acknowledgement from the other end, Unix time in seconds
state Bulk string Where the migration is (below)
message Bulk string Why the migration failed or was cancelled, and empty otherwise
cow_size Integer Kept for compatibility with Valkey’s field list. Expect 0.
remaining_repl_size Integer Bytes of writes an export has still to send, and 0 otherwise

States

Section titled “States”

On the source:

State Meaning
connecting, sending-auth-command, reading-auth-response, sending-establish-command, reading-establish-response Connecting to the target and signing in
waiting-to-snapshot, snapshotting Copying the slots
replicating Sending the writes made since the copy
waiting-to-pause, failover-paused, failover-granted Handing the slots over, with writes to them held for a moment
success, cancelled, failed Finished

On the target:

State Meaning
waiting-for-ack, receiving-snapshot Receiving the copy
waiting-for-paused, failover-requested, failover-granted Taking the slots over
cleaning-up Deleting what a migration that did not succeed brought
success, cancelled, failed Finished

A replica of the target shows the state occurring-on-primary while its primary imports.

Examples

Section titled “Examples”

One export that has finished, as RESP2 and then as RESP3:

127.0.0.1:7000> CLUSTER GETSLOTMIGRATIONS
1)  1) "name"
    2) "e98bd81974aa340bbf99db5c4a42d5db26765fdd"
    3) "operation"
    4) "EXPORT"
    5) "slot_ranges"
    6) "0-99"
    7) "target_node"
    8) "49a04a859cbe2f18b168fdff41f4f2346045f9e3"
    9) "source_node"
   10) "ea0c1bd255fc04ab7dfc3aabf682cb8f64f84cba"
   11) "create_time"
   12) (integer) 1791064153
   13) "last_update_time"
   14) (integer) 1791064153
   15) "last_ack_time"
   16) (integer) 1791064153
   17) "state"
   18) "success"
   19) "message"
   20) ""
   21) "cow_size"
   22) (integer) 0
   23) "remaining_repl_size"
   24) (integer) 0
$ redis-cli -3 --no-raw -p 7000 CLUSTER GETSLOTMIGRATIONS
1)  1# "name" => "e98bd81974aa340bbf99db5c4a42d5db26765fdd"
    2# "operation" => "EXPORT"
    3# "slot_ranges" => "0-99"
    4# "target_node" => "49a04a859cbe2f18b168fdff41f4f2346045f9e3"
    5# "source_node" => "ea0c1bd255fc04ab7dfc3aabf682cb8f64f84cba"
    6# "create_time" => (integer) 1791064153
    7# "last_update_time" => (integer) 1791064153
    8# "last_ack_time" => (integer) 1791064153
    9# "state" => "success"
   10# "message" => ""
   11# "cow_size" => (integer) 0
   12# "remaining_repl_size" => (integer) 0

A migration that was cancelled on the source, and what the target says about it:

127.0.0.1:7000> CLUSTER GETSLOTMIGRATIONS
1)  1) "name"
    2) "39fe0301eb56d86e0d5e94690b4008363bf347a5"
    ...
   17) "state"
   18) "cancelled"
   19) "message"
   20) ""
   ...
127.0.0.1:7001> CLUSTER GETSLOTMIGRATIONS
1)  1) "name"
    2) "39fe0301eb56d86e0d5e94690b4008363bf347a5"
    ...
   17) "state"
   18) "failed"
   19) "message"
   20) "Connection lost to source. Check CLUSTER GETSLOTMIGRATIONS on the source node for more information."
   ...

Compatibility

Section titled “Compatibility”

The fields, their order and the state names match Valkey 9.1. The same list also shows migrations started with Redis 8’s CLUSTER MIGRATION IMPORT, in these words; CLUSTER MIGRATION STATUS shows Valkey-style migrations in Redis’s words.

See also

Section titled “See also”

CLUSTER MIGRATESLOTS, CLUSTER CANCELSLOTMIGRATIONS, CLUSTER MIGRATION, CLUSTER INFO, Monitoring a cluster