Provisioning Heroku Postgres
Last updated May 12, 2023
Table of Contents
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.
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
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.
You can provision a database that allows installing extensions outside of the
heroku_ext schema but setting the
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,
You can confirm the names and values of your app’s config vars with the
heroku config command.
The value of your app’s
DATABASE_URL config var can change at any time.
Don’t rely on this value either inside or outside your Heroku app.
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.