Last updated August 16, 2024

Heroku Private Spaces are isolated runtime environments with their own dedicated network to which Heroku apps can be deployed using the Heroku developer experience. Heroku Postgres can run within the boundaries of a Private Space.

The migration instructions in this document apply to moving a database from the current Heroku Common Runtime environment into a Private Space.

Migrate with Follower Changeovers

The follower changeover method lets you migrate a production database while the original database is still operating. It’s only available with Standard, Premium, or Enterprise tier databases (or legacy production databases).

Migrating databases with a follower changeover entails provisioning a follower for a database in the new Private Space. This process allows the follower to catch up to the old database, and then promote it to be the primary database for the target application.

The advantage of a follower upgrade is that it requires little downtime, usually less than a minute. Before the changeover, it can take several hours to prepare a new follower (during which your application is still active), so plan accordingly.

1. Create Follower

To begin, create a new follower for your common runtime database.

First, use heroku pg:info to find the resource name of the database that you want to follow:

$ heroku pg:info --app common-runtime-example
=== DATABASE_URL, HEROKU_POSTGRESQL_GREEN_URL
Plan:        Standard 0
Status:      available
Add-on:      looking-simply-2449
...

When the resource name has been found, type the following command to have a follower attached to it using the main database from common-runtime-example:

$ heroku addons:create heroku-postgresql:private-4 --follow looking-simply-2449 -a private-spaces-example

$ heroku addons:create heroku-postgresql:private-4 -a private-spaces-example -- --follow looking-simply-2449
Adding heroku-postgresql:private-4 to private-spaces-example... done, v71 ($1500/mo)
Attached as HEROKU_POSTGRESQL_PURPLE
Follower will become available for read-only queries when up-to-date
Use `heroku pg:wait` to track status

Then wait for the follower to catch up to the leader database.

$ heroku pg:wait --app private-spaces-example
Waiting for database HEROKU_POSTGRESQL_PURPLE_URL... available

After a follower is caught up, it’s generally within 200 commits of the database. Monitor how many commits a follower is behind by using the pg:info command (looking at the Behind By row of the follower database):

$ heroku pg:info --app private-spaces-example
=== HEROKU_POSTGRESQL_PURPLE
Plan:        Private 4
Status:      available
...
Behind By:   125 commits

2. Prevent New Database Updates

It’s important that no new data is written to your application on the source system during the migration process or it doesn’t get transferred to the new database. To prevent new updates, place your source app into maintenance mode. If you have scheduler jobs running as well, disable them.

$ heroku maintenance:on  --app private-spaces-example
Enabling maintenance mode for private-spaces-example... done

Maintenance mode doesn’t automatically scale down any dynos. Scale down web and any non-web dynos to make sure that no connections are writing data to the database.

$ heroku ps:scale worker=0 --app private-spaces-example
Scaling worker processes... done, now running 0

3. Promote Follower

In maintenance mode no new data is written to the leader database, assuming that the dynos have been scaled down and any open connections aren’t writing data. Wait for the follower database to catch up to the leader (as indicated by being behind by 0 commits).

$ heroku pg:info --app private-spaces-example
=== HEROKU_POSTGRESQL_PURPLE_URL
Plan:        Private 4
Status:      available
...
Behind By:   0 commits

When the follower is caught up and no new data is being generated, issue an unfollow command to relinquish its follower duties and make it a full, writeable database. Promoting it then sets it as the primary database (at the DATABASE_URL location) used by your target application:

$ heroku pg:unfollow HEROKU_POSTGRESQL_PURPLE_URL
$ heroku pg:promote HEROKU_POSTGRESQL_PURPLE
Promoting HEROKU_POSTGRESQL_PURPLE_URL to DATABASE_URL... done

The follower database is now the primary database (though the application isn’t yet receiving new requests).

4. Make Target Application Active

To resume normal application operation, scale any non-web dynos back to their original levels. (If the application wasn’t previously using non-web dynos, skip this step in order to avoid scaling any dynos that you don’t need).

$ heroku ps:scale worker=1

Finally, turn off maintenance mode.

$ heroku maintenance:off

Your application is now receiving requests to your migrated database instance. This can be confirmed by running heroku pg:info. The database denoted by DATABASE_URL is considered the primary database.

Steps to Take After the Migration

After upgrading your database, deprovision the old database so that you aren’t paying for an unused database.

$ heroku addons:destroy HEROKU_POSTGRESQL_GREEN_URL --app common-runtime-example

Dataclips that were associated with the old database must be reassigned to the new database. To recover these dataclips, open a support ticket via help.heroku.com.