How to Migrate a Customer Database Without Losing Relationships

A Customer Database Is Not a Contact Table

A customer database migration is often imagined as exporting a single file and importing it into a new CRM. This approach works only for a simple address list. In a working system, a customer record is linked to contact people, companies, deals, tasks, emails, documents, owners, sources, and consents. If field values are transferred without restoring the relationships, the database may look complete while no longer supporting real business processes.

It is useful to treat a migration as transferring a graph. Entities are the nodes, while the links between them are the edges: a deal belongs to a company, a contact represents a company, a task is assigned to an employee, a file belongs to a document, and the document belongs to a customer. The loading order is determined by these dependencies. Reference data and parent records are created in the target system first, followed by child entities, and only then by history, files, and calculated data.

Create an Inventory and a Mapping Specification

Before writing a script, document the full set of sources. Data may be spread across the old CRM, sales representatives' spreadsheets, telephony, an email service, cloud storage, and the accounting system. For each source, record the owner, export method, format, encoding, time zone, update frequency, and access restrictions. This inventory reveals where the primary record lives and which source is authoritative when values conflict.

The next document is the field mapping specification. It maps each source field to its target, describing its type and whether it is required, normalization rules, default value, and error behavior. Reference data needs a separate dictionary: legacy statuses, categories, currencies, cities, and roles rarely match the new model exactly. It is safer to send an unknown value to an exception report than to silently replace it with the closest available option.

Preserve Stable Identifiers

A name, telephone number, and email address are not reliable migration keys. They may be duplicated, change, be missing, or be stored in different formats. Every source record needs a stable technical identifier. If the new CRM creates its own ID, preserve the legacy identifier in a dedicated field and record the “legacy ID — new ID” pair in a mapping log. This log is required for loading dependent entities, rerunning the migration, and investigating discrepancies.

Primary keys uniquely identify records, while foreign keys maintain referential integrity between tables. The same principle should be applied in an application-level migration even when the target CRM hides the physical database structure behind an API. A deal should reference the newly created customer by its new ID rather than search for the customer by name during every import. Otherwise, identical names and corrected contact details will create unpredictable relationships.

• Do not change the source ID when exporting the same record again.
• Keep the mapping log under version control together with the run protocol.
• Prevent the creation of a child record if the parent ID cannot be found.
• Track merged records separately when several legacy IDs map to one new customer.
• Make the import idempotent: a rerun updates the record that has already been found instead of creating a duplicate.

Separate Cleansing, Merging, and Loading

A migration quickly becomes unmanageable when one script simultaneously corrects telephone numbers, guesses which records are duplicates, transforms statuses, and writes the result. It is better to build several observable stages. First, save the export unchanged as a source snapshot. Then normalize formats in a separate layer. After that, matching rules create load-ready records, while the loader is responsible only for sending them to the target system and logging the response.

Merging duplicates requires business decisions. A matching telephone number can be a strong signal, but it does not prove that two records belong to the same person: families and organizations may share a number. A matching name is an even weaker signal. Therefore, separate the rules into automatic ones and those requiring review. For every merge, preserve the reason, source IDs, and the rule used to select field values. Otherwise, correcting an erroneous merge after launch will be difficult.

Run a Complete Migration Rehearsal

The first complete load should not take place in the production CRM. Run the rehearsal in a separate environment with a copy of the configuration, reference data, roles, and integrations. It should include every stage: export, transformation, loading, file attachment, index creation, and control reports. The team measures how long each stage takes, not to promise an exact timeline, but to determine whether the process fits within the available cutover window.

1. 01

   Capture a Snapshot

   Preserve the source exports, file checksums, schema versions, and migration code versions.

2. 02

   Load in the Correct Order

   Start with reference data and users, then migrate customers, deals, activities, documents, and files.

3. 03

   Collect Exceptions

   Do not conceal errors; create a list of rejected records with the reason and the source identifier.

4. 04

   Test Working Scenarios

   Ask representatives of each role to find a customer, open a deal, verify a document, continue a task, and generate a report available to them.

A rehearsal is complete not when a command finishes successfully, but after discrepancies have been investigated and the corrected version has been run again. It is also advisable to test recovery from a backup: the mere existence of a backup file does not prove that the system can be restored from it to a known working state.

Plan the Cutover and the Change Delta

Between the test export and launch, users continue to update customers and deals. These changes form the delta. For a smaller process, the team can agree on a short window during which the old CRM is available in read-only mode. A system that cannot be stopped requires change capture: an event log, a repeat export of records based on update time, or specialized replication. The choice depends on the source system's capabilities, but the rule is always the same: every record must have an unambiguous state at the moment of cutover.

The launch plan assigns responsibility for the export, import, verification, rollback decision, and employee communication. It includes checkpoints at which the team either proceeds or returns to the old system. During cutover, stop any integrations capable of creating data in both systems, then re-enable them in a defined sequence. Otherwise, the new website might send a lead to the old CRM after the final export has already been completed.

• Announce the exact time when changes in the old system must stop.
• Create the final backup and verify the point in time it represents.
• Run the full load or apply the verified delta.
• Switch forms, telephony, email, and automations to the new CRM.
• Keep the old system in read-only mode until acceptance is complete.

Reconcile More Than Row Counts

An equal number of customers in two systems does not prove that the database has been preserved. One important customer may be missing while an accidental duplicate compensates for the count. Reconciliation should operate at several levels: counts by entity and status, presence of key fields, existence of all relationships, aggregates for business indicators, and spot checks of specific records. For automated verification, it is useful to generate a machine-readable report listing matched, missing, and differing records.

The official AWS DMS documentation describes comparing source and target rows and tracking mismatched records separately. The specific tool may differ, but the principle remains applicable: reconciliation results should be reproducible and leave an exception list. The manual conclusion that “everything looks similar” is not an acceptable basis for customer database acceptance.

Prepare a Rollback and Controlled Acceptance

Rollback is designed before the migration begins. The team defines the conditions that would make the launch unacceptable: a critical role cannot access the system, relationships are broken, forms do not work, documents cannot be opened, or reconciliation reveals unexplained discrepancies. It also sets a final deadline for the decision. The longer employees work in the new CRM, the harder it becomes to move the changes back without a second migration.

A straightforward rollback is possible if the old system remained available only in read-only mode and no new operations have begun. Once work starts, the team needs a plan for migrating the delta back or a deliberate decision to fix the new system without returning. The backup, recovery instructions, and list of external integrations must be available to the responsible specialist. NIST recovery guidance emphasizes the importance of returning a system to a known state and testing the procedures, rather than merely having backup data.

Business acceptance follows technical reconciliation. Representatives of sales, support, management, and administration test workflows within their own permissions. For example, in the verified Crypto Exchange CRM case, customers, documents, deals, offices, and cash desks are linked to an organization, while the server applies role-based restrictions to APIs, reports, and files. For a model like this, a migration is correct only when it restores not merely the records, but also organizational ownership, the employee's working context, and the permitted access to related data.

A migration is complete not when the last field has been imported, but when relationships, permissions, and the continuation of critical operations have been verified.

Agentix Labs migration principle