You need to enable JavaScript to run this app.
Cache for Redis

Cache for Redis

  • Documentation
    • Cache for RedisDevelopment reference (Control plane)API referenceInstance managementSwitchOver
Copy page
Download PDF
Instance management
SwitchOver
Copy page
Download PDF
SwitchOver

Call the SwitchOver API to perform primary-secondary node switchover for a specified instance.

Request type

Asynchronous request.

Precautions

  • The node being switched may experience a temporary disconnection lasting several seconds. We recommend that you switch it during off-peak hours and ensure that there is an automatic reconnection mechanism.
  • The node being switched may have a brief (less than 30 seconds) read-only state, which aims to avoid potential data loss risks caused by primary and secondary switchover and data double-write due to the DNS cache.

Request parameters

Name
Type
Required
Example
Description
InstanceId
String
Yes
redis-cn0212gzmh2xs****

Instance ID.

tip

  • Only primary-secondary instances (InstanceClass value is PrimarySecondary) support calling this API. Single-node instances (InstanceClass value is Standalone) do not support calling this API. For more information on the feature differences between two types of instances, refer to Feature differences.
  • You can call DescribeDBInstances to query the basic information of all Redis instances in a target region, including instance IDs.
TargetPrimaryNodeIds
String[]
No
["server-redis-cn0212gzmh2xs****-0-1"]

A list of secondary node IDs that need batch primary-secondary switchover.

tip

  • A batch primary switchover supports up to 50 shards simultaneously.
  • During a batch primary switchover, only one secondary node can be selected from per shard.
  • The TargetPrimaryNodeIds and TargetPrimaryNodeId parameters cannot both be empty. If both parameters are set, the value of TargetPrimaryNodeIds takes precedence.
  • The current role of the specified node must be secondary node (CurrentRole value is SecondaryNode).
  • Call the DescribeDBInstanceShards API to query the Server node details of each shard under a specified instance, including node ID and node role.
TargetPrimaryNodeId
String
No
server-redis-cn0212gzmh2xs****-0-1

The secondary node ID that requires primary/secondary switchover.

tip

  • The TargetPrimaryNodeIds and TargetPrimaryNodeId parameters cannot both be empty. If both parameters are set, the value of TargetPrimaryNodeIds takes precedence.
  • The current role of the specified node must be secondary node (CurrentRole value is SecondaryNode).
  • Call the DescribeDBInstanceShards API to query the Server node details of each shard under a specified instance, including node ID and node role.
ClientToken
String
No
WbiAlPqJM6tMoSOYhT****
To ensure the idempotence of requests and prevent duplicate submission of requests. The client generates the parameter values to ensure the uniqueness among different requests. Values are case-sensitive, no more than 127 ASCII characters.

Response parameters

The current API has no specified response parameters. For more information, refer to Response structure.

Request sample 

POST https://redis.cn-beijing.volcengineapi.com/?Action=SwitchOver&Version=2020-12-07 HTTP/1.1
Host: redis.cn-beijing.volcengineapi.com
Content-Type: application/json; charset=utf-8
X-Date: 20201103T104027Z
Authorization: HMAC-SHA256 Credential=AK****/20201103/cn-beijing/Redis/request,SignedHeaders=content-type;host;x-date,Signature=****
{
    "InstanceId": "redis-cn0212gzmh2xs****",
    "TargetPrimaryNodeIds": [
        "server-redis-cn0212gzmh2xs****-0-1"
    ]
}

Response sample 

{
    "ResponseMetadata": {
        "RequestId": "20230915202143DA8DBA604CA9E91C****",
        "Action": "SwitchOver",
        "Version": "2020-12-07",
        "Service": "Redis",
        "Region": "cn-beijing"
    },
    "Result": null
}

Error codes

For more information, refer to Error codes.

Last updated: 2026.04.14 10:59:24