Syntax Properties Return values Remarks Examples

AWS::RDS::DBInstance

The AWS::RDS::DBInstance resource creates an Amazon DB instance. The new DB instance can be an RDS DB instance, or it can be a DB instance in an Aurora DB cluster.

For more information about creating an RDS DB instance, see Creating an Amazon RDS DB instance in the Amazon RDS User Guide.

For more information about creating a DB instance in an Aurora DB cluster, see Creating an Amazon Aurora DB cluster in the Amazon Aurora User Guide.

If you import an existing DB instance, and the template configuration doesn't match the actual configuration of the DB instance, AWS CloudFormation applies the changes in the template during the import operation.

Important

If a DB instance is deleted or replaced during an update, AWS CloudFormation deletes all automated snapshots. However, it retains manual DB snapshots. During an update that requires replacement, you can apply a stack policy to prevent DB instances from being replaced. For more information, see Prevent Updates to Stack Resources.

Updating DB instances

When properties labeled "Update requires:Replacement" are updated, AWS CloudFormation first creates a replacement DB instance, then changes references from other dependent resources to point to the replacement DB instance, and finally deletes the old DB instance.

Important

We highly recommend that you take a snapshot of the database before updating the stack. If you don't, you lose the data when AWS CloudFormation replaces your DB instance. To preserve your data, perform the following procedure:

Deactivate any applications that are using the DB instance so that there's no activity on the DB instance.
Create a snapshot of the DB instance. For more information, see Creating a DB Snapshot.
If you want to restore your instance using a DB snapshot, modify the updated template with your DB instance changes and add the DBSnapshotIdentifier property with the ID of the DB snapshot that you want to use.

After you restore a DB instance with a DBSnapshotIdentifier property, you can delete the DBSnapshotIdentifier property. When you specify this property for an update, the DB instance is not restored from the DB snapshot again, and the data in the database is not changed. If you specify a different DBSnapshotIdentifier value, a new DB instance is restored from the specified snapshot, and the original DB instance is deleted.
Update the stack.

For more information about updating other properties of this resource, see ModifyDBInstance. For more information about updating stacks, see AWS CloudFormation Stacks Updates.

Deleting DB instances

For DB instances that are part of an Aurora DB cluster, you can set a deletion policy for your DB instance to control how AWS CloudFormation handles the DB instance when the stack is deleted. For Amazon RDS DB instances, you can choose to retain the DB instance, to delete the DB instance, or to create a snapshot of the DB instance. The default AWS CloudFormation behavior depends on the DBClusterIdentifier property:

For AWS::RDS::DBInstance resources that don't specify the DBClusterIdentifier property, AWS CloudFormation saves a snapshot of the DB instance.
For AWS::RDS::DBInstance resources that do specify the DBClusterIdentifier property, AWS CloudFormation deletes the DB instance.

For more information, see DeletionPolicy Attribute.

Syntax

To declare this entity in your CloudFormation template, use the following syntax:

JSON


{
  "Type" : "AWS::RDS::DBInstance",
  "Properties" : {
      "AdditionalStorageVolumes" : [ AdditionalStorageVolume, ... ],
      "AllocatedStorage" : String,
      "AllowMajorVersionUpgrade" : Boolean,
      "ApplyImmediately" : Boolean,
      "AssociatedRoles" : [ DBInstanceRole, ... ],
      "AutomaticBackupReplicationKmsKeyId" : String,
      "AutomaticBackupReplicationRegion" : String,
      "AutomaticBackupReplicationRetentionPeriod" : Integer,
      "AutoMinorVersionUpgrade" : Boolean,
      "AvailabilityZone" : String,
      "BackupRetentionPeriod" : Integer,
      "BackupTarget" : String,
      "CACertificateIdentifier" : String,
      "CertificateRotationRestart" : Boolean,
      "CharacterSetName" : String,
      "CopyTagsToSnapshot" : Boolean,
      "CustomIAMInstanceProfile" : String,
      "DatabaseInsightsMode" : String,
      "DBClusterIdentifier" : String,
      "DBClusterSnapshotIdentifier" : String,
      "DBInstanceClass" : String,
      "DBInstanceIdentifier" : String,
      "DBName" : String,
      "DBParameterGroupName" : String,
      "DBSecurityGroups" : [ String, ... ],
      "DBSnapshotIdentifier" : String,
      "DBSubnetGroupName" : String,
      "DBSystemId" : String,
      "DedicatedLogVolume" : Boolean,
      "DeleteAutomatedBackups" : Boolean,
      "DeletionProtection" : Boolean,
      "Domain" : String,
      "DomainAuthSecretArn" : String,
      "DomainDnsIps" : [ String, ... ],
      "DomainFqdn" : String,
      "DomainIAMRoleName" : String,
      "DomainOu" : String,
      "EnableCloudwatchLogsExports" : [ String, ... ],
      "EnableIAMDatabaseAuthentication" : Boolean,
      "EnablePerformanceInsights" : Boolean,
      "Engine" : String,
      "EngineLifecycleSupport" : String,
      "EngineVersion" : String,
      "Iops" : Integer,
      "KmsKeyId" : String,
      "LicenseModel" : String,
      "ManageMasterUserPassword" : Boolean,
      "MasterUserAuthenticationType" : String,
      "MasterUsername" : String,
      "MasterUserPassword" : String,
      "MasterUserSecret" : MasterUserSecret,
      "MaxAllocatedStorage" : Integer,
      "MonitoringInterval" : Integer,
      "MonitoringRoleArn" : String,
      "MultiAZ" : Boolean,
      "NcharCharacterSetName" : String,
      "NetworkType" : String,
      "OptionGroupName" : String,
      "PerformanceInsightsKMSKeyId" : String,
      "PerformanceInsightsRetentionPeriod" : Integer,
      "Port" : String,
      "PreferredBackupWindow" : String,
      "PreferredMaintenanceWindow" : String,
      "ProcessorFeatures" : [ ProcessorFeature, ... ],
      "PromotionTier" : Integer,
      "PubliclyAccessible" : Boolean,
      "ReplicaMode" : String,
      "RestoreTime" : String,
      "SourceDBClusterIdentifier" : String,
      "SourceDBInstanceAutomatedBackupsArn" : String,
      "SourceDBInstanceIdentifier" : String,
      "SourceDbiResourceId" : String,
      "SourceRegion" : String,
      "StorageEncrypted" : Boolean,
      "StorageThroughput" : Integer,
      "StorageType" : String,
      "Tags" : [ Tag, ... ],
      "Timezone" : String,
      "UseDefaultProcessorFeatures" : Boolean,
      "UseLatestRestorableTime" : Boolean,
      "VPCSecurityGroups" : [ String, ... ]
    }
}

YAML


Type: AWS::RDS::DBInstance
Properties:
  AdditionalStorageVolumes: 
    - AdditionalStorageVolume
  AllocatedStorage: String
  AllowMajorVersionUpgrade: Boolean
  ApplyImmediately: Boolean
  AssociatedRoles: 
    - DBInstanceRole
  AutomaticBackupReplicationKmsKeyId: String
  AutomaticBackupReplicationRegion: String
  AutomaticBackupReplicationRetentionPeriod: Integer
  AutoMinorVersionUpgrade: Boolean
  AvailabilityZone: String
  BackupRetentionPeriod: Integer
  BackupTarget: String
  CACertificateIdentifier: String
  CertificateRotationRestart: Boolean
  CharacterSetName: String
  CopyTagsToSnapshot: Boolean
  CustomIAMInstanceProfile: String
  DatabaseInsightsMode: String
  DBClusterIdentifier: String
  DBClusterSnapshotIdentifier: String
  DBInstanceClass: String
  DBInstanceIdentifier: String
  DBName: String
  DBParameterGroupName: String
  DBSecurityGroups: 
    - String
  DBSnapshotIdentifier: String
  DBSubnetGroupName: String
  DBSystemId: String
  DedicatedLogVolume: Boolean
  DeleteAutomatedBackups: Boolean
  DeletionProtection: Boolean
  Domain: String
  DomainAuthSecretArn: String
  DomainDnsIps: 
    - String
  DomainFqdn: String
  DomainIAMRoleName: String
  DomainOu: String
  EnableCloudwatchLogsExports: 
    - String
  EnableIAMDatabaseAuthentication: Boolean
  EnablePerformanceInsights: Boolean
  Engine: String
  EngineLifecycleSupport: String
  EngineVersion: String
  Iops: Integer
  KmsKeyId: String
  LicenseModel: String
  ManageMasterUserPassword: Boolean
  MasterUserAuthenticationType: String
  MasterUsername: String
  MasterUserPassword: String
  MasterUserSecret: 
    MasterUserSecret
  MaxAllocatedStorage: Integer
  MonitoringInterval: Integer
  MonitoringRoleArn: String
  MultiAZ: Boolean
  NcharCharacterSetName: String
  NetworkType: String
  OptionGroupName: String
  PerformanceInsightsKMSKeyId: String
  PerformanceInsightsRetentionPeriod: Integer
  Port: String
  PreferredBackupWindow: String
  PreferredMaintenanceWindow: String
  ProcessorFeatures: 
    - ProcessorFeature
  PromotionTier: Integer
  PubliclyAccessible: Boolean
  ReplicaMode: String
  RestoreTime: String
  SourceDBClusterIdentifier: String
  SourceDBInstanceAutomatedBackupsArn: String
  SourceDBInstanceIdentifier: String
  SourceDbiResourceId: String
  SourceRegion: String
  StorageEncrypted: Boolean
  StorageThroughput: Integer
  StorageType: String
  Tags: 
    - Tag
  Timezone: String
  UseDefaultProcessorFeatures: Boolean
  UseLatestRestorableTime: Boolean
  VPCSecurityGroups: 
    - String

Properties

AdditionalStorageVolumes

The additional storage volumes associated with the DB instance. RDS supports additional storage volumes for RDS for Oracle and RDS for SQL Server.

Required: No

Type: Array of AdditionalStorageVolume

Update requires: No interruption

AllocatedStorage

The amount of storage in gibibytes (GiB) to be initially allocated for the database instance.

Note

If any value is set in the Iops parameter, AllocatedStorage must be at least 100 GiB, which corresponds to the minimum Iops value of 1,000. If you increase the Iops value (in 1,000 IOPS increments), then you must also increase the AllocatedStorage value (in 100-GiB increments).

Amazon Aurora

Not applicable. Aurora cluster volumes automatically grow as the amount of data in your database increases, though you are only charged for the space that you use in an Aurora cluster volume.

Db2