Last updated November 30, 2021

Heroku Connect interacts with your Salesforce org and your Postgres database in a variety of ways, which means there are a number of factors than can impact the performance, reliability and correctness of sync operations.

Heroku provides a CLI plugin to inspect the current state of your connection and perform basic operations. One of those operations is the ability to run some simple diagnostics to identify common problems that may affect you, using the connect:diagnose command.

$ heroku connect:diagnose --verbose
Diagnosing connection... done

=== Connection: protected-ridge-4963
GREEN: Salesforce API Version
GREEN: Number of Mappings
GREEN: Database Plan

=== Account
GREEN: Calculated Fields
GREEN: Upsert Field
GREEN: Binary Fields
GREEN: Number of Fields
GREEN: Required Fields

Results can be either red, yellow or green. Red results indicate errors that are likely causing problems with the flow of data. Yellow results indicate warnings that may or may not be actual problems, depending on your application. Both red or yellow results will include additional details about the problem, as well as a link to more documentation, where applicable. Green results indicate no known problems, and therefore no additional detail is provided.

Connection Checks

Check: Salesforce API Version

Salesforce periodically upgrades the capabilities of its API, but Heroku Connect will not automatically use newer versions as they’re released, in order to ensure consistency in how your data is handled. If you’re using a very old API version, you should consider recreating your connection with a newer API version.

Check: Number of Mappings

Heroku Connect performance degrades as more mappings are added to your connection. This affects reading from and writing to Salesforce, as well as the responsiveness of your dashboard.

Check: Heroku Postgres

Normal operation and customer support of Heroku Connect rely on services only available on Heroku Postgres. Other database providers are not supported.

Check: Database Plan

Hobby tier Postgres databases are underpowered for typical Heroku Connect usage. If you’re using the paid enterprise or danketsu Heroku Connect plans, you should also be using at least a ‘-4’ Heroku Postgres plan, eg ‘Standard-4’.

Check: Data Locality

Heroku Connect operates in multiple regions around the world, and it works best when your app and its database are located in the same region as the connection that syncs your data. Having your connection and database in different regions can introduce significant delay in transferring data.

Check: View/Modify All Permissions

Heroku Connect works best when the authorized Salesforce user has View All and, if necessary, Modify All permissions on each mapped object. Without these permissions, queries to Salesforce can take longer, and may return incomplete data.

Read more: Read errors

Check: Configured Log Drain

You can monitor and analyze Heroku Connect’s logs if a logging add-on or log drain is configured for either your app or your Shield Private Space. It is strongly recommend that you configure logging so that you can view historical logs without hitting log history limits.

Mapping Checks

Check: Binary Fields

Binary fields aren’t supported by Heroku Connect, and don’t behave as you expect.

Read more: Base64 binary fields

Check: Calculated Fields

Calculated fields aren’t supported by Heroku Connect, and may not behave as you expect.

Read more: Cross-object formula and roll-up summary fields

Check: Number of Fields

When Heroku Connect pulls data from Salesforce, it reads in the entire record at once. When a lot of fields are mapped, this can severely degrade performance.

Check: Required Fields

There are a number of fields required for Heroku Connect to properly insert data from Postgres into Salesforce. If you have failed to map any of the required fields in Heroku Connect, you’ll need to ensure they’re being populated in Salesforce, for example by using a “before insert” trigger in Apex code.

Check: Unique Identifier

When writing from Postgres to Salesforce, a unique-identifier is required to ensure that data can be matched correctly between the two systems. A unique identifier must be defined as a unique external ID field in Salesforce.

Read more: Unique identifier

Check: Number of Large Text Area Fields

When Heroku Connect pulls data from Salesforce, it reads in the entire record at once. When this includes multiple large text area fields (which can be Long Text Area fields or Rich Text Area fields), this can severely degrade performance.

Read more: Minimize the Size of the Mapped Object

Check: Synthetic Fields

Synthetic fields are created by Heroku Connect and used to reference objects when writing data to Salesforce. Synthetic fields are unnecessary for read-only mappings and typically shouldn’t be mapped. In cases where you need or expect to switch between read-only and read-write, they can be mapped.

Check: Salesforce Field Changes

When the definition of a mapped field is changed in Salesforce, a corresponding change needs to be made to your database. On the Edit Mapping screen, Heroku Connect will check for changed fields and will display warnings if there are changes. A change will be one of:

• An increase to the length of a text field – Heroku Connect will alter your database table to increase the length of the field.
• Any other change – these are considered to be unsafe and require you to:
  1. Remove the field from the mapping by editing the mapping, unselecting the field, and saving the mapping.
  2. Add the field to the mapping again by editing the mapping, selecting the field, and saving the mapping.

Check: Database Field Changes

Heroku Connect expects to manage the schema of the tables it syncs. Any fields that are added, removed, or altered by something other than Heroku Connect will need to be restored to the state that Heroku Connect expects. To correct the problem using the dashboard, go to the Edit Mapping screen. Heroku Connect will check for the following changes:

• Added or removed fields – upon saving the mapping, Heroku Connect will alter your database table automatically.
• Altered fields – you need to remove and then re-add the altered fields:
  1. Remove the altered fields from the mapping by editing the mapping, unselecting the fields, and saving the mapping.
  2. Add the fields to the mapping again by editing the mapping, selecting the fields, and saving the mapping.

Check: IsArchived Field

Task and Event objects have an IsArchived field that allows archiving of these objects, removing from view without fully deleting them from the system. But Salesforce doesn’t mark records as modified when this happens. As a result, Heroku has no way to reliably detect changes to the IsArchived field. Heroku only gets updates to the IsArchived field’s value when something else on the record also changed, so it’s very easy for this field to contain different data between Salesforce and Heroku.

Check: Polymorphic External ID

Heroku Connect uses external IDs to uniquely identify records within Postgres, before Salesforce has issued its own IDs. In order to accurately reference records in a related object, Heroku Connect needs to know which object the ID will refer to. Therefore, polymorphic fields, like WhatId and WhoId, which can reference more than one type of object, cannot be used as external IDs with Heroku Connect.

Check: Maximum Record Size

When writing data to Salesforce, the APIs involved have a limit to how much data can be provided in a single record. If your data exceeds this limit, Heroku Connect may fail to write the record to Salesforce. Because the limit is based on actual data in the record, this check simply checks for a mapping that could conceivably contain enough to data to exceed the API limits.

Check: Query Size

When Heroku Connect retrieves data from Salesforce, it issues SOQL a query containing only the fields that you’ve mapped, to avoid transferring more data than necessary. For mappings with a large number of fields, or with very long field names, that SOQL query can exceed the limits imposed by the Salesforce API.

Check: Synthetic Field/Unique Identifier Agreement

When mapping a synthetic field, the field on the related object should also be configured as a unique-identifier on that object, if you have a unique-identifier configured. This helps ensure that you can populate multiple records in Postgres using that field as an external ID, and have all the records match up properly in Salesforce.

Check: SObject Not Supported By Bulk API

Heroku Connect uses the Salesforce Bulk API to process large volumes of data more efficiently. However, the Bulk API does not support all sObjects. Heroku Connect will still attempt to sync objects using the Salesforce SOAP API if it can’t use the Bulk API, although there are known issues with large bulk data volumes. Salesforce has a Knowledge Article that lists some of the objects that aren’t supported by the Bulk API.