From Heroku using the Migrator tool

The Crunchy Bridge Heroku Migrator is a tool you can use to move data from a Heroku database into a new Crunchy Bridge cluster. The Crunchy Bridge Heroku Migrator is intended for users with databases under 100GB in size. For larger databases, please reach out to Support for assistance planning and executing your migration.

As with any change to your production systems, we recommend testing this process first with a development or staging database before moving forward with the full production migration.


Only team administrators can complete a migration using the Heroku migrator tool. Team members and managers should contact an admin on the team for help with migrations or permissions changes.

Connect your Heroku account

Select a database

If you start the Crunchy Bridge Heroku Migrator tool and don't see the database you want to migrate, visit in order to refresh the list. When you reload the database selection page of the migrator, your databases should show up as available to migrate.

Select a Crunchy Bridge plan

Memory and storage size

To start your migration, you will need to create a new cluster on the Crunchy Bridge side. We recommend you select a similar tier in terms of memory and storage. Many customers find that they are able to downside their cluster after migration is complete, particularly in terms of memory due to better performance on Crunchy Bridge. You can change your cluster plan at any time.

Postgres version

In addition to moving your data, you can use the migrator tool to upgrade your Postgres version at the same time. Choose the version of Postgres you would like to use for your Crunchy Bridge cluster.

Enable maintenance mode on Heroku

Make sure your Heroku application is in maintenance mode. This will ensure the successful and complete migration of data. Follow the on-screen prompts to:

  • Scale down your application
  • Enter maintenance mode

Run the migrator

Once you've created your Crunchy Bridge cluster and prepared your Heroku application, you're ready to run the actual migration of your data. The migration process includes the following actions being taken on your behalf:

  • Auditing will be disabled for the postgres user
  • The system will run pg_dump from Heroku & pg_restore to Crunchy Bridge. This generally takes about an hour for every 100GB.
  • During the restore process all of your roles and indexes will be rebuilt
  • Table permissions will be updated
  • Auditing will be re-enabled

A progress window will be displayed showing a green dot as each step is completed:

Finalize the migration

Once your data has been migrated into Crunchy Bridge, you can complete the last steps to point your Heroku application to your new cluster. Follow the on-screen steps to:

  • Detach your original database
  • Update your database URL to use your Crunchy Bridge cluster's connection URL
  • Scale your application dynos back up
  • Exit maintenance mode

Connect to your new cluster

You can connect your new cluster to a GUI, or to any other resources and tools you prefer to use. See our connection documentation, or get in touch with Support if you need additional help.

Verify successful migration

Confirm your successful migration of data to Crunchy Bridge by checking that operations have returned to normal for all applications and clients that use this database. Once operations have returned to normal, you should be fully online with your new Crunchy Bridge cluster.

Still need help?

Welcome to Crunchy Bridge, we're happy you're here! 🎉 If you find that you still need help after the end of your migration, don't hesitate to get in touch with Support.

You can also read more about using the Heroku migrator tool here on the blog.