MIGRATE(3valkey)

📦
version 9.0.6 · 2 versions
, in fedora 44

✨ MIGRATE ✨

okay bestie, buckle up, this is a 3valkey manual page and it's lowkey one of the most powerful moves in the whole book 💅

🌸 NAME 🌸

migrate — atomically transfers a key from one instance to another. no cap. it just picks the key up and moves it, and the whole thing is atomic, which is giving ✨main character✨ energy.

🎀 SYNOPSIS 🎀

MIGRATE host port <key | ""> destination-db timeout [COPY] [REPLACE]
[AUTH password | AUTH2 username password] [KEYS key [key...]]

💖 DESCRIPTION 💖

Atomically transfer a key from a source Valkey instance to a destination Valkey instance. On success the key is deleted from the original instance and is guaranteed to exist in the target instance. like. it's THERE. no takebacks, no leftovers 🫶

The command is atomic and blocks the two instances for the time required to transfer the key, at any given time the key will appear to exist in a given instance or in the other instance, unless a timeout error occurs. In 3.2 and above, multiple keys can be pipelined in a single call to MIGRATE by passing the empty string (““) as key and adding the KEYS clause. obsessed honestly.

The command internally uses valkey-dump(7) DUMP to generate the serialized version of the key value, and valkey-restore(7) RESTORE in order to synthesize the key in the target instance. The source instance acts as a client for the target instance. If the target instance returns OK to the RESTORE command, the source instance deletes the key using valkey-del(7) DEL. it's a whole little relay race 🏃♀️💨

The timeout specifies the maximum idle time in any moment of the communication with the destination instance in milliseconds. This means that the operation does not need to be completed within the specified amount of milliseconds, but that the transfer should make progress without blocking for more than the specified amount of milliseconds. so it's not "finish in X ms", it's "don't go quiet on me for more than X ms", okay? 🕐

MIGRATE operates on the database currently selected in the connection. Before calling MIGRATE, you can switch databases using valkey-select(7) SELECT <dbid>, and the command will migrate keys from that database. pick your db first, babe 💅

MIGRATE needs to perform I/O operations and to honor the specified timeout. When there is an I/O error during the transfer or if the timeout is reached the operation is aborted and the special error - IOERR returned. When this happens the following two cases are possible:

  • The key may be on both the instances.
  • The key may be only in the source instance.

It is not possible for the key to get lost in the event of a timeout, but the client calling MIGRATE, in the event of a timeout error, should check if the key is also present in the target instance and act accordingly. so like, the key can't just vanish, but YOU gotta go look. do your own vibe check 🔍

When any other error is returned (starting with ERR) MIGRATE guarantees that the key is still only present in the originating instance (unless a key with the same name was also already present on the target instance).

If there are no keys to migrate in the source instance NOKEY is returned. Because missing keys are possible in normal conditions, from expiry for example, NOKEY isn’t an error. it's not a flop, it's just... nothing was there 🥲

🦋 Migrating multiple keys with a single command call 🦋

MIGRATE supports a bulk-migration mode that uses pipelining in order to migrate multiple keys between instances without incurring in the round trip time latency and other overheads that there are when moving each key with a single MIGRATE call. literally the glow-up version.

In order to enable this form, the KEYS option is used, and the normal key argument is set to an empty string. The actual key names will be provided after the KEYS argument itself, like in the following example:

MIGRATE 192.168.1.34 6379 "" 0 5000 KEYS key1 key2 key3

When this form is used the NOKEY status code is only returned when none of the keys is present in the instance, otherwise the command is executed, even if just a single key exists. one little key and the whole thing goes 💫

🎀 OPTIONS 🎀

  • COPY — Do not remove the key from the local instance. keep a copy, share the wealth 💖
  • REPLACE — Replace existing key on the remote instance. no hesitation, no "but it's already there" 🙈
  • KEYS — If the key argument is an empty string, the command will instead migrate all the keys that follow the KEYS option (see the above section for more info). bulk mode activate ⚡
  • AUTH — Authenticate with the given password to the remote instance. 🔐
  • AUTH2 — Authenticate with the given username and password pair. 🔐👑 the upgraded version fr fr

🌈 REPLY 🌈

One of the following:

⭐ COMPLEXITY ⭐

This command actually executes a DUMP+DEL in the source instance, and a RESTORE in the target instance. See the pages of these commands for time complexity. Also an O(N) data transfer between the two instances is performed. so yeah, O(N), it's moving real data, not just vibes 🌸

💜 ACL CATEGORIES 💜

@dangerous @keyspace @slow @write

@dangerous is right there in the list bestie. this is a real one, be careful 💅

👑 HISTORY 👑

  • Available since: 2.6.0
  • Changed in 3.0.0: Added the COPY and REPLACE options.
  • Changed in 3.0.6: Added the KEYS option.
  • Changed in 4.0.7: Added the AUTH option.
  • Changed in 6.0.0: Added the AUTH2 option.

look at that glow-up timeline. she's been evolving since 2.6.0 🦋

🌸 SEE ALSO 🌸

copy(3valkey), del(3valkey), dump(3valkey), exists(3valkey), expire(3valkey), expireat(3valkey), expiretime(3valkey), keys(3valkey), move(3valkey), object(3valkey), object-encoding(3valkey), object-freq(3valkey), object-help(3valkey), object-idletime(3valkey), object-refcount(3valkey), persist(3valkey), pexpire(3valkey), pexpireat(3valkey), pexpiretime(3valkey), pttl(3valkey), randomkey(3valkey), rename(3valkey), renamenx(3valkey), restore(3valkey), scan(3valkey), sort(3valkey), sort_ro(3valkey), touch(3valkey), ttl(3valkey), type(3valkey), unlink(3valkey), wait(3valkey), waitaof(3valkey)

okay that's the whole page bestie, you ate it 💅✨ this was version 9.0.0, dated 2025-10-21, and that's the MIGRATE page fr fr — go move some keys responsibly 🫶🎀

📦 where this page comes from