Last updated January 11, 2023

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, such as the pg Ruby gem.

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)                mini  $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 a Mini plan database:

$ heroku addons:create heroku-postgresql:mini
Creating heroku-postgresql:mini on ⬢ example-app... $5/month
Database has been created and is available
 ! This database is empty. If upgrading, you can transfer
 ! data from another database with pg:copy
Created postgresql-concave-52656 as DATABASE_URL

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=12

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.