Forking Your Heroku Postgres Database
Last updated January 25, 2021
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.
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
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 ```