Heroku Connect

Last Updated: 07 May 2015

Table of Contents

Heroku Connect is an add-on that synchronizes data between a Salesforce org and a Heroku Postgres database. Using Heroku Connect with Heroku Postgres, you can build apps that interact with your Salesforce data using your favorite language or web framework like Rails, Django, Node.js, Play or PHP.

Provision the free demo edition plan from the Heroku Connect addons page, via Heroku Button, or via the CLI using heroku addons:create herokuconnect:demo. Contact sales regarding access to the commercial plan.

How Heroku Connect works

Heroku Connect operates by synchronizing data between all records of a standard or custom Salesforce object and a Heroku Postgres database table using the identical schema. The schema is defined by the Salesforce system.

Heroku Connect creates each database table on demand as an exact replica of the Salesforce object. Table and column names are the same between Salesforce and the database, except the database uses only lower-case letters. Whenever data changes in Salesforce, those changes are applied to the relational table. Similarly, any changes made to data in the relational table may be synchronized to Salesforce.

Heroku Connect uses SysModStamp to detect changes to Salesforce objects selected for synchronization from Salesforce to the database. Heroku Connect uses database triggers to record changes to be sent from the database to Salesforce.

Heroku Connect implements a “last writer wins” scheme where the latest update on either side is propagated to the other. All Salesforce changes will be written to the database. All updates to the database will be written back to Salesforce subject to user permissions and validation rules in effect within Salesforce.

Heroku Connect does not support in­flight transformations. Instead, data transformations can be performed inside the relational database using standard SQL or via any application which can connect to the Heroku Postgres database.

When a record is updated in the database, only the modified columns of that row are updated in Salesforce. This helps to prevent update conflicts in cases where the columns updated by Heroku Connect are distinct from those fields typically updated in Salesforce.

Provisioning the add-on

Verified Heroku user accounts can use a simple Heroku button to create an app, database, and Heroku Connect instance in their accounts with a single click deployment. Or attach Heroku Connect to an existing Heroku app via the Heroku Addons Marketplace or the CLI.

For the demo edition of Heroku Connect:

$ heroku addons:create herokuconnect:demo -a appname
-----> Adding herokuconnect:demo to sleepy-ocean-5276... done, v5 (free)

For the commercial plan:

$ heroku addons:create herokuconnect:danketsu -a appname
-----> Adding herokuconnect:danketsu to sleepy-ocean-5276... done, v5 (free)

Using the command heroku addons:create herokuconnect without specifying a plan name will provision the herokuconnect:demo plan, with a 10,000 row sync limit; users with commercial entitlements will automatically be upgraded to the commercial plan. Or upgrade from herokuconnect:demo to herokuconnect:danketsu manually via the CLI:

$ heroku addons:upgrade herokuconnect -a sleepy-ocean-5276
Upgrading to herokuconnect on sleepy-ocean-5276... done, v5 (free)
Plan change successful
Use `heroku addons:docs herokuconnect` to view documentation.

If you attach Heroku Connect to an app, you will need a Postgres database attached to the same app to act as a target for Heroku Connect before you can complete setup. Visit Heroku Postgres for information on creating a new database.

Heroku Connect instances are located in the same region as the app they are attached to, US or EU. Once Heroku Connect has been added, you can complete the provisioning process by navigating to the Heroku Connect add-on from the Heroku UI, or by opening it in a browser from the CLI:

$ heroku addons:open herokuconnect -a appname

To complete configuration of Heroku Connect, follow these steps:

  1. Choose the DATABASE_URL or specify another Heroku Postgres database attached to the app from the menu options. If there are no matches found, you’ll need to attach a database to the Heroku app prior to completing the Heroku Connect setup process.
  2. Choose a new, unique schema name to hold the synchronized tables. The default schema is salesforce. You may elect to put your tables in an existing schema, including the default public schema, as long as that schema is empty.
  3. Complete the database setup process.
  4. Authenticate to the Salesforce org. Heroku Connect will possess the same read / write entitlements as the authenticating user.

    It is recommended that you use a dedicated Integration User for Heroku Connect whose Read/Write permissions are calibrated to the degree of access required for successful synchronization. Some API optimizations for dealing with large Salesforce tables are not available without the View All Data permission, or View All Data permission for a particular object. Creating and authenticating a dedicated Heroku Connect Integration User with a System Administrator is the most permissive option, but may not be required.

  5. Choose one or more Salesforce objects to synchronize.

  6. If you plan on running the Heroku Connect demo Rails app, please map your Account and Contact objects.

By default your connections will read data from SF -> DB. DB -> SF will not be automatically enabled, nor automatically queued for write. If you want to make changes to your Salesforce data you must first enable DB -> SF via the Heroku Connect application.

Once initial setup is complete, the HEROKUCONNECT_URL and HEROKUCONNECT_SCHEMA values will be available in your app’s config vars. They contain the connection information for the synchronized database. It is recommended that your application code connect to the synchronized database by consulting these variables at runtime.

$ heroku config:get HEROKUCONNECT_URL
$ heroku config:get HEROKUCONNECT_SCHEMA

Mapping objects

Once you have authenticated to your Salesforce org you can start mapping objects. Note that read sync operations SF -> DB involving more than 20,000 records for an object may require the authenticating user to possess the “View All Data” permission for the mapped object, and “API Enabled” permissions for that SFDC org. A System Administrator role will automatically enable both.

Click the Create Mapping button from the Overview screen.

The list of objects defined in your Salesforce organization will be displayed.Select an object from the list and click Next. Now the list of fields defined for the object will be displayed. You can choose which fields you want to synchronize to the database.

Heroku Connect supports all standard and custom objects except those that are not queryable via the API, or which require the use of object specific filter criteria to retrieve results. KnowledgeArticleVersion is an example of an object that requires the use of additional query criteria, “PublishStatus=Online”, and thus is not currently supported in Heroku Connect.

Pre-selected fields in the list are required to enable synchronization and may not be deselected. Once you click Save, Heroku Connect will immediately build a table corresponding to the Salesforce object in your database, query for all records from Salesforce and insert them into the database.

Navigate to the Overview tab to monitor the synchronization progress. You can click on an object row to open a detailed log of activity. Select Debug to see an expanded view of the activity log.

Synchronization frequency

By default, Heroku Connect requests updates from Salesforce (reads) via polls every 10 minutes. Users may set polling frequency to any interval between 2 and 60 minutes when creating a mapping, and may change this frequency at any time. Shorter polling intervals may result in higher API utilization. Higher polling intervals will reduce API utilization.

The recommended synchronization mode from Salesforce to Heroku Postgres is Event Driven for those objects that support Streaming API connections. Streaming API connections are available for all custom objects and many frequently used standard objects such as Account, Contact, Case, Campaign, Lead and Opportunity. Some standard objects, such as ContractLineItem, or Tasks that are created or updated using the Lead Conversion method, do not have Push Topics available. Additional information about Push Topics may be found in the Force.com Streaming API Developer’s Guide: http://www.salesforce.com/us/developer/docs/api_streaming/api_streaming.pdf

If the object is not eligible for Push Topic creation, the user will be given polling configuration options for the mapping. If Event driven mode is available for an object and the user saves the mapping in Event Driven mode, Heroku Connect will create a Push Topic with a name that looks like this: HC_123. This naming convention can help users identify which Push Topics in a given Salesforce deployment are in use by Heroku Connect.

Push Topics notify Heroku Connect of change events, triggering polls to Force.com on event. The polling rate does not exceed once every 10 seconds. Minimum sync latency for any object is 10 seconds. Heroku Connect destroys the Push Topics it creates when a user changes from Event driven to Polling mode, or deletes the relevant mapping entirely.

Heroku Connect will proactively poll every 10 minutes for objects in Event driven mode that have not received a event during the last 10 minutes.

By default, Heroku Connect instances in Read/Write mode poll for database changes (writes) every 10 seconds.

Heroku Connect and Salesforce API consumption

Heroku Connect employs a large set of best practices and heuristics to optimize interaction with the Salesforce APIs. The most efficient transfer mechanism (SOAP or Bulk) is automatically chosen based on data change volume, and many subtle details of Salesforce API operation are automatically handled by the system. By moving data in batches and employing the Bulk API, Heroku Connect provides the most efficient use of Salesforce API calls. The net result is to remove the burden of Salesforce API knowledge from the Heroku Connect customer and their application code.

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.

As a general guideline, Heroku Connect users should expect Heroku Connect to use a few hundred API calls per day per bi-directionally synchronized SFDC object, depending on sync settings and data change volumes. An estimate of Force.com API usage for read operations is provided per mapping in the Heroku Connect UI for planning purposes.

Sync operations of >100M records per table, or where data change volumes exceed 100M records/ day, may require Bulk API calls, as Heroku Connect reads records from tables in batches of 250K per API call when batch sizes exceed 20,000 records per request.

Force.com API calls used by Heroku Connect do count against a customer org’s API limits. However, Heroku Connect manages API usage to keep net Force.com API utilization at 10,000 Force.com API calls per mapping, pooled across read and write operations over a rolling 24 hour period, unless the customer specifically requests a different default. Customers with very high data change volumes, in the hundreds of millions of records per day range, may find that requesting a different default improves sync frequency.

API utilization for writes will vary as a result of write volumes. Heroku Connect groups operations of the same type into batches. Maximum batch size for operations of the same type is 200 records; so the minimum number of API calls needed for a 10,000 record batch is 50.

The initial synch of a single object with over 20K records will use Bulk, not SOAP, API calls. Initial load of an object of ~5M records typically takes 15 minutes to complete and uses 20 calls. Initial load of an object with ~250M rows can take 4 hours or more.

How Salesforce objects map to Postgres database tables

The database created by Heroku Connect obeys the following rules:

  1. All tables are created in the schema specified during setup
  2. Tables use the same name as the Salesforce object, except with all lower-case letters
  3. Columns use the same name as the corresponding Salesforce field, except with all lower-case letters
  4. Each database table defines a native, unique, auto-increment integer primary key column named id
  5. The Saleforce Id field is renamed as sfid in the database table
  6. A unique index is defined on the sfid column

Heroku Connect does not support untyped or compound fields, such as Address.

The following table shows how Salesforce data types are represented in the Postgres database schema.

Salesforce Type Postgres Type Notes
ID varchar (18) Postgres column name is ‘sfid’. An index is created on this column
Boolean boolean
Number double precision
Date date
Timestamp timestamp Timestamps are stored in UTC timezone
Longtext text
Geolocation double Must synchronize latitude and longitude fields separately

Heroku Connect also creates several tables within the schema. The “_trigger_last_id” and “_trigger_log” tables are created on switch to read/write mode. These tables should be reserved for the exclusive use of the Heroku Connect application.

Resolving read errors

Heroku Connect requires “View All Data” permissions, or “View all Data” scoped to the mapped objects, for optimal operation. For SFDC orgs with large record sets, some operations may not be possible without those permissions. The system will notify the owner of the Heroku Connect instance if an operation requiring those permissions fails without them.

Heroku Connect supports read of all standard and custom objects. Knowledge Base objects, and standard or custom objects requiring special API handling or without required attributes such as SystemModStamp are not mappable. Heroku Connect attempts to detect and suppress these unmappable objects from presentation in the UI.

  1. If Heroku Connect cannot query for a mapped object, this error or similar will display in the logs: ‘INVALID_TYPE_FOR_OPERATION…’

  2. If Heroku Connect cannot map an object because it requires object specific filters, this error or similar will display in the logs: ‘MALFORMED_QUERY…’

  3. If Heroku Connect cannot map an object because it lacks a required attribute, this error or similar will display in the logs: ‘Cannot poll changes for table ’>fieldname<‘ because it contains neither…’

Remove the ineligible object or field from the mapping to resolve these errors.

Accessing the synchronized tables

Connect to the database via the same credentials that you provided during setup. The synchronized tables will appear in the schema you specified at setup. By default this schema will be named salesforce. To query a table, qualify the table name with the schema name:

select * from salesforce.account;

If you are using the psql command line client, you can set your search path for easier reference to your tables:

set search_path=salesforce.public;

Updating data in Salesforce

By default your database will be in Read Only mode. Changes to the database will synchronize only after a switch to Read/Write mode. Go to the Salesforce tab to switch state from Read Only to Read/Write. When you do this, database triggers will be added to each of your database tables. These triggers will record all operations into the special table _trigger_log. Those changes will be detected by Heroku Connect and sent back to Salesforce.

To update Salesforce records, just execute any UPDATE table (cols) values (vals) statement against your database. Updates will be sent to Salesforce. Inserting records directly into the _trigger_log table is not supported.

Updates to Salesforce via Heroku Connect are attempted once. Each attempt to update a record may end in one of these states: SUCCESSFUL, IGNORED, or FAILED. Ignored and Failed updates to Salesforce are retained in the Heroku Postgres _trigger_log table. Successful updates may be truncated from the _trigger_log table. The ‘_trigger_log’ table is automatically archived by Heroku Connect.

Inserting records to Salesforce

To insert new records to Salesforce, just insert rows in your database tables. Note that the native Salesforce key (the 18 character Salesforce Id column) will be updated on your new row after the insert operation is complete.

Heroku Connect does not support Salesforce upsert operations. If you insert a record, such as a Contact, into Postgres, and then update that record before the insert is sent to Salesforce, Heroku Connect will:

  1. Merge updates that reference the same record id, if there is no sfId
  2. Combine values and send to SFDC as a single INSERT. The most recent value for any given field will persist
  3. This also works for DELETE, so that if you delete the record then it will never be sent to SF at all
  4. One caveat is that a record that has been through a merge prior to insertion into SFDC will not trigger any workflow in SFDC based on an intermediate state that was not written to SFDC. An example would be a Lead that first existed in a “New” state in the DB, and was “Converted” in the database before being inserted as “New,” would be inserted as “Lead” that is “Converted” in SFDC without ever having passed through the “New” stage in SFDC.

After the initial insert has completed, and the SFID has been returned and associated with the record in the database, subsequent updates to that database record will be treated as updates to Salesforce.

In the case of Person Account objects, there may be additional fields that require specification.

Heroku Connect does not provide a mechanism for validating field level updates against picklist values. Heroku Connect does not provide Metadata API support.

Inserting Records with Master/ Detail Relationships Using External IDs

Heroku Connect supports use of external IDs to manage relationships between objects. To use this method, your master object should define an External ID field in its Salesforce configuration. When you map the detail object in Heroku Connect, the related external ID field for the master object will be shown at the bottom of the field list. Map the related external ID field to parent the detail to the master.

Now when you insert rows into the detail table, you should provide the external ID value for the related master record to link the detail to the master.

A common example of this pattern is creating an Account record for a company and a related Contact record for a user at the same time, where the Account is the parent of the Contact and no SFID is available for either at time of insertion.

An example of how to create and link related records without reference to an SFID:

  1. Start with an SFDC org with Account and Contacts where Contacts are detail records on Accounts
  2. Create a custom field in Salesforce on Account, called ExternalID__c
  3. Map the Account object in Heroku Connect, including ExternalID__c
  4. Map the Contact object in Heroku Connect. At the bottom of the list of mappable fields, there will be a field called Account__ExternalID__c available because of the relationship between the Account and Contact objects. Map Account_ExternalID__c for Contact.
  5. Switching to the Heroku Connect database: Insert a record into the master record, Account, with a unique value for ExternalID__c
  6. Insert a record into Contact with the same unique value for Account__ExternalID__c

When the Account and Contact records are inserted into the SFDC org via Heroku Connect, an SFID will be returned and populated for each item in the database. The Contact will appear as a detail on the Account. The Account will appear as the master of the Contact.

Heroku Connect reorders inserts within a batch to enable insertion of records with these master-detail relationships. For example, if you are inserting records of type Accounts and type Contacts to SFDC via Heroku Connect, both with an identical timestamp for record time creation within Postgres, insertion will be executed by Heroku Connect in this way:

  1. Heroku Connect batches together inserts for the master object
  2. Heroku Connect attempts to write all master object inserts
  3. Heroku Connect attempts to write all detail objects inserts
  4. Within each object type, order of insertion is set by LastModifiedTimestamp.

Please note that at this time there are a few special objects for which this method of parenting a record is not supported. Task is one such object.

Resolving write errors

Database updates may fail to be propagated to Salesforce in the case that a record insert or update fails due to a Salesforce validation error or due to lack of write permission for the authenticating user.

In this case the error state and message are recorded in the database and reported through the Heroku Connect web application under the Salesforce tab.

To review errors for a given object, select the object and review the Logs. Your application should include logic to apply a corrected update or to delete the insert.

A common write error is the attempt to update a value for a readable, but non writeable per Salesforce validation rules, field. An example: Contact’s “Name” where “Name” is a compilation “First Name” and “Last Name” values. “First Name” and “Last Name” are the writable values. “Name” is a display value.

Schema changes

Changes to object schema coming from Salesforce are considered an exceptional event. User intervention will be required if schema changes impact an existing mapping. If a field mapped in Heroku Connect is removed from Salesforce, Heroku Connect will fall into an error state until the field is removed from the mapping. The corresponding column in the database will be dropped and synchronization may proceed.

Additive changes will not impact Heroku Connect. If a new field is added to Salesforce, simply update the Heroku Connect configuration and save if you wish to synchronize it. The corresponding column is created in the database and the missing data is queried from Salesforce and updated in the database.

Pausing Heroku Connect

You can tell Heroku Connect to temporarily stop synchronization. Navigate to the Settings tab, Manage Connection and select Pause. Heroku Connect will complete any pending operations before suspending polling operations. Some changes to overall setup may require a pause, such as a upgrading the database.

Import and export of configuration files

Heroku Connect supports the import/export of .yaml files for Salesforce mapping configurations. Navigate to the Settings tab and choose Import/Export Configuration to expose import/export options. This functionality is very useful for mirroring Sandbox/Production setups that must match configuration precisely.

Upgrading your database

Heroku Connect operates continuously on a single database, which requires a few steps in order to upgrade that database and allow sync operations to continue as expected. The upgrade itself is done using a follower database, and these instructions illustrate how Heroku Connect fits into that process.

These steps ensure that the new database is an exact copy of your current database. Heroku Connect will not create tables or transfer data to an empty database, so be sure to follow the proper upgrade process.

  1. Create your follower database and allow it to get mostly caught up with your lead database. This will minimize the amount of downtime required for the upgrade.

  2. Pause your connection for the same reason that you put your app into maintenance mode, to prevent Heroku Connect from trying to write to your database during the upgrade.

  3. Wait for your follower to catch up. Now that Heroku Connect and your application have both stopped writing to your database, the follower can get completely caught up. You can check its status using heroku pg:info.

  4. Promote the follower to become the new lead database. This will make it accessible as DATABASE_URL.

  5. Resume Heroku Connect using the same process used to pause it in step 2, and bring your application out of maintenance mode. Heroku Connect will automatically pick up the new DATABASE_URL for your application and resume synchronization using the new database.

If you’re upgrading from a hobby database, you won’t be able to create a follower. Instead, use the PG Copy process instead to copy data into the new database. Simply pause Heroku Connect at the same time as you put your app into maintenance mode, and resume it again when you reactivate your application.


Each Heroku Connect instance is automatically created with an owner. You can find the owner of the instance listed on the Notifications tab in the UI. This owner can be changed, but only to another Heroku user with access to the relevant Heroku app. Other users may opt into notifications on the Notifications tab, but the application requires an owner to direct system notifications to via email.

Heroku Connect sends notifications for these types of errors to the owner and other subscribed users:


Notification emails contain help for understanding and resolving any error conditions detected. Resolution emails are also sent.

Once a Heroku Connect instance has been mapped to a specific Salesforce org, it will not allow re-authentication to a different Salesforce org. Remove the Heroku Connect add-on and re-provision it to change Salesforce org.

Heroku External Objects

Heroku External Objects is currently GA as an opt-in feature on Heroku Connect. Heroku External Objects provides an oData wrapper for the Heroku Postgres database that Heroku Connect maintains a Connection for. This feature allows other web services to retrieve data from within the specified Heroku Postgres DB using RESTful endpoints generated by the wrapper.

Used in tandem with Salesforce1 Lightning Connect, the feature permits data in a Heroku PG DB to be represented in a Salesforce deployment, where it can be viewed, including viewed within Apex and Visual Force pages, searched, and related to other objects. It cannot be edited or used in standard reports; the data is available by reference.

When Heroku External Objects is enabled on a Connection, a new element will appear in the main navigation: ‘External Objects.’ Click through to access the settings page.

  1. Any user can view the endpoint for the oData enabled Heroku External Objects data source
  2. Credentials to the service can be sent or resent by any user, but will only be delivered via email to owners of the specified instance
  3. User must also select which tables within the specified source/ schema can be accessed via the service. Click to select a specific table within the schema.

All schema within the specified database will be available, including those schema not actively managed by Heroku Connect as part of the bi-directional synchronization service.


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.

For more information on Heroku security: https://www.heroku.com/policy/security

Using Heroku Connect and the demo Rails app

Download the Heroku Connect Rails demo app:

$ git clone https://github.com/heroku/herokuconnectdemo.git
$ cd herokuconnectdemo

Create a Heroku app and deploy the demo application code.

$ heroku apps:create
$ git push heroku master
$ heroku run rake db:migrate

This will automatically provision a Heroku Postgres add-on to the application.

Now add the Heroku Connect add-on, and open it to finish the provisioning process:

$ heroku addons:create herokuconnect
$ heroku addons:open herokuconnect

In the Heroku Connect application, select the DATABASE_URL for your app. Once the provision process is done, map your Contact and Account Salesforce objects.

During provisioning, the HEROKUCONNECT_URL config var will have been added to your app’s configuration. Restart the demo app, and then open it in your browser:

$ heroku ps:restart
$ heroku apps:open

The demo application does not enforce any security, which means that anyone can access the data it is showing. Don’t run the app against a Heroku Connect database which contains sensitive data.

To access your data through ActiveRecord on your local machine, you just need to configure your local environment:

$ export HEROKUCONNECT_URL=`heroku config:get HEROKUCONNECT_URL`
$ export DATABASE_URL=`heroku config:get DATABASE_URL`
$ rails console
Loading development environment (Rails 3.2.13)
> Account.count
 => 25

Customizing the sample app

The sample app contains a reusable mechanism for accessing the Heroku Connect database tables. An abstract base class is defined in salesforce_model.rb which connects to the Heroku Connect database:

class SalesforceBase < ActiveRecord::Base
  self.abstract_class = true
  establish_connection ENV['HEROKUCONNECT_URL']

And each class to access a Heroku Connect table inherits from the base class:

class Account < SalesforceBase
  self.table_name = 'account'
  has_many :contacts, :primary_key => "sfid", :foreign_key => "accountid"

Note how we related Accounts to Contacts via the sfid column. This is the actual Salesforce id. The records in the Heroku Connect database also use Rails-standard autoincrement id columns, so specifying the foreign key like this isn’t strictly necessary.

Removing Heroku Connect from your Heroku app

In the web UI, navigate to the Settings tab, Manage Connection and click the Delete Connection button. From the command line, run heroku addons:destroy herokuconnect -a appname to remove Heroku Connect from the specified app.


Why is re-authorization of Salesforce credentials required on February 15, 2015?

One of the top requests from Heroku Connect customers has been for the requests Heroku Connect makes to the Salesforce API not to count against commercial API limits or entitlements. On February 15, 2015 we are laying technical groundwork for Heroku Connect customers to receive free SOAP API calls to Salesforce. This Heroku Connect feature is tentatively scheduled for release in summer of 2015.

What this means for Heroku Connect customers:

  1. The Salesforce authorization that Heroku Connect uses to synchronize your data may expire on or after 1PM Pacific for US and 4pm GMT for EU customers on February 12, 2015 due to changes the Heroku Connect team is implementing.
  2. Once your authorization expires, Heroku Connect will not be able to automatically refresh it. Your Heroku Connect instance will automatically be paused until you re-authorize with Salesforce.
  3. We recommend you proactively re-authorize your Heroku Connect services immediately after the changes on February 12, 2015 to prevent any delay in sync attributable to a lack of valid Salesforce authorization.

To re-authorize, just visit http://connect.heroku.com and navigate to the “Salesforce” tab. Click the Authorize button to complete reauthentication.

Alt text

If you’re already using the new Heroku Connect dashboard currently in beta, click on “Manage Salesforce” in the “Settings” navigation to start the reauthentication flow.

Alt text

How does the graph work?

The blue values above the midline show the volume of reads from Salesforce relative to the volume of writes, which are shown in purple below the midline. Use the controls at the top of the graph to change the time period and granularity of the data volumes shown.

What does Restart do?

Use the Restart button located in the Manage Connection tab to attempt restart of an instance in an error state. This is a non destructive action: Heroku Connect will restart all processes from last completion time.

What does Reload do?

When you RELOAD an object, Heroku Connect repopulates the table in the Postgres DB with a fresh set of data from SFDC. All data in the Postgres table that has not been written to SFDC will be overwritten. This is a destructive action. Attempt recovery of an object in a SYSTEM ERROR state through Restart first.

I changed my Salesforce data model but I don’t see the changes in the mappings menu.

Open the Mapping to refresh the list of available fields for an object. Fields in error will be highlighted in red.

I hit “Pause” to stop synching, but some rows still synchronized- what is happening?

When you “Pause” a Heroku Connect instance, Heroku Connect will finish execution of any jobs in flight. It will not initiate any new synchronization activities such as polling for new changes from Force.com or writing DB changes to Force.com, but is already a job in flight, it will complete before the Pause kicks in.

I’m trying to map an object, but it’s grayed out in the menu. Why can’t I select it?

If an object has been recently removed, the removal operation may still be underway. Otherwise, the object may not be eligible for mapping.

Why can’t I authorize my Heroku Connect instance to a new Salesforce org?

Heroku Connect created all tables in the database from objects and fields that originated from a unique Salesforce org. Allowing users to authorize a new SFDC org into this preexisting database presents a very high chance of data conflict or corruption. Remove the add-on and reprovision to the same Heroku app, or create a new Heroku app and attach a fresh Heroku Connect add-on to it.

I refreshed by Salesforce sandbox data and now Heroku Connect wants me to reauthorize my credentials, but the reauthorization didn’t work. How do I fix this?

When you use the “Refresh” option on an existing Salesforce sandbox, and then “Activate” it, your existing sandbox including org ID are deactivated by Salesforce and a new sandbox is created, including a new org ID. Heroku Connect checks org ID when it attempts a reauthorization, so you are attempting to reauthorize to what appears to be a brand new org in the system. The best way to resolve this is to export the configuration for the old sandbox, create a new addon, and import the YAML to mimic the previous configuration.

I want to change the Salesforce org I am using Heroku Connect with, but I get an error when I try to authenticate to the new org.

Heroku Connect has two modes: single org and multi org. When you are using it in single org mode, it will only connect to the Salesforce org it was originally auth’d to. You will need to destroy the instance and add it back on to the app. When you are using it in multi org mode, it will connect to as many Salesforce orgs as you want. This multi-org mode must be turned on for you by Heroku Support; please file a ticket.

I removed the add-on but I saved my data. How do I access it?

If you removed the Heroku Connect add-on from a Heroku app, but opted to save the data in the underlying database, you may continue to access the data in the database the same way you would access data in any other Heroku Postgres database.

If I delete the Heroku app that Heroku Connect and the Heroku Postgres database were connected to, what happens to Heroku Connect? What happens to the database?

Heroku Connect will be deleted along with the Heroku app because it is an app specific add-on. The Heroku Postgres database will likewise be destroyed if it is an app-specific resource, but will not be destroyed if it is attached to other apps. However the Heroku Connect synchronization will no longer be running on it.

How do I change the address I get notifications at?

Navigate to the Account tab, enter a new owner for Heroku Connect and delete the current owner. The new owner must be an entitled user of the Heroku app. Additional users may be added to the notifications list.

I want to synch images between Salesforce and Postgres. Can Heroku Connect synch images?

Heroku Connect does not support image or file synch. If you want to manage a reference to an image in Salesforce, you can store the image on S3 or another service and synch the URI between Salesforce and Postgres.

How do I push records to SFDC that were written to the DB, but error'ed out when Heroku Connect tried to synch them back to Salesforce?

In your database, run something like this:

update _trigger_log set state = 'NEW' where state = 'FAILED' and table_name = '<your table name>';`

That will reset any error’d updates. One caveat: the trigger log is periodically trimmed, so you should check to make sure all your updates are in the _trigger_log table still.

After 30 seconds s a sweeper will run and find any “old” _trigger_log rows that are state NEW and resubmit them.

If your updates are gone from the _trigger_log and you are updating records without an SFID, then you could do the following: update any rows in your original table that have sfid column = null. You need to find some column you can update to a new value, so something like:

update contact set fax = '510-555-5555' where contact.sfid is null

This will generate a new set of updates to the _trigger_log, but in the absence of the sfId value they will be treated as inserts.


Heroku Connect does not support Deletes on OpportunityContactRole table as Salesforce does not support Isdeleted functionality on that table. Work arounds are using a custom object to replace the OpportunityContactRole table or periodically reloading that table.


All Heroku Connect support and runtime issues should be submitted via on of the Heroku Support channels. Any non-support related issues or product feedback is welcome at connect-team@heroku.com.