Skip Navigation
Show nav
Dev Center
  • Get Started
  • Documentation
  • Changelog
  • Search
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
    • .NET
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
View categories

Categories

  • Heroku Architecture
    • Compute (Dynos)
      • Dyno Management
      • Dyno Concepts
      • Dyno Behavior
      • Dyno Reference
      • Dyno Troubleshooting
    • Stacks (operating system images)
    • Networking & DNS
    • Platform Policies
    • Platform Principles
  • Developer Tools
    • Command Line
    • Heroku VS Code Extension
  • Deployment
    • Deploying with Git
    • Deploying with Docker
    • Deployment Integrations
  • Continuous Delivery & Integration (Heroku Flow)
    • Continuous Integration
  • Language Support
    • Node.js
      • Working with Node.js
      • Node.js Behavior in Heroku
      • Troubleshooting Node.js Apps
    • Ruby
      • Rails Support
      • Working with Bundler
      • Working with Ruby
      • Ruby Behavior in Heroku
      • Troubleshooting Ruby Apps
    • Python
      • Working with Python
      • Background Jobs in Python
      • Python Behavior in Heroku
      • Working with Django
    • Java
      • Java Behavior in Heroku
      • Working with Java
      • Working with Maven
      • Working with Spring Boot
      • Troubleshooting Java Apps
    • PHP
      • PHP Behavior in Heroku
      • Working with PHP
    • Go
      • Go Dependency Management
    • Scala
    • Clojure
    • .NET
      • Working with .NET
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Getting Started
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
      • Migrating to Heroku Postgres
    • Heroku Key-Value Store
    • Apache Kafka on Heroku
    • Other Data Stores
  • AI
    • Working with AI
    • Heroku Inference
      • Inference API
      • Quick Start Guides
      • AI Models
      • Inference Essentials
    • Vector Database
    • Model Context Protocol
  • Monitoring & Metrics
    • Logging
  • App Performance
  • Add-ons
    • All Add-ons
  • Collaboration
  • Security
    • App Security
    • Identities & Authentication
      • Single Sign-on (SSO)
    • Private Spaces
      • Infrastructure Networking
    • Compliance
  • Heroku Enterprise
    • Enterprise Accounts
    • Enterprise Teams
    • Heroku Connect (Salesforce sync)
      • Heroku Connect Administration
      • Heroku Connect Reference
      • Heroku Connect Troubleshooting
  • Patterns & Best Practices
  • Extending Heroku
    • Platform API
    • App Webhooks
    • Heroku Labs
    • Building Add-ons
      • Add-on Development Tasks
      • Add-on APIs
      • Add-on Guidelines & Requirements
    • Building CLI Plugins
    • Developing Buildpacks
    • Dev Center
  • Accounts & Billing
  • Troubleshooting & Support
  • Integrating with Salesforce
  • Heroku Enterprise
  • Heroku Connect (Salesforce sync)
  • Quick Start: Heroku Connect CLI

Quick Start: Heroku Connect CLI

English — 日本語に切り替える

Last updated August 13, 2024

Table of Contents

  • Prerequisites
  • Step 1: Create a Heroku App and Heroku Postgres Database
  • Step 2: Provision the Heroku Connect Add-on
  • Step 3: Install the Heroku Connect CLI Plugin
  • Step 4: Add User to Heroku Connect
  • Step 5: Configure the Connection to Heroku Postgres
  • Step 6: Configure the Connection to Salesforce
  • Step 7: Check Connection State
  • Step 8: Set Up Mappings
  • (Optional) Step 9: Verify Setup
  • Next Steps

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

  • A verified Heroku Account
  • You have the Heroku CLI plugin installed

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.

Keep reading

  • Heroku Connect (Salesforce sync)

Feedback

Log in to submit feedback.

Writing Data to Salesforce with Heroku Connect Reading Data from Salesforce with Heroku Connect

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Training & Education
  • Blog
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure
  • .NET

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing
  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Github
  • LinkedIn
  • © 2025 Salesforce, Inc. All rights reserved. Various trademarks held by their respective owners. Salesforce Tower, 415 Mission Street, 3rd Floor, San Francisco, CA 94105, United States
  • heroku.com
  • Legal
  • Terms of Service
  • Privacy Information
  • Responsible Disclosure
  • Trust
  • Contact
  • Cookie Preferences
  • Your Privacy Choices