• Relational Database Service

rds
  1. Help Center
  2. Relational Database Service
  3. API Reference
  4. API v1
  5. DB Instance Management
  6. Creating a DB Instance

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/{versionId}/{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.

    NOTICE:

    RDS for Microsoft SQL Server does not support creating primary/standby DB instances or 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 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, the default value is 3306.
    • For PostgreSQL, 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.

    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. The DB instance name of the same type must be unique for 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 MySQL 5.6 and 5.7. Example value: 5.7
    • PostgreSQL databases support PostgreSQL 9.5 and 9.6. Example value: 9.6
    • Microsoft SQL Server databases support Microsoft SQL Server 2014 SP2 SE. Example value: 2014_SP2_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.

    Table 7 nics field data structure description

    Name

    Mandatory

    Type

    Description

    subnetId

    Yes

    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.

    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.

    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": 8635,
            "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": 8635,
            "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 DB instance ID.

    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. For example, in the Beijing time zone, the time zone offset is shown as +0800.

    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 subnet ID.

    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": 8635,
            "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": 8635,
            "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": 8635,
            "dataStoreInfo": null,
            "extendparam": {
                "jobs": [
                    {
                        "id": "ff8080815564ddf5015564f64a560024"
                    }
                ]
            },
            "replica_of": "252f11f1-2912-4c06-be55-1999bde659c5"
        }
    }

Abnormal Response

For details, see Abnormal Request Results.