AWS CloudFormation
User Guide (API Version 2010-05-15)
Did this page help you?  Yes | No |  Tell us about it...
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.

AWS::RDS::DBInstance

The AWS::RDS::DBInstance type creates an Amazon RDS database instance. For detailed information about configuring RDS DB instances, see CreateDBInstance.

Important

If a DB instance is deleted or replaced during an update, all automated snapshots are deleted. However, manual DB snapshot are retained. 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.

Syntax

{
   "Type" : "AWS::RDS::DBInstance",
   "Properties" :
   {
      "AllocatedStorage" : String,
      "AllowMajorVersionUpgrade" : Boolean,
      "AutoMinorVersionUpgrade" : Boolean,
      "AvailabilityZone" : String,
      "BackupRetentionPeriod" : String,
      "DBInstanceClass" : String,
      "DBInstanceIdentifier" : String,
      "DBName" : String,
      "DBParameterGroupName" : String,
      "DBSecurityGroups" : [ String, ... ],
      "DBSnapshotIdentifier" : String,
      "DBSubnetGroupName" : String,
      "Engine" : String,
      "EngineVersion" : String,
      "Iops" : Number,
      "LicenseModel" : String,
      "MasterUsername" : String,
      "MasterUserPassword" : String,
      "MultiAZ" : Boolean,
      "Port" : String,
      "PreferredBackupWindow" : String,
      "PreferredMaintenanceWindow" : String,
      "PubliclyAccessible" : Boolean,
      "SourceDBInstanceIdentifier" : String,
      "Tags" : [ Resource Tag, ..., ],
      "VPCSecurityGroups" : [ String, ... ]
   }
}     

Properties

AllocatedStorage

The allocated storage size specified in gigabytes (GB).

If any value is used in the Iops parameter, AllocatedStorage must be at least 100 GB, which corresponds to the minimum Iops value of 1000. If Iops is increased (in 1000 IOPS increments), then AllocatedStorage must also be increased (in 100 GB increments) correspondingly.

Required: Yes

Type: String

Update requires: No interruption

AllowMajorVersionUpgrade

Indicates whether major version upgrades are allowed. Changing this parameter does not result in an outage, and the change is applied asynchronously as soon as possible.

Constraints: This parameter must be set to true when you specify an EngineVersion that differs from the DB instance's current major version.

Required: No

Type: Boolean

Update requires: No interruption

AutoMinorVersionUpgrade

Indicates that minor engine upgrades will be applied automatically to the DB instance during the maintenance window. The default value is true.

Required: No

Type: Boolean

Update requires: No interruption or some interruptions. For more information, see ModifyDBInstance in the Amazon Relational Database Service API Reference.

AvailabilityZone

The name of the Availability Zone where the DB instance is located. You cannot set the AvailabilityZone parameter if the MultiAZ parameter is set to true.

Required: No

Type: String

Update requires: Replacement

BackupRetentionPeriod

The number of days for which automatic DB snapshots are retained.

Important

If this DB instance is deleted or replaced during an update, all automated snapshots are deleted. However, manual DB snapshot are retained.

Required: No

Type: String

Update requires: No interruption or some interruptions. For more information, see ModifyDBInstance in the Amazon Relational Database Service API Reference.

DBInstanceClass

The name of the compute and memory capacity class of the DB instance.

Required: Yes

Type: String

Update requires: Some interruptions

DBInstanceIdentifier

A name for the DB instance. If you don't specify a name, AWS CloudFormation generates a unique physical ID and uses that ID for the DB instance. For more information, see Name Type.

Important

If you specify a name, you cannot do updates that require this resource to be replaced. You can still do updates to this resource if the update requires no or some interruption.

Required: No

Type: String

Update requires: Replacement

DBName

The name of the initial database of this instance that was provided at create time, if one was specified. This same name is returned for the life of the DB instance.

Required: No

Type: String

Update requires: Replacement

DBParameterGroupName

The name of an existing DB parameter group or a reference to an AWS::RDS::DBParameterGroup resource created in the template.

Required: No

Type: String

Update requires: No interruption or some interruptions. For more information, see ModifyDBInstance in the Amazon Relational Database Service API Reference. Also, if any of the data members of the referenced parameter group are changed during an update, the database instance may need to be restarted, causing some interruption.

DBSecurityGroups

A list of the DB security groups to assign to the Amazon RDS instance. The list can include both the name of existing DB security groups or references to AWS::RDS::DBSecurityGroup resources created in the template.

If you set DBSecurityGroups, you must not set VPCSecurityGroups, and vice-versa.

Required: No

Type: A list of strings

Update requires: No interruption

DBSnapshotIdentifier

The identifier for the DB snapshot to restore from.

By specifying this property, you can create a DB instance from the specified DB snapshot. If the DBSnapshotIdentifier property is an empty string or the AWS::RDS::DBInstance declaration has no DBSnapshotIdentifier property, the database is created as a new database. If the property contains a value (other than empty string), AWS CloudFormation creates a database from the specified snapshot. If a snapshot with the specified name does not exist, the database creation fails and the stack rolls back.

Required: No

Type: String

Update requires: Replacement

DBSubnetGroupName

A DB subnet group to associate with the DB instance.

If there is no DB subnet group, then it is a non-VPC DB instance.

For more information about using Amazon RDS in a VPC, go to Using Amazon RDS with Amazon Virtual Private Cloud (VPC) in the Amazon Relational Database Service Developer Guide.

Required: No

Type: String

Update requires: Replacement

Engine

The name of the database engine that the DB instance uses. This property is optional when you specify the DBSnapshotIdentifier property to create DB instances.

For valid values, see the Engine parameter of the CreateDBInstance action in the Amazon Relational Database Service API Reference.

Required: Conditional

Type: String

Update requires: Replacement

EngineVersion

The version number of the database engine to use.

Required: No

Type: String

Update requires: Some interruptions

Iops

The number of I/O operations per second (IOPS) that the database should provision. This can be any integer value from 1000 to 10,000, in 1000 IOPS increments.

If any value is used in the Iops parameter, AllocatedStorage must be at least 100 GB, which corresponds to the minimum Iops value of 1000. If Iops is increased (in 1000 IOPS increments), then AllocatedStorage must also be increased (in 100 GB increments) correspondingly.

For more information about this parameter, see Provisioned IOPS Storage in the Amazon Relational Database Service User Guide.

Required: No

Type: Number

Update requires: No interruption

LicenseModel

The license model information for the DB instance.

Required: No

Type: String

Update requires: Replacement.

MasterUsername

The master user name for the DB instance. This property is optional when you specify the DBSnapshotIdentifier property to create DB instances.

Required: Conditional

Type: String

Update requires: Replacement.

MasterUserPassword

The master password for the DB instance. This property is optional when you specify the DBSnapshotIdentifier property to create DB instances.

Required: Conditional

Type: String

Update requires: No interruption.

MultiAZ

Specifies if the DB instance is a multiple Availability Zone deployment. You cannot set the AvailabilityZone parameter if the MultiAZ parameter is set to true.

Required: No

Type: Boolean

Update requires: No interruption.

Port

The port for the instance.

Required: No

Type: String

Update requires: Replacement.

PreferredBackupWindow

The daily time range during which automated backups are created if automated backups are enabled, as determined by the BackupRetentionPeriod.

Required: No

Type: String

Update requires: No interruption.

PreferredMaintenanceWindow

The weekly time range (in UTC) during which system maintenance can occur.

Required: No

Type: String

Update requires: No interruption or some interruptions. For more information, see ModifyDBInstance in the Amazon Relational Database Service API Reference.

PubliclyAccessible

Indicates whether the database instance is an Internet-facing instance. If you specify true, an instance is created with a publicly resolvable DNS name, which resolves to a public IP address. If you specify false, an internal instance is created with a DNS name that resolves to a private IP address.

The default behavior value depends on your VPC setup and the database subnet group. For more information, see the PubliclyAccessible parameter in CreateDBInstance in the Amazon Relational Database Service API Reference.

Required: No

Type: Boolean

Update requires: Replacement.

SourceDBInstanceIdentifier

If you want to create a read replica DB instance, specify the ID of the source DB instance. Each DB instance can have a certain number of read replicas. For more information, see Working with Read Replicas in the Amazon Relational Database Service Developer Guide.

The SourceDBInstanceIdentifier property determines whether a DB instance is a read replica. If you remove the SourceDBInstanceIdentifier property from your current template and then update your stack, the read replica is deleted and a new DB instance (not a read replica) is created.

If you specify SourceDBInstanceIdentifier, do not set the MultiAZ property to true and do not specify the DBSnapshotIdentifier property. You cannot deploy read replicas in multiple Availability Zones, and you cannot create a read replica from a snapshot.

Important

Note the following:

  • Read replicas do not support deletion policies. Any deletion policy that's associated with a read replica is ignored.

  • You must create read replicas that are in the same region as the source DB instance. Currently, cross-region replicas are not supported.

Required: No

Type: String

Update requires: Replacement.

Tags

An arbitrary set of tags (key–value pairs) for this RDS database instance.

Required: No

Type: AWS CloudFormation Resource Tags

Update requires: No interruption.

VPCSecurityGroups

A list of the VPC security groups to assign to the Amazon RDS instance. The list can include both the physical IDs of existing VPC security groups or references to AWS::EC2::SecurityGroup resources created in the template.

If you set VPCSecurityGroups, you must not set DBSecurityGroups, and vice-versa.

Important

You can migrate a database instance in your stack from an RDS DB security group to a VPC security group, but you should keep the following points in mind:

  • You cannot revert to using an RDS security group once you have established a VPC security group membership.

  • When you migrate your DB instance to VPC security groups, if your stack update rolls back because of another failure in the database instance update, or because of an update failure in another AWS CloudFormation resource, the rollback will fail because it cannot revert to an RDS security group.

To avoid this situation, only migrate your DB instance to using VPC security groups when that is the only change in your stack template.

Required: No

Type: A list of strings

Update requires: No interruption.

Updating and Deleting AWS:RDS::DBInstances

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

Caution

If you do not take a snapshot of the database before updating the stack, you will lose the data when your DB instance is replaced. To preserve your data, take the following precautions:

  1. Deactivate any applications that are using the DB instance so that there is no activity against the DB instance.

  2. Create a snapshot of the DB instance. For more information about creating DB snapshots, see Creating a DB snapshot.

  3. If you want to restore your instance using a DB snapshot, modify the update template with your DB instance changes and add the DBSnapshotIdentifier property with the ID of the DB snapshot that you want to use.

  4. Update the stack.

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

You can set a deletion policy for your DB instance to control how AWS CloudFormation handles the instance when the stack is deleted. For Amazon RDS DB instances, you can choose to retain the instance, to delete the instance, or to create a snapshot of the instance. For more information, see DeletionPolicy Attribute.

Return Values

Ref

When you provide the RDS DB instance's logical name to the Ref intrinsic function, Ref will return the DBInstanceIdentifier. For example: mystack-mydb-ea5ugmfvuaxg.

For more information about using the Ref function, see Ref.

Fn::GetAtt

Fn::GetAtt returns a value for a specified attribute of this type. This section lists the available attributes and corresponding return values.

  • Endpoint.Address

    The connection endpoint for the database. For example: mystack-mydb-1apw1j4phylrk.cg034hpkmmjt.us-east-1.rds.amazonaws.com.

  • Endpoint.Port

    The port number on which the database accepts connections. For example: 3306.

For more information about using Fn:GetAtt, see Fn::GetAtt.

Examples

Example DBInstance with a set MySQL version, Tags and DeletionPolicy

This example shows how to set the MySQL version that has a DeletionPolicy Attribute set. With the DeletionPolicy set to Snapshot, AWS CloudFormation will take a snapshot of this DB instance before deleting it during stack deletion. A tag that contains a friendly name for the database is also set.

"MyDB" : {
   "Type" : "AWS::RDS::DBInstance",
   "Properties" : {
      "DBName" : { "Ref" : "DBName" },
      "AllocatedStorage" : { "Ref" : "DBAllocatedStorage" },
      "DBInstanceClass" : { "Ref" : "DBInstanceClass" },
      "Engine" : "MySQL",
      "EngineVersion" : "5.5",
      "MasterUsername" : { "Ref" : "DBUser" },
      "MasterUserPassword" : { "Ref" : "DBPassword" },
      "Tags" : [ { "Key" : "Name", "Value" : "My SQL Database" } ]
   },
   "DeletionPolicy" : "Snapshot"
}         

Example DBInstance with provisioned IOPS

This example sets a provisioned IOPS value in the Iops property. Note that the AllocatedStorage property is set according to the 10:1 ratio between IOPS and GiBs of storage.

"MyDB" : {
   "Type" : "AWS::RDS::DBInstance",
   "Properties" : {
      "AllocatedStorage" : "100",
      "DBInstanceClass" : "db.m1.small",
      "Engine" : "MySQL",
      "EngineVersion" : "5.5",
      "Iops" : "1000",
      "MasterUsername" : { "Ref" : "DBUser" },
      "MasterUserPassword" : { "Ref" : "DBPassword" }
   }
}        

Example Read replica DBInstance

This example creates a read replica named MyDBreadreplica for the MyDB DB instance.

"MyDB" : {
   "Type" : "AWS::RDS::DBInstance",
   "Properties" : {
      "DBName" : { "Ref" : "DBName" },
      "AllocatedStorage" : { "Ref" : "DBAllocatedStorage" },
      "DBInstanceClass" : { "Ref" : "DBClass" },
      "Engine" : "MySQL",
      "EngineVersion" : "5.6",
      "MasterUsername" : { "Ref" : "DBUser" } ,
      "MasterUserPassword" : { "Ref" : "DBPassword" },
      "Port" : "5804",
      "Tags" : [{"Key" : "Role", "Value" : "Primary"}] 
   }
},

"MyDBreadreplica" : {
   "Type": "AWS::RDS::DBInstance",
   "Properties": {
      "SourceDBInstanceIdentifier": { "Ref" : "MyDB" },
      "Port" : "5802",
      "Tags" : [{"Key" : "Role", "Value" : "ReadRep"}]     
      }
   }
}

To view more AWS::RDS::DBInstance template snippets, see Amazon RDS Template Snippets.