Last updated June 20, 2025

Each Heroku Connect add-on is configured to connect to a single Heroku Postgres database and a single Salesforce org. This article covers how to manage your sync and connections.

Configuring a Connection

See the Quick Start: Heroku Connect to configure your connection.

Pause a Connection

When performing certain tasks, such as upgrading your database, you can pause synchronization activity in Heroku Connect.

To pause synchronization:

1. Open the Heroku Connect dashboard.
2. Select the Settings tab.
3. Select Manage Connection. 4.Selectk the Pause button.

Heroku Connect completes any pending operations before entering the paused state. When paused, changes to data in the database are still added to the trigger log. There’s no polling for changes made in Salesforce. Push Topic notifications from Salesforce for mappings using the streaming mode are also ignored.

Resume a Connection

Any changes made to data in the Heroku Postgres database or in Salesforce while it was paused automatically syncs upon resuming the connection.

To resume synchronization:

1. Open the Heroku Connect dashboard.
2. Select the Settings tab.
3. Select Manage Connection.
4. Select Resume.

Heroku Connect continues where it left off by processing trigger log entries to push changes to Salesforce. It also retrieves changes made in Salesforce using polling, including mappings that normally use the Streaming API.

Recreating a Connection After a Sandbox Refresh

If you reloaded a sandbox organization, you must delete your existing connection and recreate it. You must manually configure these settings in the sandbox org:

• Collaborators and their notifications settings
• Beta features
• The Write Algorithm
• The Salesforce API version

To automate the rest of the recreation, follow these instructions for the Heroku CLI or the Heroku Connect Dashboard.

CLI

From the Heroku CLI:

1. Export your Heroku Connect configuration with:

   $ heroku connect:export -a appname herokuconnect-resource-name
   

2. If you have any read or write mappings, make sure you aren’t writing any new data to those tables. Also, make sure all the mappings are in DATA_SYNCED to ensure all your data is present in Salesforce. To stop activity on the connection, run:

   $ heroku connect:pause -a appname herokuconnect-resource-name
   

3. Destroy the Heroku Connect add-on with:

   $ heroku addons:destroy -a appname herokuconnect-resource-name
   

4. Create a new Heroku Connect add-on with:

   $ heroku addons:create herokuconnect
   

5. Authenticate your add-on with the following command and login with your Salesforce credentials:

   $ heroku connect:sf:auth -a appname herokuconnect-resource-name
   

6. Import the mapping configuration you exported from step one with:

   $ heroku connect:export mapping_file.json -a appname herokuconnect-resource-name
   

Dashboard

From the Heroku Connect Dashboard:

1. Export your Heroku Connect configuration from the Settings tab.

   a. Select Import/Export Configuration, then Export, and Export again in the confirmation window to download the JSON file.

2. If you have any read or write mappings, make sure you aren’t writing any new data to those tables. Also, make sure all the mappings are in DATA_SYNCED to ensure all your data is present in Salesforce. From the Settings tab, click Manage Connection, and then Pause to stop activity on the connection.

3. Destroy the Heroku Connect add-on from the Resources tab on Heroku Dashboard. Select the actions button (three vertically-stacked dots) on the add-on’s to open the menu. Then select Delete Add-on.

4. Create a new Heroku Connect add-on from the Resources tab on Heroku Dashboard. Search for and add the Heroku Connect add-on.

5. Authenticate your add-on by opening the Heroku Connect Dashboard and select Setup Connection.

   a. Select the Heroku Postgres database and schema to connect to your add-on, and click Next.

   b. Select the Salesforce org type and API version for your connection and select Authorize to log in with your Salesforce credentials.

6. Import the mapping configuration you exported from step one from the Settings tab.

   a. Select Import/Export Configuration, then Import.

   b. Select Choose File and select the file to upload, and then select Upload.

Select the Write Algorithm For Your Connection

Select the algorithm Heroku Connect uses when writing data to Salesforce. The same algorithm is used for all read-write mappings. See Write Algorithms for more info.

1. Open the Heroku Connect dashboard.
2. Select the Settings tab.
3. Select Manage Connection.
4. Scroll down to the Write Algorithm section and select your choice.

Recover Synchronization After an Error

1. Open the Heroku Connect dashboard.
2. Select the Settings tab.
3. Select Manage Connection.
4. Select Recover From Error to clear out an unexpected error state and resume synchronization. See Heroku Connect Log Messages and Common Errors for more info.

Recover Synchronization After a Database Rollback

Heroku Connect uses a high-water mark methodology. Rolling back a synced Heroku Postgres database causes inconsistent data. Reload mappings after a database rollback to recover data consistency.

Changing Field Definitions in Salesforce

Heroku Connect doesn’t automatically change the table schema in PostgreSQL after you’ve changed the corresponding field definition in Salesforce. Attempts to automatically change the field can result in data loss or corruption. See Changing Field Definitions in Salesforce for more info.

Connection Configuration Audit Trail

Heroku Connect keeps a record of administrative changes to your connection’s configuration. Click Download Audit Trail to export to CSV. See Audit Messages for more info.