Last updated June 15, 2021
Table of Contents
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 custom applications that interact with your Salesforce data.
Setting up Heroku Connect
Heroku Connect can only be used with Salesforce editions that have API access. Some Salesforce plan types, including trial versions, do not have API access by default and cannot be used with Heroku Connect.
You can provision the add-on via the Heroku Dashboard or the CLI. By default, the Heroku Connect
demo plan is used when the add-on is provisioned. Customers with contracts for Heroku Connect’s paid plans can also provision
shield plans. Please see the Available plans section and contact sales for more details.
Creating a new instance via the Heroku Dashboard
To open the Heroku Dashboard, navigate to dashboard.heroku.com/apps.
- Select the application you would like to attach Heroku Connect to from your applications list.
- Click the
Resourcestab at the top of the page.
- Search for Heroku Connect in the
Add-onssection of the page.
- Select a plan and click the
Submit OrderForm button.
Creating a new instance via the CLI
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
If you have purchased Heroku Connect you can specify the plan type when adding the add-on to your application:
$ heroku addons:create herokuconnect:enterprise $ heroku addons:create herokuconnect:shield
Heroku Connect instances are located in the same region as the application that they are attached to.
Provisioning the database
A Heroku Postgres database is used by Heroku Connect to store data for your mapped Salesforce objects.
Heroku Connect supports the following Heroku Postgres plan types:
private. Heroku Connect
shield plans can additionally support Heroku Postgres
shield plans. Heroku Connect can be used to sync data between a Salesforce org and a Heroku Postgres database inside or outside a Heroku Private Space.
Provision a Heroku Postgres database if your app does not already have one. Refer to the Heroku Postgres article for instructions.
It’s important to carefully consider the solution architecture of geographically distributed architectures as network latency can become a significant factor in service performance. The best practice is to co-locate Connect and Postgres in the same region, as geographically close to the Salesforce org as possible.
Although it is possible to use a hobby tier database with Heroku Connect, it is strongly recommended that you use at least a standard-4, premium-4, private-4 or shield-4 database. Smaller database plans have insufficient connection limits and I/O performance for most production use cases of Heroku Connect.
- Open the Heroku Connect Dashboard by navigating to the add-on from the Heroku Dashboard or from the CLI (
heroku addons:open herokuconnect)
- Click the
Setup Connectionbutton 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_URLconfig var is selected by default.
- 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.
Nextto set up the database.
- Choose to authenticate to a production or sandbox Salesforce organization. You can choose to use a custom login domain.
- 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.
- Click the
Authorizebutton and you will be taken to Salesforce to enter your login credentials and authorize Heroku Connect to have access to your data.
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.
When authenticating to an organization it will not be possible to change the organization at a later date: see Salesforce organizations for more information.
Supported objects and API versions
The complete list of objects that Heroku Connect supports for your version of Salesforce is available on the Supported Salesforce Standard Objects page. The Bulk API is not available in versions before Salesforce API v39 and thus you should use at least v39 with Heroku Connect. See Supported Salesforce Objects for more info.
New Heroku Connect add-ons default to Salesforce API version 52.0. You can specify the API version at connection creation.
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 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 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 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 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
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 contains a drop-down list where you can choose:
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.
Recover From Error attempts to clear out an error state and to resume synchronization.
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 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.
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.
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.
Sandbox organizations can be periodically refreshed: this involves creating a new snapshot of data from the production organization and, at the point of activation, will replace the current sandbox with a new organization.
If you want to synchronize data from a new production or a refreshed sandbox organization you will need to:
Export your current configuration to a JSON file.
Navigate to the
Import/Export Configuration, click the
Exportbutton and then on the confirmation page click
Exportto 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.
Import the JSON configuration file.
Navigate to the
Import/Export Configuration, click the
Importbutton and then click
Choose fileto locate the file to upload. Click the
Uploadbutton 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 find your connection’s cell by going to the connection’s Manage Connection page and finding the Cell Label value.
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.
Salesforce has a session setting that allows you to lock sessions to the IP address from which they originated. Because Heroku Connect uses multiple IP addresses, you should avoid enabling this setting.
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
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.
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.
Using a different database schema name for each organization allows a single Heroku Postgres database to be used with multiple Heroku Connect add-ons.
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 using multiple Heroku Connect add-ons, you must use a distinct integration user per add-on. Salesforce enforces a limit of ten concurrent queries per user. Additionally, each Heroku Connect add-on uses a different access token for Salesforce API calls, and Salesforce has a default limit of five tokens per integration user. If you use the same integration user for multiple add-ons and exceed the limit, your connections will require frequent re-authorization into Salesforce, which will repeatedly pause synchronization.
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
For more detailed information on Heroku Connect usage and features, see the Heroku Connect category page.
Managing add-on 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:
enterprise: This is the paid plan that you will use after purchasing Heroku Connect. If you have existing add-ons using the
demoplan, 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.
enterprise plan was called
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.
danketsu plans will appear with a ‘contract’ price in the add-ons list for your application in the Heroku dashboard. You should verify that the plan name is enterprise, shield, or danketsu if you wish to ensure that you are using a paid plan.
Please contact sales for more information on the Heroku Connect
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
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
Removing the add-on
You can remove the add-on using the Heroku dashboard or using the CLI.
Mapped tables will be dropped from your Postgres database when removing the add-on: you should ensure you have an up-to-date backup of your database before proceeding.
When you remove your add-on, we will try to
DROP SCHEMA for your connection schema. The schema will not be dropped if there are any remaining tables or functions associated with the schema.
$ 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
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 you wish to remove when using the CLI.
- Heroku Connect is incompatible with connection pooling for Heroku Postgres.
- Heroku Connect can’t be added to review apps via the
app.jsonfile. You can manually provision Heroku Connect once the review app has been created.
- Heroku Connect creates functions in the
publicschema of your database in order sync your data. If the
publicschema is removed from your
search_pathor if these functions are deleted, Heroku Connect can no longer find them which impairs data syncs. See this Knowledge Base article if Heroku Connect cannot find
get_xmlbinaryor other shared functions.
- Foreign data wrappers cannot be used with Heroku Connect as
pg_catalog. This prevents Connect from using shared functions stored in the
publicschema needed to sync data.
- Heroku Connect uses Postgres triggers to observe changes in your Connect tables and write your changes to Salesforce. If you implement your own custom triggers on Connect tables, Connect may miss your updates, or you may create additional load. Heroku Support may not be able to provide help with custom triggers, so use them at your own risk. See more guidance on using custom triggers.
All Heroku Connect support and runtime issues should be submitted via one of the Heroku Support channels.