Migrate shards requests
REST API requests to migrate database shards
| Method | Path | Description |
|---|---|---|
| POST | /v1/shards/actions/migrate |
Migrate multiple shards |
| POST | /v1/shards/{uid}/actions/migrate |
Migrate a specific shard |
Migrate multiple shards
POST /v1/shards/actions/migrate
Migrates the list of given shard UIDs to the node specified by target_node_uid. The shards can be from multiple databases. This request is asynchronous.
For more information about shard migration use cases and considerations, see Migrate database shards.
Required permissions
| Permission name | Roles |
|---|---|
| migrate_shard | admin cluster_member db_member |
Request
Example HTTP request
POST /shards/actions/migrate
Example JSON body
{
"shard_uids": ["2","4","6"],
"target_node_uid": 9,
"override_rack_policy": false,
"preserve_roles": false,
"max_concurrent_bdb_migrations": 3
}
Request headers
| Key | Value | Description |
|---|---|---|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |
Request body
The request body is a JSON object that can contain the following fields:
| Field | Type | Description |
|---|---|---|
| shard_uids | array of strings | List of shard UIDs to migrate. |
| target_node_uid | integer | UID of the node to where the shards should migrate. |
| override_rack_policy | boolean | If true, overrides and ignores rack-aware policy violations. |
| dry_run | boolean | Determines whether the migration is actually done. If true, will just do a dry run. If the dry run succeeds, the request returns a 200 OK status code. Otherwise, it returns a JSON object with an error code and description. |
| preserve_roles | boolean | If true, preserves the migrated shards' roles after migration. |
| max_concurrent_bdb_migrations | integer | The number of concurrent databases that can migrate shards. |
Response
Returns a JSON object with an action_uid. You can track the action's progress with a GET /v1/actions/<action_uid> request.
Example JSON body
{
"action_uid": "e5e24ddf-a456-4a7e-ad53-4463cd44880e",
"description": "Migrate was triggered"
}
Status codes
| Code | Description |
|---|---|
| 200 OK | No error. |
| 400 Bad Request | Conflicting parameters. |
| 404 Not Found | A list of shard UIDs is required and not given, a specified shard does not exist, or a node UID is required and not given. |
| 500 Internal Server Error | Migration failed. |
Migrate shard
POST /v1/shards/{int: uid}/actions/migrate
Migrates the shard with the given shard_uid to the node specified by target_node_uid. If the shard is already on the target node, nothing happens. This request is asynchronous.
For more information about shard migration use cases and considerations, see Migrate database shards.
Required permissions
| Permission name | Roles |
|---|---|
| migrate_shard | admin cluster_member db_member |
Request
Example HTTP request
POST /shards/1/actions/migrate
Example JSON body
{
"target_node_uid": 9,
"override_rack_policy": false,
"preserve_roles": false
}
Request headers
| Key | Value | Description |
|---|---|---|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |
URL parameters
| Field | Type | Description |
|---|---|---|
| uid | integer | The unique ID of the shard to migrate. |
Request body
The request body is a JSON object that can contain the following fields:
| Field | Type | Description |
|---|---|---|
| target_node_uid | integer | UID of the node to where the shard should migrate. |
| override_rack_policy | boolean | If true, overrides and ignores rack-aware policy violations. |
| dry_run | boolean | Determines whether the migration is actually done. If true, will just do a dry run. If the dry run succeeds, the request returns a 200 OK status code. Otherwise, it returns a JSON object with an error code and description. |
| preserve_roles | boolean | If true, preserves the migrated shards' roles after migration. |
Response
Returns a JSON object with an action_uid. You can track the action's progress with a GET /v1/actions/<action_uid> request.
Example JSON body
{
"action_uid": "e5e24ddf-a456-4a7e-ad53-4463cd44880e",
"description": "Migrate was triggered"
}
Status codes
| Code | Description |
|---|---|
| 200 OK | No error. |
| 404 Not Found | Shard does not exist, or node UID is required and not given. |
| 409 Conflict | Database is currently busy. |