Creating a DB Instance
Function
This API is used to create a TaurusDB instance. Before calling this API:
- Learn how to authorize and authenticate it.
- Obtain the required region and endpoint.
URI
POST /v3/{project_id}/instances
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
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: Default value: en-us |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
region |
Yes |
String |
Definition: Region ID. Constraints: N/A Range: The value cannot be empty. Obtain the parameter value from the enterprise administrator. 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:
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:
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: 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). |
security_group_id |
No |
String |
Definition: Security group ID. To obtain this value, use either of the following methods:
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: The value cannot be empty. Obtain the parameter value from the enterprise administrator. Default value: N/A |
tags |
No |
Array of MysqlTags objects |
Definition: Tag list. Each instance can be associated with tag key–value pairs while being created. Constraints: 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:
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 |
restore_point |
No |
MysqlRestorePoint object |
Definition: Backup information. Constraints: N/A |
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 |
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. 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 |
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 |
Parameter |
Mandatory |
Type |
Description |
---|---|---|---|
source_instance_id |
Yes |
String |
Definition: Source instance ID. Constraints: N/A Range: The value can contain 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: Default value: N/A |
Response Parameters
Status code: 201
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 |
Parameter |
Type |
Description |
---|---|---|
id |
String |
Definition: Instance ID. Range: The value can contain 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. |
Parameter |
Type |
Description |
---|---|---|
type |
String |
Definition: DB engine. Range: gaussdb-mysql |
version |
String |
Definition: DB version. Range: N/A |
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. 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 |
Status code: 400
Parameter |
Type |
Description |
---|---|---|
error_code |
String |
Error code. |
error_msg |
String |
Error message. |
Status code: 500
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.
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.