Last updated July 31, 2026

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. Select 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 or Change Data Capture (CDC).

Change the API Version

You can change the Salesforce API version after configuring the connection from the Heroku Connect dashboard or with the Heroku Connect CLI.

Dashboard

From the Heroku Connect dashboard:

1. On the Settings tab, select Manage Salesforce.

2. Next to the API Version, select Manage Version.

3. Select the Salesforce API version to change to in the API Version dropdown.

   Selecting a version shows a comparison of the schema on your current API version and your target API version. The table shows if there are any changes required to your schema before you can change the version. Schema issues include:

   • The length of a field increased in Salesforce in the target version. Heroku Connect automatically updates your database schema.
   • The definition of a field changed in Salesforce in the target version, and Heroku Connect can’t update your database automatically. In this case, un-map the field and save the mapping before changing the version. Then re-map the field after successfully changing the version.
   • A field was removed in Salesforce in the target version. You must edit the mapping to remove it from Heroku Connect.

4. If there are no schema conflicts, click Pause Connection to pause the connection. If there are any mappings actively syncing, you must wait for them to finish syncing before changing the version.

5. Click Change Version.

6. Resume the connection after changing the API version by clicking Resume Connection.

CLI

From the CLI, run heroku connect:manage-sf-api-version with the target version to change versions to. If your app has multiple connections, provide the name of the Heroku Connect connection to change as well:

$ heroku connect:manage-sf-api-version --app example-app --resource herokuconnect-resource-name --target-version 67.0
Comparing schemas... done
=== Connection: example-app:full
Current API Version: 32.0
Target API Version:  67.0
Mapping         Status              Details
──────────────  ─────────────────── ────────────────────────────────
Task            No action required  Length increased in Salesforce for field: priority. Heroku Connect alters your database table to match the Salesforce definition when the mapping is saved.
Contact10k__c   No action required
Opportunity     No action required
Profile         No action required
To change example-app:full to Salesforce API 67.0, re-run this command with --confirm example-app.

You must pause the connection and wait for all the mappings to complete syncing before changing the version. Make sure that your connection is in the PAUSED state.

Pass the --confirm flag with the name of your app to confirm the version upgrade:

$ heroku connect:manage-sf-api-version --app example-app --resource herokuconnect-resource-name --target-version 67.0 --confirm example-app

Changing example-app:full to API 67.0... done
=== Connection: example-app:full
Current API Version: 32.0
Target API Version:  67.0
Mapping        Status              Details
─────────────  ──────────────────  ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Task           No action required  Length increased in Salesforce for field: priority. Heroku Connect alters your database table to match the Salesforce definition when the mapping is saved.
Contact10k__c  No action required
Opportunity    No action required
Profile        No action required
Successfully changed version on example-app:full to Salesforce API 67.0. Run heroku connect:resume to resume sync.

Then, resume the connection after successfully changing the API version.

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.