Last updated March 11, 2025

Before Provisioning

Before you provision Heroku Postgres, confirm that it isn’t already provisioned for your app. Heroku automatically provisions Postgres for apps that include certain libraries if you created your account before May 15, 2023 or if you asked Heroku Support to enable auto-provisioning for your account.

Use the heroku addons command to determine whether your app has already provisioned Heroku Postgres:

$ heroku addons
Add-on                                               Plan         Price     State
───────────────────────────────────────────────────  ───────────  ────────  ───────
heroku-postgresql (postgresql-concave-52656)         essential-0  $5/month  created

Provision the Add-on

If heroku-postgresql isn’t in your app’s list of add-ons, you can provision it with the CLI command:

$ heroku addons:create heroku-postgresql:<PLAN_NAME>

For example, to provision an Essential-0 plan database:

$ heroku addons:create heroku-postgresql:essential-0
Creating heroku-postgresql:essential-0 on ⬢ example-app... ~$0.007/hour (max $5/month)
Database should be available soon
postgresql-concave-52656 is being created in the background. The app will restart when complete...
Use heroku addons:info postgresql-concave-52656 to check creation progress
Use heroku addons:docs heroku-postgresql to view documentation

Specify the Version

You can specify the version of Postgres you want to provision by including the --version flag in your provisioning command:

$ heroku addons:create heroku-postgresql:<PLAN_NAME> --version=15

$ heroku addons:create heroku-postgresql:<PLAN_NAME> -- --version=15

Learn more about PostgreSQL version support.

Depending on the plan you choose, your database can take up to 5 minutes to become available. You can track its status with the heroku pg:wait command, which blocks until your database is ready to use.

Blocking Logs

At add-on creation time, you can pass a flag to prevent logging of queries that get run against the database. If you turn this option on, you can’t turn it off after provisioning the database. To turn it off after you turned it on, you must migrate to a new database.

$ heroku addons:create heroku-postgresql:standard-0 -a example-app --block-logs

$ heroku addons:create heroku-postgresql:standard-0 -a example-app -- --block-logs

Application Config Vars

As part of the provisioning process, a DATABASE_URL config var is added to your app’s configuration. DATABASE_URL contains the URL your app uses to access the database. If your app already has a Heroku Postgres database and you provision another one, this config var’s name instead has the format HEROKU_POSTGRESQL_<COLOR>_URL (for example, HEROKU_POSTGRESQL_YELLOW_URL).

You can confirm the names and values of your app’s config vars with the heroku config command.

At this point, an empty PostgreSQL database is provisioned. To populate it with data from an existing data source, see the import instructions or follow the language-specific instructions to connect from your application.

Designating a Primary Database

The DATABASE_URL config var designates the URL of an app’s primary Heroku Postgres database. For apps with a single database, its URL is automatically assigned to this config var.

For apps with multiple Postgres databases, set the primary database with heroku pg:promote. Common use cases include leader-follower high-availability setups or as part of the database upgrade process.

Sharing Heroku Postgres Between Applications

You can share a single Heroku Postgres database between multiple apps with the heroku addons:attach command. You can also specify an alias for your add-on using the --as flag.:

$ heroku addons:attach my-originating-app::DATABASE --app example-app --as ATTACHED_DB
Attaching postgresql-addon-name to example-app... done
Setting ATTACHED_DB vars and restarting example-app... done, v11

By default, the attached database’s URL is assigned to a config var with the name format HEROKU_POSTGRESQL_<COLOR>_URL. In the example, since an alias was set, the config var’s name is ATTACHED_DB.

A shared database isn’t necessarily the primary database for any given app that it’s shared with. To promote a shared database, use the same command that you use for any other database.

To stop sharing your Heroku Postgres instance with another app, use the heroku addons:detach command:

$ heroku addons:detach ATTACHED_DB --app example-app
Detaching ATTACHED_DB to postgresql-addon-name from example-app... done
Unsetting ATTACHED_DB config vars and restarting example-app... done, v11

Removing the Add-on

You can delete the add-on using the Heroku dashboard or using the CLI.

Delete Using the Dashboard

To delete a Postgres database from the Heroku Dashboard:

1. From the Heroku Dashboard, navigate to your application and then select the Resources tab.
2. Select the Heroku Postgres add-on you want to delete, choose the dropdown on the right, and select Delete Add-on.
3. On the Remove Add-on page, enter the app’s name to confirm, and select Remove add-on.

Delete Using the CLI

To remove your Heroku Postgres database, use the following command:

$ heroku addons:destroy heroku-postgresql

If you have two databases of the same type you must remove the add-on using its config var name. For example, to remove the HEROKU_POSTGRESQL_GRAY_URL database, run the command:

$ heroku addons:destroy HEROKU_POSTGRESQL_GRAY

If the removed database was the same one used in DATABASE_URL, that DATABASE_URL config var is unset on the app.

Next Steps

For information on how to connect to your Postgres database, see Connecting to Heroku Postgres.