Last updated March 26, 2026

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        Max price  State
 ───────────────────────────────────────────────────── ───────────── ──────────── ────────── ───────
 heroku-postgresql (postgresql-concave-52656)            essential-0   ~$0.007/hour $5/month   created
  └─ as DATABASE

Provision the Add-on

To provision a new heroku-postgresql add-on, use the addons:create CLI command:

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

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

$ heroku addons:create heroku-postgresql:essential-0 -a example-app
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

Depending on the plan, 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.

After 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.

Specify the Postgres 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=16

Learn more about PostgreSQL version support.

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

Application Config Vars

As part of the provisioning process, Heroku Postgres adds a new config var to your app’s configuration that includes the connection string to access the database. The config var name matches the attachment name for your database.

You can specify an attachment name when provisioning your database with addons:create and the --as flag:

$ heroku addons:create heroku-postgresql:essential-0 --as ANALYTICS_DATABASE -a example-app

Heroku Postgres uses the DATABASE attachment name and the DATABASE_URL config var by default. If your app already has a Heroku Postgres database attached as 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.

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 the attachment name as 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_URL.

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

Destroying the Add-on

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

Destroy Using the Dashboard

To destroy 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.

Destroy Using the CLI

To destroy a Heroku Postgres database, use the addons:destroy command and specify the add-on name, config var, or attachment name of the database:

$ heroku addons:destroy postgresql-concave-52656

Or:

$ heroku addons:destroy DATABASE_URL

Next Steps

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