Andrew Hanna

Andrew Hanna

Data Migration in Salesforce: A Practical Step-by-Step Guide

Data Migration in Salesforce: A Practical Step-by-Step Guide

TL;DR: Data migration in Salesforce means moving records into an org, or between orgs, so they arrive with their relationships, owners and history intact. The reliable pattern is to deploy metadata first, give every record a stable external ID, upsert parents before children, rehearse in a sandbox, then validate counts and relationships. Most guides stop at the one-time legacy import, but the migration most teams run every month is org-to-org: production data into sandboxes and scratch orgs.

What is data migration in Salesforce?

It is the movement of records, not configuration. There are two kinds:

  • Legacy to Salesforce: a one-time import from an old CRM, ERP or spreadsheet, usually at go-live.
  • Org to org: a recurring copy between Salesforce orgs, such as seeding a sandbox, merging orgs after an acquisition, or loading test data for a release.

Either way, the objects and fields must already exist in the destination, and the destination assigns its own record IDs. You cannot carry Salesforce IDs from one org to another, which is why relationships are the hard part.

Which Salesforce data migration tool should you use?

  • Data Import Wizard: built into Setup and handles up to 50,000 records at a time for common standard objects and custom objects, according to Trailhead.
  • Data Loader: a client application that imports up to 150 million records at a time, covers objects the wizard does not, and suits scheduled loads. Above that volume, Salesforce recommends working with a partner.
  • Salesforce CLI: sf data upsert bulk upserts a CSV through Bulk API 2.0 with a required --external-id flag, so loads can be scripted and repeated. Our guide to mastering Salesforce development with the Salesforce CLI covers the setup.
  • Org-to-org data deployment: when both ends are Salesforce orgs, a tool that reads the source and writes the destination in one run saves the export, transform and reimport loop.

How do you migrate data in Salesforce step by step?

  1. Scope it. List the objects, decide how much history you really need, and agree what gets archived instead of migrated.
  2. Deploy metadata first. Every field you load needs a matching field in the destination, with the same type and picklist values.
  3. Clean at the source. Deduplicate, normalize picklists and fix inactive owners before export. Cleaning after load costs more.
  4. Map fields and add external IDs. Store each legacy key in an External ID field. Upsert matches on it, updating a record that exists and inserting one that does not, and lets child rows point at a parent without knowing its new Salesforce ID. Reruns then update instead of duplicate.
  5. Load parents before children. Users and owners, then accounts, then contacts, then opportunities, then junction objects such as opportunity products.
  6. Control automation. Document the flows and triggers on each object and bypass them during the load, so a migration does not send thousands of emails. Re-enable them with a named owner signing off.
  7. Rehearse in a sandbox. Salesforce recommends importing a small test file first. Then run the full volume in a sandbox before production.
  8. Validate. Compare record counts per object, check that every child has its parent, read the error files and spot-check records with the business owner.
  9. Keep a way back. Back up the destination before you write to it and keep the source export until users sign off.

How do you migrate data between Salesforce orgs?

This is the gap in most guides, and it is the migration DevOps teams run most often. In Serpent it is a single flow: open the Migrate Data screen in the Data Management tab, pick a source and a destination org, turn on PII masking if you need it, start the migration, then review its progress and results. Built-in dependency checks reduce migration surprises, and the Migration Details page shows the execution timeline, with a Migrated Objects table you can filter by success and failed status. The full walkthrough is in the help center: data migration and masking.

Because metadata and data move in the same release flow, and Migrate Data is an action in the visual automation flow builder, the data a release depends on ships with the release instead of in a separate script. See Serpent data deployment for how that fits a pipeline; Deploy data is on every plan, including the free Essentials plan.

How do you keep personal data safe when copying production data?

Copying production records into a sandbox copies the personal data in them too. Serpent's PII masking obfuscates common personal fields during preview and migration, which keeps production-shaped data usable in lower environments while meeting GDPR and similar rules. For repeatable test environments, Serpent seeds sample or masked data as part of environment setup and release pipelines, so refreshed sandboxes and scratch orgs come back populated without a manual script run. Our guide on how to seed a Salesforce sandbox with realistic data goes deeper.

What are the most common Salesforce data migration mistakes?

  • Children before parents. Lookups fail or point at nothing.
  • Trusting source IDs. They do not exist in the destination; use external IDs.
  • Leaving automation on. Flows fire on every inserted record.
  • No dry run. The first full load should never be the production load.
  • No recovery plan. Data is harder to reverse cleanly than a metadata release. Serpent's Backups view captures a known-good state, recovers supported metadata and records, and keeps a Restore History; see backup and restore.
  • Forgetting the integration user. Every tool authenticates as someone; if you are changing how, read our Salesforce authentication migration guide first.

Data belongs in your release process alongside code and configuration, one of the ideas behind the 5 pillars of Salesforce DevOps. For more how-tos, browse the SF Guides.

FAQ

How many records can the Data Import Wizard handle?

Up to 50,000 records at a time. For more, Data Loader handles up to 150 million records at a time.

Do you need to migrate metadata before data?

Yes. Every object and field you load must already exist in the destination org with a matching type.

What is an external ID in a Salesforce migration?

A field that stores a stable key from the source system. Upsert uses it to match records and link children to parents without Salesforce IDs.

Can you migrate data between two Salesforce orgs without exporting CSVs?

Yes. An org-to-org tool such as Serpent's Migrate Data reads the source org and writes the destination in one run, with optional PII masking.

Related Articles

Curious about faster shipping before you dive in? Let's talk

Commitment free!