Last updated August 28, 2023
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.
If you’re new to Heroku in general, see our Getting Started guides before setting up Heroku Connect.
Heroku Connect provides a pure data integration. It syncs only object and table data. You can decide which objects sync as read-only or as read-write. This architecture is useful in many scenarios where you want a Heroku application to store or manipulate the data. If you’re building a Heroku app or already have data in Heroku Postgres, then Heroku Connect is a good fit for your Heroku to Salesforce integration.
For example, one or more Salesforce orgs can sync to the same Heroku Postgres database. Your Heroku app can pull from the Postgres database to perform analytics, invoice generation, lookups with other services, and so on. The output of these actions can modify or generate Postgres database rows which sync back to Salesforce.
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 isn’t available in versions before Salesforce API v39 so use at least v39 with Heroku Connect. See Supported Salesforce Objects for more info.
New Heroku Connect add-ons default to the current major release version of the Salesforce API. You can also specify the API version at connection creation.
Setting Up Heroku Connect
Heroku Connect can only be used with Salesforce editions that have API access. Some Salesforce plan types, including trial versions, don’t have API access by default and can’t be used with Heroku Connect.
Heroku Connect instances are located in the same region as the application that they’re attached to.
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. See the Available plans section and contact sales for more details.
Quick Start Guides
See setup instructions using the tool of your choice:
- Quick Start: Heroku Connect: This guide helps you set up Heroku Connect via the dashboard.
- Quick Start: Heroku Connect CLI: This guide helps you set up using the Heroku Connect CLI plugin.
- Quick Start: Heroku Connect API: This guide helps you set up using the Heroku Connect API.
Setup Recommendations and Considerations
- Although you can use a smaller plan with Heroku Connect, it’s strongly recommended to 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.
- 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.
- After authenticating to an org, you can’t change it at a later date: see Salesforce organizations for more information.
- After selecting the Salesforce API version you want Heroku Connect to use during setup, the API version can’t be changed. Create a new instance using a different API version to change it at a later date.
- It’s recommended to leave your Heroku Postgres database times in the UTC timezone. Heroku Connect expects the UTC timezone to operate properly.
- Use a dedicated integration user for Heroku Connect with sufficient permissions for sync. For example, the most permissive option is to make the integration user a System Administrator. Both the user and the Salesforce org must have the
API Enabledpermission granted. To ensure optimal performance, grant the
View All Dataand
Modify All Datapermissions in Salesforce. Without the
View All Datapermission, Salesforce checks permissions for each row individually, which precludes use of indices and results in greatly reduced performance. For larger connections, the lack of
View All Datacan also result in
OPERATION_TOO_LARGEerrors that cause sync to fail altogether.
When the integration user’s password changes or expires in Salesforce, it doesn’t affect the session or refresh token that Heroku Connect is using. It doesn’t cause connections to become unauthorized.
Factors that affect sync performance:
- Object size (mapping many columns)
- High volumes of changes on either side (Salesforce or database)
- Using an ORM that ‘touches’ or saves nonexistent changes to records
- Overall database load
Sync performance varies widely from one connection to another. The best way to determine performance is testing with a production Salesforce org and a production database plan. See Optimizing Heroku Connect Performance for more info.
The Heroku Connect Dashboard
Heroku Connect comes with its own dashboard to configure, monitor and troubleshoot your connection. See The Heroku Connect Dashboard for more info.
You authenticate to a Salesforce org as part of the configuration process for Heroku Connect.
When you authenticate Heroku Connect to an org, the mappings you create are specific to that org. 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’s not possible to reauthenticate an existing Heroku Connect connection to a different Salesforce org.
Sandbox orgs can be periodically refreshed: this involves creating a new snapshot of data from the production org and, at the point of activation, replaces the current sandbox with a new org.
To sync data from a new production or a refreshed sandbox org, see Managing Heroku Connect Sync and Connections.
Login IP Restrictions
If your Salesforce org has org-wide or profile-based IP restrictions, you must extend your range of allowed IP addresses to include Heroku Connect. Connect runs inside its own Private Space and you can add these IPs to your allowed list in Salesforce.
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 org. 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, avoid enabling this setting.
Heroku announces changes made to these IP addresses in the Changelog. Subscribe to the changelog to get notifications of these changes.
Heroku Connect observes Salesforce secure practices by storing an OAuth token which can be revoked at any time by the Salesforce admin. Heroku Connect automatically refreshes the access token in Salesforce when the token expires.
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 isn’t 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. This plan meets HIPAA data processor requirements. To provision this plan, you must have both a Shield Private Space and Shield Postgres provisioned and a contractual entitlement in place. To enable access to Shield Connect, work with your account representative.
You can choose the Shield plan when adding a Heroku Connect add-on via the Heroku Dashboard. You can also provision it via the CLI:
heroku addons:create herokuconnect:shield -a your_app_name
Note that the standard Heroku Connect plan can’t be provisioned inside of a Shield Private Space.
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’s 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. Heroku Postgres performance typically begins degrading when there are around 50 schemas in one database.
It’s 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 reauthorization into Salesforce, which will repeatedly pause synchronization.
When multiple Heroku Connect add-ons exist it’s 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’ll 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’ll 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’re using a paid plan.
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’re 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’ll 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 are dropped from your Postgres database when removing the add-on. Ensure you have an up-to-date backup of your database before proceeding.
When you remove your add-on, we try to
DROP SCHEMA for your connection schema. The schema isn’t 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 must specify the globally unique identifier assigned to the add-on you wish to remove when using the CLI. For example
- 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 after the review app has been created.
- Heroku Connect creates functions in the
publicschema of your database in order to 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 can’t find
get_xmlbinaryor other shared functions.
- Foreign data wrappers can’t 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.
- By default, when Heroku Connect writes data to Salesforce, assignment rules aren’t run. If you’d like to enable your default assignment rules for Leads and Cases, create a support ticket. If you have multiple connections, be sure to mention them so that they can enable the setting for each one.
What Happens If You Delete Your Application
Heroku Connect is an application-specific add-on. You can’t share the add-on across applications. When you delete the application, it also deletes the add-on and the associated data from the database. If the Heroku Postgres database used by Heroku Connect is attached to other applications, then the database remains when you delete the application. However, deleting the app still removes the mapped tables used by Connect from the database.
All Heroku Connect support and runtime issues should be submitted via one of the Heroku Support channels.