Forking Your Heroku Postgres Database
Last updated 12 September 2017
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.
Forks do not have to be the same database plan as their master. Production tier database plans can be forked to all other production tier plans. If your database is on an older 32-bit machine then the follower can only be followed by the same plan. You can identify this by running heroku pg:info on your 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 ```