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, visit the ApsaraDB RDS pricing page.

For more information about ApsaraDB RDS instance types, see Primary 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 instance. For more information, see Primary instance types. You can call the DescribeAvailableResource operation to query the instance types that are available to a region.

DBInstanceNetType String Yes Internet

The network connection type of 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 instance types. You can call the DescribeAvailableResource operation to query the storage capacity range that is supported for an 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
EngineVersion String Yes 5.6

The database engine version 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: 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 instances. 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 these entries with commas (,). Each entry must be unique. The IP address whitelist can contain up to 1,000 entries. The IP address whitelist supports the following two formats:

  • IP address. Example: 10.23.12.24.
  • CIDR block. Example:10.23.12.24/24, where 24 indicates that the prefix of each IP address is 24 bits in length. You can replace 24 with a value that ranges from 1 to 32.
SystemDBCharset String No gbk

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

DBInstanceDescription String No Test database

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

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

The client token that is used to ensure the idempotence of request. You can use the client to generate the value, but you must ensure that it is unique among different requests. The token can contain only 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 select the RDS High-availability Edition, you must specify the ZoneIdSlave1 parameter. This parameter specifies whether to use the single-zone or multi-zone deployment method.
  • If you select the RDS Enterprise Edition, you must specify the ZoneIdSlave1 and ZoneIdSlave2 parameters. These parameters specify whether to use the single-zone or 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 network type of the instance. Valid values:

  • VPC: VPC network type.
  • Classic: classic network type. This is the default network type.
Note
  • If you select standard or enhanced SSDs, you can select 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 this 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.

By default, the system assigns a connection mode to 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 this 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 these vSwitch IDs with commas (,).

Note If you set the InstanceNetworkType parameter to VPC, you must specify this 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. By default, the system assigns a private IP address to the instance based on 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 this 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 this 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 SSD of performance level (PL)1.
  • cloud_essd2: enhanced SSD of PL2.
  • cloud_essd3: enhanced SSD 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 for disk encryption 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 enabled. In this case, you must 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 to the service account of the instance by your Alibaba Cloud account. The ARN is used to connect to KMS. You can copy the ARN from the Resource Access Management (RAM) console.

Note For more information about how to grant permissions by using 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. You need to specify this parameter only when the instance uses the subscription billing method. 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 the instance in a dedicated cluster, you must specify the DedicatedHostGroupId parameter.

Note
TargetDedicatedHostIdForMaster String No i-bpxxxxxxx1

The ID of the host to which the primary instance belongs.

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

Note
TargetDedicatedHostIdForSlave String No i-bpxxxxxxx2

The ID of the host to which the secondary instance belongs.

If you create the instance in a dedicated cluster and select the RDS High-availability or Enterprise Edition, 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 logger instance belongs.

If you create the instance in a dedicated cluster and select the RDS Enterprise Edition, 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 UTC time zone of the instance. Valid values: -12:59 to +13:00.

Note
  • If you do not specify this parameter, the system assigns a time zone to the instance. The assigned time zone is the default time zone of the region to which the instance belongs.
  • If the instance uses local SSDs, you can name the time zone. For example, you can name the time zone as Asia/Hong_Kong. For more information, see the official documentation of the database engine in use.
DBIsIgnoreCase String No 1

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

  • 1: Table names are not case-sensitive. This is the default value.
  • 0: Table names are case-sensitive.
TargetMinorVersion String No rds_20200229

The minor engine version that is run on the instance. You need to specify this parameter only when you select 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 RDS editions:

  • rds: The instance runs the RDS Basic or 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 the minor engine versions, see Release notes of minor AliSQL versions.
StorageAutoScale String No Disable

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

  • Enable: The feature is enabled.
  • Disable: The feature is disabled.

Default value: Disable.

Note After the instance is created, you can call the ModifyDasInstanceConfig operation to configure the feature 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: %. Valid values:

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

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

Note If you set the StorageAutoScale parameter to Enable, you must specify this parameter.

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 internal or public.
Port String 3306

The port number that is used to connect to the instance.

Note The DBInstanceNetType parameter indicates whether the port number is internal or public.
RequestId String 1E43AAE0-BEE8-43DA-860D-EAF2AA0724DC

The ID of the request.

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 responses

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 specified zone does not allow you to create an instance in a VPC. Change the 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 your Alibaba Cloud account does not provide a valid payment method. 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 your Alibaba Cloud account does not provide a valid payment method. Add a valid payment method and try again.
400 SYSTEM.CONCURRENT_OPERATE Concurrent operation is detected. The error message returned because the system runs threads in parallel.
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 specified deployment method.
400 CreditPayInsufficientBalance Insufficient credit pay limit. Please contact your channel partner to increase the limit. The error message returned because your Alibaba Cloud account does not have sufficient balance. Make sure that you have sufficient balance in your Alibaba Cloud account.

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