Help Center/ Relational Database Service/ API Reference/ API v3.1 (Recommended)/ Restoring Data to an Existing DB Instance

Updated on 2024-04-11 GMT+08:00

View PDF

Restoring Data to an Existing DB Instance

Function

This API is used to restore a database to an existing DB instance.

Before calling an API, you need to understand the API in Authentication.

Constraints

RDS for SQL Server supports batch calling of this API to restore one database to an existing DB instance.
When data is restored to an existing DB instance, the API has the following constraints:
- The DB engine of the original DB instance must be the same as that of the target DB instance. For example, if the original DB instance is running MySQL, the target DB instance must also run MySQL.
- For RDS for MySQL, the DB engine version of the target DB instance must be at least equal to that of the original DB instance, for example, from MySQL 5.7.25 to 5.7.27.
- For RDS for PostgreSQL, the DB engine version of the target DB instance must be the same as that of the original DB instance.
- For RDS for SQL Server, the time zone of the target DB instance must be the same as that of the original DB instance. Otherwise, data inconsistency may occur.
- For version constraints of RDS for SQL Server, see Table 1.
- The total storage space of the target DB instance must be at least equal to that of the original DB instance for RDS for MySQL.
- Cross-region restoration is not supported.
- For RDS for MySQL DB instances, when data is restored to an existing DB instance, the case sensitivity setting of the existing DB instance must be the same as that of the original DB instance. Otherwise, the restoration may fail.

When data is restored to an original DB instance:

This API is supported only for the Microsoft SQL Server DB engine.

**Table 1** Restoring to the DB engine versions supported by RDS for SQL Server
Original DB Engine Version	Restore To
2008 R2 Standard Edition	2008 R2 Standard Edition 2008 R2 Enterprise Edition 2012 Standard Edition 2012 Enterprise Edition 2014 Standard Edition 2014 Enterprise Edition 2016 Standard Edition 2016 Enterprise Edition 2017 Standard Edition 2017 Enterprise Edition
2012 Web Edition	2012 Web Edition 2012 Standard Edition 2012 Enterprise Edition 2014 Web Edition 2014 Standard Edition 2014 Enterprise Edition 2016 Web Edition 2016 Standard Edition 2016 Enterprise Edition 2017 Web Edition 2017 Standard Edition 2017 Enterprise Edition
2012 Standard Edition	2012 Standard Edition 2012 Enterprise Edition 2014 Standard Edition 2014 Enterprise Edition 2016 Standard Edition 2016 Enterprise Edition 2017 Standard Edition 2017 Enterprise Edition
2012 Enterprise Edition	2012 Enterprise Edition 2014 Enterprise Edition 2016 Enterprise Edition 2017 Enterprise Edition
2014 Standard Edition	2014 Standard Edition 2014 Enterprise Edition 2016 Standard Edition 2016 Enterprise Edition 2017 Standard Edition 2017 Enterprise Edition
2014 Enterprise Edition	2014 Enterprise Edition 2016 Enterprise Edition 2017 Enterprise Edition
2016 Standard Edition	2016 Standard Edition 2016 Enterprise Edition 2017 Standard Edition 2017 Enterprise Edition
2016 Enterprise Edition	2016 Enterprise Edition 2017 Enterprise Edition
2017 Web Edition	2017 Web Edition 2017 Standard Edition 2017 Enterprise Edition
2017 Standard Edition	2017 Standard Edition 2017 Enterprise Edition
2017 Enterprise Edition	2017 Enterprise Edition

URI

URI format
POST /v3.1/{project_id}/instances/recovery

Parameter description

**Table 2** Parameter description
Name	Mandatory	Description
project_id	Yes	Project ID of a tenant in a region. For details about how to obtain the project ID, see Obtaining a Project ID.

Request

**Table 3** Parameter description
Name	Mandatory	Type	Description
source	Yes	Object	Specifies the restoration information. For details, see Table 4.
target	Yes	Object	Specifies the restoration target. For details, see Table 5.

**Table 4** source field data structure description
Name	Mandatory	Type	Description
instance_id	Yes	String	Specifies the DB instance ID.
type	No	String	Specifies the restoration mode. Enumerated values include: backup: indicates using backup files for restoration. In this mode, type is not mandatory and backup_id is mandatory. timestamp: indicates the point-in-time restoration mode. In this mode, type and restore_time are mandatory.
backup_id	No	String	Specifies the ID of the backup used to restore data. This parameter must be specified when the backup file is used for restoration.
restore_time	No	Integer	Specifies the time point of data restoration in the UNIX timestamp. The unit is millisecond and the time zone is UTC.
database_name	No	Map<String, String>	This parameter applies only to the Microsoft SQL Server DB engine. If this parameter is specified, you can restore all or specific databases and rename new databases. If this parameter is not specified, all databases are restored by default. You can enter multiple new database names and separate them with commas (,). The new database names can contain but cannot be the same as the original database names. Note the following when you are specifying new database names: New database names must be different from the original database names. If they are left blank, the original database names will be used for restoration by default. The case-sensitivity settings of the new databases are the same as those of the original databases. Make sure the new database names are unique. The total number of new and existing databases on the existing or original DB instances where data is restored cannot exceed the database quota specified by rds_databases_quota. New database names cannot contain the following fields (case-insensitive): rdsadmin, master, msdb, tempdb, model, and resource. New database names must consist of 1 to 64 characters, including only letters, digits, underscores (_), and hyphens (-). If you want to restore data to multiple new databases, separate them with commas (,). New database names must be different from any database names on the original DB instance. New database names must be different from any database names on the existing or original DB instances where data is restored. Example: "database_name":{"Original database name":"New database name"} Correct example: "database_name":{"A":"A,A1,A2","B":"B1,B2","C":""} Wrong example: "database_name":{"A":"A","B":"B1,B2","C":"B1,C1","D":"D1,d1"}, Error causes are as follows: The new database name (A) is the same as the original database name (A). The new database name (B1) is not unique. When the database name is case insensitive, the database names D1 and d1 conflict. Exercise caution when restoring data to an existing or original DB instance. NOTICE: Before the restoration, make sure that the size of the restored data does not exceed the purchased disk capacity. Expand disk capacity, if necessary.
restore_all_database	No	Boolean	Specifies whether to restore all databases. The default value is false, indicating that not all databases are to be restored to the target instance. This field is available only for Microsoft SQL Server. NOTICE: If you want to restore all databases to an existing instance, set restore_all_database to true.

**Table 5** target field data structure description
Name	Mandatory	Type	Description
instance_id	Yes	String	Specifies the ID of the DB instance where the backup will be restored to.

Example Request

Restore data to a DB instance from a backup.

POST https://{endpoint}/v3.1/0483b6b16e954cb88930a360d2c4e663/instances/recovery

{
	"source": {
		"instance_id": "d8e6ca5a624745bcb546a227aa3ae1cfin01",
		"type": "backup",
		"backup_id": "2f4ddb93-b901-4b08-93d8-1d2e472f30fe"
	},
	"target": {
		"instance_id": "d8e6ca5a624745bcb546a227aa3ae1cfin01"
	}
}

Restore all databases to a DB instance from an RDS for SQL Server backup.

{
	"source": {
		"instance_id": "61879e6085bc44d1831b0ce62d988fd9in04",
		"type": "backup",
		"backup_id": "b021670e69ba4538b7b2ed07257306aebr04",
                "restore_all_database":true
	},
	"target": {
		"instance_id": "d8e6ca5a624745bcb546a227aa3ae1cfin04"
	}
}

Restore instance data to a specific point in time.

{
	"source": {
		"instance_id": "d8e6ca5a624745bcb546a227aa3ae1cfin01",
		"type": "timestamp",
		"restore_time": 1532001446987
	},
	"target": {
		"instance_id": "d8e6ca5a624745bcb546a227aa3ae1cfin01"
	}
}

Restore some databases of an RDS for SQL Server instance to a specific point in time.

{
	"source": {
		"instance_id": "61879e6085bc44d1831b0ce62d988fd9in04",
		"type": "timestamp",
		"restore_time": 1532001446987,
		"database_name": {
			"db1": "dbtest1,dbtest2",
			"db2": "db2,db02",
                        "db3": ""
		}
	},
	"target": {
		"instance_id": "d8e6ca5a624745bcb546a227aa3ae1cfin04"
	}
}

Response

Normal response

**Table 6** Parameter description
Name	Type	Description
job_id	String	Indicates the job ID.

Example normal response

{
	"job_id": "ff80808157127d9301571bf8160c001d"
}

Abnormal response
For details, see Abnormal Request Results.

Status Code

Normal
200
Abnormal
For details, see Status Codes.

Error Code

For details, see Error Codes.

Parent topic: API v3.1 (Recommended)

Previous topic: Modifying Parameters of a Specified Instance

Next topic: Restoring Tables to a Specified Point in Time (RDS for MySQL)

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot