Last updated July 26, 2024

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 already has Heroku Postgres provisioned:

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

Provision the Add-on

If heroku-postgresql doesn’t appear in your app’s list of add-ons, you can provision it with the following 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

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.

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’ve provisioned 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 in this article to connect from your application.

Next Steps

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