Performs a master-replica switchover to switch node roles. This feature is applicable to disaster recovery drills and nearby access to applications that are deployed across zones.

Note For more information about nearby access to applications that are deployed across zones, see Switch node roles.

To call this operation, the ApsaraDB for Redis instance must be of Community Edition or Enhanced Edition (performance-enhanced instances or hybrid-storage instances).

After you call this operation:

  • The data nodes may change to the read-only state and become disconnected for a few seconds. Make sure that your applications are configured to automatically reconnect to the instance.
  • If an instance enters the Switching state, you cannot manage this instance. For example, you cannot modify the instance configurations or migrate the instance to another zone.


OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes SwitchInstanceHA

The operation that you want to perform. Set the value to SwitchInstanceHA.

InstanceId String Yes r-bp1zxszhcgatnx****

The ID of the instance. You can call the DescribeInstances operation to obtain instance IDs.

SwitchType String Yes AvailablePriority

The switching mode. Valid values:

  • AvailablePriority: prioritizes availability.
  • ReliabilityPriority: prioritizes reliability.
  • DataConsistency: prioritizes data consistency.
Note You must evaluate the requirements for data and services based on your business scenarios, and select a switching mode.
RegionId String No cn-hangzhou

The ID of the region where the instance is deployed. You can call the DescribeRegions operation to query region IDs.

NodeId String No r-bp1zxszhcgatnx****db-0,r-bp1zxszhcgatnx****db-1

The ID of the data node. Separate multiple IDs with commas (,).

  • This parameter is available only for read/write splitting instances or cluster instances of ApsaraDB for Redis.
  • You can call the DescribeLogicInstanceTopology operation to query node IDs. Remove the number sign (#) and the content that follows the queried data node ID. For example, keep only r-bp10noxlhcoim2****-db-0.
SwitchMode Integer No 0

The time when the switchover is performed. Valid values:

  • 0: immediately switches the roles. This is the default value.
  • 1: switches over the roles during a maintenance window.
Note You can call the ModifyInstanceMaintainTime operation to modify the maintenance window of an ApsaraDB for Redis instance.

Response parameters

Parameter Type Example Description
RequestId String 5D622714-AEDD-4609-9167-F5DDD3D1****

The ID of the request.


Sample requests

http(s):// Action=SwitchInstanceHA
&<Common request parameters>

Sample success responses

XML format


JSON format

	"RequestId": "5D622714-AEDD-4609-9167-F5DDD3D1****"

Error codes

For a list of error codes, visit the API Error Center.