{
  "schema_version": 2,
  "id": "operate/rs/databases/migrate-shards",
  "title": "Migrate database shards",
  "url": "https://redis.io/docs/latest/operate/rs/databases/migrate-shards/",
  "summary": "How to migrate database shards to other nodes in a Redis Software cluster.",
  "tags": [
    "docs",
    "operate",
    "rs"
  ],
  "last_updated": "2026-09-24T09:16:24+01:00",
  "page_type": "content",
  "content_hash": "61ac6cdfcb70c0f27a97d5c4a2cf0174787b5dc241b6e2d41059c6b30491f0df",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "To migrate database shards to other nodes in the cluster, you can use the [`rladmin migrate`](https://redis.io/docs/latest/operate/rs/references/cli-utilities/rladmin/migrate) command or [REST API requests](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/shards/actions/migrate)."
    },
    {
      "id": "use-cases-for-shard-migration",
      "title": "Use cases for shard migration",
      "role": "content",
      "text": "Migrate database shards to a different node in the following scenarios:\n\n- Before node removal.\n\n- To balance the database manually in case of latency issues or uneven load distribution across nodes.\n\n- To manage node resources, such as memory usage."
    },
    {
      "id": "considerations-for-shard-migration",
      "title": "Considerations for shard migration",
      "role": "content",
      "text": "For databases with replication:\n\n- Migrating a shard will not cause disruptions since a primary shard will still be available.\n\n- If you try to migrate a primary shard, it will be demoted to a replica shard and a replica shard will be promoted to primary before the migration. If you set `\"preserve_roles\": true` in the request, a second failover will occur after the migration finishes to change the migrated shard's role back to primary.\n\nFor databases without replication, the migrated shard will not be available until the migration is done.\n\nConnected clients shouldn't be disconnected in either case.\n\nIf too many primary shards are placed on the same node, it can impact database performance."
    },
    {
      "id": "migrate-specific-shard",
      "title": "Migrate specific shard",
      "role": "content",
      "text": "To migrate a specific database shard, use one of the following methods:\n\n- [`rladmin migrate shard`](https://redis.io/docs/latest/operate/rs/references/cli-utilities/rladmin/migrate#migrate-shard):\n\n    [code example]\n\n- [Migrate shard](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/shards/actions/migrate#post-shard) REST API request:\n\n    Specify the ID of the shard to migrate in the request path and the destination node's ID as the `target_node_uid` in the request body. See the [request reference](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/shards/actions/migrate#post-request-body) for more options.\n\n    [code example]\n\n    Example JSON response body:\n\n    [code example]\n\n    You can track the action's progress with a [`GET /v1/actions/<action_uid>`](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/actions#get-action) request."
    },
    {
      "id": "migrate-multiple-shards",
      "title": "Migrate multiple shards",
      "role": "content",
      "text": "To migrate multiple database shards, use one of the following methods:\n\n- [`rladmin migrate shard`](https://redis.io/docs/latest/operate/rs/references/cli-utilities/rladmin/migrate#migrate-shard):\n\n    [code example]\n\n- [Migrate multiple shards](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/shards/actions/migrate#post-multi-shards) REST API request:\n\n    Specify the IDs of the shards to migrate in the `shard_uids` list and the destination node's ID as the `target_node_uid` in the request body. See the [request reference](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/shards/actions/migrate#post-multi-request-body) for more options.\n\n    [code example]\n\n    Example JSON response body:\n\n    [code example]\n\n    You can track the action's progress with a [`GET /v1/actions/<action_uid>`](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/actions#get-action) request."
    },
    {
      "id": "migrate-all-shards-from-a-node",
      "title": "Migrate all shards from a node",
      "role": "content",
      "text": "To migrate all shards from a specific node to another node, run [`rladmin migrate all_shards`](https://redis.io/docs/latest/operate/rs/references/cli-utilities/rladmin/migrate#migrate-all_shards):\n\n[code example]"
    },
    {
      "id": "migrate-primary-shards",
      "title": "Migrate primary shards",
      "role": "content",
      "text": "You can use the [`rladmin migrate all_master_shards`](https://redis.io/docs/latest/operate/rs/references/cli-utilities/rladmin/migrate#migrate-all_master_shards) command to migrate all primary shards for a specific database or node to another node in the cluster.\n\nTo migrate a specific database's primary shards:\n\n[code example]\n\nTo migrate all primary shards from a specific node:\n\n[code example]"
    },
    {
      "id": "migrate-replica-shards",
      "title": "Migrate replica shards",
      "role": "content",
      "text": "You can use the [`rladmin migrate all_slave_shards`](https://redis.io/docs/latest/operate/rs/references/cli-utilities/rladmin/migrate#migrate-all_slave_shards) command to migrate all replica shards for a specific database or node to another node in the cluster.\n\nTo migrate a specific database's replica shards:\n\n[code example]\n\nTo migrate all replica shards from a specific node:\n\n[code example]"
    }
  ],
  "examples": [
    {
      "id": "migrate-specific-shard-ex0",
      "language": "sh",
      "code": "rladmin migrate shard <shard_id> target_node <node_id>",
      "section_id": "migrate-specific-shard"
    },
    {
      "id": "migrate-specific-shard-ex1",
      "language": "sh",
      "code": "POST /v1/shards/<shard_id>/actions/migrate\n    {\n        \"target_node_uid\": <node_id>\n    }",
      "section_id": "migrate-specific-shard"
    },
    {
      "id": "migrate-specific-shard-ex2",
      "language": "json",
      "code": "{\n        \"action_uid\": \"<action_id>\",\n        \"description\": \"Migrate was triggered\"\n    }",
      "section_id": "migrate-specific-shard"
    },
    {
      "id": "migrate-multiple-shards-ex0",
      "language": "sh",
      "code": "rladmin migrate shard <shard_id1> <shard_id2> <shard_id3> target_node <node_id>",
      "section_id": "migrate-multiple-shards"
    },
    {
      "id": "migrate-multiple-shards-ex1",
      "language": "sh",
      "code": "POST /v1/shards/actions/migrate\n    {\n        \"shard_uids\": [\"<shard_id1>\",\"<shard_id2>\",\"<shard_id3>\"],\n        \"target_node_uid\": <node_id>\n    }",
      "section_id": "migrate-multiple-shards"
    },
    {
      "id": "migrate-multiple-shards-ex2",
      "language": "json",
      "code": "{\n        \"action_uid\": \"<action_id>\",\n        \"description\": \"Migrate was triggered\"\n    }",
      "section_id": "migrate-multiple-shards"
    },
    {
      "id": "migrate-all-shards-from-a-node-ex0",
      "language": "sh",
      "code": "rladmin migrate node <origin_node_id> all_shards target_node <node_id>",
      "section_id": "migrate-all-shards-from-a-node"
    },
    {
      "id": "migrate-primary-shards-ex0",
      "language": "sh",
      "code": "rladmin migrate db db:<id> all_master_shards target_node <node_id>",
      "section_id": "migrate-primary-shards"
    },
    {
      "id": "migrate-primary-shards-ex1",
      "language": "sh",
      "code": "rladmin migrate node <origin_node_id> all_master_shards target_node <node_id>",
      "section_id": "migrate-primary-shards"
    },
    {
      "id": "migrate-replica-shards-ex0",
      "language": "sh",
      "code": "rladmin migrate db db:<id> all_slave_shards target_node <node_id>",
      "section_id": "migrate-replica-shards"
    },
    {
      "id": "migrate-replica-shards-ex1",
      "language": "sh",
      "code": "rladmin migrate node <origin_node_id> all_slave_shards target_node <node_id>",
      "section_id": "migrate-replica-shards"
    }
  ]
}