Updated on 2025-07-29 GMT+08:00

Creating a DB Instance

Function

This API is used to create a TaurusDB instance. Before calling this API:

URI

POST /v3/{project_id}/instances

Table 1 URI parameter

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition

Project ID of a tenant in a region.

To obtain this value, see Obtaining a Project ID.

Constraints

N/A

Range

The value contains 32 characters. 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

Definition

User token. To obtain this value, call the IAM API for obtaining a user token.

The value of X-Subject-Token in the response header is the token value.

Constraints

N/A

Range

N/A

Default Value

N/A

X-Language

No

String

Definition

Request language type.

Constraints

N/A

Range

  • en-us

  • zh-cn

Default Value

en-us

Table 3 Request body parameters

Parameter

Mandatory

Type

Description

region

Yes

String

Definition

Region ID.

Constraints

N/A

Range

For details, see Regions and Endpoints.

Default Value

N/A

name

Yes

String

Definition

Instance name.

Constraints

Instances of the same type can have the same name under the same tenant.

Range

The name must start with a letter and consist of 4 to 64 characters. Only letters (case-sensitive), digits, hyphens (-), and underscores (_) are allowed.

Default Value

N/A

datastore

Yes

MysqlDatastoreInReq object

Definition

Database information.

Constraints

N/A

mode

Yes

String

Definition

Instance type.

Constraints

Currently, only the cluster type is supported.

Range

Cluster

Default Value

N/A

flavor_ref

Yes

String

Definition

Specification code.

For details, see spec_code in Table 5 in Querying Database Specifications.

Constraints

N/A

Range

N/A

Default Value

N/A

vpc_id

Yes

String

Definition

VPC ID. To obtain this value, use either of the following methods:

  • Method 1: Log in to the VPC console and view the VPC ID on the VPC details page.

  • Method 2: Query the VPC ID through the VPC API. For details, see Querying VPCs.

Constraints

N/A

Range

N/A

Default Value

N/A

subnet_id

Yes

String

Definition

Subnet ID. To obtain this value, use either of the following methods:

  • Method 1: Log in to the VPC console and click the target subnet on the Subnets page. You can view the subnet ID on the displayed page.

  • Method 2: Query the subnet ID through the VPC API. For details, see Querying Subnets.

Constraints

N/A

Range

N/A

Default Value

N/A

password

Yes

String

Definition

Database password.

Constraints

You are advised to enter a strong password to improve security and prevent security risks such as brute force cracking. If you enter a weak password, the system automatically determines that the password is invalid.

Range

The password can consist of 8 to 32 characters and must contain at least three types of the following: uppercase letters, lowercase letters, digits, and special characters |.~!@#$%^*-_=+?,()&

Default Value

N/A

availability_zone_mode

Yes

String

Definition

AZ type.

Constraints

N/A

Range

  • single: single AZ

  • multi: multiple AZs

Default Value

N/A

slave_count

Yes

Integer

Definition

Number of read replicas.

Constraints

A maximum of nine read replicas can be created at a time.

Range

1–9

Default Value

N/A

charge_info

Yes

MysqlChargeInfo object

Definition

Billing mode, which is yearly/monthly or pay-per-use (default setting).

Constraints

You cannot create yearly/monthly instances in a DeC.

security_group_id

No

String

Definition

Security group ID. To obtain this value, use either of the following methods:

  • Method 1: Log in to VPC console. Choose Access Control > Security Groups in the navigation pane. On the displayed page, click the target security group. You can view the security group ID on the displayed page.

  • Method 2: Query the security group ID through the VPC API. For details, see Querying Security Groups.

Constraints

If a network ACL is enabled for the subnet used by the created instance, this parameter is optional. If a network ACL is not enabled, this parameter is mandatory.

Range

N/A

Default Value

N/A

configuration_id

No

String

Definition

Parameter template ID. For details, see id in Table 5 in Querying Parameter Templates.

Constraints

N/A

Range

N/A

Default Value

N/A

backup_strategy

Yes

MysqlBackupStrategy object

Definition

Automated backup policy.

Constraints

N/A

time_zone

No

String

Definition

Time zone.

Constraints

N/A

Range

All the full hours from UTC-11:00 to UTC+12:00.

Default Value

UTC

master_availability_zone

No

String

Definition

Primary AZ ID.

Constraints

This parameter is optional for a single-AZ instance and mandatory for a multi-AZ instance.

Range

For details, see Regions and Endpoints.

Default Value

N/A

volume

No

MysqlVolume object

Definition

Volume information.

Constraints

This parameter is only available for yearly/monthly instances. It is not available for pay-per-use instances.

tags

No

Array of MysqlTags objects

Definition

Tag list. Each instance can be associated with tag key–value pairs while being created.

Constraints

  • {key} indicates the tag key. It must be unique and cannot be empty.

  • {value} indicates the tag value, which can be empty.

If you want to create instances with multiple tag key–value pairs, separate them with commas (,). A maximum of 20 key–value pairs can be added for an instance.

lower_case_table_names

No

Integer

Definition

Whether table names are case sensitive.

Constraints

This parameter cannot be changed after the instance is created.

Range

  • 0: Table names are stored as specified and are case sensitive.

  • 1: Table names are stored in lowercase and are case insensitive.

Default Value

1

enterprise_project_id

No

String

Definition

Enterprise project ID.

Constraints

This parameter is mandatory when the enterprise project is enabled.

Range

N/A

Default Value

N/A

dedicated_resource_id

No

String

Definition

ID of the dedicated resource pool.

Constraints

This parameter is only available when the dedicated resource pool is enabled.

Range

N/A

Default Value

N/A

restore_point

No

MysqlRestorePoint object

Definition

Backup information.

Constraints

N/A

tde_info

No

MysqlTdeInfo object

Definition

TDE configuration. The AES-256 and SM4 algorithms are supported.

Constraints

TDE is in the open beta test (OBT) phase. To use it, submit a service ticket.

Table 4 MysqlDatastoreInReq

Parameter

Mandatory

Type

Description

type

Yes

String

Definition

DB engine.

Constraints

Only gaussdb-mysql is supported.

Range

gaussdb-mysql

Default Value

N/A

version

Yes

String

Definition

DB version.

Constraints

N/A

Range

Enter a two-number major version. For details about how to obtain the version, see the name field returned in Querying Version Information About a DB Engine.

Default Value

N/A

kernel_version

No

String

Definition

DB kernel version. If you need to specify a kernel version, contact customer service.

Constraints

N/A

Range

Enter a complete four-number kernel version. For details about how to obtain the value, see the kernel_version field returned in Querying Version Information About a DB Engine.

Default Value

N/A

Table 5 MysqlChargeInfo

Parameter

Mandatory

Type

Description

charge_mode

Yes

String

Definition

Billing mode.

Constraints

N/A

Range

  • prePaid: yearly/monthly
  • postPaid: pay-per-use

Default Value

postPaid

period_type

No

String

Definition

Subscription period type in yearly/monthly mode.

Constraints

This parameter is only available and mandatory when charge_mode is set to prePaid.

Range

  • month: The service is subscribed by month.

  • year: The service is subscribed by year.

Default Value

N/A

period_num

No

Integer

Definition

Subscription period in yearly/monthly mode.

Constraints

This parameter is only available and mandatory when charge_mode is set to prePaid.

Range

  • When period_type is set to month, the parameter value ranges from 1 to 9.

  • When period_type is set to year, the parameter value ranges from 1 to 3.

Default Value

N/A

is_auto_renew

No

String

Definition

Whether automatic renewal is enabled for yearly/monthly instances. The renewal period is the same as the original period and the order will be automatically paid during the subscription renewal.

Constraints

This parameter is only available when charge_mode is set to prePaid.

Range

  • true: Automatic renewal is enabled.

  • false: Automatic renewal is disabled.

Default Value

false

is_auto_pay

No

String

Definition

Whether the order will be automatically paid after yearly/monthly instances are created. This parameter does not affect the payment method of automatic renewal.

Constraints

This parameter is only available when charge_mode is set to prePaid.

Range

  • true: The order will be automatically paid.

  • false: The order will be manually paid.

Default Value

true

Table 6 MysqlBackupStrategy

Parameter

Mandatory

Type

Description

start_time

Yes

String

Definition

Automated backup start time. An automated backup will be triggered within one hour after the time specified by this parameter.

Constraints

N/A

Range

The value cannot be empty. It must be a valid value in the "hh:mm-HH:MM" format. The current time is the UTC time.

  1. The HH value must be 1 greater than the hh value.

  2. The values of mm and MM must be the same and must be set to 00.

Default Value

N/A

keep_days

No

String

Definition

Retention period of automated backups.

Constraints

The value must be a positive integer.

Range

1–732

Default Value

N/A

Table 7 MysqlVolume

Parameter

Mandatory

Type

Description

size

Yes

String

Definition

Disk size, in GB.

Constraints

The value must be an integer multiple of 10.

Range

10–128000

Default Value

10

Table 8 MysqlTags

Parameter

Mandatory

Type

Description

key

Yes

String

Definition

Tag key.

Constraints

It cannot be an empty string, a space, or left blank.

Range

The value contains a maximum of 36 Unicode characters. Only uppercase letters, lowercase letters, digits, hyphens (-), and underscores (_) are allowed.

Default Value

N/A

value

Yes

String

Definition

Tag value.

Constraints

It can be an empty string.

Range

The value contains a maximum of 43 Unicode characters. Only uppercase letters, lowercase letters, digits, hyphens (-), and underscores (_) are allowed.

Default Value

N/A

Table 9 MysqlRestorePoint

Parameter

Mandatory

Type

Description

source_instance_id

Yes

String

Definition

Source instance ID.

Constraints

N/A

Range

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

Default Value

N/A

restore_time

No

Long

Definition

Point in time when the backup is to be restored.

Constraints

The value is a Unix timestamp in milliseconds and represents UTC time. When specifying the parameter, convert the local time from your relevant time zone to a UTC timestamp first.

Range

To obtain this value, see Querying the Restoration Time Range.

Default Value

N/A

backup_id

No

String

Definition

Backup file ID.

Constraints

N/A

Range

N/A

Default Value

N/A

type

No

String

Definition

Backup type.

Constraints

If this parameter is left blank, backup_id cannot be left blank and data is restored using backup files by default.

Range

If this parameter is not left empty, the value can be:

  • backup: Data is restored using backups.

  • timestamp: Data is restored to a point in time.

Default Value

N/A

Table 10 MysqlTdeInfo

Parameter

Mandatory

Type

Description

enable_tde

Yes

Boolean

Definition

Whether to enable TDE.

Constraints

N/A

Range

  • true: TDE is enabled.

  • false: TDE is disabled.

Default Value

N/A

encryption_type

Yes

String

Definition

TDE algorithm.

Constraints

N/A

Range

  • AES256

  • SM4

Default Value

N/A

Response Parameters

Status code: 201

Table 11 Response body parameters

Parameter

Type

Description

instance

MysqlInstanceResponse object

Definition

Instance information.

job_id

String

Definition

ID of the task for creating an instance.

This parameter is only returned for pay-per-use instances.

Range

N/A

order_id

String

Definition

Order ID. This parameter is only returned for yearly/monthly instances.

Range

N/A

Table 12 MysqlInstanceResponse

Parameter

Type

Description

id

String

Definition

Instance ID.

Range

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

name

String

Definition

Instance name.

Range

The value is the same as the instance name in the request.

status

String

Definition

Instance status.

Range

N/A

datastore

MysqlDatastore object

Definition

Database information.

mode

String

Definition

Instance type.

Range

The value is the same as the instance type in the request.

configuration_id

String

Definition

Parameter template ID.

Range

N/A

port

String

Definition

Database port.

Range

N/A

backup_strategy

MysqlBackupStrategy object

Definition

Automated backup policy.

Constraints

N/A

enterprise_project_id

String

Definition

Enterprise project ID.

Range

The value is the same as the enterprise project ID in the request.

region

String

Definition

Region ID.

Range

The value is the same as the region ID in the request.

availability_zone_mode

String

Definition

AZ type.

Range

The value is the same as the AZ type in the request.

master_availability_zone

String

Definition

Primary AZ ID.

Range

The value is the same as the primary AZ ID in the request.

vpc_id

String

Definition

VPC ID, which is the same as the request parameter.

Range

The value is the same as the VPC ID in the request.

security_group_id

String

Definition

Security group ID, which is the same as the request parameter.

Range

The value is the same as the security group ID in the request.

subnet_id

String

Definition

Subnet ID, which is the same as the request parameter.

Range

The value is the same as the subnet ID in the request.

flavor_ref

String

Definition

Specification code.

Range

The value is the same as the specification code in the request.

charge_info

MysqlChargeInfo object

Definition

Billing mode, which is yearly/monthly or pay-per-use. By default, pay-per-use is used.

volume

MysqlVolumeResp object

Definition

Volume information. This parameter is only returned for yearly/monthly instances.

Table 13 MysqlDatastore

Parameter

Type

Description

type

String

Definition

DB engine.

Range

gaussdb-mysql

version

String

Definition

DB version.

Range

N/A

kernel_version

String

Definition

DB kernel version.

Range

N/A

Table 14 MysqlBackupStrategy

Parameter

Type

Description

start_time

String

Definition

Automated backup start time. An automated backup will be triggered within one hour after the time specified by this parameter.

Constraints

N/A

Range

The value cannot be empty. It must be a valid value in the "hh:mm-HH:MM" format. The current time is the UTC time.

  1. The HH value must be 1 greater than the hh value.

  2. The values of mm and MM must be the same and must be set to 00.

Default Value

N/A

keep_days

String

Definition

Retention period of automated backups.

Constraints

The value must be a positive integer.

Range

1–732

Default Value

N/A

Table 15 MysqlChargeInfo

Parameter

Type

Description

charge_mode

String

Definition

Billing mode.

Constraints

N/A

Range

  • prePaid: yearly/monthly

  • postPaid: pay-per-use

Default Value

postPaid

period_type

String

Definition

Subscription period type in yearly/monthly mode.

Constraints

This parameter is only available and mandatory when charge_mode is set to prePaid.

Range

  • month: The service is subscribed by month.

  • year: The service is subscribed by year.

Default Value

N/A

period_num

Integer

Definition

Subscription period in yearly/monthly mode.

Constraints

This parameter is only available and mandatory when charge_mode is set to prePaid.

Range

  • When period_type is set to month, the parameter value ranges from 1 to 9.

  • When period_type is set to year, the parameter value ranges from 1 to 3.

Default Value

N/A

is_auto_renew

String

Definition

Whether automatic renewal is enabled for yearly/monthly instances. The renewal period is the same as the original period and the order will be automatically paid during the subscription renewal.

Constraints

This parameter is only available when charge_mode is set to prePaid.

Range

  • true: Automatic renewal is enabled.

  • false: Automatic renewal is disabled.

Default Value

false

is_auto_pay

String

Definition

Whether the order will be automatically paid after yearly/monthly instances are created. This parameter does not affect the payment method of automatic renewal.

Constraints

This parameter is only available when charge_mode is set to prePaid.

Range

  • true: The order will be automatically paid.

  • false: The order will be manually paid.

Default Value

true

Table 16 MysqlVolumeResp

Parameter

Type

Description

size

Integer

Definition

Disk size, in GB.

Range

The value is an integer multiple of 10 and ranges from 10 to 128000.

Status code: 400

Table 17 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

Status code: 500

Table 18 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

Example Request

The value of region in the following is used as an example.

  • Creating a DB instance billed at a pay-per-use basis (An automated backup is created during 08:00-09:00.)
    POST https://{endpoint}/v3/054e292c9880d4992f02c0196d3ea468/instances
    {
      "name" : "gaussdb-mysql-instance1",
      "region" : "br-iaas-odin1",
      "charge_info" : {
        "charge_mode" : "postPaid"
      },
      "datastore" : {
        "type" : "gaussdb-mysql",
        "version" : "8.0"
      },
      "mode" : "Cluster",
      "flavor_ref" : "gaussdb.mysql.xlarge.arm.4",
      "vpc_id" : "3cedfc54-b105-4652-a4e0-847b11576b58",
      "subnet_id" : "c1cfa53c-65d3-431e-8552-326bf310c7ad",
      "security_group_id" : "fc577a1a-f202-424a-977f-24faec3fdd55",
      "configuration_id" : "43570e0de32e40c5a15f831aa5ce4176pr07",
      "password" : "*****",
      "backup_strategy" : {
        "start_time" : "08:00-09:00"
      },
      "availability_zone_mode" : "single",
      "slave_count" : 1,
      "enterprise_project_id" : 0
    }
  • Restoring data to a new pay-per-use DB instance using backups
    POST https://{endpoint}/v3/054e292c9880d4992f02c0196d3ea468/instances
    {
      "name" : "gaussdb-mysql-instance2",
      "region" : "br-iaas-odin1",
      "charge_info" : {
        "charge_mode" : "postPaid"
      },
      "datastore" : {
        "type" : "gaussdb-mysql",
        "version" : "8.0"
      },
      "mode" : "Cluster",
      "flavor_ref" : "gaussdb.mysql.xlarge.arm.4",
      "vpc_id" : "3cedfc54-b105-4652-a4e0-847b11576b58",
      "subnet_id" : "c1cfa53c-65d3-431e-8552-326bf310c7ad",
      "security_group_id" : "fc577a1a-f202-424a-977f-24faec3fdd55",
      "configuration_id" : "43570e0de32e40c5a15f831aa5ce4176pr07",
      "password" : "****",
      "backup_strategy" : {
        "start_time" : "08:00-09:00"
      },
      "availability_zone_mode" : "single",
      "slave_count" : 1,
      "enterprise_project_id" : 0,
       "restore_point" : { 
         "source_instance_id" : "7033e7c3cf93438797d44ad7ae0a7d95in07", 
         "backup_id" : "7ffbf305376b4cbea0ae491257b6aaf9br07", 
         "type" : "backup" 
       } 
    }
  • Restoring data to a new pay-per-use instance through point-in-time recovery (PITR)
    POST https://{endpoint}/v3/054e292c9880d4992f02c0196d3ea468/instances
    {
      "name" : "gaussdb-mysql-instance3",
      "region" : "br-iaas-odin1",
      "charge_info" : {
        "charge_mode" : "postPaid"
      },
      "datastore" : {
        "type" : "gaussdb-mysql",
        "version" : "8.0"
      },
      "mode" : "Cluster",
      "flavor_ref" : "gaussdb.mysql.xlarge.arm.4",
      "vpc_id" : "3cedfc54-b105-4652-a4e0-847b11576b58",
      "subnet_id" : "c1cfa53c-65d3-431e-8552-326bf310c7ad",
      "security_group_id" : "fc577a1a-f202-424a-977f-24faec3fdd55",
      "configuration_id" : "43570e0de32e40c5a15f831aa5ce4176pr07",
      "password" : "xxxxx",
      "backup_strategy" : {
        "start_time" : "08:00-09:00"
      },
      "availability_zone_mode" : "single",
      "slave_count" : 1,
      "enterprise_project_id" : 0,
       "restore_point" : { 
         "source_instance_id" : "7033e7c3cf93438797d44ad7ae0a7d95in07", 
         "restore_time" : 1673852043000, 
         "type" : "timestamp"
       } 
    }

Example Response

Status code: 201

The values of region and master_availability_zone are used as examples.

Success.

{
  "instance" : {
    "id" : "5eebbb4c0f9f4a99b42ed1b6334569aain07",
    "name" : "gaussdb-mysql-instance1",
    "status" : "BUILD",
    "region" : "br-iaas-odin1",
    "charge_info" : {
      "charge_mode" : "postPaid"
    },
    "datastore" : {
      "type" : "gaussdb-mysql",
      "version" : "8.0"
    },
    "mode" : "Cluster",
    "port" : "3306",
    "enterprise_project_id" : 0,
    "flavor_ref" : "gaussdb.mysql.xlarge.arm.4",
    "vpc_id" : "3cedfc54-b105-4652-a4e0-847b11576b58",
    "subnet_id" : "c1cfa53c-65d3-431e-8552-326bf310c7ad",
    "security_group_id" : "fc577a1a-f202-424a-977f-24faec3fdd55",
    "configuration_id" : "43570e0de32e40c5a15f831aa5ce4176pr07",
    "backup_strategy" : {
      "start_time" : "08:00-09:00",
      "keep_days" : 7
    },
    "availability_zone_mode" : "single"
  },
  "job_id" : "dff1d289-4d03-4942-8b9f-463ea07c000d"
}

Status Code

For details, see Status Codes.

Error Code

For details, see Error Codes.