Provisioning Heroku Postgres
Last updated May 12, 2023
Table of Contents
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.
You can provision a database that allows installing extensions outside of the heroku_ext
schema but setting the --allow-extensions-on-public-schema
flag.
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.
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.