Last updated February 24, 2023

Heroku Connect interacts with your Salesforce org and your Postgres database in a variety of ways, which means there are a number of factors that 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 can 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 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 doesn’t 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, 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 aren’t supported.

Check: Database Plan

Essential-tier Postgres databases are underpowered for typical Heroku Connect usage. If you’re using the enterprise or danketsu Heroku Connect plans, use at least a ‘-4’ Heroku Postgres plan, for example, ‘Standard-4’.

Check: Data Locality

Heroku Connect operates in multiple regions around the world. 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 can 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’s strongly recommended 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 don’t 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. Mapping a large number of fields can severely degrade performance. We recommend keeping the number of mapped fields to be less than 100 fields per object.

Check: Required Fields

There are a number of fields required for Heroku Connect to properly insert data from Postgres into Salesforce. If you’ve failed to map any of the required fields in Heroku Connect, you must 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 aren’t 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 must be made to your database. On the Edit Mapping screen, Heroku Connect checks for changed fields and displays warnings if there are changes. A change is one of:

• An increase to the length of a text field – Heroku Connect alters 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 must be restored to the state that Heroku Connect expects. To correct the problem using the dashboard, go to the Edit Mapping screen. Heroku Connect checks for the following changes:

• Added or removed fields – upon saving the mapping, Heroku Connect alters your database table automatically.
• Altered fields – you must 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 must know which object the ID refers to. Therefore, polymorphic fields, like WhatId and WhoId, which can reference more than one type of object, can’t 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 fails 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 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 must 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 doesn’t support all sObjects. Heroku Connect still attempts 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.