Quick Start: Heroku Connect

Last updated February 06, 2023

We recommend using our low-cost plans to complete this tutorial. Eligible students can apply for platform credits through our new Heroku for GitHub Students program.

This guide helps you set up the Heroku Connect add-on via the Heroku and Heroku Connect dashboards. See Heroku Connect for more info about this add-on.

See Setting Up Heroku Connect for setup recommendations and considerations.

See Quick Start: Heroku Connect CLI and Heroku Connect API if you prefer to set up with those tools instead of dashboards. Trailhead also has a step-by-step tutorial for deploying an application with Heroku Connect.

Prerequisites

Step 1: Create a Heroku App and Heroku Postgres Database

Heroku Connect requires Heroku Postgres for syncing data from Salesforce. Both Heroku Connect and Heroku Postgres are add-ons and must be attached to a Heroku app. You can attach add-ons to an empty app - deploying code isn’t required.

Adding a database to complete this tutorial counts towards your usage. Delete your database as soon as you’re done to control costs. Learn about our low-cost plans. Eligible students can apply for platform credits through our Heroku for GitHub Students program.

Create an empty app and attach Heroku Postgres to it:

  1. Open the Heroku Dashboard.
  2. Click New in the upper right and select Create new app.
  3. Provide an app name, choose a region for the app and click Create app.
  4. The app view loads when the app is created. Click the Resources tab.
  5. Search for Heroku Postgres in the Add-ons section.
  6. Select a plan and click the Submit Order Form button. Choose a -4 plan or larger for production use cases. See Heroku Connect for more info. For tutorial purposes only, you can choose the mini plan to minimize costs.

Step 2: Provision the Heroku Connect Add-on

  1. Open the Heroku Dashboard.
  2. Click the app you want to attach Heroku Connect to.
  3. Click the Resources tab.
  4. Search for Heroku Connect in the Add-ons section.
  5. Select a plan and click the Submit Order Form button. See Available Plans for more info.

Heroku Connect appears in the Add-ons section of your Resources tab when provisioned.

Step 3: Provision a Logging Add-on

Heroku Connect produces logs of its sync activity, which you can access from your log drain. Provision one of these logging add-ons for your application:

  1. Open the Heroku Dashboard.
  2. Click the app you want to attach Heroku Connect to.
  3. Click the Resources tab.
  4. Search for the add-on in the Add-ons section.
  5. Select a plan and click the Submit Order Form button.

Step 4: Configure the Connection

  1. Open the Heroku Connect Dashboard by clicking the add-on from the Heroku Dashboard Resources tab.
  2. Click the Setup Connection button in the dashboard.
  3. Choose a Heroku Postgres database that is attached to your application. If you have multiple databases attached to your application you can choose the one you want Heroku Connect to use. The database specified by the DATABASE_URL config var is selected by default.
  4. Choose the Postgres schema to be used for the tables created by Heroku Connect. The default is salesforce. You can choose to put your tables in an existing schema, including public, as long as no tables exist in the schema.
  5. Click Next to set up the database.
  6. Choose to authenticate to a production or sandbox Salesforce org. You can use a custom login domain.
  7. Select the Salesforce API version you want Heroku Connect to use. You can’t change the API version after configuring the connection. Recreate the connection to change the API version.
  8. Click the Authorize button and a browser opens for you to enter your Salesforce login credentials and authorize Heroku Connect. It’s recommended to use a dedicated integration user with View All Data permissions. See Heroku Connect for more info.

Step 5: Set Up Mappings

After you’ve authenticated to your Salesforce org, you can start mapping objects. To begin the process, click Create Mapping on the Overview tab of the Heroku Connect dashboard. See Managing Heroku Connect Mappings for full details.

(Optional) Step 6: Verify Setup

Check the following to verify that your data is syncing:

  1. Click the Mappings tab.
  2. The Status column indicates a mapping’s sync state. Check Mapping States Reference to ensure that all of your mappings are in a non-error state.

You can also verify that data is syncing by using the Explorer tab. You can view a side-by-side comparison of the data held in Salesforce and in the mapped database tables.

Next Steps

In this tutorial, you set up an empty Heroku app. To deploy code to this app, see these articles on deployments. Most users deploy their code with Git.

To connect to your Heroku Postgres database from your Heroku app, see Heroku Postgres.

To connect to Heroku Postgres from external connections, see External Connections (ingress) and Heroku Postgres on Private and Shield Spaces.

Feedback

Log in to submit feedback.