Migrating Orgs Safely
Moving data and configuration between orgs is where careful admins get burned. The failure modes are well known — broken references, silent overwrites, no way back — and all of them are avoidable with a disciplined sequence. This is that sequence.
1. Pick the right strategy
Not every migration is the same, and the right approach depends on the relationship between the orgs:
- Sandbox seed. Populating a sandbox from production. The orgs are related and share record IDs, so matching is direct. You usually want a report-only default so you do not clobber existing sandbox data.
- Promote. Pushing changes forward through related environments. Auto-patching drift is appropriate here.
- Unrelated orgs. Two productions that do not share IDs. You cannot match on Id; you need an external ID or a composite natural key.
Naming the strategy up front decides everything downstream — matching, drift handling, and rollback posture.
2. Map objects and dependencies
List the objects, then order them by dependency: parents before children. A migration that loads child records before their parents fails on missing references. Let the tooling resolve the order from the relationship metadata rather than building the list by hand — and remember that required lookups are non-nillable but are not Master-Detail; classify by relationshipOrder, not by whether the field is required.
3. Always dry-run first
Never let the first write be a surprise. A dry run shows exactly what will be created, updated, or skipped, and buckets records by how they compare to the target:
- identical — leave alone
- drifted — exists but differs
- missing — needs creating
- ambiguous — matches more than one target; do not guess, filter it out
Read the dry run before you write. It is the single highest-leverage habit in org migration.
4. Match records deliberately
When orgs share IDs, matching is automatic. When they do not, choose your key explicitly: a true external ID field if you have one, or a composite natural key (for example, account name plus billing country) when you do not. A wrong key is worse than no migration — it merges records that should be distinct.
5. Keep rollback available
Inserts are easy to undo. Updates are not — unless you captured the target's before-state first. Insist on a migration path that snapshots prior values and can PATCH them back, so an update is reversible field-for-field, not just "delete what I created." Treat any migration that cannot reverse an update as a one-way door.
6. Verify after the write
A run that reports success is not the same as a correct migration. Verify:
- record counts match expectations per object
- relationship integrity holds — sample child records and confirm their parents resolved
- picklist and required-field values are valid in the target
How Data Migrator implements this
Each step above maps to a built-in safeguard in Data Migrator: related/unrelated detection, automatic dependency ordering, mandatory dry-run with drift buckets, external-ID and composite-key matching, before-state rollback snapshots, and post-load verification with relationship-integrity sampling. The discipline is the point; the tool just makes it the default.