Ways to Migrate Data Between Salesforce Environments

Data migration is not metadata deployment. When you push a change set from sandbox to production, it moves your object schema — the field definitions, validation rules, flows, and Apex classes. It does not move the records inside those objects.

If you've been testing with data in your sandbox, those records stay in the sandbox. Moving them to another environment is a separate operation with separate tools, a separate API, and different ways to break things.

When you need data migration

Common scenarios where metadata deployment alone isn't enough:

• Moving developer test data from sandbox to scratch org
• Populating a new sandbox with a subset of production data
• Migrating historical records when implementing a new Salesforce org
• Moving reference or configuration data as part of a deployment runbook
• Setting up seed data for automated test runs

Each scenario is slightly different, and different tools fit each one best.

The 5 approaches

External IDs — the critical concept

Before covering the tools, you need to understand External IDs. Salesforce record IDs are org-specific — the 18-character ID that identifies a record in your sandbox means nothing in production. Using them to reference records across orgs will fail.

External IDs are custom fields marked as External ID in Setup. Salesforce indexes them and allows you to use them as matching keys during upsert operations.

The correct pattern for cross-org migration:

1. Create External ID fields on all objects you plan to migrate
2. Populate them with stable unique values in the source org
3. Export records including their External ID field
4. In child record CSVs, reference the parent's External ID using the ParentObject__r.ExternalIdField__c notation
5. Use upsert (not insert) so the migration is idempotent

Approach 1: Data Loader

Data Loader is the standard tool for bulk data migration in Salesforce. It's a free Java-based application available from Setup → Apex Data Loader. It connects directly to your Salesforce org via API and supports all standard and custom objects.

Operations

• Export: write a SOQL query, Data Loader runs it and outputs a CSV file. Always include External ID fields in your export query.
• Insert: creates new records from a CSV. All required fields must be present. Validation rules apply.
• Update: modifies existing records. Requires the Salesforce record ID (Id) in the CSV.
• Upsert: inserts or updates records based on a matching field — use this with External IDs for cross-org migrations.
• Delete / Hard Delete: removes records. Hard Delete bypasses the Recycle Bin.

Migrating relationships

When your migration includes records with lookup relationships — contacts with accounts, for example — the parent records must be migrated first. In the child record CSV, reference the parent using the External ID notation:

After each run

Data Loader generates two files after every operation: a success file and an error file. Open the error file after every run, even if the status looks clean. Partial failures in bulk operations don't always surface as visible errors during the run.

Approach 2: Dataloader.io

Dataloader.io is a browser-based alternative to the desktop Data Loader. No local installation required. Authenticate with your Salesforce org through an OAuth flow in the browser, then use a wizard-based interface for field mapping and operation selection.

Key advantages over Data Loader: built-in scheduling for recurring migrations, more accessible interface for non-technical users, and no installation or Java dependency to manage.

The free tier includes a rate limit of approximately 100,000 records per month. If your migration needs exceed that, a paid tier removes the limit.

Approach 3: SFDX data commands

The Salesforce CLI provides two commands designed for developer environment data migration.

Exporting

This exports Account records and their related Contacts into structured JSON files. The JSON format preserves the relationship structure and is version-controllable alongside your code.

Importing

The import command reads the JSON structure and creates records in the correct order — parents before children. Relationships are resolved via the External IDs in the JSON, so no Salesforce IDs are needed.

SFDX data commands are the right choice for developer environments, scratch orgs, and structured data sets you want to be reproducible. For large volumes or production migrations, use Data Loader.

Approach 4: Salesforce Inspector

Salesforce Inspector is a browser extension that provides a SOQL query editor, record viewer, and single-object CSV export. It's useful for developer workflows — quickly checking field values, running ad hoc queries, exporting a small set of records for debugging.

It is not suitable for production data migrations. Volume and reliability limitations make it the wrong tool for anything beyond small, developer-level data operations.

Approach 5: ETL tools

Extract-Transform-Load tools — MuleSoft, Informatica, Talend, Jitterbit — are the right choice when the migration requires transformation, when it needs to run on an ongoing basis, or when data comes from multiple source systems.

Data Loader and SFDX data commands assume your source data is already clean and correctly formatted for Salesforce. ETL tools handle the transformation layer — mapping field formats, converting values, enriching data from multiple sources before it lands in Salesforce.

For a one-time migration where the data is already clean: Data Loader or SFDX. For complex transformation or ongoing sync between Salesforce and external systems: ETL.

Common mistakes

• Using Salesforce IDs cross-org. IDs are org-specific. Always use External IDs for cross-org references.
• No External IDs before migrating relationships. Related lookups will be empty or wrong in the target org.
• No 50-record test before the full migration. Field mapping errors, missing required fields, and validation rule failures are far cheaper to find in a test run than after 200,000 records.
• Not reading the error log. Data Loader's bulk operations can fail partially without surfacing clearly during the run. The error log tells the truth.
• Using insert instead of upsert. Insert will create duplicates if the migration runs twice. Upsert on an External ID field is idempotent.

Deployment runbook pattern

When a deployment includes data migration steps — creating configuration records, seeding lookup values, migrating reference data — incorporate them into the deployment runbook as a documented, separate step:

1. Deploy metadata via change set or SFDX deploy
2. Run the data migration step with upsert and External IDs
3. Run the verification query — confirm record counts and spot-check relationships

Building the verification SOQL before you start the migration — and running it immediately after — makes it much easier to confirm the migration completed cleanly.