Help Center/ Relational Database Service/ API Reference/ API v3.1 (Recommended)/ Restoring Data to an Existing DB Instance
Updated on 2025-08-20 GMT+08:00

Restoring Data to an Existing DB Instance

Function

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

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 MySQL and Microsoft SQL Server DB engines.

    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 Parameters

    Parameter

    Mandatory

    Description

    project_id

    Yes

    Definition

    Project ID of a tenant in a region.

    To obtain the value, see Obtaining a Project ID.

    Constraints

    N/A

    Range

    N/A

    Default Value

    N/A

Request

Table 3 Parameters

Parameter

Mandatory

Type

Description

source

Yes

Object

Definition

Restoration information.

For details, see Table 4.

Constraints

N/A

Range

N/A

Default Value

N/A

target

Yes

Object

Definition

Instance to which the backup is restored.

For details, see Table 5.

Constraints

N/A

Range

N/A

Default Value

N/A

Table 4 source field data structure description

Parameter

Mandatory

Type

Description

instance_id

Yes

String

Definition

Instance ID.

Constraints

N/A

Range

N/A

Default Value

N/A

type

No

String

Definition

Restoration mode of the instance.

Constraints

N/A

Range

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

Default Value

N/A

backup_id

No

String

Definition

ID of the backup used to restore data. This parameter must be specified when the backup file is used for restoration.

Constraints

N/A

Range

N/A

Default Value

N/A

restore_time

No

Integer

Definition

Time point of data restoration in the UNIX timestamp format. The unit is millisecond and the time zone is UTC.

Constraints

N/A

Range

N/A

Default Value

N/A

database_name

No

Map<String, String>

Definition

Name of the new database after the restoration. If this parameter is available, you can restore specific databases and rename new databases.

Constraints

  • This parameter is only available to RDS for SQL Server.
  • If this parameter is not specified, all databases are restored by default.
  • Before the restoration, make sure that the size of the restored data does not exceed the purchased disk capacity. Expand disk capacity, if necessary.

Range

  • You can enter multiple new database names and separate them with commas (,). The new database names can contain the original 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.
  • Check whether new database names are case sensitive based on the character set selected during instance creation and make sure each new database name is 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.

Default Value

N/A

restore_all_database

No

Boolean

Definition

Whether to restore all databases to the target instance.

Constraints

This field is available only for Microsoft SQL Server.

Range

  • true: All databases will be restored to the target instance.
  • false: Not all databases will be restored to the target instance.

Default Value

The default value is false.

Table 5 target field data structure description

Name

Mandatory

Type

Description

instance_id

Yes

String

Definition

Specifies the ID of the DB instance where the backup will be restored to.

Constraints

N/A

Range

N/A

Default Value

N/A

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 Parameters

    Parameter

    Type

    Description

    job_id

    String

    Definition

    Indicates the job ID.

    Range

    N/A

  • Example normal response
    {
    	"job_id": "ff80808157127d9301571bf8160c001d"
    }
  • Abnormal response

    For details, see Abnormal Request Results.

Status Code

Error Code

For details, see Error Codes.