All docs pages (49)

Data Migrator

Copy records between orgs in dependency order, with a required dry run and a rollback for the records a run creates or updates.

Updated 2026-06-08

Data Migrator copies records from one Salesforce org to another, without CSV files or hand-built dependency lists. It moves records only. It also compares the two orgs' schema and permission sets so you can see gaps first, but it does not deploy fields or permissions. Two rules shape it: a dry run is required before anything is written, and the records a run creates or updates can be rolled back.

Connecting orgs

You select a source and a target org. Both connect through the Salesforce sessions you are already signed in to: no connected app and no password. Data Migrator guesses from several signals whether the two orgs are related (for example a sandbox and its production org) or unrelated, and shows the guess. For unrelated orgs it suggests a natural key to match records on. You choose the matching yourself.

Choosing what to move

Pick the objects you want to migrate. Data Migrator resolves parent-child dependencies automatically and orders the work so that parents are written before the children that reference them. This avoids the "missing reference" failures common in manual data loads.

For Master-Detail and Lookup relationships, it uses relationshipOrder to classify the relationship correctly. A child is read only for the parents you picked. If the parent Id list is too long for one query, that filter is left out of the query. In version 1.1.9 the child may then copy rows whose parents you did not pick; from version 1.1.13 those rows are filtered out after reading and the run says the read was wider.

Dry run first

A dry run is required before a migration can start. It writes nothing and reports, per object: record counts, the order the objects will be written in, likely conflicts, the estimated API calls, field problems and missing references. It does not list each record.

During the run, when the key you chose can't be used for an upsert and the object falls back to insert, each record is first compared with the target by that key:

  • identical: already matches, skipped
  • drifted: exists but differs; patched if Auto-update on drift is on (on by default for Promote, Mirror and Repair, off for Seed), otherwise reported
  • missing: not in the target; created
  • ambiguous: matches more than one target record; not written, so you can pick the right one in ErrorSurgery

Matching records

Records are matched on an external ID or a composite natural key you pick, or inserted as new. Record Ids are never used as the match key, even between related orgs. Duplicate-value errors are parsed per-row and the conflicting target Id is extracted automatically (with 15/18-character deduplication) so a single bad row does not stall the run.

Rollback

Rollback undoes inserts by deleting the created rows. Before it patches a record, it captures a before-state snapshot. On rollback, it PATCHes the original values back, field for field. Rollback does not bring back records a run deleted. In version 1.1.9, some lookups filled in a second pass (after the records were created) were written without a snapshot, so rollback can't undo them. From version 1.1.13, a second-pass value that can't be snapshotted is not written.

Migration modes

  • Seed — populate an empty sandbox; reports drift rather than overwriting.
  • Promote — push changes forward; auto-patches drift.
  • Mirror — make the target match the source.
  • Repair — fix specific drifted records.

Resilience and recovery

Long migrations survive interruption. Progress is checkpointed, so a run can resume rather than restart. When records fail validation, the ErrorSurgery panel offers targeted resolutions — map to an existing record, remap a value, provide a default, auto-truncate an over-length field, assign to the current user, or skip — and retries only the rows you resolved.

Walkthrough

Moving and making test data follows a real migration step by step: 41 filtered accounts sent insert-only to a second org, 1 written and 40 refused as duplicates of existing records, then a rollback that removed exactly the one record created.