Migrate Heroku Postgres to AWS RDS (with & without downtime)

This guide provides you with essential knowledge to transfer your database from Heroku Postgres to RDS, with minimal or no downtime.

Migrating Without Downtime

The process of migrating data without any downtime is difficult. This section explains how to do it, but most people opt to migrate with a small amount of downtime at a time when your app has minimal traffic. Migration with downtime is explained further below.

To migrate without downtime you need to modify your application to write to both the old and new databases to ensure they stay in sync during the migration.

1. Create a new Postgres RDS via Flightcontrol

2. Copy the Heroku Database data to AWS Database (see instructions below)

3. Modify your application to write to both Heroku Database and AWS Database (continue reading from Heroku Database)

4. Test and validate the AWS Database Database correct and up to date

5. Switch your app to read from the AWS Database

6. Stop writing to Heroku Database

7. Migration is complete

Migrating With Minimal Downtime

Here are the detailed steps you will take to migrate your PostgreSQL database from Heroku to Amazon RDS:

Process

Step 1: Create a New RDS via Flightcontrol

1. Create a new project on Flightcontrol
2. Under Services click + Add Database
3. The default settings for the database are fine. Make sure you have Postgres selected.
4. Choose a database tier.
5. Click Create Project and complete any required steps (like linking your AWS account).

After configuring a database with Flightcontrol, the default behavior is that the DATABASE_URL environment variable contains the connection string for the RDS database.

Step 2: Enable Maintenance Mode Wherever Your App is Running (on Heroku or Flightcontrol)

Follow this guide to enable Maintenance Mode.

Step 3: Create a Dump of Your Heroku Database

A database dump is a complete export of a database, including users, table structures, relationships, and data. For PostgreSQL, the commonly used method is to utilize the pg_dump command-line tool. However, with Heroku, you will want to use their wrapper around the pg_dump command. You can find full instructions in their documentation(https://devcenter.heroku.com/articles/heroku-postgres-import-export).

The resulting backup file will be in a binary format with a UUID string, for example, 4637916d-533c-4a15-82a1-a36ce8a31e3f. Rename it so it has a .dump extension.

Step 4: Run the pg_restore Command

From your shell again, run the pg_restore command like this.

pg_restore -d {rds-connection-string} -U --jobs={number-of-jobs} \
            --verbose --clean --no-acl --no-owner {dump-file-path}

Placeholder Definitions

Step 5: Make Sure the Database has all the Data you Expect

Before proceeding, ensure that your migrated database is in good working condition:

• Verify that auto-increment on any columns in your tables is functioning correctly.
• Run your data validation scripts.
• Double-check indexes and foreign keys for accuracy.

After thoroughly testing, you can proceed with the production migration.

Step 6: Switch your App to Connect to New Database

After successfully migrating the database and verifying its readiness, it’s time to configure your production applications to use the new Amazon RDS database:

• Configure your applications with your new connection settings to connect to the Amazon RDS instance.
• Deploy the new application configuration and restore your application from maintenance mode to make it live with the new database configuration.

Do a Dry Run Before Production Migration

Before doing the production migration, go through the process with a test DB and application. You’ll get familiar with the process and uncover any snags without affecting production traffic.

1. Create a dump of your production Heroku database
2. Create a new RDS Postgres
3. Use pg_restore to upload the dump to RDS
   • Record how long this process takes. This is how long of downtime you’ll need for the production migration.
4. Connect a test app to this new RDS and ensure everything is correct and functioning
5. If all is well, you’re ready for the production migration.

Plan Migration Downtime

Choose a time that will have minimal traffic, and if possible inform your users ahead of time.

Afterwards

After you have switched your production database, follow the steps below:

• Monitor for any unexpected errors
• Ensure database instance size is sufficient for the traffic
• We recommend keeping the old database for about a week just in case. Then it can be deleted.

White Glove Migration Assistance

For users on our Team plan, we offer white glove migration support to help you at every step of the way and ensure that migration is a success for you and your users.

Additional Resources

• Migrate from Heroku to AWS
• Troubleshooting
• Setting Environment Variables on Flightcontrol