Creating a DB Instance¶
Function¶
This API is used to create a single DB instance, primary/standby DB instances, or a read replica.
URI¶
URI format
PATH: /rds/v1/{project_id}/instances
Method: POST
Parameter description
Table 1 Parameter description¶ Name
Mandatory
Description
versionId
Yes
Specifies the API version. It is case-sensitive and the value is v1.
project_id
Yes
Specifies the project ID of a tenant in a region.
Request¶
Parameter description
Table 2 Parameter description¶ Name
Type
Description
instance
Dictionary data structure.
For details on the field description when creating single or primary/standby DB instances, see Table 3.
For details on the field description when creating a read replica, see Table 4.
Specifies the detailed DB instance information.
Important
NOTICE: RDS for Microsoft SQL Server does not support creating read replicas.
Table 3 instance field data structure (creating single or primary/standby DB instances)¶ Name
Mandatory
Type
Description
name
Yes
String
Specifies the DB instance name.
DB instances of the same type can have same names under the same tenant.
Valid value:
The value must be 4 to 64 characters in length and start with a letter. It is case-insensitive and can contain only letters, digits, hyphens (-), and underscores (_).
datastore
Yes
Dictionary data structure. For details, see Table 5.
Specifies the database information.
flavorRef
Yes
String
Specifies the specification ID (flavors.id in the response message in section Obtaining All DB Instance Specifications).
Valid value:
The value cannot be empty. The string length and whether the string complying with UUID regular expression rules are verified.
volume
Yes
Dictionary data structure. For details, see Table 6.
Specifies the volume information.
region
Yes
String
Specifies the region ID.
Valid value:
The value cannot be empty. For details about how to obtain this parameter value, see Regions and Endpoints.
availabilityZone
Yes
String
Specifies the AZ ID.
Valid value:
The value cannot be empty. For details about how to obtain this parameter value, see Regions and Endpoints.
vpc
Yes
String
Specifies the VPC ID. For details about how to obtain this parameter value, see section "Virtual Private Cloud" in the Virtual Private Cloud API Reference.
Valid value:
The value cannot be empty. The string length and whether the string complying with UUID regular expression rules are verified.
nics
Yes
Dictionary data structure. For details, see Table 7.
Specifies the nics information. For details about how to obtain this parameter value, see section "Subnet" in the Virtual Private Cloud API Reference.
securityGroup
Yes
Dictionary data structure. For details, see Table 8.
Specifies the security group which the RDS DB instance belongs to.
For details about how to obtain this parameter value, see section "Security Group" in the Virtual Private Cloud API Reference.
dbPort
No
Int
Specifies the database port information.
The MySQL database port ranges from 1024 to 65535 (excluding 12017 and 33071, which are occupied by the RDS system and cannot be used).
The PostgreSQL database port ranges from 2100 to 9500.
The Microsoft SQL Server database port can be 1433 or ranges from 2100 to 9500, excluding 5355 and 5985.
If this parameter is not set, the default value is as follows:
For MySQL databases, the default value is 3306.
For PostgreSQL databases, the default value is 5432.
For Microsoft SQL Server, the default value is 1433.
backupStrategy
No
Dictionary data structure. For details, see Table 9.
Specifies the advanced backup policy.
dbRtPd
Yes
String
Specifies the password for user root of the database.
Valid value:
The value cannot be empty and should contain 8 to 32 characters, including uppercase and lowercase letters, digits, and the following special characters:
~!@#%^*-_=+?ha
No
Dictionary data structure. For details, see Table 10.
Specifies the HA configuration parameters, which are used when creating primary/standby DB instances.
Important
NOTICE: RDS for Microsoft SQL Server does not support creating primary/standby DB instances and this parameter is not involved.
Table 4 instance field data structure description (creating a read replica)¶ Name
Mandatory
Type
Description
name
Yes
String
Specifies the DB instance name.
DB instances of the same type can have same names under the same tenant.
Valid value:
The value must be 4 to 64 characters in length and start with a letter. It is case-insensitive and can contain only letters, digits, hyphens (-), and underscores (_).
flavorRef
Yes
String
Specifies the specification ID (flavors.id in the response message in section Obtaining All DB Instance Specifications).
Valid value:
The value cannot be empty. The string length and whether the string complying with UUID regular expression rules are verified.
replicaOf
Yes
String
Specifies the read replica configuration parameter. It is used to create a read replica of a primary DB instance specified by replicaOf
Valid value:
Only the primary DB instance ID is valid.
Table 5 datastore field data structure description¶ Name
Mandatory
Type
Description
type
Yes
String
Specifies the DB engine. Currently, the following DB engines are supported:
MySQL
PostgreSQL
SQLServer
version
Yes
String
Specifies the database version.
MySQL databases support 5.6, 5.7 and 8.0. Example value: 5.7
PostgreSQL databases support 11, 12, 13, 14, 15 and 16. Example value: 11
Microsoft SQL Server databases support 2017_SE, 2017_EE, 2019_SE, 2019_EE, 2022_SE and 2022_EE. Example value: 2017_SE
For details about supported database versions, see section Database Version Queries.
Table 6 volume field data structure description¶ Name
Mandatory
Type
Description
type
Yes
String
Specifies the volume type.
Its value can be any of the following and is case-sensitive:
COMMON: indicates the SATA type.
ULTRAHIGH: indicates the SSD type.
size
Yes
Int
Specifies the volume size.
Its value range is from 40 GB to 4000 GB. The value must be a multiple of 10.
Note
For read replicas, this parameter is invalid. The volume size is the same as that of the primary DB instance by default.
Table 7 nics field data structure description¶ Name
Mandatory
Type
Description
subnetId
Yes
String
Specifies the network ID of the subnet obtained from VPC.
Valid value:
The value cannot be empty. The string length and whether the string complying with UUID regular expression rules are verified.
Table 8 securityGroup field data structure description¶ Name
Mandatory
Type
Description
id
Yes
String
Valid value:
The value cannot be empty. The string length and whether the string complying with UUID regular expression rules are verified.
Table 9 backupStrategy field data structure description¶ Name
Mandatory
Type
Description
startTime
Yes
String
Specifies the backup start time that has been set.
Valid value:
The value cannot be empty. It must use the hh:mm:ss format and must be valid. The time is in the UTC format.
keepDays
No
Int
Specifies the number of days to retain the generated backup files.
The value range is from 0 to 732. If this parameter is not specified or set to 0, the automated backup policy is disabled. To extend the retention period, contact customer service. Automated backups can be retained for up to 2562 days.
Table 10 ha field data structure description¶ Name
Mandatory
Type
Description
enable
Yes
Boolean
Specifies the HA configuration parameter.
Valid value:
The value is true or false. The value true indicates creating primary/standby DB instances. The value false indicates creating a single DB instance.
replicationMode
Yes
String
Specifies the replication mode for the standby DB instance.
The value cannot be empty.
For MySQL, the value is async or semisync.
For PostgreSQL, the value is async or sync.
For Microsoft SQL Server, the value is sync.
Note
async indicates the asynchronous replication mode.
semisync indicates the semi-synchronous replication mode.
sync indicates the synchronous replication mode.
Request example
Creating a single DB instance:
{ "instance": { "name": "trove-instance-rep2", "datastore": { "type": "MySQL", "version": "5.7" }, "flavorRef": "bf07a6d4-844a-4023-a776-fc5c5fb71fb4", "volume": { "type": "ULTRAHIGH", "size": 100 }, "region": "eu-de", "availabilityZone": "eu-de-01", "vpc": "490a4a08-ef4b-44c5-94be-3051ef9e4fce", "nics": { "subnetId": "0e2eda62-1d42-4d64-a9d1-4e9aa9cd994f" }, "securityGroup": { "id": "2a1f7fc8-3307-42a7-aa6f-42c8b9b8f8c5" }, "dbPort": 3306, "backupStrategy": { "startTime": "01:00:00", "keepDays": 3 }, "dbRtPd": "Test@123" } }Creating primary/standby DB instances:
{ "instance": { "name": "trove-instance-ha", "datastore": { "type": "MySQL", "version": "5.7" }, "flavorRef": "bf07a6d4-844a-4023-a776-fc5c5fb71fb4", "volume": { "type": "ULTRAHIGH", "size": 100 }, "region": "eu-de", "availabilityZone": "eu-de-01", "vpc": "490a4a08-ef4b-44c5-94be-3051ef9e4fce", "nics": { "subnetId": "0e2eda62-1d42-4d64-a9d1-4e9aa9cd994f" }, "securityGroup": { "id": "2a1f7fc8-3307-42a7-aa6f-42c8b9b8f8c5" }, "dbPort": 3306, "backupStrategy": { "startTime": "01:00:00", "keepDays": 3 }, "dbRtPd": "Test@123", "ha": { "enable": true, "replicationMode": "async" } } }Creating a read replica:
{ "instance": { "name": "trove-instance-replica2", "flavorRef": "bf07a6d4-844a-4023-a776-fc5c5fb71fb4", "replicaOf": "373af3b8-8f44-44f6-bb90-85f1c32c50d6" } }
Normal Response¶
Parameter description
Table 11 Parameter description¶ Name
Type
Description
instance
Dictionary data structure. For details, see Table 12.
Indicates the DB instance information.
Table 12 instance field data structure description¶ Name
Type
Description
id
String
Indicates the primary node ID of the DB instance.
Note
This field is not the DB instance ID. You are advised to use API v3 and the DB instance ID to perform related operations.
status
String
Indicates the DB instance status. The value is BUILD.
name
String
Indicates the created DB instance name.
created
String
Indicates the creation time in the "yyyy-mm-dd Thh:mm:ssZ" format.
T is the separator between the calendar and the hourly notation of time. Z indicates the time zone offset.
Note
The value is empty when the DB instance is being created. After the DB instance is created, the value is not empty.
hostname
String
Indicates the DB instance connection address. It is a blank string.
type
String
Indicates the DB instance type, which can be master or readreplica.
region
String
Same as the request parameter.
updated
String
Indicates the updated time, which is the same as created.
Note
The value is empty when the DB instance is being created. After the DB instance is created, the value is not empty.
availabilityZone
String
Same as the request parameter.
vpc
String
Same as the request parameter.
nics
Dictionary data structure. For details, see Table 13.
Indicates the nics information.
securityGroup
Dictionary data structure. For details, see Table 14.
Indicates the security group information.
flavor
Dictionary data structure. For details, see Table 15.
Indicates the DB instance specifications.
volume
String
Same as the request parameter.
dbPort
Int
Same as the request parameter.
dataStoreInfo
Dictionary data structure
Indicates the database information.
Note
The value is null when the DB instance is being created. After the instance is created, the value is not null.
extendparam
Dictionary data structure. For details, see Table 16.
Indicates the returned extendparam key-value pair.
backupStrategy
Dictionary data structure. For details, see Table 18.
Indicates the backup policy.
slaveId
String
It is returned only when you create primary/standby DB instances.
ha
Dictionary data structure. For details, see Table 19.
Indicates the primary/standby DB instance information. It is returned only when you create primary/standby DB instances.
replica_of
String
Same as the request parameter. It is returned only when you create a read replica.
Table 13 nics field data structure description¶ Name
Type
Description
subnetId
String
Indicates the network ID of the subnet.
Table 14 securityGroup field data structure description¶ Name
Type
Description
id
String
Indicates the security group ID.
Table 15 flavor field data structure description¶ Name
Type
Description
id
String
Indicates the specification ID.
Table 16 extendparam field data structure description¶ Name
Type
Description
jobs
List data structure. For details, see Table 17.
Indicates the returned jobs parameter information.
Table 17 jobs field data structure description¶ Name
Type
Description
id
String
Indicates the task ID.
Table 18 backupStrategy field data structure description¶ Name
Type
Description
startTime
String
Indicates the backup start time that has been set. The backup task will be triggered within one hour after the backup start time.
keepDays
Int
Indicates the number of days to retain the generated backup files.
Table 19 ha field data structure description¶ Name
Type
Description
replicationMode
String
Indicates the replication mode for the standby DB instance. Same as the request parameter.
Response example
Creating a single DB instance:
{ "instance": { "id": "252f11f1-2912-4c06-be55-1999bde659c5", "status": "BUILD", "name": "trove-instance-rep3", "created": "", "hostname": "", "type": "master", "region": "eu-de", "updated": "", "availabilityZone": "eu-de-01", "vpc": "490a4a08-ef4b-44c5-94be-3051ef9e4fce", "nics": { "subnetId": "0e2eda62-1d42-4d64-a9d1-4e9aa9cd994f" }, "securityGroup": { "id": "2a1f7fc8-3307-42a7-aa6f-42c8b9b8f8c5" }, "flavor": { "id": "bf07a6d4-844a-4023-a776-fc5c5fb71fb4" }, "dbPort": 3306, "volume": { "type": "ULTRAHIGH", "size": 100 }, "dataStoreInfo": null, "extendparam": { "jobs": [ { "id": "ff8080815564ddf5015564f64a560024" } ] }, "backupStrategy": { "startTime": "01:00:00", "keepDays": 3 } } }Creating primary/standby DB instances:
{ "instance": { "id": "252f11f1-2912-4c06-be55-1999bde659c5", "status": "BUILD", "name": "trove-instance-rep3", "created": "", "hostname": "", "type": "master", "region": "eu-de", "updated": "", "availabilityZone": "eu-de-01", "vpc": "490a4a08-ef4b-44c5-94be-3051ef9e4fce", "nics": { "subnetId": "0e2eda62-1d42-4d64-a9d1-4e9aa9cd994f" }, "securityGroup": { "id": "2a1f7fc8-3307-42a7-aa6f-42c8b9b8f8c5" }, "flavor": { "id": "bf07a6d4-844a-4023-a776-fc5c5fb71fb4" }, "volume": { "type": "ULTRAHIGH", "size": 100 }, "dbPort": 3306, "dataStoreInfo": null, "extendparam": { "jobs": [ { "id": "ff8080815564ddf5015564f64a560024" }, { "id": "ae3081675564ddf5357564f64a560025" } ] }, "backupStrategy": { "startTime": "01:00:00", "keepDays": 3 }, "slaveId": "9405d8b8-a87d-4531-bd3a-e504c8434281", "ha": { "replicationMode": "async" } } }Creating a read replica:
{ "instance": { "id": "252f11f1-2912-4c06-be55-1999bde659c5", "status": "BUILD", "name": "trove-instance-rep3", "created": "", "hostname": "", "type": "readreplica", "region": "eu-de", "updated": "", "availabilityZone": "eu-de-01", "vpc": "490a4a08-ef4b-44c5-94be-3051ef9e4fce", "nics": { "subnetId": "0e2eda62-1d42-4d64-a9d1-4e9aa9cd994f" }, "securityGroup": { "id": "2a1f7fc8-3307-42a7-aa6f-42c8b9b8f8c5" }, "flavor": { "id": "bf07a6d4-844a-4023-a776-fc5c5fb71fb4" }, "volume": { "type": "ULTRAHIGH", "size": 100 }, "dbPort": 3306, "dataStoreInfo": null, "extendparam": { "jobs": [ { "id": "ff8080815564ddf5015564f64a560024" } ] }, "replica_of": "252f11f1-2912-4c06-be55-1999bde659c5" } }
Abnormal Response¶
For details, see Abnormal Request Results.