You can call the CloneDBInstance operation to restore the data of an original 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 backup sets, the original instance must have at least one backup set.
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 account information and data of the new instance are the same as the account information and data that are indicated by the backup file 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 No CloneDBInstance

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

RegionId String No cn-hangzhou

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

ZoneId String No cn-hangzhou-b

The zone ID of the primary instance. You can call the DescribeRegions operation to query the most recent zone 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 primary instance.
DBInstanceStorage Integer No 1000

The storage capacity of the new instance. Unit: GB. The storage capacity increases at a step size 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 primary instance.
DbNames String No test1,test2

The name of the database. If you specify more than one database, the value of this parameter is in the following format: Original database name 1,Original database name 2.

PayType String No Postpaid

The billing method of the new instance. Valid values:

  • Postpaid: pay-as-you-go.
  • Prepaid: subscription.
  • Serverless: serverless. This value is supported only for instances that run MySQL. For more information, see Overview.
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 primary instance.
DBInstanceId String No rm-uf6wjk5xxxxxxxxxx

The ID of the instance.

BackupId String No 902****

The ID of the backup set.

You can call the DescribeBackups operation to query the backup sets.

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

The point in time to which you want to restore data. The point in time must fall within the specified backup retention period. Specify the time in 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 the 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. The vSwitch must belong to the zone that is specified by the ZoneId parameter.

  • If you set the InstanceNetworkType parameter to VPC, you must also specify this parameter.
  • If you specify the ZoneSlaveId1 parameter, you must specify the IDs of two vSwitches for this parameter and separate the IDs with a comma (,).
PrivateIpAddress String No 172.XX.XXX.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 new instance based on the values of the VPCId and VSwitchId parameters.

UsedTime Integer No 1

The subscription duration of the new instance.

  • 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. 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: RDS Basic Edition.
  • HighAvailability: RDS High-availability Edition.
  • AlwaysOn: RDS Cluster Edition for SQL Server.
  • cluster: RDS Cluster Edition for MySQL.
  • Finance: RDS Enterprise Edition. This edition is available only on the China site (aliyun.com).
  • serverless_basic: RDS Serverless Basic Edition.
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 from 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 from the ZoneId parameter, the multi-zone deployment method is used.

DBInstanceStorageType String No cloud_essd

The storage type of the new instance. Valid values:

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

Specifies whether to restore the databases and tables that you specify. The value 1 indicates that you want to restore the specified databases and tables. If you do not want to restore the specified databases or tables, do not 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. Syntax:

[{"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 backup type. Valid values:

  • FullBackup
  • IncrementalBackup
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.

Default value: false.

AutoPause Boolean No true

Specifies whether to enable the automatic start and stop feature for the serverless instance. After the automatic start and stop feature is enabled, if no connections to the instance are established within 10 minutes, the instance is suspended. After a connection is established to the instance, the instance is automatically resumed. Valid values:

  • true: enables the feature.
  • false: disables the feature. This is the default value.
MaxCapacity double No 8

The maximum number of RDS Capacity Units (RCUs).

MinCapacity double No 0.5

The minimum number of RCUs.

SwitchForce Boolean No false

Specifies whether to enable the forced scaling feature for the serverless instance. In most cases, ApsaraDB RDS automatically scales in or out the RCUs of a serverless instance based on business requirements in real time. In rare cases, the scaling does not take effect in real time. You can enable the forced scaling feature to forcefully scales in or out the RCUs of the instance. Valid values:

  • true: enables the feature.
  • false: disables the feature. This is the default value.

Response parameters

Parameter Type Example Description
DBInstanceId String rm-uf6wjk5xxxxxxx

The ID of the instance.

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

The ID of the request.

OrderId String 100789370****

The ID of the order.

Examples

Sample requests

http(s)://rds.aliyuncs.com/?Action=CloneDBInstance
&RegionId=cn-hangzhou
&ZoneId=cn-hangzhou-b
&DBInstanceClass=mysql.n1.micro.1
&DBInstanceStorage=1000
&DbNames=test1,test2
&PayType=Postpaid
&InstanceNetworkType=VPC
&DBInstanceId=rm-uf6wjk5xxxxxxxxxx
&BackupId=902****
&RestoreTime=2011-06-11T16:00:00Z
&VPCId=vpc-uf6f7l4fg90xxxxxxxxxx
&VSwitchId=vsw-uf6adz52c2pxxxxxxxxxx
&PrivateIpAddress=172.XX.XXX.69
&UsedTime=1
&Period=Year
&Category=HighAvailability
&ZoneIdSlave1=cn-hangzhou-c
&ZoneIdSlave2=cn-hangzhou-d
&DBInstanceStorageType=cloud_essd
&RestoreTable=1
&TableMeta=[{"type":"db","name":"testdb1","newname":"testdb1_new","tables":[{"type":"table","name":"testdb1table1","newname":"testdb1table1_new"}]}]
&DedicatedHostGroupId=dhg-7a9xxxxxxxx
&BackupType=FullBackup
&DeletionProtection=true
&ServerlessConfig={"AutoPause":true,"MaxCapacity":8.0,"MinCapacity":0.5,"SwitchForce":false}
&Common request parameters

Sample success responses

XML format

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

<CloneDBInstanceResponse>
    <DBInstanceId>rm-uf6wjk5xxxxxxx</DBInstanceId>
    <RequestId>1E43AAE0-BEE8-43DA-860D-EAF2AA0724DC</RequestId>
    <OrderId>100789370****</OrderId>
</CloneDBInstanceResponse>

JSON format

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

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

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 InvalidAvZone.NotSupport Specified availableArea multiZone does not support in RDS. The error message returned because the value specified for the availableArea multiZone parameter is not supported in ApsaraDB RDS.
400 CannotDecreaseEssdPerfLevel cannot decrease cloud essd performance level. The error message returned because the change of the storage type is not allowed. The storage type of an instance that runs SQL Server with standard SSDs can be changed only to ESSDs. The storage type 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 InvalidIPAddress.Conflict IP address conflict. The error message returned because the IP addresses conflict.
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.
400 InvalidInstanceLevel.DiskType Specified instance level not support request disk type The error message returned because the specified instance type does not support the specified storage type.
400 InvalidRecoveryDbInstance.StorageType The disk local_ssd can not clone to cloud disk type The error message returned because you cannot restore the data of an instance that uses local SSDs to an instance that uses standard SSDs or ESSDs.
400 InvalidRecoveryDbInstance.StorageSize The disk space of the new instance cannot be less than that of the current instance The error message returned because the available storage of the new instance must be greater than or equal to the total size of data that is stored in the original instance.
403 IncorrectMinorVersion Current engine minor version does not support operations. The error message returned because this operation is not supported for the current minor engine version.
403 IncorrectCharacterType Current DB instance character type does not support this operation. The error message returned because this operation is not supported for the character type of the current instance.

For a list of error codes, see Service error codes.