Creating a DB Instance¶
Function¶
This API is used to create a single RDS DB instance or a read replica.
URI¶
URI format
PATH: /v1.0/{project_id}/instances
Method: POST
Parameter description
Table 1 Parameter description¶ Name
Mandatory
Description
project_id
Yes
Specifies the project ID of a tenant in a region.
Restrictions
Currently, only the DB engines MySQL and PostgreSQL are supported by the API.
Request¶
Parameter description
Table 2 Parameter description¶ Name
Type
Description
instance
Dictionary data structure.
For details on the field description when creating a single DB instance, see Table 3.
For details on the field description when creating a read replica, see Table 4.
Specifies the detailed DB instance information.
Table 3 instance field data structure (creating a single DB instance)¶ Name
Mandatory
Type
Description
datastore
Yes
Dictionary data structure. For details, see Table 5.
Specifies the database information.
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 can contain only uppercase letters, lowercase letters, digits, underscores (_), and hyphens (-).
flavorRef
Yes
String
Specifies the specification ID (str_id in the response message in Table 3 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.
users
Yes
List data structure. For details, see Table 6.
Specifies the user information.
It must contain the administrator username (for mysql and postgres, the administrator username is root) and the administrator password.
volume
Yes
Dictionary data structure. For details, see Table 7.
Specifies the volume information.
configuration
No
String
Specifies the configuration parameter set used for initializing the database. For details about how to obtain this parameter value, see configurations.id in the response message in section Obtaining a Parameter Template List.
Valid value: The value cannot be empty. The string length and whether the string complying with UUID regular expression rules are verified.
databases
No
List data structure. For details, see Table 8.
Currently, this parameter is not supported.
modules
No
Array
Currently, this parameter is not supported.
nics
No
Array. For details, see Table 9.
Specifies the nics information. For details about how to obtain this parameter value, see section "Subnet" in the Virtual Private Cloud API Reference.
If this parameter is not specified, RDS will query the VPC, subnet, and security group of the tenant. By default, the first query result is the parameter value.
availability_zone
No
String
Specifies the AZ ID.
Valid value:
For details about how to obtain this parameter value, see Regions and Endpoints.
vpc
No
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.
restorePoint
No
Dictionary data structure. For details, see Table 10.
Specifies the configuration parameter for restoring data to a new DB instance.
Currently, this parameter is not supported.
cluster_config
No
Dictionary data structure. For details, see Table 11.
Currently, this parameter is not supported.
Table 4 instance field data structure description (creating a read replica)¶ Name
Mandatory
Type
Description
datastore
Yes
Dictionary data structure. For details, see Table 5.
Specifies the database information. Its value must be the same as the primary DB instance.
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 can contain only letters, digits, underscores (_), and hyphens (-).
flavorRef
Yes
String
Specifies the specification ID (str_id in the response message in Table 3 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 7.
Specifies the volume information. The volume information must be the same as that of the primary DB instance.
slave_of
No
String
Specifies the read replica configuration parameter. It is used to create a read replica of a primary DB instance specified by slave_of.
Valid value: The value cannot be empty. The string length and whether the string complying with UUID regular expression rules are verified. Only the primary DB instance ID is valid.
replica_of
Yes
String
Specifies the read replica configuration parameter. It is used to create a read replica of a primary DB instance specified by replica_of.
Valid value: The value cannot be empty. The string length and whether the string complying with UUID regular expression rules are verified. Only the primary DB instance ID is valid.
If both slave_of and replica_of exist, use replica_of first.
replica_count
No
Int
Specifies the number of read replicas.
Currently, creating multiple read replicas at a time is not supported.
Valid value: 1 or not contained in the request.
Table 5 datastore field data structure description¶ Name
Mandatory
Type
Description
type
Yes
String
Specifies the DB engine.
Currently, the DB engines MySQL and PostgreSQL are supported.
version
Yes
String
Specifies the database version.
MySQL databases support 5.6, 5.7 and 8.0. Example value: 5.7
PostgreSQL databases support 9.5, 9.6, 10, 11, 12, 13, 14 and 15. Example value: 9.6
For details about supported database versions, see section Database Version Queries.
Table 6 users field data structure description¶ Name
Mandatory
Type
Description
name
Yes
String
Specifies the database username. Currently, the database username for mysql and postgres is root.
password
Yes
String
Specifies the password of the database user.
The value cannot be empty and should contain 8 to 32 characters, including uppercase and lowercase letters, digits, and the following special characters:
~!@#%^*-_=+?If provided password will be considered by system as weak, you will receive an error and you should provide stronger password.
databases
No
Array
Currently, this parameter is not supported.
Table 7 volume field data structure description¶ Name
Mandatory
Type
Description
type
No
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.
Note
In the Trove API, this parameter is optional in the request. If this parameter is not contained in the request, its value is COMMON by default. If this parameter is specified, the volume type must be set to a value supported by the old API.
size
Yes
Int
Specifies the volume size in gigabytes (GB).
Its value must be a multiple of 10 and the value range is from 40 GB to 4000 GB.
Note
If the size is a decimal value, the system will round it down.
Table 8 databases field data structure description (not supported currently)¶ Name
Mandatory
Type
Description
name
Yes
String
Specifies the database name.
collate
No
String
Specifies the database code.
characterSet
No
String
Specifies the database code.
Table 9 nics field data structure description¶ Name
Mandatory
Type
Description
net-id
No
String
Specifies the subnet ID obtained from the VPC.
Valid value:
The value cannot be empty. The string length and whether the string complying with UUID regular expression rules are verified.
Note
RDS will query the VPC associated with the specified net-id, associate the VPC with the DB instance, and query the security group based on the VPC. Then, RDS sets the queried security group.
securityGroupId
No
String
Valid value:
The value cannot be empty. The string length and whether the string complying with UUID regular expression rules are verified.
Table 10 restorePoint field data structure description (not supported currently)¶ Name
Mandatory
Type
Description
backupRef
Yes
String
Specifies the full backup file.
Valid value: The value cannot be empty. The string length and whether the string complying with UUID regular expression rules are verified.
Table 11 cluster_config field data structure description (not supported currently)¶ Name
Mandatory
Type
Description
id
Yes
String
Specifies the cluster ID.
Request example
Creating a single DB instance:
{ "instance": { "datastore": { "type": "MySQL", "version": "MySQL-5.7" }, "name": "json-rack-instance", "flavorRef": "123", "users": [ { "name": "root", "password": "Demo@12345678" } ], "volume": { "size": 100 }, "configuration" : "ft26458f-d9f8-4cab-8fe1-cb8704fbo9bp", "nics":[ { "net-id": "3226458f-d9f8-4cab-8fe1-cb8704fb9fb8", "securityGroupId":"fpo6458f-d9f8-4cab-8fe1-cb8704fb9fb8" } ], "availability_zone": "az1pod1", "vpc":"98ik458f-d9f8-4cab-8fe1-cb8704fb9fbb" } }Creating a read replica:
{ "instance": { "datastore": { "type": "MySQL", "version": "MySQL-5.7" }, "name": "json-rack-instance", "flavorRef": "123", "volume": { "size": 100 }, "replica_of": "123", "replica_count":1 } }
Normal Response¶
Parameter description
Table 12 Parameter description¶ Name
Type
Description
instance
Dictionary data structure
Indicates the DB instance information.
Table 13 instance field data structure description¶ Name
Type
Description
status
String
Indicates the DB instance status.
updated
String
Indicates the DB instance updated time.
name
String
Instances the DB instance name. When a single DB instance is created, its name is automatically added with the suffix "_node0", for example, rds-test-openstack_node0.
links
List data structure. For details, see Table 14.
Indicates the DB instance information link.
created
String
Indicates the DB instance creation time.
id
String
Indicates the DB instance ID.
volume
Dictionary data structure. For details, see Table 15.
Indicates the DB instance volume information.
flavor
Dictionary data structure. For details, see Table 16.
Indicates the DB instance specifications.
datastore
Dictionary data structure. For details, see Table 17.
Indicates the DB engine information.
Table 14 links field data structure description¶ Name
Type
Description
href
String
Indicates the link address. Its value is "".
rel
String
Its value is self or bookmark.
Table 15 volume field data structure description¶ Name
Type
Description
size
Int
Indicates the volume size in GB.
Table 16 flavor field data structure description¶ Name
Type
Description
id
String
Indicates the specification ID.
links
List data structure. For details, see Table 14.
Indicates the DB instance specification link.
Table 17 datastore field data structure description¶ Name
Type
Description
type
String
Indicates the DB engine.
version
String
Indicates the database version, such as MySQL-5.6.33.
Response example
{ "instance": { "status": "BUILD", "updated": "2017-05-06T05:55:03", "name": "creat-trove-instance-28-MySQL-1-1", "links": [ { "href": "", "rel": "self" }, { "href": "", "rel": "bookmark" } ], "created": "2017-05-06T05:55:03", "id": "c90c1234-f687-462a-a6bd-cec35919c096", "volume": { "size": 100 }, "flavor": { "id": "99001234-dfc2-4418-b224-fea05d358ce3", "links": [ { "href": "", "rel": "self" }, { "href": "", "rel": "bookmark" } ] }, "datastore": { "type": "MySQL", "version": "MySQL-5.7" } } }
Abnormal Response¶
For details, see Abnormal Request Results.