db_instance submodule

Reference for the db_instance submodule — the core resource module that provisions the aws_db_instance and supporting resources.

The db_instance submodule is the core of the terraform-aws-rds module. It provisions the aws_db_instance resource along with the Enhanced Monitoring IAM role, CloudWatch log groups, and Secrets Manager password rotation. The root module wraps this submodule and coordinates it with the subnet group, parameter group, and option group submodules.

Source

./modules/db_instance

Usage

To use this submodule directly:

module "db_instance" {
  source  = "terraform-aws-modules/rds/aws//modules/db_instance"
  version = "~> 7.0"

  identifier        = "mydb"
  engine            = "postgres"
  engine_version    = "17"
  instance_class    = "db.t4g.large"
  allocated_storage = 20

  db_name  = "myapp"
  username = "dbadmin"
  password_wo = var.db_password
  password_wo_version = 1
  manage_master_user_password = false

  db_subnet_group_name   = module.db_subnet_group.db_subnet_group_id
  parameter_group_name   = module.db_parameter_group.db_parameter_group_id
  vpc_security_group_ids = [aws_security_group.rds.id]

  tags = {
    Environment = "production"
  }
}

In most cases, use the root module (terraform-aws-modules/rds/aws) rather than this submodule directly. The root module creates and wires together the subnet group, parameter group, and option group automatically.

Input variables

Resource control

create · bool

Whether to create the DB instance and all associated resources. Set to false to skip all resource creation.

Default: true

region · string

Region where this resource will be managed. Defaults to the region set in the provider configuration.

Default: null

Instance

identifier · string · required

The name of the RDS instance.

use_identifier_prefix · bool

Determines whether to use identifier as-is or create a unique identifier beginning with identifier as the specified prefix.

Default: false

engine · string

The database engine to use. Not required when replicate_source_db is set.

Default: null

engine_version · string

The engine version to use.

Default: null

engine_lifecycle_support · string

The life cycle type for this DB instance. Applies only to RDS for MySQL and RDS for PostgreSQL. Valid values: open-source-rds-extended-support, open-source-rds-extended-support-disabled.

Default: null

instance_class · string

The instance type of the RDS instance (e.g. db.t3.micro, db.r6g.large).

Default: null

allocated_storage · number

The allocated storage in gigabytes.

Default: null

storage_type · string

One of standard, gp2, gp3, or io1. Defaults to io1 if iops is specified, gp2 otherwise.

Default: null

storage_encrypted · bool

Specifies whether the DB instance is encrypted.

Default: true

kms_key_id · string

The ARN for the KMS encryption key.

Default: null

max_allocated_storage · number

Enables Storage Autoscaling when set to a value greater than allocated_storage. Set to 0 to disable.

Default: 0

storage_throughput · number

Storage throughput for gp3 storage type.

Default: null

iops · number

The amount of provisioned IOPS. Requires storage_type of io1 or gp3.

Default: null

dedicated_log_volume · bool

Use a dedicated log volume (DLV) for the DB instance. Requires Provisioned IOPS.

Default: false

custom_iam_instance_profile · string

RDS custom IAM instance profile name.

Default: null

Database credentials

db_name · string

The DB name to create. If omitted, no database is created initially.

Default: null

username · string

Username for the master DB user. Ignored when replicate_source_db is set.

Default: null

password_wo · string

Write-only, ephemeral password for the master DB user. Not used when manage_master_user_password is true or replicate_source_db is set.

Default: null

password_wo_version · number

Version counter for password_wo. Increment to trigger a password update.

Default: null

manage_master_user_password · bool

Set to true to let RDS manage the master user password via Secrets Manager.

Default: true

master_user_secret_kms_key_id · string

KMS key ARN/ID/alias for encrypting the Secrets Manager secret.

Default: null

port · string

The port on which the DB accepts connections.

Default: null

Network

vpc_security_group_ids · list(string)

List of VPC security group IDs to associate.

Default: []

db_subnet_group_name · string

Name of the DB subnet group for the instance.

Default: null

parameter_group_name · string

Name of the DB parameter group to associate.

Default: null

option_group_name · string

Name of the DB option group to associate.

Default: null

publicly_accessible · bool

Bool to control if instance is publicly accessible.

Default: false

multi_az · bool

Specifies if the RDS instance is multi-AZ.

Default: false

availability_zone · string

The Availability Zone of the RDS instance.

Default: null

network_type · string

The type of network stack to use. Valid values: IPV4, DUAL.

Default: null

customer_owned_ip_enabled · bool

Indicates whether to enable a customer-owned IP address (CoIP) for an RDS on Outposts DB instance.

Default: null

Backup & Recovery

backup_retention_period · number

The days to retain backups for.

Default: null

backup_window · string

The daily time range (UTC) during which automated backups are created.

Default: null

copy_tags_to_snapshot · bool

On delete, copy all Instance tags to the final snapshot.

Default: true

skip_final_snapshot · bool

If true, no final snapshot is created on deletion.

Default: false

final_snapshot_identifier_prefix · string

Prefix for the final snapshot identifier.

Default: "final"

delete_automated_backups · bool

Specifies whether to remove automated backups immediately after the DB instance is deleted.

Default: true

snapshot_identifier · string

Snapshot ID from which to create the DB instance.

Default: null

restore_to_point_in_time · object

Restore to a point in time. MySQL is not supported. See inputs reference for the full object schema.

Default: null

s3_import · object

Restore from a Percona Xtrabackup in S3. Only MySQL is supported. See inputs reference for the full object schema.

Default: null

Maintenance

maintenance_window · string

The window to perform maintenance in.

Default: null

apply_immediately · bool

Apply database modifications immediately rather than during the next maintenance window.

Default: false

allow_major_version_upgrade · bool

Allow major engine version upgrades.

Default: false

auto_minor_version_upgrade · bool

Automatically apply minor engine upgrades during the maintenance window.

Default: true

blue_green_update · object

Enable low-downtime updates using RDS Blue/Green deployments.

Default: null

upgrade_storage_config · bool

Upgrade the storage file system configuration on the read replica.

Default: null

Monitoring

monitoring_interval · number

Enhanced Monitoring collection interval in seconds. Valid values: 0, 1, 5, 10, 15, 30, 60. Use 0 to disable.

Default: 0

monitoring_role_arn · string

ARN of the IAM role for Enhanced Monitoring. Required when monitoring_interval > 0 and create_monitoring_role = false.

Default: null

monitoring_role_name · string

Name of the IAM role to create for Enhanced Monitoring.

Default: "rds-monitoring-role"

monitoring_role_use_name_prefix · bool

Use monitoring_role_name as a prefix instead of an exact name.

Default: false

monitoring_role_description · string

Description of the monitoring IAM role.

Default: null

create_monitoring_role · bool

Create an IAM role for Enhanced Monitoring.

Default: false

monitoring_role_permissions_boundary · string

ARN of the permissions boundary policy for the monitoring IAM role.

Default: null

performance_insights_enabled · bool

Enable Performance Insights.

Default: false

performance_insights_retention_period · number

Days to retain Performance Insights data. Valid values: 7, 731, or a multiple of 31.

Default: 7

performance_insights_kms_key_id · string

KMS key ARN for encrypting Performance Insights data.

Default: null

database_insights_mode · string

Database Insights mode. Valid values: standard, advanced.

Default: null

CloudWatch Logs

enabled_cloudwatch_logs_exports · list(string)

Log types to export to CloudWatch Logs.

Default: []

create_cloudwatch_log_group · bool

Create CloudWatch log groups for each export type. Not created when use_identifier_prefix is true.

Default: false

cloudwatch_log_group_retention_in_days · number

Days to retain CloudWatch logs.

Default: 7

cloudwatch_log_group_kms_key_id · string

KMS key ARN for encrypting CloudWatch log data.

Default: null

cloudwatch_log_group_skip_destroy · bool

Preserve log groups on destroy.

Default: null

cloudwatch_log_group_class · string

Log group class. Valid values: STANDARD, INFREQUENT_ACCESS.

Default: null

cloudwatch_log_group_tags · map(string)

Additional tags for the CloudWatch log group(s).

Default: {}

Authentication — Password Rotation

manage_master_user_password_rotation · bool

Manage master user password rotation via Secrets Manager. Requires manage_master_user_password = true.

Default: false

master_user_password_rotate_immediately · bool

Rotate the secret immediately on next apply.

Default: null

master_user_password_rotation_automatically_after_days · number

Days between automatic rotations.

Default: null

master_user_password_rotation_duration · string

Length of the rotation window in hours (e.g. 3h).

Default: null

master_user_password_rotation_schedule_expression · string

cron() or rate() expression for the rotation schedule.

Default: null

Active Directory

domain · string

ID of the Directory Service Active Directory domain.

Default: null

domain_auth_secret_arn · string

ARN of the Secrets Manager secret with Active Directory credentials.

Default: null

domain_dns_ips · list(string)

IPv4 DNS IPs of Active Directory domain controllers.

Default: null

domain_fqdn · string

FQDN of the self-managed Active Directory domain.

Default: null

domain_iam_role_name · string

Name of the IAM role for Directory Service API calls.

Default: null

domain_ou · string

Active Directory organizational unit for the DB instance.

Default: null

Replicas

replicate_source_db · string

Identifier of the source DB instance to replicate.

Default: null

replica_mode · string

Oracle replica mode. Valid values: mounted, open-read-only.

Default: null

Database settings

character_set_name · string

Character set name for Oracle instances. Cannot be changed after creation.

Default: null

nchar_character_set_name · string

National character set for Oracle NCHAR/NVARCHAR2/NCLOB columns. Cannot be changed after creation.

Default: null

timezone · string

DB instance timezone. Only supported by Microsoft SQL Server.

Default: null

license_model · string

License model for the DB instance. Required for some engines.

Default: null

iam_database_authentication_enabled · bool

Enable IAM database authentication.

Default: false

deletion_protection · bool

Prevent the instance from being deleted.

Default: false

ca_cert_identifier · string

Identifier of the CA certificate for the DB instance.

Default: null

Tags & Timeouts

tags · map(string)

Tags to assign to all resources.

Default: {}

db_instance_tags · map(string)

Additional tags for the DB instance only.

Default: {}

timeouts · object

Terraform resource management timeouts for aws_db_instance. Supports create, update, and delete keys with duration strings (e.g. 40m).

Default: null

Outputs

db_instance_address · string

The hostname of the RDS instance.

db_instance_arn · string

The ARN of the RDS instance.

db_instance_availability_zone · string

The Availability Zone of the RDS instance.

db_instance_endpoint · string

The connection endpoint in address:port format.

db_listener_endpoint · object

The listener connection endpoint for SQL Server Always On.

db_instance_engine · string

The database engine.

db_instance_engine_version_actual · string

The running version of the database engine.

db_instance_hosted_zone_id · string

The canonical hosted zone ID of the DB instance.

db_instance_identifier · string

The RDS instance identifier.

db_instance_resource_id · string

The RDS Resource ID of this instance.

db_instance_status · string

The RDS instance status.

db_instance_name · string

The database name.

db_instance_username · string

The master username for the database. Sensitive.

db_instance_port · number

The database port.

db_instance_ca_cert_identifier · string

The CA certificate identifier.

db_instance_domain · string

The ID of the Active Directory domain the instance is joined to.

db_instance_domain_auth_secret_arn · string

The ARN of the Active Directory credentials secret.

db_instance_domain_dns_ips · list(string)

The DNS IP addresses of the Active Directory domain controllers.

db_instance_domain_fqdn · string

The FQDN of the Active Directory domain.

db_instance_domain_iam_role_name · string

The IAM role name used for Directory Service API calls.

db_instance_domain_ou · string

The Active Directory organizational unit the instance joined.

db_instance_master_user_secret_arn · string

The ARN of the Secrets Manager secret for the master user password.

db_instance_upgrade_rollout_order · string

The upgrade rollout order for the instance.

db_instance_cloudwatch_log_groups · map(object)

Map of CloudWatch log groups created for the DB instance.

db_instance_secretsmanager_secret_rotation_enabled · bool

Whether automatic Secrets Manager rotation is enabled.

enhanced_monitoring_iam_role_name · string

The name of the Enhanced Monitoring IAM role.

enhanced_monitoring_iam_role_arn · string

The ARN of the Enhanced Monitoring IAM role.