Help Center/ Distributed Database Middleware/ API Reference/ APIs (Recommended)/ Schemas/ Creating a Schema (a V3 API)
Updated on 2026-05-30 GMT+08:00
Online Debugging
CLI Examples
View PDF
Share

Creating a Schema (a V3 API)

Function

This API is used to create a schema.

URI

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

Table 1 URI parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition

Project ID of a tenant in a region.

For details about how to obtain the project ID, see Obtaining a Project ID.

Constraints

N/A

Range

The value contains 32 characters. Only letters and digits are allowed.

Default Value

N/A

instance_id

Yes

String

Definition

Instance ID, which uniquely identifies an instance.

Constraints

N/A

Range

The value contains 36 characters with a suffix of in09. Only letters and digits are allowed.

Default Value

N/A

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

name

Yes

String

Schema name, which:

  • Can include 2 to 48 characters.

  • Must start with a lowercase letter.

  • Contains only lowercase letters, digits, and underscores (_).

  • Cannot be the following names:

information_schema, mysql, performance_schema, or sys

shard_mode

Yes

String

Sharding mode of the schema. The value can be:

  • cluster: indicates that the schema is in sharded mode.

  • single: indicates that the schema is in unsharded mode.

shard_number

Yes

Integer

Number of shards in the same working mode

  • If shard_unit is not empty, the value is the product of shard_unit multiplied by the associated data nodes.

  • If shard_unit is left blank, the value must be greater than the number of associated data nodes and less than or equal to the product of the associated data nodes multiplied by 64.

dn_instances

Yes

Array of DatabaseDnInstances objects

Data nodes associated with the schema. A maximum of 256 data nodes are supported.
Table 4 DatabaseDnInstances

Parameter

Mandatory

Type

Description

id

Yes

String

ID of the data node associated with the schema

user_name

Yes

String

Username for logging in to the associated data node

user_password

Yes

String

Password of the user for logging in to the associated data node

Response Parameters

Status code: 202

Table 5 Response body parameters

Parameter

Type

Description

name

String

Schema name.

job_id

String

Workflow 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

POST https://cn-north-1/v3/{project_id}/instances/{instance_id}/databases

{
  "name" : "mytestdb",
  "shard_mode" : "cluster",
  "shard_number" : 8,
  "dn_instances" : [ {
    "id" : "f296c394f13f48449d715bf99af07e59in01",
    "user_name" : "root",
    "user_password" : "PassWord_234"
  } ]
}

Example Response

Status code: 202

Success.

{
  "name" : "mytestdb",
  "job_id" : "0e20f87b-cb3a-4612-a2ae-16e3f04e1f4c"
}

Status code: 400

Bad request

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

Status code: 500

Server error

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

Status Codes

Status Codes

Description

202

Success.

400

Bad request

500

Server error

Error Codes

For details, see Error Codes.

Parent topic: Schemas