How to Migrate Off Heroku Without Breaking Salesforce Sync
Leaving Heroku while Salesforce data flows through Heroku Connect? Learn how to sequence the app move and the sync swap so no records are lost or duplicated.
- Author
- Stacksync · App tips writer
- Published
- Read time
- 4 min read
How do you migrate off Heroku without breaking Salesforce sync?
Treat the app move and the sync swap as one coordinated cutover. Move the app and Postgres with a platform partner such as Build.io, then replace Heroku Connect with a sync that writes to the same tables in the new database, like Stacksync. Freeze writes during the switch, match existing rows by Salesforce ID, and only then turn on two-way sync.
The rest of this guide explains where Salesforce sync usually breaks during a Heroku exit and how to avoid each failure.
Where does Salesforce sync break during a Heroku migration?
Heroku Connect runs inside Heroku and writes to a Heroku Postgres database. That coupling is convenient while you stay, and it is the main risk when you leave. Most breakages fall into four patterns.
- The database moves, the sync does not. The new Postgres has the data as of the dump, but no new Salesforce changes arrive.
- Writes are lost in the gap. Rows written by the app between the final dump and the new sync going live never reach Salesforce.
- Duplicates appear. A new sync that does not recognize existing rows inserts every Salesforce record a second time.
- Schema drift. Table or column names change, and application queries fail.
Each of these is a sequencing problem, not a technology problem. A clear order of operations prevents all four.
Which migration approach is safest?
| Approach | Risk to Salesforce data | App changes needed | Notes |
|---|---|---|---|
| Move app first, fix sync later | High: database stops receiving Salesforce changes | Possibly large | Leaves a window with stale data |
| Rebuild sync with custom code | Medium to high: depends on in-house testing | Often large | Ongoing maintenance on your team |
| Move app with Build.io and swap Heroku Connect for Stacksync in one cutover | Low when rehearsed in staging | Minimal: same objects, same tables | Two specialists, one plan |
The coordinated approach keeps the database contract stable. Your app sees the same tables before and after. For details on object coverage and sync options, see the Salesforce connector.
What are the steps to migrate safely?
- 01Export the Heroku Connect configurationRecord every mapped object, field, sync direction and table name. This is your contract with the application.
- 02Stand up the target platformBuild.io provisions the new environment and moves the app, workers and Postgres.
- 03Configure Stacksync in stagingConnect a Salesforce sandbox and the staging database. Recreate each mapping with the same table and column names.
- 04Rehearse the cutoverRun the full sequence in staging: freeze writes, move data, match records by Salesforce ID, enable sync, verify writebacks.
- 05Run the production cutoverPause app writes to synced tables, stop Heroku Connect, take the final database move, enable Stacksync, then reopen writes.
- 06Verify and monitorCompare record counts per object, test a create and update in each direction, and watch the sync dashboard for errors.
How do you prevent duplicates when the new sync starts?
Heroku Connect stores each record's Salesforce ID in the Postgres table. A replacement sync should use that ID to link existing rows to existing Salesforce records rather than inserting new ones. Stacksync matches on the Salesforce ID, so the first sync run updates rows in place.
Who should be involved in the cutover?
A Heroku exit touches several teams, and the Salesforce sync sits between them. Bring each group in early so the cutover window is agreed in advance and nobody is surprised by a write freeze.
- Engineering owns the application, the list of tables it reads and writes, and the go or no-go decision.
- Salesforce admins confirm field mappings, validation rules and automation that may react to records written from Postgres.
- Build.io owns the platform move: hosting, dynos, Postgres, add-ons and pipelines.
- Stacksync owns the sync configuration, initial matching and enablement against the new database.
- Business owners who rely on reports or services reading the synced tables are told when the freeze happens.
Salesforce automation deserves particular attention. Flows and triggers that fire on update can run when the new sync first touches existing records. Testing in a sandbox shows whether any automation needs to be paused during the initial run.
What should you check after cutover?
- Record counts per object match between Salesforce and Postgres.
- A record created in Salesforce appears in Postgres.
- A row updated by the app appears in Salesforce.
- No sync errors are open, or each open error has an owner.
- Heroku Connect is disabled so two syncs are not writing at once.
Once production is stable, Build.io can retire the remaining Heroku resources. To review your Heroku Connect mappings with our team, book a demo, or read more about Stacksync as a Heroku Connect alternative.
FAQ
Frequently asked questions
Related articles
