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.

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.