github.com/nathanielks/terraform@v0.6.1-0.20170509030759-13e1a62319dc/website/source/docs/providers/aws/r/db_instance.html.markdown (about) 1 --- 2 layout: "aws" 3 page_title: "AWS: aws_db_instance" 4 sidebar_current: "docs-aws-resource-db-instance" 5 description: |- 6 Provides an RDS instance resource. 7 --- 8 9 # aws\_db\_instance 10 11 Provides an RDS instance resource. A DB instance is an isolated database 12 environment in the cloud. A DB instance can contain multiple user-created 13 databases. 14 15 Changes to a DB instance can occur when you manually change a 16 parameter, such as `allocated_storage`, and are reflected in the next maintenance 17 window. Because of this, Terraform may report a difference in its planning 18 phase because a modification has not yet taken place. You can use the 19 `apply_immediately` flag to instruct the service to apply the change immediately 20 (see documentation below). 21 22 When upgrading the major version of an engine, `allow_major_version_upgrade` must be set to `true` 23 24 ~> **Note:** using `apply_immediately` can result in a 25 brief downtime as the server reboots. See the AWS Docs on [RDS Maintenance][2] 26 for more information. 27 28 ~> **Note:** All arguments including the username and password will be stored in the raw state as plain-text. 29 [Read more about sensitive data in state](/docs/state/sensitive-data.html). 30 31 ## Example Usage 32 33 ```hcl 34 resource "aws_db_instance" "default" { 35 allocated_storage = 10 36 storage_type = "gp2" 37 engine = "mysql" 38 engine_version = "5.6.17" 39 instance_class = "db.t1.micro" 40 name = "mydb" 41 username = "foo" 42 password = "bar" 43 db_subnet_group_name = "my_database_subnet_group" 44 parameter_group_name = "default.mysql5.6" 45 } 46 ``` 47 48 ## Argument Reference 49 50 For more detailed documentation about each argument, refer to 51 the [AWS official documentation](http://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_CreateDBInstance.html). 52 53 The following arguments are supported: 54 55 * `allocated_storage` - (Required unless a `snapshot_identifier` or `replicate_source_db` is provided) The allocated storage in gigabytes. 56 * `engine` - (Required unless a `snapshot_identifier` or `replicate_source_db` is provided) The database engine to use. 57 * `engine_version` - (Optional) The engine version to use. 58 * `identifier` - (Optional, Forces new resource) The name of the RDS instance, if omitted, Terraform will assign a random, unique identifier. 59 * `identifier_prefix` - (Optional, Forces new resource) Creates a unique identifier beginning with the specified prefix. Conflicts with `identifer`. 60 * `instance_class` - (Required) The instance type of the RDS instance. 61 * `storage_type` - (Optional) One of "standard" (magnetic), "gp2" (general 62 purpose SSD), or "io1" (provisioned IOPS SSD). The default is "io1" if 63 `iops` is specified, "standard" if not. Note that this behaviour is different from the AWS web console, where the default is "gp2". 64 * `final_snapshot_identifier` - (Optional) The name of your final DB snapshot 65 when this DB instance is deleted. If omitted, no final snapshot will be 66 made. 67 * `skip_final_snapshot` - (Optional) Determines whether a final DB snapshot is created before the DB instance is deleted. If true is specified, no DBSnapshot is created. If false is specified, a DB snapshot is created before the DB instance is deleted, using the value from `final_snapshot_identifier`. Default is `false`. 68 * `copy_tags_to_snapshot` – (Optional, boolean) On delete, copy all Instance `tags` to 69 the final snapshot (if `final_snapshot_identifier` is specified). Default 70 `false` 71 * `name` - (Optional) The DB name to create. If omitted, no database is created 72 initially. 73 * `password` - (Required unless a `snapshot_identifier` or `replicate_source_db` is provided) Password for the master DB user. Note that this may 74 show up in logs, and it will be stored in the state file. 75 * `username` - (Required unless a `snapshot_identifier` or `replicate_source_db` is provided) Username for the master DB user. 76 * `availability_zone` - (Optional) The AZ for the RDS instance. 77 * `backup_retention_period` - (Optional) The days to retain backups for. Must be 78 `1` or greater to be a source for a [Read Replica][1]. 79 * `backup_window` - (Optional) The backup window. 80 * `iops` - (Optional) The amount of provisioned IOPS. Setting this implies a 81 storage_type of "io1". 82 * `maintenance_window` - (Optional) The window to perform maintenance in. 83 Syntax: "ddd:hh24:mi-ddd:hh24:mi". Eg: "Mon:00:00-Mon:03:00". 84 See [RDS Maintenance Window docs](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/AdjustingTheMaintenanceWindow.html) for more. 85 * `multi_az` - (Optional) Specifies if the RDS instance is multi-AZ 86 * `port` - (Optional) The port on which the DB accepts connections. 87 * `publicly_accessible` - (Optional) Bool to control if instance is publicly accessible. Defaults to `false`. 88 * `vpc_security_group_ids` - (Optional) List of VPC security groups to associate. 89 * `security_group_names` - (Optional/Deprecated) List of DB Security Groups to associate. 90 Only used for [DB Instances on the _EC2-Classic_ Platform](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_VPC.html#USER_VPC.FindDefaultVPC). 91 * `db_subnet_group_name` - (Optional) Name of DB subnet group. DB instance will be created in the VPC associated with the DB subnet group. If unspecified, will be created in the `default` VPC, or in EC2 Classic, if available. 92 * `parameter_group_name` - (Optional) Name of the DB parameter group to associate. 93 * `option_group_name` - (Optional) Name of the DB option group to associate. 94 * `storage_encrypted` - (Optional) Specifies whether the DB instance is encrypted. The default is `false` if not specified. 95 * `apply_immediately` - (Optional) Specifies whether any database modifications 96 are applied immediately, or during the next maintenance window. Default is 97 `false`. See [Amazon RDS Documentation for more information.](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Overview.DBInstance.Modifying.html) 98 * `replicate_source_db` - (Optional) Specifies that this resource is a Replicate 99 database, and to use this value as the source database. This correlates to the 100 `identifier` of another Amazon RDS Database to replicate. See 101 [DB Instance Replication][1] and 102 [Working with PostgreSQL and MySQL Read Replicas](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_ReadRepl.html) for 103 more information on using Replication. 104 * `snapshot_identifier` - (Optional) Specifies whether or not to create this database from a snapshot. This correlates to the snapshot ID you'd find in the RDS console, e.g: rds:production-2015-06-26-06-05. 105 * `license_model` - (Optional, but required for some DB engines, i.e. Oracle SE1) License model information for this DB instance. 106 * `auto_minor_version_upgrade` - (Optional) Indicates that minor engine upgrades will be applied automatically to the DB instance during the maintenance window. Defaults to true. 107 * `allow_major_version_upgrade` - (Optional) Indicates that major version upgrades are allowed. Changing this parameter does not result in an outage and the change is asynchronously applied as soon as possible. 108 * `monitoring_role_arn` - (Optional) The ARN for the IAM role that permits RDS to send 109 enhanced monitoring metrics to CloudWatch Logs. You can find more information on the [AWS Documentation](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_Monitoring.html) 110 what IAM permissions are needed to allow Enhanced Monitoring for RDS Instances. 111 * `monitoring_interval` - (Optional) The interval, in seconds, between points when Enhanced Monitoring metrics are collected for the DB instance. To disable collecting Enhanced Monitoring metrics, specify 0. The default is 0. Valid Values: 0, 1, 5, 10, 15, 30, 60. 112 * `kms_key_id` - (Optional) The ARN for the KMS encryption key. 113 * `character_set_name` - (Optional) The character set name to use for DB encoding in Oracle instances. This can't be changed. 114 [Oracle Character Sets Supported in Amazon RDS](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.OracleCharacterSets.html) 115 * `iam_database_authentication_enabled` - (Optional) Specifies whether or mappings of AWS Identity and Access Management (IAM) accounts to database accounts is enabled. 116 * `tags` - (Optional) A mapping of tags to assign to the resource. 117 * `timezone` - (Optional) Time zone of the DB instance. `timezone` is currently only supported by Microsoft SQL Server. 118 The `timezone` can only be set on creation. See [MSSQL User Guide](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_SQLServer.html#SQLServer.Concepts.General.TimeZone) for more information 119 120 ~> **NOTE:** Removing the `replicate_source_db` attribute from an existing RDS 121 Replicate database managed by Terraform will promote the database to a fully 122 standalone database. 123 124 ## Attributes Reference 125 126 The following attributes are exported: 127 128 * `id` - The RDS instance ID. 129 * `address` - The address of the RDS instance. 130 * `arn` - The ARN of the RDS instance. 131 * `allocated_storage` - The amount of allocated storage 132 * `availability_zone` - The availability zone of the instance 133 * `backup_retention_period` - The backup retention period 134 * `backup_window` - The backup window 135 * `endpoint` - The connection endpoint 136 * `engine` - The database engine 137 * `engine_version` - The database engine version 138 * `instance_class`- The RDS instance class 139 * `maintenance_window` - The instance maintenance window 140 * `multi_az` - If the RDS instance is multi AZ enabled 141 * `name` - The database name 142 * `port` - The database port 143 * `status` - The RDS instance status 144 * `username` - The master username for the database 145 * `storage_encrypted` - Specifies whether the DB instance is encrypted 146 * `hosted_zone_id` - The canonical hosted zone ID of the DB instance (to be used in a Route 53 Alias record) 147 148 On Oracle instances the following is exported additionally: 149 150 * `character_set_name` - The character set used on Oracle instances. 151 152 153 <a id="timeouts"></a> 154 ## Timeouts 155 156 `aws_db_instance` provides the following 157 [Timeouts](/docs/configuration/resources.html#timeouts) configuration options: 158 159 - `create` - (Default `40 minutes`) Used for Creating Instances, Replicas, and 160 restoring from Snapshots 161 - `update` - (Default `80 minutes`) Used for Database modifications 162 - `delete` - (Default `40 minutes`) Used for destroying databases. This includes 163 the time required to take snapshots 164 165 [1]: https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Overview.Replication.html 166 [2]: https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_UpgradeDBInstance.Maintenance.html 167 168 ## Import 169 170 DB Instances can be imported using the `identifier`, e.g. 171 172 ``` 173 $ terraform import aws_db_instance.default mydb-rds-instance 174 ```