Create a read-only instance -

You can call the CreateReadOnlyDBInstance operation to create a read-only instance for a primary instance.

Before you call this operation, take note of the following limits:

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 on RDS Cluster Edition.
- PostgreSQL 10, PostgreSQL 11, PostgreSQL 12, PostgreSQL 13, PostgreSQL 14, or PostgreSQL 15 on RDS High-availability Edition. If the primary instance runs PostgreSQL 10, it must use local SSDs and it must be a dedicated instance that provides at least 8 cores and 32 GB of memory.
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

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.
ClientToken	String	No	ETnLKlblzczshOTUbOC****	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 make sure that the value 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 region ID of the read-only instance. 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 zone ID of the read-only instance. You can call the DescribeRegions operation to query the most recent zone list.
DBInstanceId	String	Yes	rm-uf6wjk5****	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. For more information, see the Storage space column in Read-only instance types. This value must be a multiple of 5 GB. Unit: GB.
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. 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. If the read-only instance runs PostgreSQL, set this parameter to 10.0, 11.0, 12.0, 13.0, 14.0, or 15.0.
PayType	String	Yes	Postpaid	The billing method of the read-only instance. Valid values: Postpaid: pay-as-you-go Prepaid: subscription
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 value must start with a letter Note but 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 the network type of the primary instance.
VPCId	String	No	vpc-uf6f7l4fg90****	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 also specify this parameter. Note If the primary instance uses local SSDs, the read-only instance and the primary instance can belong to the same VPC or different VPCs. If the primary instance uses standard SSDs or ESSDs, the read-only instance and the primary instance must belong to the same VPC.
VSwitchId	String	No	vsw-uf6adz52c2p****	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 also specify this parameter.
PrivateIpAddress	String	No	172.16.XX.XX	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-acfmy****	The ID of the resource group to which the read-only instance belongs.
Category	String	No	HighAvailability	The RDS edition of the new instance. Valid values: Basic: RDS Basic Edition. HighAvailability: RDS High-availability Edition. This is the default value. AlwaysOn: RDS Cluster Edition. 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 storage type of the read-only instance. Valid values: local_ssd: local SSD cloud_ssd: standard SSD cloud_essd: ESSD of performance level 1 (PL1) cloud_essd2: ESSD of PL2 cloud_essd3: ESSD of PL3 Note If the primary instance runs MySQL with local SSDs, you must set this parameter to local_ssd. If the primary instance runs MySQL with standard SSDs or ESSDs, you must set this parameter to cloud_ssd, cloud_essd, cloud_essd2, or cloud_essd3. If the primary instance runs SQL Server, you must set this parameter to cloud_ssd, cloud_essd, cloud_essd2, or cloud_essd3.
DedicatedHostGroupId	String	No	dhg-4n****	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-bp****	The host ID of the primary instance to which the read-only instance is attached. 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: 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 also specify this parameter.
Period	String	No	Month	The renewal cycle of the read-only instance. Valid values: Year Month
AutoRenew	String	No	true	Specifies whether to enable auto-renewal for the read-only instance. If you set the PayType parameter to Prepaid, you must also 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.
DeletionProtection	Boolean	No	true	Specifies whether to enable the release protection feature for the read-only instance. Valid values: true: enables the release protection feature. false: disables the release protection feature. This is the default value. Note This feature can be enabled only when you set the PayType parameter to Postpaid.

Response parameters


Parameter	Type	Example	Description
DBInstanceId	String	rr-uf6wjk5****	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-****.mysql.rds.aliyuncs.com	The internal endpoint that is used to connect to the read-only instance.
OrderId	String	10078937****	The ID of the order.

Examples

Sample requests

http(s)://rds.aliyuncs.com/?Action=CreateReadOnlyDBInstance
&ClientToken=ETnLKlblzczshOTUbOC****
&RegionId=cn-hangzhou
&ZoneId=cn-hangzhou-b
&DBInstanceId=rm-uf6wjk5****
&DBInstanceClass=rds.mys2.small
&DBInstanceStorage=20
&EngineVersion=5.6
&PayType=Postpaid
&DBInstanceDescription=Test read-only instance
&InstanceNetworkType=Classic
&VPCId=vpc-uf6f7l4fg90****
&VSwitchId=vsw-uf6adz52c2p****
&PrivateIpAddress=172.16.XX.XX
&ResourceGroupId=rg-acfmy****
&Category=HighAvailability
&DBInstanceStorageType=local_ssd
&DedicatedHostGroupId=dhg-4n****
&TargetDedicatedHostIdForMaster=i-bp****
&GdnInstanceName=None
&TddlBizType=None
&TddlRegionConfig=None
&InstructionSetArch=None
&UsedTime=1
&Period=Month
&AutoRenew=true
&DeletionProtection=true
&<Common request parameters>

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<CreateReadOnlyDBInstanceResponse>
    <DBInstanceId>rr-uf6wjk5****</DBInstanceId>
    <RequestId>1E43AAE0-BEE8-43DA-860D-EAF2AA0724DC</RequestId>
    <Port>3306</Port>
    <ConnectionString>rr-****.mysql.rds.aliyuncs.com</ConnectionString>
    <OrderId>10078937****</OrderId>
</CreateReadOnlyDBInstanceResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "DBInstanceId" : "rr-uf6wjk5****",
  "RequestId" : "1E43AAE0-BEE8-43DA-860D-EAF2AA0724DC",
  "Port" : 3306,
  "ConnectionString" : "rr-****.mysql.rds.aliyuncs.com",
  "OrderId" : "10078937****"
}

Error codes


HTTP status code	Error code	Error message	Description
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	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 support the creation of an instance of the VPC network type. 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, see Service error codes.