Last updated 19 May 2017
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 applications that interact with your Salesforce data using your favorite tools, including all languages and frameworks supported by Heroku.
This article describes the process for provisioning Heroku Connect.
If you are just getting started with Heroku Connect, also see this step-by-step tutorial for deploying an application.
If you are familiar with Heroku Connect basics, see the Heroku Connect category page for advanced topics.
Provisioning the add-on
Heroku Connect can only be used with Salesforce editions that have API access. Some plan types, including trial versions, do not have API access by default and cannot be used with Heroku Connect.
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.
If your app is in a Private Space other than US/Virginia new Connections will be placed in a Heroku Connect Beta for that region. You will need to do this provision via the Heroku CLI so you can explicitly acknowledge that your Connection is being created in a Heroku Connect Beta region.
There are two 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:
danketsu: This is the paid plan that you will use after purchasing Heroku Connect. If you have existing add-ons using the demo plan they will be automatically upgraded to danketsu if you are entitled to use it. Even if you provision a ‘demo’ plan, it will automatically upgrade to danketsu if you are entitled to use the higher plan level.
The danketsu plan will appear as 'free’ in the add-ons list for your application in the Heroku Connect dashboard. You should verify that the plan name is danketsu if you wish to ensure that you are using the paid plan.
Please contact sales for more information on the Heroku Connect danketsu plan.
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
If you have purchased Heroku Connect you can specify the
danketsu plan when adding the add-on to your application using:
$ heroku addons:create herokuconnect:danketsu
Heroku Connect instances are located in the same region as the application that they are attached to.
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 all 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.
Please carefully consider the overall architecture of any solution which employs a Heroku Connect, Heroku Postgres, and Salesforce org distributed across divergent geographic locations. Network latency can become a factor in service performance.
Although it is possible to use a hobby tier database with Heroku Connect it is strongly recommended that you use a standard tier Heroku Postgres database or premium tier Heroku Postgres database. Hobby tier databases have limited row and connection counts that can be consumed quickly if you configure multiple mappings in Heroku Connect.
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 setup 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).
Heroku Connect typically requires View All Data permission 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. This can make many of Connect’s operations much slower. For larger connections, it 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.
Multiple add-ons per application
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 may also be desirable to use multiple add-ons per application, each with their own dedicated and distinct integration user to the same Salesforce org, if your intended sync pattern is to sync hundreds of objects from a single org into a single Postgres database. There are concurrency limits on long running SOAP queries for a single user which can slow sync if a single integration user is employed for hundreds of objects, or conflict with other operations the same integration user identity is likewise performing.
Using a different database schema name for each organization allows a single Heroku Postgres database to be used with multiple Heroku Connect add-ons.
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
When using multiple Heroku Connect add-ons, it is strongly recommended to use a distinct integration user per add-on. 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.
Upgrading the add-on plan
You can upgrade from the free
demo to the paid
danketsu plan using the Edit plan option in the Heroku Dashboard or using the CLI, assuming you are operating inside a Heroku organization with a paid plan entitlement:
$ heroku addons:upgrade herokuconnect:danketsu 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:danketsu... done, (free) 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:danketsu Changing herokuconnect-gladly-8321 plan to herokuconnect:danketsu... done, (free) Plan change successful
The Heroku Connect dashboard
The Heroku Connect dashboard allows you to configure, monitor and troubleshoot your mappings.
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.
The Overview tab allows you to get a real-time overview of your mappings as well as providing links to create new and edit existing mappings.
There is also a chart showing the number of rows written to Salesforce in blue at the top and the number of rows read from Salesforce in purple at the bottom. The number of errors for reads and writes are also shown in orange on each chart. You can highlight a data point to see the specific number of rows and errors and you can change the time period shown using the drop-down list to the top-right of the chart.
The Logs tab allows you to view detailed information about the synchronization operations being performed by Heroku Connect. You can filter by mapped object, log type and detail and by date.
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
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.
The Settings tab contains a drop-down list where you can choose:
From here you can Pause or Resume the connection, view your plan type, view the list of users with access to the dashboard, check for orphaned mappings, enable Logplex logging, enable the event log and delete the connection.
This 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.
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.
Creating a mapping
To create a new mapping:
Click the Create Mapping button on the Overview tab of the Heroku Connect dashboard.
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 that do not support bulk paging. For example
KnowledgeArticleVersionrequires the use of additional query criteria,
PublishStatus=Onlineand therefore cannot currently be mapped in Heroku Connect. 'LeadHistory’ does not support Bulk Paging, and thus cannot be retrieved via the API once the number of records exceeds 20,000, unless the fallback Heroku Connect attempts to retrieve all records in a single batch succeeds per Force.com requirements. 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.
You will now be able to choose the synchronization mode 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
SystemModStamp) as they are required for Heroku Connect to perform synchronization.
It is recommended that certain fields, such as
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.
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:
- Click on the object name in the Mappings list on the Overview tab of the Heroku Connect dashboard.
- On the mapping detail page click the Edit button.
- You will now be able to edit the synchronization mode as well as adding and removing fields from the mapping.
- 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.
Mappings are read-only by default: Heroku Connect will poll your Salesforce organization for changes and synchronize them to your database; however, changes made in your database will not be synchronized back to Salesforce.
To enable changes made in your database to synchronized back to your Salesforce organization tick the box in the Database → Salesforce section of the create/edit mapping page.
Heroku Connect will poll your database for updates every 2 minutes. If updates are detected, Heroku Connect will begin to write changes back to Salesforce. Heroku Connect will not poll for additional database updates while the write operation to Salesforce is underway; write operations are executed in serial across all mappings in chronological order.
Once a given write operation is completed, the poll cycle begins again every 2 minutes. In addition to the 2-minute poll, your database will also attempt to detect new or updated records and notify Connect to initiate a poll using
pg_notify. This notification will happen at most every 10 seconds. These intervals are not configurable.
By default Heroku Connect will poll your Salesforce organization for changes every 10 minutes. You can configure the polling interval from two minutes (10 minutes in the demo plan) to 60 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.
Streaming mode makes use of the Streaming API to notify Heroku Connect when data changes in your mapped objects. Heroku Connect makes use of these notifications to trigger polling, however it does not rely on the notifications to determine what data has changed, instead it uses the same method as polling mode. You can think of streaming mode as 'polling on demand’ whereas polling mode is 'polling at a fixed interval’.
Streaming mode is available for all custom objects and many standard objects: for those objects that do not support streaming you will not be able to select this mode when creating or editing a mapping.
In order to reduce API utilization Heroku Connect will not poll for changes more often than once every 10 seconds regardless of the number of notifications received. In addition if no notifications are received within the configured polling interval then Heroku Connect will automatically poll for changes: this is to ensure that your mappings remain in sync even if notifications fail to be received.
Heroku Connect read-write mappings work best when they have a unique external ID specified as a part of the mapping configuration. Because separate threads are utilized 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 back the Salesforce ID for those same records. Specifying an external ID allows allows Heroku Connect to match changes coming back from Salesforce to those changes originating in your Heroku Postgres database. You can also reference the newly inserted row from a foreign table by this external id (see: Relationships between objects).
Heroku Connect allows you to specify a unique external ID via the Upsert Field setting of the mapping configuration. When this setting is configured, Heroku Connect matches records coming from Salesforce by either by Salesforce ID (if available) or the specified Unique External ID if a record matches the External ID and the Salesforce ID is NULL. This ensures that no matter which process attempts to write the SFID of the record first, there are no Integrity Errors and the record is always matched.
The External ID values should not be changed as this could lead to a lack of parity in the data synced between your database and Salesforce.
There are a 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. Lastly, 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.
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 Settings tab, choose Import/Export Configuration, click the Export button and then on the confirmation page click Export to download the file.
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 your region:
220.127.116.11, 18.104.22.168, 22.214.171.124, 126.96.36.199
188.8.131.52, 184.108.40.206, 220.127.116.11, 18.104.22.168
22.214.171.124, 126.96.36.199, 188.8.131.52, 184.108.40.206
220.127.116.11, 18.104.22.168, 22.214.171.124, 126.96.36.199
188.8.131.52, 184.108.40.206, 220.127.116.11, 18.104.22.168
22.214.171.124, 126.96.36.199, 188.8.131.52, 184.108.40.206
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 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.
Heroku Connect does not store data in flight.
More information on Heroku security can be found here.
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.
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.
$ 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 Removing vars for HEROKUCONNECT from sleepy-ocean-5276 and restarting... done, v88
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.
All Heroku Connect support and runtime issues should be submitted via one of the Heroku Support channels.