Connecting to Heroku Postgres Databases from Outside of Heroku
Last updated December 28, 2021
Heroku Postgres databases are designed to be used with a Heroku app. All Heroku Postgres databases have a corresponding Heroku application. You can find the application name on the database page at data.heroku.com. Your database is attached to the Heroku app and is accessible via an app config var containing the database URL, even if you host no code in the application itself. This variable is managed by Heroku, and is the primary way we tell you about your database’s network location and credentials.
However, except for private and shield tier databases, Heroku Postgres databases are accessible from anywhere and can be used from any application using standard Postgres clients. For private databases, outside access can be enabled using Mutual TLS.
To make effective use of Heroku Postgres databases outside of a Heroku application, keep in mind the following:
Don’t copy and paste credentials to a separate environment or app code
The database URL is managed by Heroku and will change under some circumstances such as:
- User-initiated database credential rotations using
- Catastrophic hardware failures that require Heroku Postgres staff to recover your database on new hardware.
- Security issues or threats that require Heroku Postgres staff to rotate database credentials.
- Automated failover events on HA-enabled plans.
Always fetch the database URL config var from the corresponding Heroku app when your application starts. For example, you may follow 12Factor application configuration principles by using the Heroku CLI and invoke your process like so:
DATABASE_URL=$(heroku config:get DATABASE_URL -a your-app) your_process
This way, you ensure your process or application always has correct database credentials.
Attach the database as an add-on to other Heroku apps
If you are connecting to a database from other Heroku apps, you can now attach a database add-on directly to multiple applications. This ensures that any changes to the database’s URL will automatically propagate to your other apps.
Applications must support and enable SSL to connect to a Heroku Postgres database. Most clients connect over SSL by default, but sometimes it’s necessary to add the
sslmode=require query parameter to your database URL before connecting.
Be sure to append the
sslmode=require parameter to your database’s URL from code, rather than by editing the value of your
DATABASE_URL config var directly. Various automated events (such as a failover) can change the value of the config var, which overwrites any edits you make.
Use Heroku Postgres backups
You can use Heroku Postgres Backups on the associated Heroku app in order to get automated backups on your database. Heroku Postgres Backups takes backups of the database pointed at by
DATABASE_URL in the Heroku app, so make sure you promote your database:
heroku pg:promote HEROKU_POSTGRESQL_VIOLET --app your-app