Creating a DB Instance

Function

This API is used to create a GaussDB(for MySQL) DB 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 parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID of a tenant in a region. To obtain this value, see Obtaining a Project ID.

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	User token. If the following response body is returned for calling the API used to obtain a user token, the request is successful. After the request is processed, the value of X-Subject-Token in the message header is the token value.
X-Language	No	String	Request language type. The default value is en-us. Value: en-us zh-cn

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
region	Yes	String	Region ID. The value cannot be empty. To obtain this value, see Regions and Endpoints.
name	Yes	String	DB instance name. Instances of the same type can have same names under the same tenant. The name must start with a letter and consist of 4 to 64 characters. Only letters (case-sensitive), digits, hyphens (-), and underscores (_) are allowed.
datastore	Yes	MysqlDatastoreInReq object	Database information.
mode	Yes	String	Instance type. Currently, only the cluster type is supported.
flavor_ref	Yes	String	Specification code.
vpc_id	Yes	String	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: See "Querying VPCs" in the Virtual Private Cloud API Reference.
subnet_id	Yes	String	Network 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 network ID on the displayed page. Method 2: See "Querying Subnets" in the Virtual Private Cloud API Reference.
password	Yes	String	Database password. The password consists of 8 to 32 characters and contains at least three types of the following: uppercase letters, lowercase letters, digits, and special characters (~!@#$%^*-_=+?,()&). 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.
availability_zone_mode	Yes	String	AZ type. Value: single: single AZ multi: multiple AZs
slave_count	Yes	Integer	Number of read replicas. A maximum of nine read replicas can be created at a time.
charge_info	No	MysqlChargeInfo object	Billing mode, which is yearly/monthly or pay-per-use (default setting). Note: You cannot create yearly/monthly instances in a DeC.
security_group_id	No	String	Security group ID. If network ACL is enabled, this parameter cannot be specified. If network ACL is disabled, this parameter is mandatory. Method 1: Log in to VPC console. Choose Access Control > Security Groups in the navigation pane on the left. On the displayed page, click the target security group. You can view the security group ID on the displayed page. Method 2: See "Querying Security Groups" in the Virtual Private Cloud API Reference.
configuration_id	No	String	Parameter template ID.
backup_strategy	No	MysqlBackupStrategy object	Automated backup policy.
time_zone	No	String	Time zone. The default time zone is UTC.
master_availability_zone	No	String	Primary AZ. If availability_zone_mode is set to multi, this parameter is mandatory. If availability_zone_mode is set to single, this parameter cannot be specified.
volume	No	MysqlVolume object	Volume information. This parameter is optional during the creation of yearly/monthly instances.
tags	No	Array of MysqlTags objects	Tag list. Instances are created based on tag keys and values. {key} indicates the tag key. It must be unique and cannot be empty. {value} indicates the tag value, which can be empty. To create instances with multiple tag keys and values, separate key-value pairs with commas (,). Up to 10 key-value pairs can be added.
lower_case_table_names	No	Integer	Whether table names are case sensitive. The default value is 1. Value: 0: Table names are fixed and case-sensitive. 1: Table names are stored in lowercase and are case-insensitive.
enterprise_project_id	No	String	Enterprise project ID. This parameter is mandatory when the enterprise project is enabled.
dedicated_resource_id	No	String	Dedicated resource pool ID. This parameter is displayed only when the dedicated resource pool is enabled.
restore_point	No	MysqlRestorePoint object	Backup information.
tde_info	No	MysqlTdeInfo object	TDE configuration. The AES 256 and SM4 algorithms are supported. 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	DB engine. Currently, only gaussdb-mysql is supported.
version	Yes	String	DB version. A two-digit major version is returned. For details about how to obtain the version, see the name field returned by the Querying Version Information About a DB Engine.
kernel_version	No	String	DB kernel version. If you need to specify a kernel version, contact customer service. A complete 4-digital kernel version is returned. For details about how to obtain the value, see the kernel_version field returned by Querying Version Information About a DB Engine.

**Table 5** MysqlChargeInfo
Parameter	Mandatory	Type	Description
charge_mode	Yes	String	Billing mode. Valid value: prePaid: indicates the yearly/monthly billing mode. postPaid: indicates the pay-per-use billing mode.
period_type	No	String	Subscription period. Valid value: month: The service is subscribed by month. year: The service is subscribed by year. NOTE: This parameter is valid and mandatory if charge_mode is set to prePaid.
period_num	No	Integer	Subscription duration. This parameter is valid and mandatory if charge_mode is set to prePaid. Valid value: 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.
is_auto_renew	No	String	Whether automatic renewal is enabled for yearly/monthly DB instances. The renewal period is the same as the original period and the order will be automatically paid during the subscription renewal. true: indicates that automatic renewal is enabled. false: indicates that automatic renewal is disabled. The default value is false.
is_auto_pay	No	String	Whether the order will be automatically paid after yearly/monthly instances are created. This parameter does not affect the payment method of automatic renewal. true: indicates the order will be automatically paid. false: indicates the order will be manually paid. The default value is false.

**Table 6** MysqlBackupStrategy
Parameter	Mandatory	Type	Description
start_time	Yes	String	Automated backup start time. The automated backup will be triggered within one hour after the time specified by this parameter. The value cannot be empty. It must be a valid value in the "hh:mm-HH:MM" format. The current time is in the UTC format. 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. Example value: 21:00-22:00
keep_days	No	String	Retention period of automated backups. Value: 1 to 732

**Table 7** MysqlVolume
Parameter	Mandatory	Type	Description
size	Yes	String	Disk size. The default value is 10 GB. Value: 10 to 128000. The value must be a multiple of 10.

**Table 8** MysqlTags
Parameter	Mandatory	Type	Description
key	Yes	String	Tag key. It contains a maximum of 36 Unicode characters. The value cannot be an empty string, a space, or left blank. Only uppercase letters, lowercase letters, digits, hyphens (-), and underscores (_) are allowed.
value	Yes	String	Tag value. It contains a maximum of 43 Unicode characters. It can be an empty string. Only uppercase letters, lowercase letters, digits, periods (.), hyphens (-), and underscores (_) are allowed.

**Table 9** MysqlRestorePoint
Parameter	Mandatory	Type	Description
source_instance_id	Yes	String	Source instance ID.
restore_time	No	Long	Point in time that data is restored to.
backup_id	No	String	Backup file ID.
type	No	String	Backup type. If this parameter is left blank, backup_id cannot be left blank and data is restored using backup files by default. When the parameter is not empty, the value can be: backup: indicates that data is restored using backup files. timestamp: indicates that data is restored to a specified point of time.

**Table 10** MysqlTdeInfo
Parameter	Mandatory	Type	Description
enable_tde	Yes	Boolean	Whether to enable TDE.
encryption_type	Yes	String	TDE algorithm. The AES 256 and SM4 algorithms are supported.

Response Parameters

Status code: 201

**Table 11** Response body parameters
Parameter	Type	Description
instance	MysqlInstanceResponse object	Instance information.
job_id	String	ID of the task for creating a DB instance. This parameter is returned only when pay-per-use DB instances are created.
order_id	String	Order ID. This parameter is returned only when yearly/monthly instances are created.

**Table 12** MysqlInstanceResponse
Parameter	Type	Description
id	String	Instance ID.
name	String	DB instance name.
status	String	DB instance status.
datastore	MysqlDatastore object	Database information.
mode	String	DB instance type. Currently, only the cluster type is supported.
configuration_id	String	Parameter template ID.
port	String	Database port.
backup_strategy	MysqlBackupStrategy object	Automated backup policy.
enterprise_project_id	String	Enterprise project ID.
region	String	Region ID, which is the same as the request parameter.
availability_zone_mode	String	AZ mode, which is the same as the request parameter.
master_availability_zone	String	Primary AZ ID.
vpc_id	String	VPC ID, which is the same as the request parameter.
security_group_id	String	Security group ID, which is the same as the request parameter.
subnet_id	String	Subnet ID, which is the same as the request parameter.
flavor_ref	String	Specification code, which is the same as the request parameter.
charge_info	MysqlChargeInfo object	Billing mode, which is yearly/monthly or pay-per-use. By default, pay-per-use is used.
volume	MysqlVolumeResp object	Volume information. This parameter is returned when a yearly/monthly DB instance is created.

**Table 13** MysqlDatastore
Parameter	Type	Description
type	String	DB engine. Currently, only gaussdb-mysql is supported.
version	String	DB version. A two-digit major version is returned. For details about how to obtain the version, see the name field returned by the Querying Version Information About a DB Engine.
kernel_version	String	DB kernel version. A complete 4-digital kernel version is returned. For details about how to obtain the version, see the kernel_version field returned by the Querying Version Information About a DB Engine.

**Table 14** MysqlBackupStrategy
Parameter	Type	Description
start_time	String	Automated backup start time. The automated backup will be triggered within one hour after the time specified by this parameter. The value cannot be empty. It must be a valid value in the "hh:mm-HH:MM" format. The current time is in the UTC format. 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.
keep_days	String	Automated backup retention days. Value: 1-732.

**Table 15** MysqlChargeInfo
Parameter	Type	Description
charge_mode	String	Billing mode, which is yearly/monthly or pay-per-use.
period_type	String	Subscription period. Valid value: month: The service is subscribed by month. year: The service is subscribed by year. This parameter is valid and mandatory only when charge_mode is set to prePaid. Valid value: month year
period_num	Integer	This parameter is valid and mandatory only when charge_mode is set to prePaid. Valid value: 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.
is_auto_renew	String	Whether automatic renewal is enabled for yearly/monthly DB instances. The renewal period is the same as the original period and the order will be automatically paid during the subscription renewal. true: indicates that automatic renewal is enabled. false: indicates that automatic renewal is disabled. The default value is false.
is_auto_pay	String	Whether the order will be automatically paid after yearly/monthly instances are created. This parameter does not affect the payment method of automatic renewal. true: indicates the order will be automatically paid from your account. The default value is true. false: indicates the order will be manually paid.

**Table 16** MysqlVolumeResp
Parameter	Type	Description
size	Integer	Storage space in GB. Value: 10 to 128000. The value must be a multiple of 10.

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 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" : "xxxxx",
  "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 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"
}