Amazon RDS is a service that allows you to set up, operate and scale a dedicated MySQL database server on top of EC2. In addition to standard MySQL features, RDS offers the following functionality:

• Automated backups.
• Point-in-time recovery.
• Seamless vertical scaling between instance types.

The free Amazon RDS add-on lets you connect your Heroku app to an RDS instance and seamlessly use it in place of the standard, Heroku-provided PostgreSQL database.

Prerequisites

Heroku does not operate RDS instances for you. Instead, we allow you connect to any running RDS instance that you control. To use the add-on, all you need is access to a database on an RDS instance.

Transferring Data

If you are migrating from Heroku’s built in PostgreSQL database to RDS, you may want to transfer database schema and data before switching over to RDS. To do this, you’ll need to allow access to the RDS instance from your workstation. Here’s how you authorize access, assuming your workstation’s public IP is 1.1.1.1:

rds-authorize-db-security-group-ingress default --cidr-ip 1.1.1.1/32

Now you can use taps to pull from your Heroku database to your RDS database:

heroku db:pull mysql://user:pass@rdshostname.amazonaws.com/databasename

Configuring the Add-on

Be sure you have the Amazon RDS Command Line Toolkit, which can be found here.

Heroku needs to be able to access your RDS instance. To allow Heroku’s cloud through your RDS firewall, run the following command:

rds-authorize-db-security-group-ingress --db-security-group-name default \ 
    --ec2-security-group-name default \
    --ec2-security-group-owner-id 098166147350 \
    --aws-credential-file ../credential-file-path.template

Once authorized, you can add the add-on using the connection information for your database:

$ heroku addons:add amazon_rds url=mysql2://user:pass@rdshostname.amazonaws.com/databasename
Adding amazon_rds to appname...Done.

That’s it! Your Heroku app should now be using your Amazon RDS database. If you check your config variables, you will see the DATABASE_URL changed:

$ heroku config
DATABASE_URL => mysql2://user:...zonaws.com/database

If you later remove the add-on, you can restore your original DATABASE_URL by copying it from the SHARED_DATABASE_URL config var.

Changing Your Credentials

If you wish to change your RDS credentials, you can do so from the console. Log in with your current account credentials with:

$ mysql -h myinstance.mydnsnameexample.rds.amazonaws.com -P 3306 -u mymasteruser -p

Once you’ve logged in, you can update your master account credentials as described in the MySQL documentation.

Migrating to a New Instance

In some cases, you may want to change the RDS instance your Heroku app points to. The easiest way to do that is to:

1. Log in to the AWS console and click on the RDS tab.
2. Select the instance you want to change.
3. Click the Take Snapshot button.
4. Once the snapshot is finished, select it and click the Restore From DB Snapshot button.
5. Fill out the fields to create your new instance.
6. After the new instance has been created, update your Heroku application config variables to use the new URL.
7. Test your application to make sure that everything works properly; assuming it does, you can now safely return to the AWS console and delete your original DB instance.