{ "schema_version": 2, "id": "commands/migrate", "title": "MIGRATE", "url": "https://redis.io/docs/latest/commands/migrate/", "summary": "Atomically transfers a key from one Redis instance to another.", "since": "2.6.0", "tags": [ "docs", "develop", "stack", "oss", "rs", "rc", "oss", "kubernetes", "clients" ], "last_updated": "2026-09-18T09:48:32+01:00", "page_type": "content", "content_hash": "3f3da7d1d6141a8b81c25780b6974913f9f52ae57a9b2b724b0dd6d1921440f3", "sections": [ { "id": "overview", "title": "Overview", "role": "overview", "text": "Atomically transfer a key from a source Redis instance to a destination Redis\ninstance.\nOn success the key is deleted from the original instance and is guaranteed to\nexist in the target instance.\n\nThe command is atomic and blocks the two instances for the time required to\ntransfer the key, at any given time the key will appear to exist in a given\ninstance or in the other instance, unless a timeout error occurs. In 3.2 and\nabove, multiple keys can be pipelined in a single call to `MIGRATE` by passing\nthe empty string (\"\") as key and adding the `KEYS` clause." }, { "id": "required-arguments", "title": "Required arguments", "role": "content", "text": "
host\n\nThe hostname or IP address of the destination Redis instance.\n\n
\n\n
port\n\nThe port of the destination Redis instance.\n\n
\n\n
key | \"\"\n\nThe key to migrate, or an empty string (`\"\"`) when migrating multiple keys with the `KEYS` option.\n\n
\n\n
destination-db\n\nThe database index to migrate the key into on the destination instance.\n\n
\n\n
timeout\n\nThe maximum idle time for the transfer, in milliseconds.\n\n
" }, { "id": "optional-arguments", "title": "Optional arguments", "role": "parameters", "text": "
COPY\n\nDo not remove the key from the local instance.\n\n
\n\n
REPLACE\n\nReplace an existing key on the destination instance.\n\n
\n\n
AUTH password\n\nAuthenticate to the destination instance with the given password. `AUTH` and `AUTH2` are mutually exclusive.\n\n
\n\n
AUTH2 username password\n\nAuthenticate to the destination instance with the given username and password (ACL-style auth, Redis 6 or later).\n\n
\n\n
KEYS key [key ...]\n\nMigrate all the listed keys. Use this when the key argument is an empty string (`\"\"`).\n\n
" }, { "id": "details", "title": "Details", "role": "content", "text": "The command internally uses [`DUMP`](https://redis.io/docs/latest/commands/dump) to generate the serialized version of the key\nvalue, and [`RESTORE`](https://redis.io/docs/latest/commands/restore) in order to synthesize the key in the target instance.\nThe source instance acts as a client for the target instance.\nIf the target instance returns OK to the [`RESTORE`](https://redis.io/docs/latest/commands/restore) command, the source instance\ndeletes the key using [`DEL`](https://redis.io/docs/latest/commands/del).\n\nThe timeout specifies the maximum idle time in any moment of the communication\nwith the destination instance in milliseconds.\nThis means that the operation does not need to be completed within the specified\namount of milliseconds, but that the transfer should make progresses without\nblocking for more than the specified amount of milliseconds.\n\n`MIGRATE` needs to perform I/O operations and to honor the specified timeout.\nWhen there is an I/O error during the transfer or if the timeout is reached the\noperation is aborted and the special error - `IOERR` returned.\nWhen this happens the following two cases are possible:\n\n* The key may be on both the instances.\n* The key may be only in the source instance.\n\nIt is not possible for the key to get lost in the event of a timeout, but the\nclient calling `MIGRATE`, in the event of a timeout error, should check if the\nkey is _also_ present in the target instance and act accordingly.\n\nWhen any other error is returned (starting with `ERR`) `MIGRATE` guarantees that\nthe key is still only present in the originating instance (unless a key with the\nsame name was also _already_ present on the target instance).\n\nIf there are no keys to migrate in the source instance `NOKEY` is returned.\nBecause missing keys are possible in normal conditions, from expiry for example,\n`NOKEY` isn't an error." }, { "id": "migrating-multiple-keys-with-a-single-command-call", "title": "Migrating multiple keys with a single command call", "role": "content", "text": "Starting with Redis 3.0.6 `MIGRATE` supports a new bulk-migration mode that\nuses pipelining in order to migrate multiple keys between instances without\nincurring in the round trip time latency and other overheads that there are\nwhen moving each key with a single `MIGRATE` call.\n\nIn order to enable this form, the `KEYS` option is used, and the normal *key*\nargument is set to an empty string. The actual key names will be provided\nafter the `KEYS` argument itself, like in the following example:\n\n MIGRATE 192.168.1.34 6379 \"\" 0 5000 KEYS key1 key2 key3\n\nWhen this form is used the `NOKEY` status code is only returned when none\nof the keys is present in the instance, otherwise the command is executed, even if\njust a single key exists." }, { "id": "redis-software-and-redis-cloud-compatibility", "title": "Redis Software and Redis Cloud compatibility", "role": "content", "text": "| Redis
Software | Redis
Cloud | Notes |\n|:----------------------|:-----------------|:------|\n| ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | |" }, { "id": "return-information", "title": "Return information", "role": "returns", "text": "**RESP2:**\n\nOne of the following:\n* [Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK` on success.\n* [Simple string reply](../../develop/reference/protocol-spec#simple-strings): `NOKEY` when no keys were found in the source instance.\n\n**RESP3:**\n\nOne of the following:\n* [Simple string reply](../../develop/reference/protocol-spec#simple-strings): `OK` on success.\n* [Simple string reply](../../develop/reference/protocol-spec#simple-strings): `NOKEY` when no keys were found in the source instance." } ], "examples": [] }