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

**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. The HH value must be 1 greater than the hh value. 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. The HH value must be 1 greater than the hh value. 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"
}