Menu
Amazon Relational Database Service
API Reference (API Version 2014-10-31)

RestoreDBInstanceToPointInTime

Restores a DB instance to an arbitrary point in time. You can restore to any point in time before the time identified by the LatestRestorableTime property. You can restore to a point up to the number of days specified by the BackupRetentionPeriod property.

The target database is created with most of the original configuration, but in a system-selected availability zone, with the default security group, the default subnet group, and the default DB parameter group. By default, the new DB instance is created as a single-AZ deployment except when the instance is a SQL Server instance that has an option group that is associated with mirroring; in this case, the instance becomes a mirrored deployment and not a single-AZ deployment.

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

AutoMinorVersionUpgrade

Indicates that minor version upgrades will be applied automatically to the DB instance during the maintenance window.

Type: Boolean

Required: No

AvailabilityZone

The EC2 Availability Zone that the database instance will be created in.

Default: A random, system-chosen Availability Zone.

Constraint: You cannot specify the AvailabilityZone parameter if the MultiAZ parameter is set to true.

Example: us-east-1a

Type: String

Required: No

CopyTagsToSnapshot

True to copy all tags from the restored DB instance to snapshots of the DB instance; otherwise false. The default is false.

Type: Boolean

Required: No

DBInstanceClass

The compute and memory capacity of the Amazon RDS DB instance.

Valid Values: db.t1.micro | db.m1.small | db.m1.medium | db.m1.large | db.m1.xlarge | db.m2.2xlarge | db.m2.4xlarge | db.m3.medium | db.m3.large | db.m3.xlarge | db.m3.2xlarge | db.m4.large | db.m4.xlarge | db.m4.2xlarge | db.m4.4xlarge | db.m4.10xlarge | db.r3.large | db.r3.xlarge | db.r3.2xlarge | db.r3.4xlarge | db.r3.8xlarge | db.t2.micro | db.t2.small | db.t2.medium | db.t2.large

Default: The same DBInstanceClass as the original DB instance.

Type: String

Required: No

DBName

The database name for the restored DB instance.

Note

This parameter is not used for the MySQL or MariaDB engines.

Type: String

Required: No

DBSubnetGroupName

The DB subnet group name to use for the new instance.

Constraints: Must contain no more than 255 alphanumeric characters, periods, underscores, spaces, or hyphens. Must not be default.

Example: mySubnetgroup

Type: String

Required: No

Domain

Specify the Active Directory Domain to restore the instance in.

Type: String

Required: No

DomainIAMRoleName

Specify the name of the IAM role to be used when making API calls to the Directory Service.

Type: String

Required: No

EnableIAMDatabaseAuthentication

True to enable mapping of AWS Identity and Access Management (IAM) accounts to database accounts; otherwise false.

You can enable IAM database authentication for the following database engines

  • For MySQL 5.6, minor version 5.6.34 or higher

  • For MySQL 5.7, minor version 5.7.16 or higher

  • Aurora 5.6 or higher.

Default: false

Type: Boolean

Required: No

Engine

The database engine to use for the new instance.

Default: The same as source

Constraint: Must be compatible with the engine of the source

Valid Values: MySQL | mariadb | oracle-se1 | oracle-se | oracle-ee | sqlserver-ee | sqlserver-se | sqlserver-ex | sqlserver-web | postgres | aurora

Type: String

Required: No

Iops

The amount of Provisioned IOPS (input/output operations per second) to be initially allocated for the DB instance.

Constraints: Must be an integer greater than 1000.

SQL Server

Setting the IOPS value for the SQL Server database engine is not supported.

Type: Integer

Required: No

LicenseModel

License model information for the restored DB instance.

Default: Same as source.

Valid values: license-included | bring-your-own-license | general-public-license

Type: String

Required: No

MultiAZ

Specifies if the DB instance is a Multi-AZ deployment.

Constraint: You cannot specify the AvailabilityZone parameter if the MultiAZ parameter is set to true.

Type: Boolean

Required: No

OptionGroupName

The name of the option group to be used for the restored DB instance.

Permanent options, such as the TDE option for Oracle Advanced Security TDE, cannot be removed from an option group, and that option group cannot be removed from a DB instance once it is associated with a DB instance

Type: String

Required: No

Port

The port number on which the database accepts connections.

Constraints: Value must be 1150-65535

Default: The same port as the original DB instance.

Type: Integer

Required: No

PubliclyAccessible

Specifies the accessibility options for the DB instance. A value of true specifies an Internet-facing instance with a publicly resolvable DNS name, which resolves to a public IP address. A value of false specifies an internal instance with a DNS name that resolves to a private IP address.

Default: The default behavior varies depending on whether a VPC has been requested or not. The following list shows the default behavior in each case.

  • Default VPC:true

  • VPC:false

If no DB subnet group has been specified as part of the request and the PubliclyAccessible value has not been set, the DB instance will be publicly accessible. If a specific DB subnet group has been specified as part of the request and the PubliclyAccessible value has not been set, the DB instance will be private.

Type: Boolean

Required: No

RestoreTime

The date and time to restore from.

Valid Values: Value must be a time in Universal Coordinated Time (UTC) format

Constraints:

  • Must be before the latest restorable time for the DB instance

  • Cannot be specified if UseLatestRestorableTime parameter is true

Example: 2009-09-07T23:45:00Z

Type: Timestamp

Required: No

SourceDBInstanceIdentifier

The identifier of the source DB instance from which to restore.

Constraints:

  • Must be the identifier of an existing database instance

  • Must contain from 1 to 63 alphanumeric characters or hyphens

  • First character must be a letter

  • Cannot end with a hyphen or contain two consecutive hyphens

Type: String

Required: Yes

StorageType

Specifies the storage type to be associated with the DB instance.

Valid values: standard | gp2 | io1

If you specify io1, you must also include a value for the Iops parameter.

Default: io1 if the Iops parameter is specified; otherwise standard

Type: String

Required: No

Tags.Tag.N

A list of tags.

Type: Array of Tag objects

Required: No

TargetDBInstanceIdentifier

The name of the new database instance to be created.

Constraints:

  • Must contain from 1 to 63 alphanumeric characters or hyphens

  • First character must be a letter

  • Cannot end with a hyphen or contain two consecutive hyphens

Type: String

Required: Yes

TdeCredentialArn

The ARN from the Key Store with which to associate the instance for TDE encryption.

Type: String

Required: No

TdeCredentialPassword

The password for the given ARN from the Key Store in order to access the device.

Type: String

Required: No

UseLatestRestorableTime

Specifies whether (true) or not (false) the DB instance is restored from the latest backup time.

Default: false

Constraints: Cannot be specified if RestoreTime parameter is provided.

Type: Boolean

Required: No

Response Elements

The following element is returned by the service.

DBInstance

Contains the result of a successful invocation of the following actions:

This data type is used as a response element in the DescribeDBInstances action.

Type: DBInstance object

Errors

For information about the errors that are common to all actions, see Common Errors.

AuthorizationNotFound

Specified CIDRIP or EC2 security group is not authorized for the specified DB security group.

RDS may not also be authorized via IAM to perform necessary actions on your behalf.

HTTP Status Code: 404

DBInstanceAlreadyExists

User already has a DB instance with the given identifier.

HTTP Status Code: 400

DBInstanceNotFound

DBInstanceIdentifier does not refer to an existing DB instance.

HTTP Status Code: 404

DBSecurityGroupNotFound

DBSecurityGroupName does not refer to an existing DB security group.

HTTP Status Code: 404

DBSubnetGroupDoesNotCoverEnoughAZs

Subnets in the DB subnet group should cover at least two Availability Zones unless there is only one Availability Zone.

HTTP Status Code: 400

DBSubnetGroupNotFoundFault

DBSubnetGroupName does not refer to an existing DB subnet group.

HTTP Status Code: 404

DomainNotFoundFault

Domain does not refer to an existing Active Directory Domain.

HTTP Status Code: 404

InstanceQuotaExceeded

Request would result in user exceeding the allowed number of DB instances.

HTTP Status Code: 400

InsufficientDBInstanceCapacity

Specified DB instance class is not available in the specified Availability Zone.

HTTP Status Code: 400

InvalidDBInstanceState

The specified DB instance is not in the available state.

HTTP Status Code: 400

InvalidRestoreFault

Cannot restore from vpc backup to non-vpc DB instance.

HTTP Status Code: 400

InvalidSubnet

The requested subnet is invalid, or multiple subnets were requested that are not all in a common VPC.

HTTP Status Code: 400

InvalidVPCNetworkStateFault

DB subnet group does not cover all Availability Zones after it is created because users' change.

HTTP Status Code: 400

KMSKeyNotAccessibleFault

Error accessing KMS key.

HTTP Status Code: 400

OptionGroupNotFoundFault

The specified option group could not be found.

HTTP Status Code: 404

PointInTimeRestoreNotEnabled

SourceDBInstanceIdentifier refers to a DB instance with BackupRetentionPeriod equal to 0.

HTTP Status Code: 400

ProvisionedIopsNotAvailableInAZFault

Provisioned IOPS not available in the specified Availability Zone.

HTTP Status Code: 400

StorageQuotaExceeded

Request would result in user exceeding the allowed amount of storage available across all DB instances.

HTTP Status Code: 400

StorageTypeNotSupported

StorageType specified cannot be associated with the DB Instance.

HTTP Status Code: 400

Example

Sample Request

Copy
https://rds.us-east-1.amazonaws.com/ ?Action=RestoreDBInstanceToPointInTime &SignatureMethod=HmacSHA256 &SignatureVersion=4 &SourceDBInstanceIdentifier=mysqldb &TargetDBInstanceIdentifier=mysqldb-pitr &UseLatestRestorableTime=true &Version=2014-09-01 &X-Amz-Algorithm=AWS4-HMAC-SHA256 &X-Amz-Credential=AKIADQKE4SARGYLE/20140428/us-east-1/rds/aws4_request &X-Amz-Date=20140428T233051Z &X-Amz-SignedHeaders=content-type;host;user-agent;x-amz-content-sha256;x-amz-date &X-Amz-Signature=087a8eb41cb1ab0fc9ec1575f23e73757ffc6a1e42d7d2b30b9cc0be988cff97

Sample Response

Copy
<RestoreDBInstanceToPointInTimeResponse xmlns="http://rds.amazonaws.com/doc/2014-09-01/"> <RestoreDBInstanceToPointInTimeResult> <DBInstance> <BackupRetentionPeriod>7</BackupRetentionPeriod> <DBInstanceStatus>creating</DBInstanceStatus> <MultiAZ>false</MultiAZ> <VpcSecurityGroups/> <DBInstanceIdentifier>mysqldb-pitr</DBInstanceIdentifier> <PreferredBackupWindow>08:14-08:44</PreferredBackupWindow> <PreferredMaintenanceWindow>fri:04:50-fri:05:20</PreferredMaintenanceWindow> <ReadReplicaDBInstanceIdentifiers/> <Engine>mysql</Engine> <PendingModifiedValues/> <LicenseModel>general-public-license</LicenseModel> <DBParameterGroups> <DBParameterGroup> <ParameterApplyStatus>in-sync</ParameterApplyStatus> <DBParameterGroupName>default.mysql5.6</DBParameterGroupName> </DBParameterGroup> </DBParameterGroups> <EngineVersion>5.6.13</EngineVersion> <OptionGroupMemberships> <OptionGroupMembership> <OptionGroupName>default:mysql-5-6</OptionGroupName> <Status>pending-apply</Status> </OptionGroupMembership> </OptionGroupMemberships> <PubliclyAccessible>true</PubliclyAccessible> <DBSecurityGroups> <DBSecurityGroup> <Status>active</Status> <DBSecurityGroupName>default</DBSecurityGroupName> </DBSecurityGroup> </DBSecurityGroups> <DBName>mysqldb</DBName> <AutoMinorVersionUpgrade>true</AutoMinorVersionUpgrade> <AllocatedStorage>100</AllocatedStorage> <MasterUsername>myawsuser</MasterUsername> <DBInstanceClass>db.m1.medium</DBInstanceClass> </DBInstance> </RestoreDBInstanceToPointInTimeResult> <ResponseMetadata> <RequestId>13447c70-be2c-11d3-f4c6-37db295f7674</RequestId> </ResponseMetadata> </RestoreDBInstanceToPointInTimeResponse>

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: