Forking Your Heroku Postgres Database
Last updated January 25, 2021
Table of Contents
Forking creates a new database containing a snapshot of an existing database at the current point in time. Forked databases differ from follower databases in that they do not stay up-to-date with the original database and are themselves writable.
Forking is only supported on production tier database plans. Follow these steps to upgrade from a starter tier (dev or basic) plan to a production plan.
Use cases
Forked databases provide a risk-free way of working with your production data and schema. For example, they can be used to test new schema migrations or to load test your application on a different database plan. They are also valuable as snapshots of your data at a point-in-time for later analysis or forensics.
Create a fork
Creating forks is subject to the same limitations as creating followers.
Forking a database uses the same mechanism as creating a follower. Namely that provisioning occurs on creation of a new database add-on with the --fork flag. The flag can take either the config var name of the database on the same app, an argument of the form appname::HEROKU_POSTGRESQL_COLOR_URL, or the full URL of any Heroku Postgres database.
After forking a database, a new HEROKU_POSTGRESQL_COLOR_URL config var is created on the app the fork is attached to. This update will restart the app.
$ heroku addons:create heroku-postgresql:standard-0 --fork HEROKU_POSTGRESQL_CHARCOAL_URL --app sushi
Adding heroku-postgresql:standard-0 on sushi... done, v71 ($50/mo)
Attached as HEROKU_POSTGRESQL_SILVER_URL
Database will become available after it completes forking
Use `heroku pg:wait` to track status
Preparing a fork can take anywhere from several minutes to several hours, depending on the size of your dataset. The heroku pg:wait command outputs the provisioning status of any new databases and can be used to determine when the fork is up-to-date.
$ heroku pg:wait --app sushi
Waiting for database HEROKU_POSTGRESQL_SILVER_URL... available
De-provision a fork using heroku addons:destroy:
Be sure to remove the _URL suffix from the database name in this command.
$ heroku addons:destroy HEROKU_POSTGRESQL_SILVER --app sushi
! WARNING: Destructive Action
! This command will affect the app: sushi
! To proceed, type "sushi" or re-run this command with --confirm sushi
Fork Fast option
Forks can be created faster using the --fast flag, however they will be up to 30 hours out-of-date. This option is useful if there have been no major changes (such as schema migrations or large data imports) to your database in the last 30 hours.
$ heroku addons:create heroku-postgresql:standard-4 --fork HEROKU_POSTGRESQL_CHARCOAL --fast --app sushi
Adding heroku-postgresql:standard-4 on dashboard... done, v1022 ($1200/mo)
Attached as HEROKU_POSTGRESQL_BLUE_URL
Fork will contain data from 5/26/2014 at 13:56 UTC (about 16 hours old)
To create a fork with up-to-date data, exclude the `--fast` flag.
Database will become available after it completes forking
Use `heroku pg:wait` to track status.
Use `heroku addons:docs heroku-postgresql` to view documentation ```