Migrate Postgres DB

This guide walks you through migrating a Postgres database from Heroku to Argonaut. This can be done in 3 easy steps.

1. Setting up your Argonaut environment
2. Preparing your Heroku DB
3. Moving data to Argonaut

Set up your environment on Argonaut

In Argonaut, you have two options for creating an environment - either AWS or GCP. This provides users the flexibility of choosing from their choice of hyperscaler while maintaining a unified experience with minimal setup and maintenance effort required.

To set up your Environment

1. Create an Argonaut account and sign in from https://ship.argonaut.dev/
2. Connect the cloud provider (AWS/GCP)
3. Connect with the Git source (GitHub/GitLab)
4. Click on Create a New environment
5. Select the region of your choice and give your environment a name

This sets up a VPC along with the basic necessary configs for your apps to run on the cloud using Kubernetes or serverless runtimes.

Prepare your Heroku PostgreSQL database for migration

The migration might require some downtime; plan your migration accordingly to have minimal downtime. Once the migration is finalized, communicate the maintenance period with your users and team.

The migration might also be a good time to alter the schema or upgrade to a newer version of the database engine. Ensure the application code can support the changes, whether it is to the schema or a change in the version of PostgreSQL.

To ensure no new data is written to the database during the copy, put your Heroku app into maintenance.

<your-app-name> is your Heroku app that owns the Heroku Postgres add-on.

This data migration process requires some downtime.

heroku maintenance:on --app <your-app-name>

Create a backup of the data in your Heroku Postgres database.

heroku pg:backups:capture --app <your-app-name>

Download the backup. This will download a file named latest.dump to your local computer.

heroku pg:backups:download --app <your-app-name>

💡 If your database is larger than 20GB or under heavy load, use Heroku’s instructions to create a backup of your data. After that has been completed, you can use the same pg_restore command above to import the data to your Argonaut PostgreSQL database.

Consider using the --jobs flag available to both the pg_dump and  pg_restore commands to reduce the time required for backup and restore.

Move your data to Argonaut

If you have an AWS environment

To migrate your Heroku PostgreSQL database to Argonaut, create a new RDS instance in Argonaut. The RDS instance can be configured with various instance types and other options like storage size, engine version, etc.

1. Select Environments from the sidebar

2. Choose your newly created AWS Environment

3. Click on the Infra tab

4. Click on Resource + and choose RDS

5. This will create a new instance of RDS

6. You enter the DB name, visibility, instance type, storage, engine, username, and password

7. You can see live cost estimates for the DB for the chosen instance type

   

8. The creation takes a couple of minutes, and once this is ready, you will see the status as Complete ✅ on your Infra tab.

9. To finish the setup, have PostgreSQL installed locally and run the following command to import data from your Heroku backup into the RDS PostgreSQL database provisioned by Argonaut:

   pg_restore --verbose --no-acl --no-owner -d <EXTERNAL CONNECTION STRING> latest.dump

This command imports latest.dump into your PostgreSQL database provisioned by Argonaut.

The connection string is used for connecting to the DB provisioned by Argonaut. The value for <EXTERNAL CONNECTION STRING> is to be provided in the format:

postgres://{user}:{password}@{hostname}:{port}/{database-name}

Values from Argonaut:

You can get the user, port, and hostname from the Outputs tab. The password will be the one you set up while creating the DB. The database name can be found in the configuration tab of your RDS resource.

Additionally, the sslmode=require parameter is included to enforce SSL connections, which is recommended for secure connections.

Sample external connection string:

Replace with values of your DB instance created using Argonaut.

postgresql://username:password@rds-instance-name.abcdefghijk.us-east-1.rds.amazonaws.com:5432/my_database?sslmode=require

---

If you have a GCP environment

To migrate to your Heroku PostgreSQL database to Argonaut, create a new PostgreSQL instance in Argonaut. The PostgreSQL instance can be configured with various instance types and other options like disk capacity, database version, etc.

1. Select Environments from the sidebar
2. Choose your newly created GCP Environment
3. Click on the Infra tab
4. Click on Resource + and choose PostgreSQL
5. You enter the DB name, visibility, instance type, database version, disk type, username password, and capacity
6. See the live cost estimate for your DB on Argonaut and then click Create PostgreSQL
7. The creation takes a couple of minutes, and once this is ready, you will see the status as Complete ✅ on your Infra tab.
8. You can then run the following command to import data from your Heroku backup into the PostgreSQL database provisioned by Argonaut: pg_restore --verbose --no-acl --no-owner -d <EXTERNAL CONNECTION STRING> latest.dump

This command imports latest.dump into your PostgreSQL database provisioned by Argonaut.

The connection string is used for connecting to the DB provisioned by Argonaut. The value for <EXTERNAL CONNECTION STRING> is to be provided in the format:

postgres://{user}:{password}@{hostname}:{port}/{database-name}

Values from Argonaut:

You can get the user, port, and hostname from the Outputs tab. The password will be the one you set up while creating the DB. The database name can be found in the configuration tab of your PostgreSQL resource.

Additionally, the sslmode=require parameter is included to enforce SSL connections, which is recommended for secure connections.

Sample external connection string:

Replace with values of your DB instance created using Argonaut.

postgresql://username:password@34.61.139.145:5432/my_database?sslmode=require

---