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

Pre-checking Shard Configuration (a V3 API)

Function

This API is used to pre-check shard configuration.

URI

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

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

Data node information after the configuration.

The number of shards or data nodes after the configuration must be greater than that before the configuration.

new_shard_number

Yes

String

Number of shards after the 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.

switch_route_begin_time

No

String

Start time of the route switchover

switch_route_end_time

No

String

End time of the route switchover

is_exclusive

No

Boolean

Whether dedicated nodes are used for shard configuration.
Table 4 DataNode

Parameter

Mandatory

Type

Description

id

Yes

String

Data node ID

user

Yes

String

Database user

password

Yes

String

Database password

Response Parameters

Status code: 202

Table 5 Response body parameters

Parameter

Type

Description

pre_check_results

Array of PreCheckResult objects

Information about associated backend data nodes

job_id

String

Workflow ID.
Table 6 PreCheckResult

Parameter

Type

Description

name

String

Check item name

status

String

Check result

note

String

Check item message

handling_suggestion

String

Handling suggestion

error_message

String

Error message

error_detail_message

String

Error details

Status code: 400

Table 7 Response body parameters

Parameter

Type

Description

error_code

String

Error code

error_msg

String

Error message

Status code: 500

Table 8 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" : "xxxxxx"
  } ]
}

Example Response

Status code: 202

{
  "job_id": "65c77858-e6a2-4694-8810-ab0b501b0003",
  "pre_check_results": [
    {
      "name": "Expire time of binlog in associated DN instances",
      "status": "SUCCESS",
      "note": "",
      "handling_suggestion": "Configuring shards require expiration of binlog more than 7 days(604800 seconds), please change binlog_expire_logs_seconds",
      "error_message": "",
      "error_detail_message": ""
    },
    {
      "name": "Tables with overwhelming table partitions",
      "status": "SUCCESS",
      "note": "",
      "handling_suggestion": "Every single row from source table will be recalculated and routed to all new partition table when shard number is changed. Because your partition table number will be overwhelming after configuring shard, shard configuring will take too long to finish. Please contact customer service.",
      "error_message": "",
      "error_detail_message": ""
    }
  ]
}

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