Help Center/ GaussDB/ API Reference/ APIs (Recommended)/ Instance Management/ Switching Roles of the Primary and Standby DNs in Shards
Updated on 2025-08-11 GMT+08:00
View PDF
Share

Switching Roles of the Primary and Standby DNs in Shards

Function

This API is used to perform a primary/standby DN switchover for one or more shards. In a shard, only one standby node can be promoted to primary. Before calling this API:

URI

POST /v3/{project_id}/instances/{instance_id}/switch-shard
Table 1 Parameter description

Name

Mandatory

Description

project_id

Yes

Definition

Project ID of a tenant in a region.

To obtain the value, see Obtaining a Project ID.

Constraints

N/A

Range

The value can contain 32 characters. Only letters and digits are allowed.

Default Value

N/A

instance_id

Yes

Definition

Instance ID, which uniquely identifies an instance.

Constraints

N/A

Range

The value can contain 36 characters. Only letters and digits are allowed.

Default Value

N/A

Request Parameters

Table 2 Parameter description

Name

Mandatory

Type

Description

shards

Yes

Array

Definition

Nodes. You can switch standby DNs of multiple shards to primary DNs. The node information is the node IDs and component IDs of shards whose standby DNs are promoted to primary. For details, see Table 3.

Constraints

The maximum number of elements in the array is 1,000.
Table 3 shards parameter description

Name

Mandatory

Type

Description

node_id

Yes

String

Definition

ID of the node where the standby DN to be promoted to primary is deployed.

Constraints

N/A

Range

N/A

Default Value

N/A

component_id

Yes

String

Definition

ID of the standby DN to be promoted to primary. For details about how to obtain the component ID, see Querying the Components of a DB Instance.

Constraints

N/A

Range

It can contain up to 7 characters. It cannot be null, an empty string, or spaces. Before verifying and using it, spaces are automatically filtered out. It can contain at least three types of the following: uppercase letters, lowercase letters, digits, and underscores (_).

Default Value

N/A

Response Parameters

Table 4 Response parameters

Name

Type

Description

job_id

String

Definition

ID of the task for switching standby DNs of multiple shards to primary DNs.

Range

N/A

Example Request

Switching roles of primary and standby DNs in multiple shards 
POST https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3/0c8243400d37468bb4aed3cc94c2911d/instances/f9b5f9b296ec6808e067in14/switch-shard
{
 
    "shards": [
        {
            "node_id": "0bc478b4d132494a8f7b804da521b4b2no14",
            "component_id": "dn_6001"
        },
        {
            "node_id": "53dee94c50574d36a0060db0a6b644f6no14",
            "component_id": "dn_6004"
        }
    ]
}

Example Response

Roles of the primary and standby DNs in the shards switched. 
{
	"job_id": "e96bbb23-e053-4bd0-b0b7-16ad3f5d9b6d"
}

Status Code

Error Code

For details, see Error Codes.

Parent topic: Instance Management