AWS Documentation » AWS CloudFormation » User Guide » Template Reference » AWS Resource Types Reference » AWS::RDS::DBInstance	« Previous Next »
	Did this page help you? Yes \| No \| Tell us about it...

AWS::RDS::DBInstance

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

Syntax

{
   "Type" : "AWS::RDS::DBInstance",
   "Properties" :
   {
      "AllocatedStorage" : String,
      "AutoMinorVersionUpgrade" : Boolean,
      "AvailabilityZone" : String,
      "BackupRetentionPeriod" : String,
      "DBInstanceClass" : 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,
      "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

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

AvailabilityZone

The name of the Availability Zone where the DB instance is. 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.

Required: No.

Type: String.

Update requires: no interruption

DBInstanceClass

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

Required: Yes.

Type: String.

Update requires: no interruption

DBName

The name of the initial database of this instance that was provided at create time, if one was specified when the DB instance was created. 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: some interruptions However, 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 that contains the DB security groups to assign to the Amazon RDS instance. The list can contain 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 that has the specified name does not exist, the database creation fails and the stack rolls back.

Required: No.

Type: String.

Update requires: no interruption

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 to be used for the DB instance.

Required: Yes.

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–10,000, in 1000 IOPS increments.

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

Required: No.

Type: Number.

Update requires: some interruptions

LicenseModel

The license model information for the DB instance.

Required: No.

Type: String.

Update requires: replacement

MasterUsername

The master username for the DB instance.

Required: Yes.

Type: String.

Update requires: replacement

MasterUserPassword

The master password for the DB instance.

Required: Yes.

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

Tags

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

Required: No.

Type: AWS CloudFormation Resource Tags

VPCSecurityGroups

A list that contains the VPC security groups to assign to the Amazon RDS instance. The list can contain 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.

As a consequence, you should 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

Caution

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.

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, you should take the following precautions:

Quiesce any applications that are using the DB instance so that there is no activity against the DB instance.
Create a snapshot of the DB instance. For more information about creating DB snapshots, see Creating a DB snapshot.
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.
Update the stack.

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

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 and has a DeletionPolicy Attribute set. With the "Snapshot" DeletionPolicy set, 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" }
   }
}

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

Document Conventions	« Previous Next »
Terms of Use	Did this page help you? Yes \| No \| Tell us about it...