You can call the CloneDBInstance operation to restore the data of an original ApsaraDB RDS instance to a new instance. The new instance is called a cloned instance.

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

  • The original instance is in the Running state.
  • The original instance does not have ongoing migration tasks.
  • The log backup feature is enabled for the original instance to support point-in-time recovery.
  • If you want to clone the original instance by using data backup files, the original instance must have at least one data backup file.
Note ApsaraDB RDS allows you to clone an instance by using the credentials of a RAM user. Make sure that the RAM user is granted the permissions that are required to clone an instance. For more information, see Use RAM to manage ApsaraDB RDS permissions.

Take note of the following information:

  • The new instance has the same IP address whitelist, SQL Explorer (SQL Audit), alert threshold, backup, and parameter settings as the original instance.
  • The data and account information of the new instance is the same as that indicated by the backup set or point in time used for restoration of the original instance.

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 CloneDBInstance

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

RegionId String No cn-hangzhou

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

ZoneId String No cn-hangzhou-b

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

Note The default value of this parameter is the ID of the zone to which the original instance belongs.
DBInstanceClass String No mysql.n1.micro.1

The instance type of the new instance. For information, see Primary ApsaraDB RDS instance types.

Note The default value of this parameter is the instance type of the original instance.
DBInstanceStorage Integer No 1000

The storage capacity of the new instance. Unit: GB. The storage capacity increases in increments of 5 GB. For more information, see Primary ApsaraDB RDS instance types.

Note The default value of this parameter is the storage capacity of the original instance.
DbNames String No testDB

The names of the databases that you want to create on the new instance.

PayType String Yes Postpaid

The billing method of the new instance. Valid values:

  • Postpaid: pay-as-you-go
  • Prepaid: subscription
InstanceNetworkType String No VPC

The network type of the new instance. Valid values:

  • VPC
  • Classic
Note The default value of this parameter is the network type of the original instance.
DBInstanceId String Yes rm-uf6wjk5xxxxxxxxxx

The ID of the new instance.

BackupId String No 9026262

The ID of the data backup file.

You can call the DescribeBackups operation to query the most recent data backup file list.

Note You must specify at least one of BackupId and RestoreTime parameters.
RestoreTime String No 2011-06-11T16:00:00Z

The point in time to which you want to restore the original instance. You can select a point in time within the backup retention period. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time must be in UTC.

Note You must specify at least one of BackupId and RestoreTime parameters.
VPCId String No vpc-uf6f7l4fg90xxxxxxxxxx

The ID of the virtual private cloud (VPC) to which the new instance belongs.

Note The VPC must belong to the specified region.
VSwitchId String No vsw-uf6adz52c2pxxxxxxxxxx

The ID of the vSwitch that is associated with the specified VPC.

Note The vSwitch must belong to the specified VPC and region.
PrivateIpAddress String No 172.16.201.69

The internal IP address of the new instance, which must be within the CIDR block supported by the specified vSwitch. The system automatically assigns an internal IP address to the read-only instance based on the values of the VPCId and VSwitchId parameters.

UsedTime Integer No 1

The subscription duration of the new instance. This parameter takes effect only when you select the subscription billing method for the new instance. Valid values:

  • If you set the Period parameter to Year, the value of the UsedTime parameter ranges from 1 to 3.
  • 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 Year

The unit that is used to calculate the billing cycle of the new instance. This parameter takes effect only when you select the subscription billing method for the new instance. Valid values:

  • Year
  • Month
Note If you set the PayType parameter to Prepaid, you must specify the Period parameter.
Category String No HighAvailability

The RDS edition of the new instance. Valid values:

  • Basic: Basic Edition
  • HighAvailability: High-availability Edition.
  • AlwaysOn: Cluster Edition
  • Finance: Enterprise Edition. This edition is available only on the China site (aliyun.com).
DBInstanceStorageType String Yes cloud_essd

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

  • local_ssd: local SSDs
  • cloud_ssd: standard SSDs
  • cloud_essd: enhanced SSDs (ESSDs) of performance level 1 (PL1)
  • cloud_essd2: ESSDs of PL2
  • cloud_essd3: ESSDs of PL3
RestoreTable String No 1

Specifies whether to restore only the databases and tables that you specify. The value 1 specifies to restore only the specified databases and tables. If you do not want to restore only the specified databases or tables, you can choose not to specify this parameter.

TableMeta String No [{"type":"db","name":"testdb1","newname":"testdb1_new","tables":[{"type":"table","name":"testdb1table1","newname":"testdb1table1_new"}]}]

The information about the databases and tables that you want to restore. Format:

[{"type":"db","name":"The original name of Database 1","newname":"The new name of Database 1","tables":[{"type":"table","name":"The original name of Table 1 in Database 1","newname":"The new name of Table 1 in Database 1"},{"type":"table","name":"The original name of Table 2 in Database 1","newname":"The new name of Table 2 in Database 1"}]},{"type":"db","name":"The original name of Database 2","newname":"The new name of Database 2","tables":[{"type":"table","name":"The original name of Table 1 in Database 2","newname":"The new name of Table 1 in Database 2"},{"type":"table","name":"The original name of Table 2 in Database 2","newname":"The new name of Table 2 in Database 2"}]}]
DedicatedHostGroupId String No dhg-7a9xxxxxxxx

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

BackupType String No FullBackup

The type of backup that is used to restore the data of the original instance. Valid values:

  • FullBackup: full backup
  • IncrementalBackup: incremental backup
DeletionProtection Boolean No true

Specifies whether to enable the release protection feature for the new instance. Valid values:

  • true: enables the feature.
  • false: disables the feature.

Response parameters

Parameter Type Example Description
DBInstanceId String rm-uf6wjk5xxxxxxx

The ID of the new instance.

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

The ID of the request.

OrderId String 100789370xxxxx

The ID of the order.

Examples

Sample requests

http(s)://rds.aliyuncs.com/?Action=CloneDBInstance
&PayType=Postpaid
&DBInstanceId=rm-uf6wjk5xxxxxxxxxx
&DBInstanceStorageType=cloud_essd
&<Common request parameters>

Sample success responses

XML format 

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

<?xml version="1.0" encoding="UTF-8" ?>
<CloneDBInstanceResponse>
    <OrderId>100789370xxxxx</OrderId>
    <DBInstanceId>rm-uf6wjk5xxxxxxx</DBInstanceId>
    <RequestId>1E43AAE0-BEE8-43DA-860D-EAF2AA0724DC</RequestId>
</CloneDBInstanceResponse>

JSON format 

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

{
  "OrderId" : "100789370xxxxx",
  "DBInstanceId" : "rm-uf6wjk5xxxxxxx",
  "RequestId" : "1E43AAE0-BEE8-43DA-860D-EAF2AA0724DC"
}

Error codes

HTTP status code Error code Error message Description
400 InvalidAvZone.Format Specified AvZone is not valid. The error message returned because the value of the ZoneID parameter is invalid.
400 CannotDecreaseEssdPerfLevel cannot decrease cloud essd performance level. The error message returned because the change of storage media is not allowed. The storage media of an instance that runs SQL Server with standard SSDs can be changed only to ESSDs. The storage media of an instance that runs SQL Server with local SSDs can be changed to standard SSDs or ESSDs.
400 CannotDecreaseEssdPerfLevel invalid cloud essd storage size. The error message returned because the value of the DBInstanceStorage parameter is invalid.
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.

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