You can call the CreateDBInstance operation to create an ApsaraDB RDS instance.

Before you call this operation, make sure that you understand the billing methods and pricing of ApsaraDB RDS. For more information, see Pricing, billable items, and billing methods.

For more information about ApsaraDB RDS instance types, see Primary ApsaraDB RDS instance types.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes CreateDBInstance

The operation that you want to perform. Set the value to CreateDBInstance.

DBInstanceClass String Yes rds.mysql.s1.small

The instance type of the RDS instance. For more information, see Primary ApsaraDB RDS instance types. You can call the DescribeAvailableResource operation to query the available instance types in a region.

DBInstanceNetType String Yes Internet

The type of network that is used to connect to the instance. Valid values:

  • Internet: The instance is connected over the Internet.
  • Intranet: The instance is connected over an internal network.
DBInstanceStorage Integer Yes 20

The storage capacity of the instance. Unit: GB. The storage capacity increases in increments of 5 GB. For more information, see Primary ApsaraDB RDS instance types. You can call the DescribeAvailableResource operation to query the storage capacity range that is supported for a specified instance type in a region.

Engine String Yes MySQL

The database engine that is run on the instance. Valid values:

  • MySQL
  • SQLServer
  • PostgreSQL
  • PPAS
  • MariaDB TX
EngineVersion String Yes 5.6

The version of the database engine that is run on the instance. Valid values:

  • MySQL: 5.5, 5.6, 5.7, and 8.0
  • SQL Server: 2008r2, 08r2_ent_ha, 2012, 2012_ent_ha, 2012_std_ha, 2012_web, 2014_std_ha, 2016_ent_ha, 2016_std_ha, 2016_web, 2017_std_ha, 2017_ent, 2019_std_ha, and 2019_ent
  • PostgreSQL: 9.4, 10.0, 11.0, 12.0, and 13.0
  • PPAS: 9.3 and 10.0
  • MariaDB TX: 10.3
PayType String Yes Postpaid

The billing method of the instance. Valid values:

  • Postpaid: pay-as-you-go
  • Prepaid: subscription
Note The system automatically generates a purchase order and completes the payment.
RegionId String Yes cn-hangzhou

The region ID of the instance. You can call the DescribeRegions operation to query the most recent region list.

SecurityIPList String Yes 10.23.12.27/24

The IP address whitelist of the instance. For more information, see Configure an IP address whitelist for an ApsaraDB RDS for MySQL instance. If the IP address whitelist contains more than one entry, separate the entries with commas (,). Each entry must be unique. The IP address whitelist can contain up to 1,000 entries. The entries in the IP address whitelist must be in one of the following formats:

  • IP address. Example: 10.23.12.24.
  • CIDR block. Example: 10.23.12.24/24. In the example provided, 24 specifies that the prefix of each IP address is 24 bits in length. You can replace 24 with a value within the range of 1 to 32.
SystemDBCharset String No gbk

The character set that is used for the instance. This parameter is deprecated.

DBInstanceDescription String No Test database

The name of the instance. The name must be 2 to 255 characters in length and must start with a letter. The name can contain letters, digits, underscores (_), and hyphens (-).

Note The name cannot start with http:// or https://.
ClientToken String No ETnLKlblzczshOTUbOCzxxxxxxxxxx

The client token that is used to ensure the idempotence of the request. You can use the client to generate the value, but you must ensure that it is unique among different requests. The token can only contain ASCII characters and cannot exceed 64 characters in length.

ZoneId String No cn-hangzhou-b

The zone ID of the primary instance.

Note
  • If you specify a virtual private cloud (VPC) and a vSwitch, you must specify the ZoneId parameter.
  • If you specify the RDS High-availability Edition, you must also specify the ZoneIdSlave1 parameter, which specifies whether to use the single-zone deployment method or the multi-zone deployment method.
  • If you specify the RDS Enterprise Edition, you must also specify the ZoneIdSlave1 and ZoneIdSlave2 parameters, which specify whether to use the single-zone deployment method or the multi-zone deployment method.
ZoneIdSlave1 String No cn-hangzhou-c

The zone ID of the secondary instance. If you set the ZoneIdSlave1 parameter to the same value as the ZoneId parameter, the single-zone deployment method is used. If you set the ZoneIdSlave1 parameter to a different value than the ZoneId parameter, the multi-zone deployment method is used.

ZoneIdSlave2 String No cn-hangzhou-d

The zone ID of the logger instance. If you set the ZoneIdSlave2 parameter to the same value as the ZoneId parameter, the single-zone deployment method is used. If you set the ZoneIdSlave2 parameter to a different value than the ZoneId parameter, the multi-zone deployment method is used.

InstanceNetworkType String No Classic

The type of network in which the instance resides. Valid values:

  • VPC: VPC.
  • Classic: classic network. This is the default value.
Note
  • If you specify standard SSDs or enhanced SSDs (ESSDs), you can specify only the VPC network type. For example, if you want to create an instance that runs the RDS Basic Edition, you must set the InstanceNetworkType parameter to VPC.
  • If you set the Engine parameter to MariaDB, you must specify the InstanceNetworkType parameter.
ConnectionMode String No Standard

The mode that is used to connect to the instance. Valid values:

  • Standard: The instance is connected in standard mode.
  • Safe: The instance is connected in database proxy mode.

The system automatically sets the connection mode of the instance.

Note SQL Server 2012, SQL Server 2016, and SQL Server 2017 support only the standard mode.
VPCId String No vpc-xxxxxxxxxxxx

The ID of the VPC to which the instance belongs.

Note If you set the InstanceNetworkType parameter to VPC, you must specify the VPCId parameter.
VSwitchId String No vsw-xxxxxxxxxxx

The ID of the vSwitch associated with the specified VPC. If you specify more than one vSwitch ID, separate the vSwitch IDs with commas (,).

Note If you set the InstanceNetworkType parameter to VPC, you must specify the VSwitchId parameter.
PrivateIpAddress String No 172.16.201.69

The private IP address of the instance. The private IP address must be within the CIDR block that is supported by the specified vSwitch. The system automatically assigns a private IP address to the instance based on the values of the VPCId and VSwitchId parameters.

UsedTime String No 2

The subscription period of the instance. Valid values:

  • If you set the Period parameter to Year, the value of the UsedTime parameter ranges from 1 to 5.
  • If you set the Period parameter to Month, the value of the UsedTime parameter ranges from 1 to 11.
Note If you set the PayType parameter to Prepaid, you must specify the UsedTime parameter.
Period String No Year

The renewal cycle of the instance. Valid values:

  • Year
  • Month
Note If you set the PayType parameter to Prepaid, you must specify the Period parameter.
ResourceGroupId String No rg-acfmyxxxxxxxxxx

The ID of the resource group to which the instance belongs.

DBInstanceStorageType String No cloud_ssd

The type of storage media that is used for the instance. Valid values:

  • local_ssd: local SSD. This is the recommended storage type.
  • cloud_ssd: standard SSD.
  • cloud_essd: enhanced SSDs (ESSDs) of performance level 1 (PL1).
  • cloud_essd2: ESSDs of PL2.
  • cloud_essd3: ESSDs of PL3.
BusinessInfo String No 121436975448952

The extended business information of the instance.

EncryptionKey String No 0d24xxxx-da7b-4786-b981-9a164dxxxxxx

The ID of the key that is used to encrypt data on standard SSDs or ESSDs in the region of the instance. You can obtain the ID of the key from the Key Management Service (KMS) console. You can also create a key. For more information, see Manage CMKs.

Note If you specify the EncryptionKey parameter, disk encryption is automatically enabled. In this case, you must also specify the RoleARN parameter. Disk encryption cannot be disabled after it is enabled.
RoleARN String No acs:ram::1406xxxxxx:role/aliyunrdsinstanceencryptiondefaultrole

The Alibaba Cloud Resource Name (ARN) that is provided by your Alibaba Cloud account for Resource Access Management (RAM) users. RAM users can use the ARN to connect to ApsaraDB RDS to KMS. You can copy the ARN from the RAM console.

Note For more information about how to grant permissions to RAM users in the RAM console, see Authorize an ApsaraDB RDS for MySQL instance to access KMS.
AutoRenew String No true

Specifies whether to enable auto-renewal for the instance. If the subscription billing method is specified for the instance, you must specify this parameter. Valid values: true and false.

Note
  • If you set the Period parameter to Month, the auto-renewal cycle is one month.
  • If you set the Period parameter to Year, the auto-renewal cycle is one year.
Category String No HighAvailability

The RDS edition of the instance. Valid values:

  • Basic: Basic Edition
  • HighAvailability: High-availability Edition
  • AlwaysOn: Cluster Edition
  • Finance: Enterprise Edition
DedicatedHostGroupId String No dhg-4nxxxxxxx

The ID of the dedicated cluster to which the instance belongs.

If you create an instance in a dedicated cluster, you must specify this parameter.

Note
TargetDedicatedHostIdForMaster String No i-bpxxxxxxx1

The ID of the host to which the instance belongs in the specified dedicated cluster.

If you create a primary instance in a dedicated cluster, you must specify this parameter. If you do not specify this parameter, the system automatically assigns a host to the instance.

Note
TargetDedicatedHostIdForSlave String No i-bpxxxxxxx2

The ID of the host to which the instance belongs in the specified dedicated cluster.

If you create a secondary instance that runs the RDS High-availability Edition or Enterprise Edition in a dedicated cluster, you must specify this parameter. If you do not specify this parameter, the system assigns a host to the instance.

Note
TargetDedicatedHostIdForLog String No i-bpxxxxxxx3

The ID of the host to which the instance belongs in the specified dedicated cluster.

If you create a logger instance that runs the RDS Enterprise Edition in a dedicated cluster, you must specify this parameter. If you do not specify this parameter, the system assigns a host to the instance.

Note
DBParamGroupId String No rpg-sys-xxxx

The ID of the parameter template that is used for the instance.

DBTimeZone String No +08:00

The time zone of the instance. This parameter takes effect only when you set the Engine parameter to MySQL or PostgreSQL.

  • If you set the Engine parameter to MySQL.
    • This time zone of the instance is in UTC. Valid values: -12:59 to +13:00.
    • You can specify this parameter when the instance is equipped with local SSDs. For example, you can specify the time zone to Asia/Hong_Kong. For more information about time zones, see Time zones.
  • If you set the Engine parameter to PostgreSQL.
    • This time zone of the instance is not in UTC. For more information about time zones, see Time zones.
    • You can specify this parameter only when the instance is equipped with standard SSDs or ESSDs.
Note
  • You can specify the time zone when you create a primary instance. You cannot specify the time zone when you create a read-only instance. Read-only instances inherit the time zone of their primary instance.
  • If you do not specify this parameter, the system assigns the default time zone of the region where the instance resides.
DBIsIgnoreCase String No true

Specifies whether the table names on the instance are case-sensitive. Valid values:

  • true: The table names on the instance are not case-sensitive. This is the default value.
  • false: The table names on the instance are case-sensitive.
TargetMinorVersion String No rds_20200229

The minor engine version of the instance. You must specify this parameter only when you specify the MySQL database engine. Format: RDS edition_Minor engine version. Examples: rds_20200229, xcluster_20200229, and xcluster80_20200229. The following codes are used to represent different MySQL versions and RDS editions:

  • rds: The instance runs the RDS Basic Edition or RDS High-availability Edition.
  • xcluster: The instance runs MySQL 5.7 on RDS Enterprise Edition.
  • xcluster80: The instance runs MySQL 8.0 on RDS Enterprise Edition.
Note For more information about minor engine versions, see Release notes of minor AliSQL versions.
StorageAutoScale String No Disable

Specifies whether to enable automatic storage expansion for the instance. Valid values:

  • Enable
  • Disable

Default value: Disable.

Note After the instance is created, you can call the ModifyDasInstanceConfig operation to adjust the settings of automatic storage expansion for the instance. For more information, see Configure automatic storage expansion for an ApsaraDB RDS for MySQL instance.
StorageThreshold Integer No 50

The threshold based on which automatic storage expansion is triggered. Unit: percent. Valid values:

  • 10
  • 20
  • 30
  • 40
  • 50
Note If you set the StorageAutoScale parameter to Enable, you must specify the StorageThreshold parameter.
StorageUpperBound Integer No 2000

The maximum storage capacity that is allowed for automatic storage expansion. The storage capacity of the instance cannot exceed the maximum storage capacity. Unit: GB. Valid values: an integer greater than or equal to 0.

Note If you set the StorageAutoScale parameter to Enable, you must specify the StorageUpperBound parameter.
DryRun Boolean No false

Specifies whether to conduct a precheck before the system creates the instance. Valid values:

  • true: The system prechecks the request and does not create the instance. The system prechecks items such as the request parameters, request format, service limits, and available resources.
  • false: The system sends the request without a precheck. After the request passes the precheck, the system creates the instance.

Default value: false.

UserBackupId String No 67798****

The ID of the backup file that is used to create the instance. You can call the ListUserBackupFiles operation to query backup files. If you want to create an instance by using the data of a backup file, you must specify this parameter.

Note This parameter is supported only when the following requirements are met:
  • The PayType parameter is set to Postpaid.
  • The Engine parameter is set to MySQL.
  • The EngineVersion parameter is set to 5.7.
  • The Category parameter is set to Basic.
Tag.N.Key String No testkey1

The key of the tag that you want to create and add to the instance. You can use this parameter to add tags to the instance. The value of the N variable in the Tag.N.Key parameter ranges from 1 to 20. You can specify multiple values for this parameter to create and add multiple tags to the instance.

For example, if you want to create and add two tags to the instance, you must specify two values: Tag.1.Key and Tag.2.Key.

Note
  • If the specified tag key is an existing key, the system directly adds the tag key to the instance. You can call the ListTagResources operation to query the details about the existing tags.
  • If the specified tag key is not an existing key, the system creates the tag key and adds the tag key to the instance.
  • This parameter cannot be an empty string.
  • This parameter must be used together with the Tag.N.Value parameter.
Tag.N.Value String No testvalue1

The tag value that is associated with the specified tag key. You can specify this parameter to add tags to the instance. The value of the N variable in the Tag.N.Value parameter ranges from 1 to 20. You can specify multiple values for this parameter to create and add multiple tags to the instance.

This parameter must be used together with the Tag.N.Key parameter. For example, you specify Tag.1.Key and Tag.2.Key, you must also specify Tag.1.Value and Tag.2.Value.

Note
  • If the specified tag value is found in the specified tag key, the system directly adds the tag value to the instance. You can call the ListTagResources operation to query the details about the existing tags.
  • If the specified tag value is not found in the specified tag key, the system creates the tag value and adds the tag value to the instance.
  • This parameter must be used together with the Tag.N.Key parameter.
Amount Integer No 2

The number of ApsaraDB RDS for MySQL instances that you want to create. The parameter takes effect only when you create multiple ApsaraDB RDS for MySQL instances by using a single request.

Valid values: 1 to 20. Default value: 1.

Note
  • If you want to create multiple ApsaraDB RDS for MySQL instances by using a single request, you can add tags to all the instances by using the Tag.N.Key parameter and the Tag.N.Value parameter. After the instances are created, you can manage the instances based on the tags.
  • After you submit a request to create multiple ApsaraDB RDS for MySQL instances, the operation returns only the TaskId parameter, RequestId parameter, and Message parameter. You can call the DescribeDBInstanceAttribute operation to query the details about a specified instance.
  • If the value of the Engine parameter is not MySQL and the value of the Amount parameter is greater than 1, the operation fails and returns an error code InvalidParam.Engine.
CreateStrategy String No Atomicity

The policy based on which you want to create multiple instances. The parameter takes effect only when the value of the Amount parameter is greater than 1. Valid values:

  • Atomicity: atomicity. The instances are all created. If one of instances cannot be created, none of the instances is created.
  • Partial: non-atomicity. Each of the instances is independently created. The failure in creating one instance does not affect the creation of the other instances.

Default value: Atomicity.

Response parameters

Parameter Type Example Description
DBInstanceId String rm-uf6wjk5xxxxxxxxxx

The ID of the instance.

OrderId String 1007893702xxxxx

The ID of the order.

ConnectionString String rm-uf6wjk5xxxxxxx.mysql.rds.aliyuncs.com

The endpoint that is used to connect to the instance.

Note The DBInstanceNetType parameter indicates whether the endpoint is an internal endpoint or a public endpoint.
Port String 3306

The port that is used to connect to the instance.

Note The DBInstanceNetType parameter indicates whether the port is an internal port or a public port.
DryRun Boolean true

Indicates that the system prechecks the request before the system creates the instance. The return value is fixed to true.

Note If the system does not perform a precheck, this parameter is not returned.
DryRunResult Boolean true

Indicates whether the request passes the precheck. Valid values:

  • true: The request passes the precheck.
  • false: The request fails the precheck.
    Note
    • If the system does not perform a precheck, this parameter is not returned.
    • If the request fails the precheck, an error is returned.
Message String Batch Create DBInstance Task Is In Process.

The message indicates the creation of multiple instances. The parameter is returned only when the value of the Amount parameter is greater than 1.

RequestId String 1E43AAE0-BEE8-43DA-860D-EAF2AA0724DC

The ID of the request.

TagResult Boolean true

Indicates whether the specified tag is added to the instance. Valid values:

  • true: The specified tag is added to the instance.
  • false: The specified tag cannot be added to the instance.
Note If you do not add a tag to the instance, this parameter is not returned.
TaskId String s2365879-a9d0-55af-fgae-f2**********

The ID of the task that is run to create multiple instances. The parameter is returned only when the value of the Amount parameter is greater than 1.

Note The TaskID parameter cannot be used to query a task.
Note In the new version of SDK, the default timeout period on the client side is different from the default timeout period on the instance. If you use the new version of SDK to call this operation, a timeout error may be reported even if the operation is successfully called. To prevent this issue, you can set the ReadTimeout parameter to 20000 before you call this operation.
Set the ReadTimeout parameter

Examples

Sample requests

http(s)://rds.aliyuncs.com/?Action=CreateDBInstance
&RegionId=cn-hangzhou
&Engine=MySQL
&EngineVersion=5.6
&DBInstanceClass=rds.mysql.s1.small
&DBInstanceStorage=20
&DBInstanceNetType=Internet
&PayType=Postpaid
&SecurityIPList=10.23.12.27/24
&<Common request parameters>

Sample success response

XML format

<CreateDBInstanceResponse>
      <OrderId>1007893702xxxxx</OrderId>
      <ConnectionString>rm-uf6wjk5xxxxxxx.mysql.rds.aliyuncs.com</ConnectionString>
      <DBInstanceId>rm-uf6wjk5xxxxxxx</DBInstanceId>
      <Port>3306</Port>
      <RequestId>1E43AAE0-BEE8-43DA-860D-EAF2AA0724DC</RequestId>
</CreateDBInstanceResponse>

JSON format

{
    "OrderId": "1007893702xxxxx",
    "ConnectionString": "rm-uf6wjk5xxxxxxx.mysql.rds.aliyuncs.com",
    "DBInstanceId": "rm-uf6wjk5xxxxxxx",
    "Port": "3306",
    "RequestId": "1E43AAE0-BEE8-43DA-860D-EAF2AA0724DC"
}

Error codes

HTTP status code Error code Error message Description
400 InvalidZoneId.NotSupported The Specified vpc Zone not supported. The error message returned because the zone that you specify does not allow you to create an instance in a VPC. Specify a different zone and try again.
400 InvalidPaymentMethod.Incomplete No payment method is specified for your account. We recommend that you add a payment method. The error message returned because no valid payment methods are provided within your Alibaba Cloud account. Add a valid payment method and try again.
400 InvalidPaymentMethod.Missing No payment method is specified for your account. We recommend that you add a payment method. The error message returned because no valid payment methods are provided within your Alibaba Cloud account. Add a valid payment method and try again.
400 SYSTEM.CONCURRENT_OPERATE Concurrent operation is detected. The error message returned because concurrent operations are run in the system.
400 ZoneId.NotMatchWithCategory The number of ZoneId specified does not match with category. The error message returned because the number of zone IDs that are specified in the ZoneId parameter is not supported for the deployment method that you specify. Specify a valid value for this parameter.
400 InvalidTagKey.Malformed The Tag.N.Key parameter is empty. The error message returned because the Tag.N.Key parameter is empty.
400 InvalidTagValue.Malformed The Tag.N.Value parameter is empty. The error message returned because the Tag.N.Value parameter is empty.
400 Duplicate.TagKey The Tag.N.Key contains duplicate keys. The error message returned because the Tag.N.Key parameter specifies a duplicate key.
400 NumberExceed.Tags The maximum number of Tags is exceeded. The maximum is 20. The error message returned because the number of tags exceeds the maximum number of tags that are allowed. The maximum number is 20.
400 MissingParameter.ResourceIds The parameter ResourceIds.N must not be null. The error message returned because the ResourceId parameter is empty.
400 InvalidParameter.TagKey The Tag.N.Key parameter is invalid. The error message returned because the value of the Tag.N.Key parameter is invalid.
400 InvalidParam.Amount Amount is allowed from 1 to 20. The error message returned because the value of the Amount parameter is not within the range of 1 to 20.
400 InvalidParam.CreateStrategy Only Atomicity and Partial are allowed. The valid values of the CreateStrategy parameter are Atomicity and Partial.

For a list of error codes, visit the API Error Center.