Last updated 09 November 2020

Heroku Connect is an add-on that synchronizes data between your Salesforce organization and a Heroku Postgres database. Using Heroku Connect with Heroku Postgres, you can build applications that interact with your Salesforce data using your favorite tools, including all languages and frameworks supported by Heroku. If you are just getting started with Heroku Connect, see this step-by-step tutorial for deploying an application.

Provisioning the add-on

To quickly create a new application, database and Heroku Connect instance use the Heroku button. To add Heroku Connect to an existing application you can either use the Heroku Dashboard or the Heroku CLI.

Available plans

There are three plans for Heroku Connect:

• demo: This is the default plan when provisioning the add-on and provides access to all features of Heroku Connect with the following limitations:

  • A maximum of 10,000 synchronized rows across all mappings.
  • A minimum polling interval of 10 minutes.
  • The trigger log is archived for 7 days instead of 31 days.

• enterprise: This is the paid plan that you will use after purchasing Heroku Connect. If you have existing add-ons using the demo plan, you can upgrade them by following the steps in the Upgrading the add-on plan section. Rows allocated to you under your contract are calculated according to the total rows synchronized across all mappings, regardless of how often they change.

• shield: This is the paid plan that you will use after purchasing Heroku Shield Connect. Heroku Shield Connect can only synchronize data with Heroku Postgres databases that have shield plans.

Please contact sales for more information on the Heroku Connect enterprise or shield plans.

You can use the heroku addons command to see if your application already has Heroku Connect provisioned and the current plan:

$ heroku addons | grep herokuconnect
herokuconnect (herokuconnect-gladly-8321)  demo   free

Create a new instance

Heroku Connect can be attached to your application using:

$ heroku addons:create herokuconnect
Creating herokuconnect-gladly-8321... done, (free)
Adding herokuconnect-gladly-8321 to sleepy-ocean-5276... done
Use `heroku addons:open herokuconnect` to finish setup
Use `heroku addons:docs herokuconnect` to view documentation.

When you provision the add-on a globally unique identifier will automatically be generated: in the above example the unique identifier is herokuconnect-gladly-8321. You can specify your own unique identifier by passing the --name flag to the addons:create command.

If you have purchased Heroku Connect you can specify the enterprise plan when adding the add-on to your application using:

$ heroku addons:create herokuconnect:enterprise

Completing configuration

When the Heroku Connect add-on has been attached to your application you can complete configuration by navigating to the add-on from the Heroku Dashboard or from the CLI:

$ heroku addons:open herokuconnect

In order to complete the configuration you will need a Postgres database attached to your application that Heroku Connect can use to store data for your mapped Salesforce objects.

Heroku Connect supports the following Heroku Postgres plan types: standard, premium and private. Heroku Connect can be used to sync data between a Salesforce org and a Heroku Postgres database inside or outside a Heroku Private Space.

To complete configuration of Heroku Connect click the Setup Connection button in the dashboard.

• 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 will be selected by default.

You can also choose the Postgres schema to be used for the tables created by Heroku Connect. The default is salesforce however you can choose to put your tables in an existing schema, including public, as long as no tables exist in the schema.

Click Next to set up the database.

• You then need to authenticate to your Salesforce organization: you can choose to authenticate to a production or sandbox organization or you can choose to use a custom login domain. Click the Authorize button and you will be taken to Salesforce to enter your login credentials and authorize Heroku Connect to have access to your data.

You have the option to select the Salesforce API version you want Heroku Connect to use. Once selected, the API version cannot be changed. It is straightforward to create a second instance using a different API version with the same configuration should you wish to change API version at a later date.

It is recommended that you use a dedicated integration user for Heroku Connect with the necessary permissions to allow for successful synchronization (for example the most permissive option is to make the integration user a System Administrator).

To ensure optimal performance, Heroku Connect should have View All Data permission in Salesforce and it may also be necessary to grant Modify All Data permission when dealing with relationships between objects. Both the user and the Salesforce organization will also need to have API Enabled permission granted.

Without the View All Data permission, Salesforce has to check permissions for each row individually, which precludes use of indices and results in greatly reduced performance. For larger connections, lack of View All Data can also result in OPERATION_TOO_LARGE errors that cause sync to fail altogether.

After you have authenticated to your Salesforce organization you can start mapping objects: to begin the process click the Create Mapping button on the Overview tab of the Heroku Connect dashboard.

Multiple instances of Heroku Connect

It is possible to add multiple Heroku Connect add-ons to a single application; for example, you may wish to synchronize data from multiple Salesforce organizations and one way to achieve this is to have multiple add-ons each authorized and configured to work with different organizations.

It is also possible for multiple instances of Heroku Connect to be connected to the same Salesforce organization. This may be desirable to synchronize large numbers of Salesforce objects from a single organization.

When multiple Heroku Connect add-ons exist it is necessary to use the globally unique identifier assigned to the add-on when running commands from the CLI. For example to open the Heroku Connect dashboard:

$ heroku addons:open herokuconnect-gladly-8321

Upgrading the add-on plan

If you are operating inside a Heroku team with a paid plan entitlement, you can upgrade by using the Edit plan option in the Heroku Dashboard or using the CLI:

$ heroku addons:upgrade herokuconnect:enterprise
WARNING: No add-on name specified (see `heroku help addons:upgrade`)
Finding add-on from service herokuconnect on app sleepy-ocean-5276... done
Found herokuconnect-gladly-8321 (herokuconnect:demo) on sleepy-ocean-5276.
Changing herokuconnect-gladly-8321 plan to herokuconnect:enterprise... done, (contract)
Plan change successful

If you have multiple Heroku Connect add-ons attached to your application you will also need to specify the globally unique identifier assigned to the add-on when running the upgrade command:

$ heroku addons:upgrade herokuconnect-gladly-8321 herokuconnect:enterprise
Changing herokuconnect-gladly-8321 plan to herokuconnect:enterprise... done, (contract)
Plan change successful

The Heroku Connect dashboard

The Heroku Connect dashboard allows you to configure, monitor and troubleshoot your connection.

The Heroku Connect dashboard is available to any member or collaborator on your application. See Collaborating with Other Developers on Your App for more information on how to manage the users who have access to your application.

Overview tab

The Overview tab provides a summary of your mappings and key associated metrics. Depending upon your configuration, there will be either one or two histograms displaying data movement from Salesforce to Heroku Postgres, and optionally from Heroku Postgres to Salesforce.

When present, errors for reads and writes are displayed in orange. You can highlight a data point to see the specific number of rows and errors and change the time period shown using the drop-down list to the top-right of the chart.

Mappings tab

The Mappings tab lists each mapping in the connection along with a set of key data points: mapped fields, Salesforce rows, Postgres rows, pending writes, and errored writes. The action button to the right of each row can be used to launch mapping-specific actions such as edit, reload and abort. Lastly, the mapping name is a hyperlink to the mapping detail view where you can view mapping-specific data movement graphs and see details of each mapped field.

Logs tab

The Logs tab allows you to view detailed information about the synchronization operations being performed by Heroku Connect as they happen. You can filter by mapped object, log type, and log level. To see and analyze historical logs, you need to configure a log drain.

Explorer tab

The Explorer tab provides access to Sync Explorer: a tool that allows you to get detailed information on the status of individual rows for each mapping.

You can filter by mapping and synchronization state (see Status information for details) and can search for text contained in the id, sfid, _hc_err and name fields.

Sync Explorer also allows you to view a side-by-side comparison of the data held in Salesforce and in the mapped database table.

Sync Explorer, used in conjunction with the Logs tab, is an invaluable tool to help you understand the operations being performed by Heroku Connect and enables you to diagnose and fix synchronization issues that can occur.

The most common synchronization error that occurs when reading is insufficient permissions to read the mapped object. The most common synchronization error that occurs when writing is insufficient write permissions for the target Salesforce org.

Settings tab

The Settings tab contains a drop-down list where you can choose:

Manage Connection

The Manage Connection page lets you Pause or Resume the connection, view your plan type, view the list of users with access to the dashboard, check for orphaned mappings, download an audit trail and even delete the connection itself.

Manage Salesforce

The Manage Salesforce page shows your current connection details (Salesforce organization ID, authenticating user and environment). You can also re-authorize the user credentials used to access Salesforce and view your current Salesforce storage usage. Re-authorizing to a different user should not have any affect on the syncing of data, provided that the new user has permissions to the same objects that the previous user had.

Database

The Database page summarizes the Heroku Postgres database settings used by Heroku Connect, including the database and schema names, host and port, as well as providing useful command line examples showing how to connect to the database using PSQL.

Import/Export Configuration

It is possible to export your existing mapping configuration to or import a new configuration from a JSON file. This can be helpful when managing your Salesforce organizations.

Mapping objects

Creating a mapping

To create a new mapping:

1. Click the Create Mapping button on the Mappings tab of the Heroku Connect dashboard.

2. You will see a list of objects that can be mapped from your Salesforce organization. Use the search box to filter the list and then click on the object that you want to map.

   Heroku Connect supports all standard and custom objects that can be retrieved via the SOAP and Bulk APIs except for those that require the use of object specific filter criteria or are not fully supported by the Bulk API. For example KnowledgeArticleVersion and objects that end with __kav require the use of additional query criteria (PublishStatus=Online) and therefore cannot be mapped in Heroku Connect. LeadHistory does not support Bulk Paging and the Base64 type of Attachment is unsupported by the Bulk API, and thus neither can be retrieved, once there are more than 20,000 changed records to sync. Other exceptions and warnings may apply.

   The complete list of objects that Heroku Connect supports for your version of Salesforce is available from the Supported Salesforce Standard Objects page.

3. You will now be able to choose the synchronization options and the fields that you want to map. Some fields in the list are pre-selected and cannot be removed from the mapping (such as Id and SystemModstamp) as they are required for Heroku Connect to perform synchronization.

   It is recommended that certain fields, such as CreatedDate and Name, are mapped to ensure you get the best experience from Heroku Connect. These fields will be pre-selected when creating a new mapping however unlike required fields they can be un-selected if you prefer not to include them.

4. To help optimize common queries Connect allows you to configure, one or more simple indexes for a Mapping. This can be done by checking the checkbox, in the Indexed column, for each field you wish to be indexed. Alternatively, if complex indexes are desired, these can be created via PostgreSQL manually. The advantage of creating simple indexes via Connect rather than manually, is they will be preserved when importing a Connect configuration into another Connection.

5. Click Save and Heroku Connect will immediately create a table in your database corresponding to the Salesforce object, query for all records from Salesforce and insert them into the mapping table.

Editing a mapping

To edit an existing mapping:

1. Click on the Mappings tab of the Heroku Connect dashboard.
2. On the mapping detail page, click the action item and select Edit from the menu.
3. You will now be able to edit the synchronization options as well as adding and removing fields from the mapping.
4. Click Save and Heroku Connect will update the mapped database table to add and remove columns and query Salesforce for data for any new fields to update existing records in the database.

Deleting a mapping

To delete an existing mapping:

1. Click on the Mappings tab of the Heroku Connect dashboard.
2. On the mapping detail page, click the action item and select Edit from the menu.
3. On the mapping editor page click the Delete button.

When you delete a mapping from Connect the underlying data table in Postgres will also be removed. Furthermore, Connect will attempt to remove any pending writes corresponding to the mapping from your trigger log.

Synchronization options

When creating or editing a mapping you can also configure the method used to synchronize data with your Salesforce organization: standard polling or accelerated polling.

Write database updates

Mappings are read-only by default: Heroku Connect will poll your Salesforce organization for changes and synchronize them to your database. In read-only mode, changes made in your database will not be synchronized back to Salesforce.

To enable changes made in your database to synchronize back to your Salesforce organization, tick the Write database updates box in the Database > Salesforce section of the create/edit mapping page. See Writing to Salesforce for more details about how Connect writes to Salesforce.

Polling mode

By default Heroku Connect will poll your Salesforce organization for changes every ten minutes. You can change the polling interval from as low as two minutes (ten minutes in the demo plan) to as high as sixty minutes in one minute increments. A shorter polling interval is suitable for mappings where data changes frequently and a longer polling interval is best for mappings that change less often as it reduces API usage and processing overheads.

Accelerated polling

The behavior of polling in Heroku Connect can be augmented by enabling accelerated polling, which makes use of Salesforce’s Streaming API to notify Heroku Connect when data changes in your mapped objects from Salesforce. Heroku Connect makes use of these notifications from Salesforce to trigger polling outside of the regularly scheduled polls. However, Connect does not rely on the notifications to determine what data has changed. You can think of the accelerated polling option as ‘polling on demand’ whereas polling mode is ‘polling at a fixed interval’. Accelerated polling is available for all custom objects and some standard objects. For those objects that do not support streaming, you will not be able to select this option when creating or editing a mapping.

If multiple notifications are received within a ten second period, Connect will only trigger a single poll to reduce Salesforce API utilization.

Unique identifier

Heroku Connect read-write mappings work best when there is a shared notion of a uniqueness between Postgres and Salesforce. Records inserted in Postgres are unable to have a Salesforce generated ID until they get propagated via Heroku Connect. Because Heroku Connect uses separate threads for reading and writing, there exists a possibility that a reader may process a write operation from Salesforce to Postgres before a write process from Postgres to Salesforce has finished writing the newly generated Salesforce ID back to the inserted records.

Salesforce provides a mechanism to define a custom field to uniquely identify records coming from an external source (like Postgres/Heroku Connect) via the External ID and Unique attributes. Both attributes need to be enabled in order for a field to be chosen as the unique identifier. When this setting is configured, Heroku Connect matches records coming from Salesforce either by Salesforce ID (if available) or the specified unique identifier if a record matches the External ID and the Salesforce ID is NULL. This ensures that no matter which process attempts to write the record first, there are no integrity errors and the record is always matched (See Ensuring Uniqueness). You can also reference the newly inserted row from a foreign table by this external id (see: Simple Relationships Between Two Objects and Relationship External IDs).

There are several considerations to keep in mind while using unique external IDs with Heroku Connect. Unique external IDs should be treated as aliases for a Salesforce ID. Therefore, they should not change over time and you should choose a similarly unique mechanism for generating them. We recommend using random UUIDs, which can be generated using uuid_generate_v4() or gen_random_uuid(). Postgres integer sequences are not recommended as they are not guaranteed to be unique. Additionally, the ID field in the Heroku Connect database should not be used since these numbers can reset when importing your configuration into a new database or on reload a table.

Salesforce organizations

As part of the provisioning process for Heroku Connect you will be required to authenticate to a Salesforce organization.

When you authenticate Heroku Connect to an organization then the mappings you create are specific to that organization: this includes both the structure of the underlying database tables and the data that is synchronized between Salesforce and the database. In order to reduce the potential for data conflict and corruption it is not possible to re-authenticate an existing Heroku Connect connection to a different Salesforce organization.

If you want to synchronize data from a new production or a refreshed sandbox organization you will need to:

1. Export your current configuration to a JSON file.

   Navigate to the Settings tab, choose Import/Export Configuration, click the Export button and then on the confirmation page click Export to download the file. If connected to a sandbox that’s already been refreshed, the connection’s dashboard will be replaced by a link to these instructions and a button to export your configuration.

2. Remove and re-provision the Heroku Connect add-on authenticating to the new Salesforce organization.

3. Import the JSON configuration file.

   Navigate to the Settings tab, choose Import/Export Configuration, click the Import button and then click Choose file to locate the file to upload. Click the Upload button to begin the import.

On successful completion of the import Heroku Connect will begin syncing data from your new Salesforce organization into the database.

Login IP restrictions

If your Salesforce organization has org-wide or profile-based IP restrictions, you will need to extend your range of allowed IP addresses to include Heroku Connect. Connect runs inside a Private Space, so you can add these IPs to your allowed list depending on the cell your connection is in:

You can verify that Heroku Connect is logging in successfully by viewing the Login History for your Salesforce organization. You should see entries where the Username matches the email address you have used to authenticate and the Application is either Heroku Connect or Heroku Connect EU depending on the region where your instance is located.

Security

Heroku Connect observes Salesforce secure practices by storing an OAuth token which can be revoked at any time by the Salesforce admin. Heroku Connect uses secure SSL connections whenever data moves from Salesforce to the Heroku Postgres database, or from the Heroku Postgres database to Salesforce. Encrypted data may travel over the public internet while in flight and may be temporarily stored on an encrypted volume for up to 24 hours while being processed but otherwise is not stored outside of your Heroku Postgres database.

More information on Heroku security can be found here.

Using with Heroku Shield

Heroku provides a Shield Connect plan that is compatible with Shield Private Spaces. See the Heroku Connect FAQ for details.

Revoking Access to a Heroku Connect Add-on

Heroku Connect uses Heroku App Permissions to allow access to the Heroku Connect dashboard. Users are remembered the first time they perform an addons:open or use the CLI to associate themselves with the Connect Add-on. Heroku Connect proactively checks that the user has access after 6 hours or a period of inactivity, whichever comes first. If you wish to revoke access to a specific user sooner, then you can revoke permissions for the target user and perform an addons:open with any other user to force the target user to lose access to the add-on.

Advanced usage

For more detailed information on Heroku Connect usage and features, see the Heroku Connect category page.

Removing the add-on

You can remove the add-on using the Heroku dashboard or using the CLI.

$ heroku addons:destroy herokuconnect

 !    WARNING: Destructive Action
 !    This command will affect the app: sleepy-ocean-5276
 !    To proceed, type "sleepy-ocean-5276" or re-run this command with --confirm sleepy-ocean-5276

> sleepy-ocean-5276
Destroying herokuconnect-gladly-8321 on sleepy-ocean-5276... done

Support

All Heroku Connect support and runtime issues should be submitted via one of the Heroku Support channels.