Shard failover requests
REST API requests to fail over database shards
| Method | Path | Description |
|---|---|---|
| POST | /v1/shards/actions/failover |
Fail over multiple shards |
| POST | /v1/shards/{uid}/actions/failover |
Fail over a specific shard |
Fail over multiple shards
POST /v1/shards/actions/failover
Performs failover on the primary shards specified by shard_uids in the request body, and promotes their replicas to primary shards. This request is asynchronous.
The cluster automatically manages failover to ensure high availability. Use this failover REST API request only for testing and planned maintenance.
Required permissions
| Permission name | Roles |
|---|---|
| failover_shard | admin cluster_member db_member |
Request
Example HTTP request
POST /shards/actions/failover
Example JSON body
{
"shard_uids": ["2","4","6"]
}
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 primary shard UIDs to fail over. The shards must belong to the same database. |
| dead_uids | array of strings | Primary shards to avoid stopping. Optional. |
| dead_nodes | array of strings | Nodes that should not be drained or used for promoted replica shards. Optional. |
| dry_run | boolean | Determines whether the failover 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. Optional. |
| force_rebind | boolean | Rebind after promotion. Optional. |
| redis_version_upgrade | string | New version of the promoted primary shards. Optional. |
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": "Failover was triggered"
}
Status codes
| Code | Description |
|---|---|
| 200 OK | No error. |
| 400 Bad Request | Shard is a replica or the specified failover shards are not in the same database. |
| 404 Not Found | A list of shard UIDs is required and not given, or a specified shard does not exist. |
| 409 Conflict | Database is currently busy. |
Error codes
When errors are reported, the server may return a JSON object with error_code and message field that provide additional information. The following are possible error_code values:
| Code | Description |
|---|---|
| db_busy | Database is currently busy. |
| failover_shards_different_bdb | All failover shards should be in the same database. |
| shard_is_slave | Shard is a replica. |
| shard_not_exist | Shard does not exist. |
| shard_uids_required | List of shard UIDs is required and not given. |
Fail over shard
POST /v1/shards/{int: uid}/actions/failover
Performs failover on the primary shard with the specified shard_uid, and promotes its replica shard to a primary shard. This request is asynchronous.
The cluster automatically manages failover to ensure high availability. Use this failover REST API request only for testing and planned maintenance.
Required permissions
| Permission name | Roles |
|---|---|
| failover_shard | admin cluster_member db_member |
Request
Example HTTP request
POST /shards/1/actions/failover
Example JSON body
{
"force_rebind": true
}
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 fail over. |
Request body
The request body is a JSON object that can contain the following fields:
| Field | Type | Description |
|---|---|---|
| dead_uid | string | Primary shard to avoid stopping. Optional. |
| dead_nodes | array of strings | Nodes that should not be drained or used for promoted replica shards. Optional. |
| dry_run | boolean | Determines whether the failover 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. Optional. |
| force_rebind | boolean | Rebind after promotion. Optional. |
| redis_version_upgrade | string | New version of the promoted primary shards. Optional. |
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": "Failover was triggered"
}
Status codes
| Code | Description |
|---|---|
| 200 OK | No error. |
| 400 Bad Request | Shard is a replica. |
| 404 Not Found | Specified shard does not exist. |
| 409 Conflict | Database is currently busy. |
Error codes
When errors are reported, the server may return a JSON object with error_code and message field that provide additional information. The following are possible error_code values:
| Code | Description |
|---|---|
| db_busy | Database is currently busy. |
| shard_is_slave | Shard is a replica. |
| shard_not_exist | Shard does not exist. |