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
project_id
Yes
Specifies the project ID of a tenant in a region.

**Table 1** Parameter description¶
Name	Mandatory	Description
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. The DB instance name of the same type must be unique for the same tenant. Valid value: The parameter must be 4 to 64 characters long, start with a letter, and contain only letters (case-insensitive), 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. Obtain the parameter value from the enterprise administrator.
availabilityZone	Yes	String	Specifies the AZ ID. Valid value: The value cannot be empty. Obtain the parameter value from the enterprise administrator.
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.

**Table 4** instance field data structure description (creating a read replica)¶
Name	Mandatory	Type	Description
name	Yes	String	Specifies the DB instance name. The DB instance name of the same type must be unique for the same tenant. Valid value: The parameter must be 4 to 64 characters long, start with a letter, and contain only letters (case-insensitive), 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 and 5.7. Example value: 5.7 PostgreSQL databases support 9.5, 9.6, 10, and 11. Example value: 9.6 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: ULTRAHIGH: indicates the SSD type.
size	Yes	Int	Specifies the volume size. Its value range is from 40 GB to 4,000 GB. The value must be a multiple of 10. Important NOTICE: The volume size of the read replica must be greater than or equal to that of the primary DB instance.

**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 the administrator. 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.

Note

The values of region and availabilityZone are used as examples.

Request example

POST https://{Endpoint}/rds/v1/375d8d8fad1f43039e23d3b6c0f60a19/instances

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": "aaa",
        "availabilityZone": "bbb",
        "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": "aaa",
        "availabilityZone": "bbb",
        "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.
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.

Note

The values of region and availabilityZone are used as examples.

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": "aaa",
        "updated": "",
        "availabilityZone": "bbb",
        "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
        },
        "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": "aaa",
        "updated": "",
        "availabilityZone": "bbb",
        "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,
        "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": "aaa",
        "updated": "",
        "availabilityZone": "bbb",
        "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,

        "extendparam": {
            "jobs": [
                {
                    "id": "ff8080815564ddf5015564f64a560024"
                }
            ]
        },
        "replica_of": "252f11f1-2912-4c06-be55-1999bde659c5"
    }
}

Abnormal Response¶

For details, see Abnormal Request Results.

Status Code¶

For details, see Status Codes.

Error Code¶

For details, see Error Codes.

last updated: 2024-11-08 14:19 UTC - commit: aae1b12bfa160248d933bc69155302800af0d0fd