You can call the CreateReadOnlyDBInstance operation to create a read-only instance for a primary ApsaraDB RDS instance.
- The primary instance cannot belong to a dedicated cluster and must run one of the
following database engine versions and RDS editions:
- MySQL 8.0 on RDS High-availability Edition or RDS Enterprise Edition
- MySQL 5.7 on RDS High-availability Edition or RDS Enterprise Edition
- MySQL 5.6
- SQL Server 2017 EE
- PostgreSQL 10, 11, or 12 on RDS High-availability Edition (If the primary instance runs PostgreSQL 10, it must use local SSDs.)
- If the primary instance runs MySQL, you can create up to 10 read-only instances.
- If the primary instance runs SQL Server, you can create up to seven read-only instances.
- If the primary instance runs PostgreSQL with local SSDs, you can create up to five read-only instances. If the primary instance runs PostgreSQL with standard SSDs or enhanced SSDs (ESSDs), you can create up to 32 read-only instances.
Debugging
Request parameters
Parameter | Type | Required | Example | Description |
---|---|---|---|---|
Action | String | Yes | CreateReadOnlyDBInstance |
The operation that you want to perform. Set the value to CreateReadOnlyDBInstance. |
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. |
RegionId | String | Yes | cn-hangzhou |
The ID of the region in which the read-only instance resides. The read-only instance and the primary instance must reside in the same region. You can call the DescribeRegions operation to query the most recent region list. |
ZoneId | String | Yes | cn-hangzhou-b |
The ID of the zone to which the read-only instance belongs. You can call the DescribeRegions operation to query the most recent zone list. |
DBInstanceId | String | Yes | rm-uf6wjk5xxxxxxx |
The ID of the primary instance. |
DBInstanceClass | String | Yes | rds.mys2.small |
The instance type of the read-only instance. For more information, see Read-only ApsaraDB RDS instance types. We recommend that you specify an instance type whose specifications are higher than or equal to the specifications of the instance type of the primary instance. If the specifications of the read-only instance are lower than the specifications of the primary instance, the read-only instance may encounter issues such as high latency and heavy load. |
DBInstanceStorage | Integer | Yes | 20 |
The storage capacity of the read-only instance. Valid values: 5 to 3000. Unit: GB. The storage capacity increases in increments of 5 GB. Note The storage capacity range that is supported varies based on the RDS edition that
is run by the read-only instance. For more information, visit the ApsaraDB RDS buy
page.
|
EngineVersion | String | Yes | 5.6 |
The major engine version of the read-only instance. The read-only instance and the primary instance must run the same major engine version.
|
PayType | String | Yes | Postpaid |
The billing method of the read-only instance. Valid values:
|
DBInstanceDescription | String | No | Test read-only instance |
The description of the read-only instance. The description must be 2 to 256 characters in length and can contain letters, digits, underscores (_), and hyphens (-). The description must start with a letter. Note The description cannot start with http:// or https://.
|
InstanceNetworkType | String | No | Classic |
The network type of the read-only instance. Valid values:
Default value: VPC. If you set this parameter to VPC, you must also specify the VPCId and VSwitchId parameters. Note The network type of the read-only instance can be different from the network type
of the primary instance.
|
VPCId | String | No | vpc-uf6f7l4fg90xxxxxxxxxx |
The ID of the virtual private cloud (VPC) to which the read-only instance belongs. If you leave the InstanceNetworkType parameter empty or set it to VPC, you must specify the VPCId parameter. Note
|
VSwitchId | String | No | vsw-uf6adz52c2pxxxxxxxxxx |
The ID of the vSwitch to which the read-only instance belongs. If you leave the InstanceNetworkType parameter empty or set it to VPC, you must specify the VPCId parameter. |
PrivateIpAddress | String | No | 172.16.201.69 |
The private IP address of the read-only 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 read-only instance based on the values of the VPCId and VSwitchId parameters. |
ResourceGroupId | String | No | rg-acfmyxxxxxxxxxx |
The ID of the resource group to which the read-only instance belongs. |
Category | String | No | HighAvailability |
The RDS edition of the read-only instance. Valid values:
Note If the read-only instance runs PostgreSQL with standard SSDs or ESSDs, you must set
this parameter to Basic.
|
DBInstanceStorageType | String | No | local_ssd |
The type of storage media that is used by the instance. Valid values:
Note
|
DedicatedHostGroupId | String | No | dhg-4nxxxxxxx |
The ID of the dedicated cluster to which the read-only instance belongs. This parameter is valid when you create the read-only instance in a dedicated cluster. |
TargetDedicatedHostIdForMaster | String | No | i-bpxxxxxxx1 |
The ID of the host to which the read-only instance belongs. This parameter is valid when you create the read-only instance in a dedicated cluster. |
GdnInstanceName | String | No | None |
A reserved parameter. |
TddlBizType | String | No | None |
A reserved parameter. |
TddlRegionConfig | String | No | None |
A reserved parameter. |
InstructionSetArch | String | No | None |
A reserved parameter. |
UsedTime | String | No | 1 |
The subscription period of the read-only instance. Valid values:
Note If you set the PayType parameter to Prepaid, you must specify the UsedTime parameter.
|
Period | String | No | Month |
The renewal cycle of the read-only instance. Valid values:
|
AutoRenew | String | No | true |
Specifies whether to enable auto-renewal for the read-only instance. If you specify the subscription billing method for the read-only instance, you must specify this parameter. Valid values:
Note
|
Response parameters
Parameter | Type | Example | Description |
---|---|---|---|
DBInstanceId | String | rr-uf6wjk5xxxxxxx |
The ID of the read-only instance. |
RequestId | String | 1E43AAE0-BEE8-43DA-860D-EAF2AA0724DC |
The ID of the request. |
Port | String | 3306 |
The internal port number that is used to connect to the read-only instance. |
ConnectionString | String | rr-xxxxx.mysql.rds.aliyuncs.com |
The internal endpoint that is used to connect to the read-only instance. |
OrderId | String | 10078937xxxxx |
The ID of the order. |
Examples
Sample requests
http(s)://rds.aliyuncs.com/?Action=CreateReadOnlyDBInstance
&RegionId=cn-hangzhou
&ZoneId=cn-hangzhou-b
&DBInstanceId=rm-uf6wjk5xxxxxxx
&DBInstanceClass=rds.mys2.small
&DBInstanceStorage=20
&EngineVersion=5.6
&PayType=Postpaid
&VPCId=vpc-uf6f7l4fg90xxxxxxxxxx
&VSwitchId=vsw-uf6adz52c2pxxxxxxxxxx
&<Common request parameters>
Sample success responses
XML
format
HTTP/1.1 200 OK
Content-Type:application/xml
<CreateReadOnlyDBInstanceResponse>
<OrderId>10078937xxxxx</OrderId>
<ConnectionString>rm-uf6wjk5xxxxxxx.mysql.rds.aliyuncs.com</ConnectionString>
<DBInstanceId>rm-uf6wjk5xxxxxxx</DBInstanceId>
<Port>3306</Port>
<RequestId>1E43AAE0-BEE8-43DA-860D-EAF2AA0724DC</RequestId>
</CreateReadOnlyDBInstanceResponse>
JSON
format
HTTP/1.1 200 OK
Content-Type:application/json
{
"CreateReadOnlyDBInstanceResponse" : {
"OrderId" : "10078937xxxxx",
"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 | InvalidEngineVersion.Malformed | The specified parameter "EngineVersion" is not valid. | The error message returned because the specified database engine version is invalid. |
400 | InvalidSecurityIPList.Malformed | The specified parameter "SecurityIPList" is not valid. | The error message returned because the IP address whitelist of the read-only instance is invalid. |
400 | InvalidSecurityIPList.Duplicate | The Security IP address is not in the available range or occupied. | The error message returned because the specified IP address is in use or is not within the valid range. Specify a valid IP address and try again. |
400 | InvalidParameter | The specified parameter "dbInstanceId" is not valid. | The error message returned because the specified instance ID is invalid. Specify a valid instance ID and try again. |
400 | OperationDenied | VPC IP is in use, please check. | The error message returned because the specified VPC IP address is in use. |
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. Specify a different zone and try again. |
400 | CDDC.AvailableHostsNotEnoughInZone | Not enough available hosts are in the target zone. | The error message returned because no hosts are available in the specified zone. Create a host in the zone and try again. |
403 | OperationDenied.PrimaryDBInstanceStatus | The operation is not permitted due to status of primary instance. | The error message returned because the instance belongs to a dedicated cluster and is not in the Running state. |
404 | IncorrectDBInstanceConnType | Current DB instance conn type does not support this operation. | The error message returned because this operation is not supported by the network connection type of the instance. |
500 | CannotDecreaseEssdPerfLevel | cannot decrease cloud essd performance level. | The error message returned because the storage type change fails verification. The storage type of an instance that runs SQL Server with cloud disks can be converted only to a different type of cloud disk. An instance that runs SQL Server with standard SSDs can be upgraded to use standard SSDs or ESSDs with the new specifications. |
500 | InvalidEssdStorageSize | invalid cloud essd storage size. | The error message returned because the specified instance type is invalid. Select a valid instance type and try again. |
For a list of error codes, visit the API Error Center.