Call the RestoreToNewInstance API to restore data to a new instance.

Request type

Asynchronous request.

Precautions

Restoring a single availability zone instance to a multiple availability zone instance, or a multiple availability zone instance to a single availability zone instance, is not supported.

Cross-major-version instance restoration is not supported. For example: Restore a MySQL 5.7 instance to a MySQL 8.0 instance.

Debug

API Explorer

You can initiate calls online through API Explorer without paying attention to the signature generation process and quickly obtain the call results.

Go to debug

Request parameters

Parameter	Type	Is it required?	Sample value	Description
SrcInstanceId	String	Yes	mysql-603e30e6****	ID of the source instance to which the backup file belongs.
BackupId	String	No	2b18d7e970c442caae05be478a9e****	Backup file ID. You can query the BackupID by calling DescribeBackups. tip Either this parameter or the RestoreTime parameter is required. You can select a backup set of a physical or logical backup to restore. When restoring from a logical backup, only the table structures and content of all non-system databases in the backup can be restored to the new instance.
RestoreTime	String	No	2022-01-01T10:10:10Z	Any point in time within the retention cycle of the original instance backup, in the yyyy-MM-ddTHH:mm:ssZ format (UTC time). You can call DescribeRecoverableTime to check if restoration to this point in time is supported. tip You must specify either this parameter or the BackupId parameter.
NodeInfo	Array of NodeInfoObject	Yes	See the request example.	The specifications of the instance. There is exactly 1 primary node, exactly 1 standby node, and 0 to 10 optional read-only nodes.
StorageType	String	Yes	LocalSSD	The storage type of the instance. Range: LocalSSD: Local SSD. CloudESSD_FlexPL: Cloud ESSD FlexPL. CloudESSD_PL0: Cloud ESSD PL0. CloudESSD_HighPerf: high performance cloud disk. tip The StorageType parameter is required if you set the StorageSpace parameter. When InstanceType is set to SingleNode, the StorageType can only be CloudESSD_FlexPL, CloudESSD_PL0, or CloudESSD_HighPerf. This parameter has different value ranges for different APIs. The rules are as follows: When used as a request parameter in the following APIs, StorageType can only be LocalSSD. RestoreToCrossRegionInstance RestoreToNewInstanceFromUserTos When used as a request parameter for some API operations, the value range of this parameter is related to the storage type of the original instance. The specific rules are as follows: If the original instance storage type is LocalSSD, the storage type cannot be changed. f the original instance storage type is CloudESSD_PL0, the value can be CloudESSD_PL0, CloudESSD_FlexPL, or CloudESSD_HighPerf. The related APIs are: RebuildDBInstance RestoreToNewInstance ModifyDBNodeSpec
StorageSpace	Integer	No	100	The storage space for the instance. Value range: [Size of the original instance's storage space, the maximum storage space for the new instance primary node specification]. The unit is GiB, with a step size of 10 GiB. The default value is the size of the source instance space. tip For more information on the value range of storage space corresponding to each specification, refer to Product specifications.
VpcId	String	Yes	vpc-2d70di2hrnbpc58ozfdx9****	Virtual private cloud (VPC) ID. You can call DescribeVpcs to query. tip Shared VPCs are not supported.
SubnetId	String	Yes	subnet-2d70dj20bob9c58ozfek6****	Subnet ID. You can call DescribeSubnets and specify the VpcId and ZoneId (the Availability zone of the primary node or secondary node) to query for available subnets.
Port	Integer	No	3306	The private network address port for the default_endpoint. The value range of the port number is 1,000-65,534, and the default value is 3,306. When a new connection endpoint is created or a new address is enabled, the private network address port of the default_endpoint is configured as the default port in real time.
AllowListIds	Array of String	No	[ "acl-a29be2559dc4406883d358892b90**", "acl-ded4c0b707e44efd8f0dbc4e88f5**" ]	Allowlists ID. To associate multiple allowlists, separate the allowlist IDs with a comma (,). An instance can be associated with up to 100 allowlists. tip When you use the RestoreToNewInstance API to restore to a new instance, the allowlists of the original instance are not associated with the new instance by default. If needed, before calling this API, you can call DescribeAllowLists to query the allowlists associated with the original instance and write them to this field. Alternatively, after restoring to the new instance, you can call AssociateAllowList to associate allowlists with the new instance.
InstanceName	String	No	Name123	Instance name. The naming rules for the instance name are as follows: It cannot start with a digit or hyphen. It can only contain Chinese characters, letters, digits, underscores (_) and hyphens (-). Length must be between 1 and 128.
DBParamGroupId	String	No	mysql-sys-6013c7b8f7ef****	Parameter templates ID. The default value is the default parameter template for the database engine version.
ProjectName	String	No	Test	Affiliated project.
ChargeInfo	Object of ChargeInfoObject	Yes	See the request example.	Payment method.
InstanceTags	Array of TagObject	No	[ { "Key":"key1", "Value":"value1" }, { "Key":"key2", "Value":"value2" } ]	Instance tag. Each MySQL instance can be associated with a maximum of 50 tags. You can add a maximum of 20 tags at a time.
AutoStorageScalingConfig	Object of AutoStorageScalingConfig	No	See the request example.	Automatic scale-out configuration.
DeletionProtection	String	No	Enabled	Indicates whether to enable deletion protection for the instance. Values: Enabled: yYes. Disabled: o. Default value.
TableMeta	Array of TableMeta	No		Specifies the databases and tables information to restore during databases and tables recovery. tip Specify this parameter only when restoring data from specified databases and tables.
ProxyNodeCustom	Object of ProxyNodeCustom	No	See the request example.	The proxy configuration of the instance. tip This field is required when the original instance of the backup is a multiple-node instance. This field does not take effect when the original instance of the backup is a double-node instance.
EnableExternalReplication	Boolean	No	false	Whether to enable native replication. Values: true: yes. false: no. Default value. tip This setting applies only when InstanceType is set to SingleNode.
PrivateIpAddress	String	No	192.168.xxx.xxx	The IP address of the default endpoint of the instance in the specified virtual private cloud and subnet. tip If this parameter is not set, an IP address within the specified virtual private cloud and subnet is automatically assigned to the default endpoint of the instance.
AutoUpgradeMinorVersion	String	No	Auto	The upgrade policy for the kernel minor version of the instance. Values: Auto: automatic. When a new kernel minor version is released, the instance is automatically upgraded to the latest kernel version during the configured Maintenance window. Manual: manual. When a new kernel version is released, you need to manually upgrade to the latest kernel version in the console. For details, refer to Manually upgrading the instance kernel version. tip If an instance's kernel minor version exceeds its maintenance cycle, the system temporarily ignores the upgrade policy and automatically upgrades the kernel minor version.

NodeInfoObject

Parameter	Type	Is it required?	Sample value	Description
NodeId	String	No	mysql-050b3e08****-r6e25	Node ID. tip This parameter is not required when you create an instance or add a node, but is required when you modify the node configuration or delete a node.
NodeType	String	Yes	Primary	Node type, with values: Primary: primary node. Secondary: secondary node. ReadOnly: read-only node. tip This parameter is optional for the DescribeDBInstancePriceDetail API. When you add a node by calling the CreateDBNodes API, you can set this parameter only to ReadOnly for a double-node instance or Secondary for a multiple-node instance. A double-node instance consists of one primary node, one secondary node, and 0 to 10 optional read-only nodes. A multiple-node instance consists of one primary node, and at least one and up to eight secondary nodes. We recommend that you reserve an independent secondary node that does not handle workloads. This allows you to switch it to the primary node when necessary. RDS for MySQL assumes no responsibility for any risks or losses incurred due to the failure to configure independent secondary nodes or the inability to complete the primary node switching due to excessive latency of all secondary nodes.
NodeSpec	String	Yes	rds.mysql.1c2g	Node specification. For details on node specification, refer to Product specification. tip The specification of the secondary node must be the same as that of the primary node. The read-only node specification can be lower than the primary node specification. However, when the read-only node specification is lower than the primary node specification, the read-only node may be delayed or even experience an OOM error due to the high load on the primary node. It is recommended that the read-only node be selected with the same or higher specification as the primary node. If StorageType is set to CloudESSD_FlexPL or CloudESSD_PL0, only the general type can be passed for NodeSpec.
ZoneId	String	Yes	cn-beijing-a	The availability zone where the node is located. You can call the DescribeAvailabilityZones API to query it. Required when creating an instance or adding a node. Optional when changing node configuration or deleting a node. tip The nodes of an instance can be distributed across a maximum of three availability zones. During a single configuration change, you can add or delete nodes in up to three availability zones.
NodeOperateType	String	No	Modify	Operation type. This parameter is not required when you create an instance but is required when you modify the node configuration. Range: Create: add. Modify: modify. tip When adding a node (CreateDBNodes), this field can only be Create. When you modify the configuration, this parameter can only be set to Modify. This value has no actual meaning when set to Delete.

ChargeInfoObject

Parameter	Type	Is it required?	Sample value	Description
ChargeType	String	Yes	PostPaid	Payment type. Values: PostPaid: pay-as-you-go (post-paid). PrePaid: subscription (pre-paid).
AutoRenew	Boolean	No	true	Specifies whether to enable Due Automatic renewal for prepaid instances. Range: true: automatic renewal. false: no automatic renewal. tip This parameter is required when the value of ChargeType is PrePaid. This parameter is not required when the value of ChargeType is PostPaid. Even if parameters are passed in, the system will automatically ignore them and the configuration will not take effect.
PeriodUnit	String	No	Month	Purchase period for prepaid scenarios. Range: Month: the purchase cycle is by month. Year: the purchase cycle is by year. tip This parameter is required when the value of ChargeType is PrePaid. This parameter is not required when the value of ChargeType is PostPaid. Even if parameters are passed in, the system will automatically ignore them and the configuration will not take effect.
Period	Integer	No	1	Subscription duration in a prepaid scenario. The value range of this parameter depends on the value of PeriodUnit: When PeriodUnit is Month, Period ranges from 1 to 9. When PeriodUnit is Year, Period ranges from 1 to 3. tip This parameter is required when the value of ChargeType is PrePaid. This parameter is not required when the value of ChargeType is PostPaid. Even if parameters are passed in, the system will automatically ignore them and the configuration will not take effect.
Number	Integer	No	1	The number of instances to purchase. Value range: 1~50. Default value: 1. tip For the RestoreToNewInstance and RestoreToCrossRegionInstance APIs, only a value of 1 is supported for this parameter. Specifying a name for each instance is not supported for batch creation. For batch instance creation: If you specify a name in the `InstanceName` parameter, a serial number is appended to the name for each instance. If you do not specify a name in the `InstanceName` parameter, the instance ID is used as the instance name.

TagObject

Parameter	Type	Is it required?	Sample value	Description
Key	String	Yes	tagkey	The key of the instance tag. The rules for the tag key are as follows: Supports letters or characters of any language, digits, and spaces. Supports special characters: _.:/=+-@. volc: is a system-reserved tag key. When adding tags, the tag key cannot start with any case form of volc:. The tag key must be 1 to 128 characters in length.
Value	String	No	tagvalue	The value of the instance tag. The rules for setting the tag value are as follows: Supports letters or characters of any language, digits, and spaces. Supports special characters: _.:/=+-@. The tag value must be 0 to 256 characters in length, which means the tag value can be empty.

AutoStorageScalingConfig

Parameter	Type	Is it required?	Sample value	Description
EnableStorageAutoScale	Boolean	Yes	true	Specifies whether to enable automatic expansion for the storage space. Values: true: yes. false: no. tip When StorageConfig is used as a request parameter, if EnableStorageAutoScale is set to false, the StorageThreshold and StorageUpperBound parameters are optional.
StorageThreshold	Integer	Yes	20	The percentage of available storage space that triggers automatic scale-out. The value range is 10 to 50, with a default value of 10. The unit is %.
StorageUpperBound	Integer	Yes	3000	The upper limit of storage space for automatic scale-out. The lower limit of this field is the instance storage space + 20 GiB, and the upper limit is the upper limit of the storage space value range corresponding to the instance primary node specifications, in GiB. For more information about the range of storage space values that can be selected for different specifications, refer to Product specifications.
ScalingDetectNode	String	No	MasterNode	The range of nodes to check for automatic expansion. Values: MasterNode: primary node. MasterSlaveNodes: primary and secondary nodes. AllNodes: all nodes. tip When used as a request parameter, the default value is MasterNode. For a multiple-node instance, setting this parameter to MasterSlaveNodes or AllNodes has the same effect. For a single-node instance, setting this parameter to MasterNode, MasterSlaveNodes, or AllNodes has the same effect.

TableMeta

Parameter	Type	Is it required?	Sample value	Description
DBName	String	Yes	testdb1	Specifies the database to restore.
NewDBName	String	No	testdb2	Rename the database name. Naming rules are as follows: The name must be unique. 2 to 64 characters in length. The name must start with a letter and end with a letter or a digit. It consists of letters, digits, underscores (_), or hyphens (-). It cannot contain certain reserved words, including root and admin. Refer to the List of forbidden keywords for forbidden reserved words. tip If you only restore tables, this parameter can be the same as DBName.
Table	Array of Table	No	[ { "TableName" : "table1", "NewTableName" : "table2" } ]	Specifies the table to restore. tip If this value is empty, the entire database specified by the DBName parameter is restored.

Table

Parameter	Type	Is it required?	Sample value	Description
TableName	String	Yes	table1	Specifies the table to restore.
NewTableName	String	No	table2	Rename the table name. Naming rules are as follows: The name must be unique. 2 to 64 characters in length. The name must start with a letter and end with a letter or a digit. It consists of letters, digits, underscores (_), or hyphens (-). It cannot contain certain reserved words, including root and admin. Refer to the List of forbidden keywords for forbidden reserved words.

ProxyNodeCustom

Parameter	Type	Is it required?	Sample value	Description
CpuNum	Integer	No	4	The number of CPU cores for the database proxy service of the instance. Range: Maximum: 1,024. The recommended number of proxy cores is the total number of CPUs of all serviceable nodes of the instance * 0.25 (round up the result). The minimum number of proxy cores is the greater of 2 and the number of CPU cores of the primary node * 0.125.

Response parameter

Parameter	Type	Sample value	Description
InstanceId	String	mysql-e7fda57b****	The Instance ID of the new instance after restoration.
OrderId	String	Order709899242175681****	Order ID.

Sample

Sample request

Sample response

Error code

For more details, refer to Error codes.

RDS for MySQL