Portmux
BLOG · PLAYBOOK

The Complete Data Migration Checklist for 2026

By Portmux Team · · 12 min read

Data migrations fail in predictable ways: undocumented custom fields, surprise referential dependencies, no rehearsal, no rollback plan. This is the actual checklist Portmux runs internally on every engagement, edited for public use. If you're planning a CRM, ERP, database, or SaaS migration in 2026, work through every section before cutover day.

1. Pre-Migration Audit

The audit phase determines whether your migration is a 4-week project or a 14-week project. Skip it and discover bad data on cutover day.

Source system inventory

  • List every record type in scope. Standard objects plus every custom object, custom entity, custom module, or custom segment. Get exact record counts per object.
  • Identify orphan records. Records with broken parent references (Contact pointing to a deleted Account, Invoice referencing a missing Customer). These get rejected at load time, find them now.
  • Inventory all custom fields. Per-object list of every custom field with type, picklist values (if applicable), required flag, and last-used date. Fields that haven't been written to in 3 years are usually dead and shouldn't migrate.
  • Catalog all integrations. Every system that reads from or writes to the source. Each one needs to be redirected to the destination on cutover day, or kept on the source via a sync layer.
  • Document undocumented automations. Workflow rules, triggers, scheduled jobs, server-side scripts, webhooks. If they exist on the source, they need an equivalent on the destination, or a documented "we deprecated this" decision.

Destination system readiness

  • Provision the destination tenant. Production and a sandbox/staging environment. Confirm storage limits, API limits, user license counts, and any feature gates that affect migration scope.
  • Confirm permissions model. Source and destination have different access control mechanisms. Document who needs what access on the destination.
  • Confirm integration partner readiness. Every system that connects to the source needs a destination-side equivalent (different API, different auth model, different webhook format). Identify any partner that requires advance lead time for redesign.

2. Data Inventory & Quality Audit

The audit phase tells you what's there. The data quality phase tells you what's worth keeping.

  • Run a deduplication audit. Email-level duplicate Contacts, exact-match duplicate Accounts, near-match duplicates (same company, different spelling). Decide dedup rules before migration, not during.
  • Identify data with referential dependencies. Foreign keys, lookup relationships, parent-child hierarchies. Load order matters: parents before children, master records before details.
  • Audit attachments. Total file count, total bytes, average file size, max file size. Destination systems often have per-attachment size limits (HubSpot 100MB, Dynamics 32MB native, Linear 50MB) that affect strategy.
  • Audit historical activity. Tasks, events, emails, comments, notes. These are usually the largest object class and the most rate-limited to extract. Plan extraction window accordingly.
  • Identify PII and regulated data. Anything subject to HIPAA, GDPR, CCPA, PCI, or industry-specific compliance. Confirm destination tenant has appropriate certifications and DPAs in place.

3. Schema Mapping

Mapping is where most migration projects spend the most time and get the least progress visibility. Document everything in a single source of truth.

  • Object-level mapping. Source object → destination object. One row per source object. Includes any object that's being collapsed into a destination object (e.g. Salesforce Lead + Contact → HubSpot Contact with lifecycle stage).
  • Field-level mapping document. Per source object: source field name, destination field name, data type, transformation rule (uppercase, format, derive from another field, leave null), sample input, expected output. This is the artifact your QA team will spot-check against.
  • Picklist value reconciliation. Source dropdown values reconciled to destination dropdown values. Decide every "Source has X, Destination doesn't" case explicitly: drop, map to default, create new picklist value.
  • Lookup relationship mapping. Source record A points to record B via field X. On the destination, A's lookup is now field Y pointing to migrated record B. Document the join column used to relink after both sides load.
  • Date and timezone handling. Source stores TIMESTAMPTZ, destination stores naive timestamps in user timezone. Define the conversion explicitly per field.
  • Currency handling. If multi-currency, define exchange rate source (cutover date snapshot vs original posting date rates) and document.
  • Owner and assignment mapping. Source User → destination User by email match. Define what happens for departed users (reassign to manager, reassign to a service account, leave unassigned).

4. Test Migration & UAT

Skip this and you'll discover edge cases on cutover day, when you have hours to fix them, not weeks.

  • Load 10% sample to a sandbox. Pick a stratified sample (representative across record types, ages, owners). Validate field mapping, parent-child references, and timestamp accuracy.
  • Validate complex scenarios manually. Pick the 5 most complex source records (largest, most fields populated, most attachments, deepest hierarchy) and verify every field on the destination by hand.
  • Run UAT with real users. Power users from each affected team. Give them a script of common workflows to execute against the sandbox. Capture every "this looks wrong" and triage before the full load.
  • Test integrations against the sandbox. Every system that integrates with the source should be pointed at the sandbox destination during UAT. Auth tokens, webhook signatures, API endpoints all need to work end-to-end before cutover.
  • Reconcile sample to source. Row count, sum of key columns, min/max of date columns. Any variance is a finding to investigate before the full load runs.

5. Cutover Plan

The cutover plan is a runbook. Print it. Tape it to the wall. Walk through it with the entire team.

  • Pick a cutover window. Low-activity time for your business (Saturday morning, end of fiscal period, holiday). Communicate it 4 weeks in advance.
  • Communicate to users. When the source goes read-only, when the destination is live, what to do during the gap, who to contact for issues.
  • Final delta plan. If you're loading the bulk of data in a pre-cutover window and finalizing on cutover day, document exactly which records are caught in the final delta and how they're loaded.
  • Integration cutover sequence. Each integration needs to be cut over in the right order. Some need destination ready first (web form integrations); some need source-as-system-of-record finalized first (billing systems).
  • DNS / URL changes. If migration involves a domain change (e.g. e-commerce platform switch), DNS TTL needs to be lowered 24 hours in advance.
  • Reconciliation report. Define exactly what reconciliation report gets delivered at sign-off: row counts per object, financial trial balance ties (for ERP migrations), open AR/AP aging reconciliation.

6. Rollback Plan

You need a rollback plan even if you never use it. Define the trigger, the time budget, and the procedure.

  • Define the rollback trigger. What concrete failure causes you to roll back? "Reconciliation report shows >0.1% variance"; "Critical workflow broken in production for >1 hour"; "Customer-facing data loss confirmed". Get specific.
  • Define the rollback window. How long after cutover are you willing to roll back? Typically 24-72 hours for SaaS migrations; longer for ERP migrations where post-cutover transactions accumulate. After the window, rollback isn't an option, you're committed to fixing forward.
  • Keep the source authoritative until sign-off. The source system stays in read-only mode (not deleted, not deprovisioned) until reconciliation is signed off and the rollback window has passed.
  • Document the rollback procedure. If you do roll back, exactly what happens? Which DNS records flip? Which integrations get repointed? Who notifies users?

7. Post-Migration Validation

Sign-off doesn't happen until validation is complete and documented.

  • Row-level reconciliation report. Per object: source count, destination count, variance (should be 0). Per critical numeric column: source SUM, destination SUM, variance.
  • Financial reconciliation (for ERP/finance migrations). Trial balance ties source-to-destination by account. AR aging ties source-to-destination by customer. AP aging ties source-to-destination by vendor. Bank balances tie source-to-destination by account.
  • Integration smoke tests. Each downstream integration verified end-to-end against production destination. Webhooks fire, API responses match expected schema, scheduled jobs run on schedule.
  • User acceptance. Each team lead signs off that their workflows function on the destination. Specific go-live verification per team (e.g. "Sales has run 5 quotes through the new system without errors").
  • Performance monitoring. First 30 days post-cutover, monitor destination system performance, API rate limits, and storage growth. Catch capacity issues before they become incidents.

8. Common Mistakes That Break Migrations

Patterns we see fail repeatedly:

  • Skipping the audit. "We'll figure out custom fields during mapping." No, you'll burn 3 weeks discovering them mid-migration.
  • No rehearsal. Loading directly to production without a sandbox dry run. Every production load runs into edge cases the sandbox would have caught.
  • No rollback plan. Cutover happens, something breaks, no documented procedure for reverting. Now it's a 4 AM all-hands incident.
  • Optimistic timeline. "Six weeks should be enough." Six weeks is enough if the source is well-documented, mapping is fast, and there are no integration partners. Every assumption that's not documented is a delay risk.
  • Not freezing source. Letting users keep working in the source during the load creates moving-target sync problems. Freeze the source (or accept a defined delta window) before you load.
  • No reconciliation acceptance criteria. What does "successful migration" mean numerically? If you can't define it before cutover, you can't sign off on it after.

Run this checklist on your next migration. Or have us run it for you.

KEEP READING
NEXT CUTOVER

Book a 20-minute
scoping call.

Tell us what's in the source, where it's going, SaaS or custom, and when you need to be live. You'll walk away with a scoped quote, a named engineer, and a go-live date.