Migrating Heroku Postgres Databases to Private Spaces
Last updated August 16, 2024
Table of Contents
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.
This migration can only be done via the Heroku CLI.
This article makes the assumption that your Heroku Space has already been provisioned and the app is running inside the 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:
The addons:create example follows the syntax for Heroku CLI v9.0.0 or later. If you’re on v8.11.5 or earlier, use the command:
$ 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.
Your application is unavailable starting at this point in the upgrade process.
$ 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.
If your Heroku Postgres database isn’t connected to a Heroku application you must retrieve the HEROKU_POSTGRESQL_PURPLE_URL and update your application to use it as your primary database.
Be sure to remove the _URL suffix from the database name in this command.
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.