How to fork a Heroku database and attach it to a review app

⚠️ TL:DR; Only do this if you have already forked your database:

# Destroy initial database add-on attached to review app
# You can also pass the `--confirm <REVIEW_APP_NAME>` flag to skip the deletion confirmation. 
# WARNING: Do this only if you're VERY sure you're deleting the right database.
heroku addons:destroy DATABASE --app <REVIEW_APP_NAME>

# Attach your forked database to the review app
heroku addons:attach <FORKED_DATABASE_NAME> --app <REVIEW_APP_NAME> --as DATABASE

If not, read the full guide below.

Here’s how to attach a forked database to a review app in Heroku.

1. Check if the database can be forked

You can’t fork a database for a short period of time if it has just been forked recently. But, this shouldn’t be an issue if you’re planning to fork your production database which is the usual case.

You can use either of the commands below to check if your database can be forked.

heroku pg:info -a <YOUR_APP_NAME>

# or

heroku pg:info <NAME_OR_URL_OF_DATABASE_TO_BE_FORKED>

The Fork/Follow status should show Available if the database can be forked.

2. Fork the database

You can use the Heroku CLI to fork the database. In the example below, I’m using the heroku-postgresql addon with a standard-0 plan for my database

heroku addons:create heroku-postgresql:standard-0 --fork <NAME_OR_URL_OF_DATABASE_TO_BE_FORKED> --app <YOUR_APP_NAME>

You can also use the Heroku dashboard:

1) Go to Heroku Data.

2) Select the database you want to fork.

3) Go to Settings

4) Click on Fork Database..

5) Select the pricing plan for your database and click on Fork Database. I recommend using the same plan for your fork for more accurate testing results.

You can read more about Heroku’s Postgres addon here.

3. Wait for the fork to be previsioned

You can check the Heroku dashboard or run:

heroku pg:wait <FORKED_DATABASE_NAME>

to check if the fork is done provisioning.

4. Create your review app

Create a review app from the branch or PR you’re working if you haven’t already: Creating Heroku review apps

5. Destroy the initial DATABASE addon for your review app

Your review app should come with a initial DATABASE addon. Since you want to attach your forked database to the review app, you no longer need this initial database addon.

You can destroy the addon with:

# You should see a confirmation step before the initial database is destroyed.
heroku addons:destroy DATABASE --app <REVIEW_APP_NAME>

Or, you can do it in the review app dashboard:

1) Go to your review app’s dashboard.

2) Click on Resources.

3) Click on the up and down arrow icon next to your database addon (in my case, it’s Heroku Postgres).

4) Click on Delete Add-on.

Again, make sure you’re in the right page and deleting the right database.

6. Attach the forked database to your review app

You can attach the forked database with the CLI via:

heroku addons:attach <FORKED_DATABASE_NAME> --app <REVIEW_APP_NAME> --as DATABASE

The command above attaches the forked database to your review app, while setting the DATABASE environment variable to point to your forked database.

And you’re done!