Connecting to Common Runtime Heroku Postgres Databases from an External Resource
Last updated June 06, 2023
Table of Contents
Common Runtime databases are accessible from anywhere. Any application using Postgres clients can connect to these databases. The Postgres plans available on the Common Runtime are Essential, Standard, and Premium.
Private and Shield-tier databases have restricted access. See Connecting to a Private or Shield Heroku Postgres Database from an External Resource for more info.
App Config Var
All Heroku Postgres databases belong to a Heroku application. You can find the application name on the database page at data.heroku.com or with
heroku pg:info from the Heroku CLI. You can access your database via an app config var containing the database URL, even if there’s no code in the application. Heroku manages this variable and it’s the primary way we tell you about your database’s network location and credentials.
To connect to your Heroku Postgres database from the CLI, run the
heroku pg:psql command from the Heroku CLI. The command uses your primary database at
DATABASE_URL by default, but you can specify the database you want to connect to:
USAGE $ heroku pg:psql [ADDON] EXAMPLE $ heroku pg:psql postgresql-sinuous-83720
heroku pg:psql is a wrapper on top of PostgreSQL’s native interactive terminal
psql. If you don’t have the Heroku CLI installed, you can also connect your Heroku Postgres database directly with
psql <DATABASE_URL> if you install Postgres locally.
Connect via a Desktop SQL Client
To connect to your Heroku Postgres database from a desktop SQL client, retrieve your Postgres connection string with
$ heroku pg:credentials:url DATABASE Connection info string: "dbname=dee932clc3mg8h host=ec2-123-73-145-214.compute-1.amazonaws.com port=6212 user=user3121 password=98kd8a9 sslmode=require"
The Postgres connection string contains:
- The URI of the database, for example,
- The database credentials, for example,
- The SSL connection, for example,
Connect from Apps and Services Outside of Heroku
Heroku Postgres databases are accessible from many programming languages and frameworks. See Connecting to Heroku Postgres for examples on creating connections with Heroku Postgres databases.
Connect from Salesforce Products
There are several ways to integrate Heroku and the Salesforce platform. Choosing the right integration method depends on your use case, the source you’re integrating with, the volume of data, the frequency of the integration, and so on. To learn about all the options to integrate Heroku with Salesforce, see the Integration Heroku and the Salesforce Platform Overview article. The following are some examples of integrating Heroku Postgres with Salesforce.
Heroku Connect is an add-on that synchronizes data between your Salesforce org and a Heroku Postgres database. Through a declarative interface, you choose and create mappings for the Salesforce objects you want to sync with Postgres tables. With Heroku Connect, you can have a one-way sync and read data from Heroku Postgres to Salesforce. You can also set up bidirectional sync and write data back to Heroku Postgres from Salesforce.
See Quick Start: Heroku Connect to get started on using Heroku Connect.
Heroku External Objects and Salesforce Connect
Heroku External Objects provides an oData wrapper for a Heroku Postgres database that’s been configured to use with Heroku Connect. Heroku External Objects lets other web services retrieve data from the Heroku Postgres database using RESTful endpoints generated by the wrapper. Used in tandem with Salesforce Connect, you can view, edit, and search your Heroku Postgres data right from your Salesforce org.
See Heroku External Objects with Salesforce Connect to get started on using Heroku External Objects with your Salesforce org.
MuleSoft is an integration Platform as a Service (iPaaS) for creating complex, multi-system integrations, and managing the full lifecycle of APIs. MuleSoft abstracts away the complexity of backend systems and processes and provides scalable and governable APIs, which you can invoke from a Heroku app. Using the Database Connector, you can connect to any JDBC-compliant database like Heroku Postgres.
See Connecting Heroku Data Services to MuleSoft to get started using MuleSoft connectors with Heroku Postgres.
CRM Analytics is a customer and business analytics platform that works with any data source. Connectors provide a way to connect data inside and outside of Salesforce, such as your Heroku Postgres data.
See Heroku Postgres Connection to connect your Heroku Postgres database to CRM Analytics.
To make effective use of Heroku Postgres databases outside of a Heroku application, keep in mind the following considerations.
Don’t Copy and Paste Credentials to a Separate Environment or App Code
Heroku manages the database URL and it changes 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 can follow the 12-Factor application configuration principles by using the Heroku CLI and invoke your process. For example:
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’re connecting to a database from other Heroku apps, you can attach a database add-on directly to multiple applications. Attaching a database to multiple apps ensures that any changes to the database’s URL 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 the code, rather than 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
To get automated backups on your database, use Heroku Postgres Backups on the associated Heroku app. You can create a manual backup on your database with the
pg:backups:capture command. You can also schedule backups to run daily against your database.
By default, PgBackups takes backups of the database at
DATABASE_URL in the Heroku app. Alternatively, you can provide the name of the database add-on you want to capture.