Quick Start: Heroku Connect CLI

Last updated August 13, 2024

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 CLI and the Heroku Connect CLI plugin. See Heroku Connect for more info about this add-on.

See Quick Start: Heroku Connect and Heroku Connect API for alternative setup options.

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 are 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. Create an app with the following Heroku CLI command: heroku apps:create
  2. Provision the database with the following Heroku CLI command: heroku addons:create heroku-postgresql:PLAN_NAME. If no plan name is specified, the essential-0 plan is provisioned but this default isn’t recommended. Choose a -4 plan or larger for production use cases. See Heroku Connect for more info. For tutorial purposes only, you can choose the essential-0 plan to minimize costs.

Step 2: Provision the Heroku Connect Add-on

Run the following Heroku CLI command: heroku addons:create herokuconnect:PLAN_NAME.

If no plan name is specified, the demo plan is provisioned. See Available Plans for more info.

Step 3: Install the Heroku Connect CLI Plugin

Run the following Heroku CLI command to install the Heroku Connect CLI plugin:

$ heroku plugins:install @heroku-cli/heroku-connect-plugin

Step 4: Add User to Heroku Connect

By default, no users can access the Heroku Connect add-on. Run heroku connect:info to associate your user with the app.

Step 5: Configure the Connection to Heroku Postgres

  1. Check the database’s config var by running heroku config.
  2. Set the database used for the connection: heroku connect:db:set --db=DATABASE_CONFIG_VAR --schema=salesforce. If there are no tables in another schema, you can choose to put your tables there instead of salesforce.

Step 6: Configure the Connection to Salesforce

Run one of the following CLI plugin commands to initiate authentication to a Salesforce org. It’s recommended to use a dedicated integration user with View All Data permissions. See Heroku Connect for more info.

Production Org

This command initiates authentication to the production org if the --environment flag isn’t specified.

heroku connect:sf:auth

Sandbox Org

heroku connect:sf:auth --environment=sandbox

Custom Login Domain

heroku connect:sf:auth --environment=custom --domain=DOMAIN

When creating the connection with the CLI plugin, Heroku Connect sets the connection to use the current default version of the Salesforce API. To use another version, complete this step in the Heroku Connect dashboard instead. The API version can’t be changed after the connection is configured. Recreate the connection to change the API version.

Step 7: Check Connection State

Ensure that the connection is configured correctly by ensuring that it is in the IDLE state.

heroku connect:state

Step 8: Set Up Mappings

You can only set up mappings by importing JSON config files when using the CLI plugin. If you’ve never configured mappings, it’s recommended to create them via the Heroku Connect dashboard instead.

If you don’t have an existing Heroku Connect add-on with mappings to export configuration, you can follow this example.

Sample JSON Configuration File

{
  "mappings": [
    {
      "object_name": "Account",
      "config": {
        "access": "read_only",
        "sf_notify_enabled": false,
        "sf_polling_seconds": 600,
        "sf_max_daily_api_calls": 30000,
        "fields": {
          "CreatedDate": {},
          "Id": {},
          "IsDeleted": {},
          "Name": {},
          "SystemModstamp": {}
        },
        "indexes": {
          "Id": {
            "unique": true
          },
          "SystemModstamp": {
            "unique": false
          }
        }
      }
    },
    {
      "object_name": "Property__c",
      "config": {
        "indexes": {
          "Address__c": {
            "unique": true
          },
          "SystemModstamp": {
            "unique": false
          },
          "Id": {
            "unique": true
          }
        },
        "sf_max_daily_api_calls": 30000,
        "access": "read_write",
        "upsert_field": "Address__c",
        "applied_at": "2021-02-16T17:40:15.177747Z",
        "sf_polling_seconds": 600,
        "sf_notify_enabled": true,
        "fields": {
          "Description__c": {},
          "Broker__c": {},
          "Name": {},
          "Address__c": {},
          "IsDeleted": {},
          "SystemModstamp": {},
          "CreatedDate": {},
          "Price__c": {},
          "Id": {}
        }
      }
    }
  ],
  "connection": {
    "app_name": "example-app",
    "organization_id": "00D5w000003xwrCEAQ",
    "exported_at": "2021-06-17T16:36:52.796896+00:00",
    "features": {
      "disable_bulk_writes": false,
      "poll_db_no_merge": true,
      "poll_external_ids": false,
      "rest_count_only": false,
      "ucs_basic_collation_index": true
    },
    "api_version": "52.0",
    "name": "",
    "logplex_log_enabled": false
  },
  "version": 1
}

Export Existing Mapping Configuration

If you have an existing Heroku Connect add-on with mappings, you can export the configuration to import into another connection. Run this CLI Command:

heroku connect:export

Import Mapping Configuration

Import a JSON configuration file with this CLI command:

heroku connect:import FILE

If you’re importing an existing file, ensure that you change the connection section of the file to match the info for the connection you’re importing into.

(Optional) Step 9: Verify Setup

Run heroku connect:info to verify that your data is syncing. It returns a table of your mappings and their states. 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 to Postgres by viewing your data with psql.

  1. Run psql against your database by running heroku pg:psql.
  2. Check the tables in your schema, for example, \dt salesforce.*;.
  3. Check for data in your tables, for example, select * from salesforce.account;.

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.