Last updated October 27, 2025

Heroku recommends testing major Postgres version upgrades for your Heroku Postgres add-ons before completing the upgrade in your production database.

Testing version upgrades helps identify and resolve any possible upgrade errors or incompatibility issues that could impact your database or application. Testing also helps reduce the downtime for your application when you’re upgrading the production database so you can address any issues in advance.

The most common upgrade issues are related to type incompatibilities between Postgres versions, object reference or dependency errors, or general application problems when an app or its PostgreSQL driver version doesn’t support the target Postgres version.

There are two methods for testing a version upgrade:

• Dry Run Method (only available for Standard-tier and higher leader databases): Tests the database’s schema and data compatibility with the Postgres version. Useful to get an estimate of how long the upgrade takes to complete.
• Fork or Copy Method: Tests your app’s compatibility and performance with the new Postgres version. Useful for end-to-end testing.

Dry Run Method

We recommend using the Direct upgrade method for all Heroku Postgres version upgrades, but you can only test an upgrade with pg:upgrade:dryrun on Standard-tier and higher leader databases. For Essential-tier databases, test with pg:copy.

The pg:upgrade:dryrun command lets you test the Postgres version upgrade to ensure that your database schema is compatible with the target version. It also gives you an estimate for the time required to upgrade a particular database.

The pg:upgrade:dryrun command simulates a version upgrade by creating and upgrading a temporary follower database with PostgreSQL’s pg_upgrade utility. The temporary follower is only for the version upgrade and isn’t the same as a normal follower you create. You can’t access the temporary follower during the dry run, and it doesn’t incur extra costs. Heroku sends the results of the test upgrade and how long the upgrade took via email. We immediately deprovision the follower after the test upgrade finishes. The process of creating the temporary follower can take hours while the actual dry run can take around 10 minutes.

$ heroku pg:upgrade:dryrun HEROKU_POSTGRESQL_RED --app example-app
› Warning: This command starts a test upgrade for postgresql-lively-15649 to the latest supported Postgres version.

To proceed, type example-app or re-run this command with --confirm example-app: example-app
Starting a test upgrade on postgresql-lively-15649... done
Started test upgrade. We'll notify you via email when it's complete.

After testing, you can start the version upgrade on the leader database with pg:upgrade:prepare.

Fork Method

Using the forked database method lets you test the upgraded database on your app to ensure compatibility and performance. This method is recommended for testing the Direct and Follower Failover upgrade methods. This method is available for Standard-tier and higher plans that support the fork feature.

First, fork your existing production database on a staging or non-production app to run and validate the complete upgrade process:

$ heroku addons:create heroku-postgresql:<database_plan> --as TEST_UPGRADE_DATABASE -a staging_app_name -- --fork production_app_name::DATABASE_URL

When the forked database is ready, start the Direct upgrade on your fork.

To complete the database version upgrade test, promote the upgraded database as the primary database for your non-production application. Verify that your application can connect and communicate with the database as expected.

$ heroku pg:promote TEST_UPGRADE_DATABASE --app staging_app_name

This approach lets you test the complete upgrade process and estimate how long your upgrade takes when you upgrade in production. This process is also helpful to confirm that your application is compatible with the new PG version, which is the case unless your application uses an old PostgreSQL client or driver.

When you’re finished testing the upgrade, you can delete the forked database and the upgraded follower.

Alternative Testing Approach

To speed up the version upgrade testing process, another approach is to create a follower of your production application in a non-production environment. You can run pg:upgrade:run on the follower directly. This command unfollows the leader and performs the Postgres upgrade to the target version.

Promote the upgraded database as the primary database in your non-production environment to verify that your application is compatible with the new version.

Copy Method

Use the pg:copy method to upgrade the Postgres versions of databases under 10 GB. You can use pg:copy to test the version upgrade on all Heroku Postgres plans. The copy method is recommended for Essential-tier databases, which don’t support the fork feature.

Using the copy method lets you test the upgraded database on your app to ensure compatibility and performance. This method is recommended for testing version upgrades on Essential-tier databases that use the Direct upgrade or the Data Copy upgrade methods.

To test the upgrade process, provision a new database on a non-production application, specifying the target Postgres version:

$ heroku addons:create heroku-postgresql:<database_plan> --as DATABASE_UPGRADE_TEST --app staging_app_name -- --version=16

When the new database is available, copy the data from your production database to the new database:

$ heroku pg:copy production_app_name::DATABASE_URL DATABASE_UPGRADE_TEST --app staging_app_name

After the data copy finishes, promote the database to your non-production application to verify that your application is compatible with the new version:

$ heroku pg:promote DATABASE_UPGRADE_TEST --app staging_app_name