Testing Migrations from Classic Heroku Postgres to Heroku Postgres Advanced

Last updated November 12, 2026

Heroku recommends testing migrations to Heroku Postgres Advanced for your Heroku Postgres classic add-ons before migrating your production database. Test your migration to identify and resolve compatibility issues between your database and the migration process and benchmark query performance on the Advanced plan. Testing a migration involves forking your classic production database to a non-production app and running the full migration process against that fork.

Step 1: Fork Your Database

First, create a fork of the database you want to test migrating to Advanced. We recommend creating this fork on a non-production app.

The Heroku Postgres Advanced migration process requires some downtime on the database you’re migrating. Forking your database allows you to run your migration testing in isolation from your production database that serves your apps.

To create a fork of your existing classic database, use the heroku addons:create command with the --fork option. In the command, include:

  • The add-on name of the classic database to fork.
  • The target app that owns the fork database. Ideally, this app is a non-production app that you create in advance.
$ heroku addons:create heroku-postgresql:standard-0 -a nonprod-testing-app – –fork postgresql-clean-12345

 ›   Warning: Release command executing: config vars set by this add-on will
 ›   not be available until the command succeeds. Use `heroku releases:output`
 ›   to view the log.
Creating heroku-postgresql:standard-0 on ⬢ nonprod-testing-app... ~$0.069/hour (max $50/month)
Database will become available after it completes forking.
Use `heroku pg:wait` to track status.
postgresql-tetrahedral-79309 is being created in the background. The app will restart when complete...
Run heroku addons:info postgresql-tetrahedral-79309 to check creation progress.
Run heroku addons:docs heroku-postgresql to view documentation.

You can use the --fast option to fork your database faster if you don’t require testing with the latest data changes in your database. Fast forks can be up to 30 hours out-of-date.

Step 2: Prepare Your Test Migration

When the forked database is available, follow the migration steps to prepare your test migration.

$ heroku data:pg:migrate -a nonprod-testing-app

Follow the interactive prompts to configure the testing migration:

  1. Select the forked database as the source database for the migration.
  2. Select Create a new Advanced database as the destination database and configure it.
  3. Select the migration method.
  4. Confirm the migration.

After you confirm the migration, Heroku starts preparing it. It can take around 30 minutes to prepare a migration.

Heroku runs a compatibility assessment as part of the migration preparation. This assessment identifies compatibility issues between your database schema and the migration process.

You receive an email when the migration preparation completes. The email reports any compatibility errors or warnings for your database, if applicable. If there are any issues during the preparation step that prevent the migration from running, fix the errors and configure a new migration.

Make sure that you test the same migration method that you plan to run for your production database to guarantee compatibility and test the process end-to-end.

Create the destination Advanced database on the lowest plan level available and remove the default high availability feature to minimize the cost of your testing database. You can scale your Advanced database level and enable high availability later.

Step 3: Run Your Test Migration

When the migration preparation is complete, you get an email that your database is ready to migrate. Follow the migration steps to run your migration.

This testing guide skips the steps to put your app in maintenance mode.

Step 4: Deprovision Your Database Fork

When the migration completes, you can deprovision the fork we created in step 1 to prevent it from incurring further costs. The forked database isn’t necessary after the migration completes.

To destroy your classic database fork, use the heroku addons:destroy command:

$ heroku addons:destroy postgresql-tetrahedral-79309 -a nonprod-testing-app

›   Warning: Destructive Action
 ›   This command will affect the app ⬢ nonprod-testing-app

✔ To proceed, type nonprod-testing-app or re-run this command with --confirm nonprod-testing-app: nonprod-testing-app
Destroying postgresql-tetrahedral-79309 on ⬢ nonprod-testing-app... done

Step 5: Validate Your Test Migration

Connect your non-production app to the migrated Advanced database and test for compatibility and performance.