Create read-only instance - API Reference| Alibaba Cloud Documentation Center

Before you call this operation, make sure that the following requirements are met:

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 Enterprise Edition
- MySQL 5.7 on RDS High-availability Edition or 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 be equipped with local SSDs.)
If the primary instance runs MySQL, the number of read-only instances that are created cannot reach the upper limit:
- If the memory capacity of the primary instance is greater than or equal to 64 GB, up to 10 read-only instances can be created.
- If the memory capacity of the primary instance is less than 64 GB, up to 5 read-only instances can be created.
If the primary instance runs SQL Server, the number of read-only instances that are created cannot reach 7.
If the primary instance runs PostgreSQL with local SSDs, the number of read-only instances that are created cannot reach 5. If the primary instance runs PostgreSQL with standard SSDs or enhanced SSDs (ESSDs), the number of read-only instances that are created cannot reach 32.

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	CreateReadOnlyDBInstance	The operation that you want to perform. Set the value to CreateReadOnlyDBInstance.
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 the specifications of the read-only instance be higher than or equal to those of the primary instance. If the specifications of the read-only instance are lower than those of the primary instance, the read-only instance may encounter high latency or heavy load issues.
DBInstanceId	String	Yes	rm-uf6wjk5xxxxxxx	The ID of the primary instance.
DBInstanceStorage	Integer	Yes	20	The storage capacity of the read-only instance. Valid values: 5 to 3,000. Unit: GB. The storage capacity increases at increments of 5 GB. Note The supported storage capacity range varies based on the RDS edition that is used. For more information, visit the ApsaraDB RDS buy page.
EngineVersion	String	Yes	5.6	The major engine version that is run on the read-only instance. The read-only instance must run the same major engine version as the primary instance. If the read-only instance runs MySQL, set this parameter to 5.6, 5.7, or 8.0. If the read-only instance runs SQL Server, set this parameter to 2017_ent or 2019_ent.
PayType	String	Yes	Postpaid	The billing method of the read-only instance. Valid values: Postpaid: pay-as-you-go Prepaid: subscription
RegionId	String	Yes	cn-hangzhou	The region ID of the read-only instance. The read-only instance must reside in the same region as the primary instance. You can call the DescribeRegions operation to query the most recent region list.
ZoneId	String	Yes	cn-hangzhou-b	The zone ID of the read-only instance. You can call the DescribeRegions operation to query the most recent zone list.
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 contain only ASCII characters and cannot exceed 64 characters in length.
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: VPC Classic 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 that 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 this parameter to VPC, you must specify the VPCId parameter. Note If local SSDs are used for the primary instance, the read-only instance can belong to a different VPC than the primary instance. If standard SSDs or ESSDs are used for the primary instance, the read-only instance must belong to the same VPC as the primary RDS instance.
VSwitchId	String	No	vsw-uf6adz52c2pxxxxxxxxxx	The vSwitch ID of the read-only instance. If you leave the InstanceNetworkType parameter empty or set this parameter to VPC, you must specify the VSwitchId 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 based on 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: Basic: Basic Edition. HighAvailability: High-availability Edition. This value is the default value. AlwaysOn: Cluster Edition. Finance: Enterprise Edition. This value is supported only on the China site (aliyun.com). Note If the primary 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 for the read-only instance. Valid values: local_ssd or ephemeral_ssd: local SSD cloud_ssd: standard SSD cloud_essd: ESSD Note MySQL supports only local SSDs. SQL Server supports only standard SSDs and ESSDs.
DedicatedHostGroupId	String	No	dhg-4nxxxxxxx	The ID of the dedicated cluster to which the read-only instance belongs if you want to create a read-only instance in a dedicated cluster.
TargetDedicatedHostIdForMaster	String	No	i-bpxxxxxxx1	The ID of the host to which the read-only instance belongs if you want to create a read-only instance in a dedicated cluster.
GdnInstanceName	String	No	None	A hidden parameter.
TddlBizType	String	No	None	A hidden parameter.
TddlRegionConfig	String	No	None	A hidden parameter.
InstructionSetArch	String	No	None	A hidden parameter.
UsedTime	String	No	1	The subscription period of the read-only 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 9. Note If you set the PayType parameter to Prepaid, you must specify the UsedTime parameter.
Period	String	No	Month	The subscription type of the read-only instance. Valid values: Year: yearly subscription Month: monthly subscription
AutoRenew	String	No	true	Specifies whether to enable auto-renewal for the read-only instance. If the subscription billing method is specified for the read-only instance, you must specify this parameter. Valid values: true: enables auto-renewal. false: disables auto-renewal. 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.

Response parameters


Parameter	Type	Example	Description
DBInstanceId	String	rr-uf6wjk5xxxxxxx	The ID of the read-only instance.
OrderId	String	10078937xxxxx	The ID of the order.
ConnectionString	String	rr-xxxxx.mysql.rds.aliyuncs.com	The internal endpoint of the read-only instance.
Port	String	3306	The internal port number of the read-only instance.
RequestId	String	1E43AAE0-BEE8-43DA-860D-EAF2AA0724DC	The ID of the request.

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

<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

{
    "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 value that you specified for the EngineVersion parameter is invalid.
400	InvalidSecurityIPList.Malformed	The specified parameter "SecurityIPList" is not valid.	The error message returned because the value that you specified for the SecurityIPList parameter is invalid.
400	InvalidSecurityIPList.Duplicate	The Security IP address is not in the available range or occupied.	The error message returned because the IP address that you specified is in use or is not within the valid range.
400	InvalidParameter	The specified parameter "dbInstanceId" is not valid.	The error message returned because the value that you specified for the DBInstanceId parameter is invalid.
403	OperationDenied.PrimaryDBInstanceStatus	The operation is not permitted due to status of primary instance.	The error message returned because the status of the primary instance does not support this operation. The primary instance supports this operation only when the primary instance is in the Running state.
400	OperationDenied	VPC IP is in use, please check.	The error message returned because the private IP address that you specified is in use. Change the private IP address and try again.
404	IncorrectDBInstanceConnType	Current DB instance conn type does not support this operation.	The error message returned because the connection type of the primary instance does not support this operation.
400	InvalidZoneId.NotSupported	The Specified vpc Zone not supported.	The error message returned because the zone that you specified does not allow you to create a read-only instance in a VPC. Change the 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 zone that you specify.

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