Browse the Repo

file-type-icon.circleci
file-type-icon_docs
file-type-iconexamples
file-type-iconmodules
file-type-iconaurora
file-type-iconlambda-cleanup-snapshots
file-type-iconlambda-copy-shared-snapshot
file-type-iconlambda-create-snapshot
file-type-iconlambda-share-snapshot
file-type-iconrds
file-type-iconREADME-MariaDb.adoc
file-type-iconREADME-MySQL.adoc
file-type-iconREADME-Oracle.adoc
file-type-iconREADME-PostgreSQL.adoc
file-type-iconREADME-SqlServer.adoc
file-type-iconREADME.adoc
file-type-iconcore-concepts.md
file-type-iconmain.tf
file-type-iconoutputs.tf
file-type-iconvars.tf
file-type-icontest
file-type-icon.gitignore
file-type-icon.pre-commit-config.yaml
file-type-iconCODEOWNERS
file-type-iconLICENSE.txt
file-type-iconREADME.adoc

Browse the Repo

file-type-icon.circleci
file-type-icon_docs
file-type-iconexamples
file-type-iconmodules
file-type-iconaurora
file-type-iconlambda-cleanup-snapshots
file-type-iconlambda-copy-shared-snapshot
file-type-iconlambda-create-snapshot
file-type-iconlambda-share-snapshot
file-type-iconrds
file-type-iconREADME-MariaDb.adoc
file-type-iconREADME-MySQL.adoc
file-type-iconREADME-Oracle.adoc
file-type-iconREADME-PostgreSQL.adoc
file-type-iconREADME-SqlServer.adoc
file-type-iconREADME.adoc
file-type-iconcore-concepts.md
file-type-iconmain.tf
file-type-iconoutputs.tf
file-type-iconvars.tf
file-type-icontest
file-type-icon.gitignore
file-type-icon.pre-commit-config.yaml
file-type-iconCODEOWNERS
file-type-iconLICENSE.txt
file-type-iconREADME.adoc
RDS

RDS

Terraform code and scripts for deploying data-storage resources (e.g. databases, cache) in AWS

Code Preview

Preview the Code

mobile file icon

core-concepts.md

down

Core RDS Concepts

What is Amazon RDS?

Before Amazon Relational Database Service (RDS) existed, teams would painstakingly configure PostgreSQL, MySQL, or other popular databases on their own. Setting up automatic failover, read replicas, backups, encryption, and handling upgrades are all non-trivial and AWS recognized they could implement these features according to best practices themselves, sparing customers the time and cost of doing it themselves.

Behind the scenes, RDS runs on EC2 Instances located in subnets and protected by security groups you specify.

Backups are handled by a snapshot taken on a nightly basis, but you can initiate a manual snapshot whenever you want. If you select the Multi-AZ option, RDS will synchronously copy every write to a standby and, in the event of a failure in the master server, automatically fail over to the standby server.

In addition, if you wish to reduce the load on your primary database, one option is to add Read Replicas and direct all read queries to them. RDS streamlines the process of adding and maintaining Read Replicas.

Common Gotcha's

  • All RDS upgrades (version upgrades, instance type upgrades, etc.) require a few minutes of scheduled downtime.
  • If an RDS instance that uses Multi-AZ fails, Amazon will automatically kick off a fail-over, but you will still experience about 3 - 5 minutes of downtime.
  • Based on the above, make sure you've written your app to gracefully handle database downtime.
  • An RDS instance that runs out of disk space will stop working, so be sure to monitor and set an alert on the FreeStorageSpace CloudWatch Metric. Consider monitoring other RDS CloudWatch Metrics as well.

How do you connect to the database?

This module provides the connection details as Terraform output variables:

  1. Primary endpoint: The endpoint for the primary DB. You should always use this URL for writes, as it points to the primary.
  2. Read replica endpoints: A comma-separated list of read replica URLs.
  3. Port: The port to use to connect to the endpoints above.

You can programmatically extract these variables in your Terraform templates and pass them to other resources (e.g. pass them to User Data in your EC2 instances). You'll also see the variables at the end of each terraform apply call or if you run terraform output.

Note that the database is likely behind a Bastion Host, so you may need to first connect to the Bastion Host (or use SSH Tunneling) before you can connect to the database.

How do you scale this database?

  • Storage: Use the allocated_storage variable.
  • Vertical scaling: To scale vertically (i.e. bigger DB instances with more CPU and RAM), use the instance_type, storage_type, and iops input variables. For a list of AWS RDS server types, see DB Instance Class
  • Horizontal scaling: To scale horizontally, you can add more replicas using the num_read_replicas input variable, and RDS will automatically deploy the new instances, begin asynchronous replication, and make them available as read replicas. FOr more info, see Working with PostgreSQL, MySQL, and MariaDB Read Replicas.

How do you configure this module?

This module allows you to configure a number of parameters, such as backup windows, maintenance window, port number, and encryption. For a list of all available variables and their descriptions, see vars.tf.

Questions? Ask away.

We're here to talk about our services, answer any questions, give advice, or just to chat.

Ready to hand off the Gruntwork?