Help Center/ Distributed Database Middleware/ API Reference/ APIs (Recommended)/ Schemas/ Configuring Shards (a V3 API)
Updated on 2026-05-30 GMT+08:00
View PDF
Share

Configuring Shards (a V3 API)

Function

This API is used to configure shards.

URI

POST /v3/{project_id}/instances/{instance_id}/databases/{db_name}/migration

Table 1 URI parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID of a tenant in a region

instance_id

Yes

String

DDM instance ID

db_name

Yes

String

Schema name

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

User token

The token can be obtained by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is the user token.
Table 3 Request body parameters

Parameter

Mandatory

Type

Description

data_nodes

Yes

Array of DataNode objects

Information about associated backend data nodes

switch_route_begin_time

No

String

Time when the automatic route switching starts (in the hh:mm:ss format, for example, 17:00:00). The start time must be earlier than the end time, and the interval cannot be less than 60 minutes. Switching routes during off-peak hours is recommended.

switch_route_end_time

No

String

Time when the automatic route switching ends (in the hh:mm:ss format, for example, 18:00:00). The end time must be later than the start time, and the interval cannot be less than 60 minutes. Switching routes during off-peak hours is recommended.

new_shard_number

Yes

String

Number of shards after the shard configuration.

The number of shards or data nodes after the configuration must be greater than that before the configuration. A single instance supports a maximum of 64 shards.

is_exclusive

No

Boolean

Whether shard configuration exclusively occupies a node. The default value is false. The value can be:

  • true: It exclusively occupies a node.
  • false: It does not exclusively occupy a node.
  • If this parameter is set to true, the execution node will be dedicated to configuring shards, so shard configuration is faster. If you are worried about not having enough nodes to handle your services, add more nodes before configuring shards.
  • If this parameter is set to true, you need to enable load balancing for the default group and ensure that the number of nodes exceeds one.
Table 4 DataNode

Parameter

Mandatory

Type

Description

id

Yes

String

Data node ID

user

Yes

String

Database user

  • Required permissions: SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, RELOAD, PROCESS, REFERENCES, INDEX, ALTER, SHOW DATABASES, CREATE TEMPORARY TABLES, LOCK TABLES, EXECUTE, REPLICATION SLAVE, REPLICATION CLIENT, CREATE VIEW, SHOW VIEW, CREATE ROUTINE, ALTER ROUTINE, CREATE USER, EVENT, TRIGGER WITH GRANT OPTION

password

Yes

String

Database password

Response Parameters

Status code: 202

Table 5 Response body parameters

Parameter

Type

Description

job_id

String

Task ID.

Status code: 400

Table 6 Response body parameters

Parameter

Type

Description

error_code

String

Error code

error_msg

String

Error message

Status code: 500

Table 7 Response body parameters

Parameter

Type

Description

error_code

String

Error code

error_msg

String

Error message

Example Request

{
  "new_shard_number" : 9,
  "data_nodes" : [ {
    "id" : "7edae0250ebc464897bd92b8d3e8b769in01",
    "user" : "root",
    "password" : "Pa**********4"
  } ]
}

Example Response

Status code: 202 
{
  "job_id":"xxxxxxxx-5d7e-4e1a-aeb4-9b1e6d0a4999"
}

Status code: 400

Bad request

{
  "error_msg" : "Parameter error.",
  "error_code" : "DBS.280001"
}

Status code: 500

Server error

{
  "error_msg" : "Parameter error.",
  "error_code" : "DBS.280001"
}

Status Codes

Status Codes

Description

202

OK

400

Bad request

500

Server error

Error Codes

For details, see Error Codes.

Parent topic: Schemas