Relational Data Migration Check¶
Validation check — instantiates Topology-Preserving Transformation
Validates that the links between migrated records — ownership, references, permissions, lineage, hierarchy — still resolve in the target system, because copying the values is not the same as preserving the relationships, and routes every broken link to a reconciliation queue.
A Relational Data Migration Check validates that the links between records survive a data migration — that after the move each ownership pointer, foreign reference, permission grant, lineage chain, and hierarchy edge still resolves to a real, correct target. Its defining insight is that copying values is not preserving relationships: a migration can transfer every field of every row and still leave a contact pointing at an account ID that no longer exists, a document whose author link resolves to nobody, or a permission that references a deleted role. It works at the level of referential resolution — following each declared link into the target and confirming it lands — and every link that fails to resolve is not just reported but handed to a reconciliation queue with an owner.
Example¶
A company is retiring its aging CRM and ERP and consolidating onto a new platform. Accounts, contacts, opportunities, invoices, and their owners all get exported and loaded, and the row counts match on both sides — every record made it across. But row counts say nothing about the links. The Relational Data Migration Check enumerates the link types that matter and resolves each one in the target: does every contact's account_id point at an account that exists? Does every opportunity still resolve to an owning sales rep whose user account survived the identity migration? Does each invoice's approval permission still attach to a role that exists in the new system?
It finds three classes of breakage the count reconciliation missed: forty-one contacts whose parent account was merged during migration and now dangle as orphans; a batch of opportunities re-pointed to a default "system" user because their real owners had been deactivated; and a set of approval permissions referencing legacy role IDs that have no equivalent target role. None of these show up as missing rows — the values are all present. The check routes each broken link into a reconciliation queue: orphaned contacts to the data-migration lead for re-parenting, mis-owned opportunities to sales ops, dangling permissions to security. The migration is declared complete only when the queue is worked down, not when the loads finish.
How it works¶
What distinguishes this check from a values-level reconciliation is that it targets link resolution, not record presence:
- Scope the link types that count. Ownership, references, permissions, lineage/history, and hierarchy are named explicitly, because "which relationships must survive" is a decision, not a default.
- Resolve each link in the target. For every migrated record, each declared link is followed into the new system to confirm it lands on a real, correct object — not merely that a value was copied.
- Classify the failures. Broken links are sorted into orphaned (points at nothing), mis-resolved (points at the wrong thing), and duplicated (fans out where it should be unique).
- Route to reconciliation with an owner. Every unresolved link becomes a queue item assigned to whoever can repair it, so discovery translates into recovery.
Tuning parameters¶
- Link-type scope — formal referential links only, or also derived and soft links (lineage, provenance, informal ownership). Wider scope catches more but demands the source system expose those links legibly.
- Resolution strictness — exact target match versus functional equivalence (a link that resolves to a renamed-but-correct object). Strict matching catches subtle corruption; functional matching tolerates legitimate remapping.
- Coverage — full validation of every link versus statistical sampling. Full coverage is definitive but expensive on large corpora; sampling is fast but can miss a rare broken class.
- Timing — pre-cutover dry run, at cutover, or post-cutover. Earlier catches breakage before users see it; later reflects the real, live state.
- Auto-repair vs. queue — whether trivially-fixable links (a deterministic ID remap) are corrected automatically or all breaks go to a human queue. Auto-repair is faster but can mask a systemic mapping error.
When it helps, and when it misleads¶
Its strength is catching the migration failures that a row-count or checksum reconciliation is structurally blind to: orphaned records, dangling references, and permissions that quietly resolve to nothing. It is what lets a team say not just "everything copied" but "everything is still connected the way it was."
Its central weakness is that it validates only the links it was scoped to check — an informal or undocumented relationship that the source system never made explicit slips through, intact-looking and actually broken.[n1] The tidy pass report also invites false confidence: it certifies referential resolution, not business correctness, so a link that resolves to the wrong but existent target can pass. The classic misuse is treating a matched row count as proof the migration succeeded — declaring victory on values while references dangle underneath. The discipline that keeps it honest is to scope the link types explicitly (permissions and lineage especially, which are the easiest to forget), validate that links resolve correctly rather than merely exist, and treat the reconciliation queue as part of the migration rather than an afterthought.
How it implements the components¶
Relational Data Migration Check realizes the referential-integrity slice of the archetype — the machinery that preserves the links carried by records rather than the records themselves:
relation_scope_boundary— it decides which link types are load-bearing (ownership, references, permissions, lineage, hierarchy) and therefore which must be validated, rather than trying to preserve every incidental value.lineage_mapping— it follows and confirms the ownership, reference, and history chains that connect records, verifying that provenance and derivation links resolve intact in the target.repair_path— every unresolved link becomes an owned reconciliation-queue item, giving broken relationships a route to correction rather than a mere report.
It does not compute a whole-graph adjacency_map or a before/after structural preservation_check — that graph-level diff is Graph Difference Review, its nearest twin; this check operates at the record and referential level, resolving each declared link rather than diffing the overall shape of the graph.
Related¶
- Instantiates: Topology-Preserving Transformation — the check is how a data migration preserves the relationships between records, not just their values.
- Sibling mechanisms: Graph Difference Review · Topology Regression Suite · Handoff Continuity Walkthrough · Organizational Path Preservation Review · Reachability Test · Interface Contract Test · Compatibility Bridge or Shim
Editorial Notes¶
Form Classification¶
Form family: Assessment, Review & Assurance
Rationale: Relational Data Migration Check operates as a bounded evaluation of existing evidence or work that produces a finding or disposition because it validates that the links between migrated records — ownership, references, permissions, lineage, hierarchy — still resolve in the target system, because copying the values is not the same as preserving the relationships, and routes every broken link to a reconciliation queue.
Independent corroboration: The frozen evidence defines Relational Data Migration Check as 'Validates that the links between migrated records — ownership, references, permissions, lineage, hierarchy — still resolve in the target system, because copying the values is not the same as preserving the relationships, and routes every broken link to a reconciliation queue', so its operative form is Assessment, Review & Assurance.
Nearest alternative: Experiment, Test & Rehearsal — Relational Data Migration Check includes features of an active test, trial, simulation, drill, or rehearsal that generates evidence through a deliberate attempt or perturbation, but its defining operation is a bounded evaluation of existing evidence or work that produces a finding or disposition.
Review outcome: Independent reviewer agreement; medium confidence.
Origin Attribution¶
Primary origin: Computer Science & Software Engineering
Origin pattern: Single lineage
Present-day reach: Multi-domain
Rationale: Preserving referential integrity while migrating records is a database and software-engineering practice.
Review resolution: Both blind reviewers agree that computer_science is the primary historical origin. Explicit reconciliation of alternate origin disagreement, encyclopedia synthesis disagreement adopts reviewer_a's evidence: Preserving referential integrity while migrating records is a database and software-engineering practice. The selected record uses alternates=none, origin_mode=single_lineage, and domain_reach=multi_domain; the other review proposed alternates=engineering_design, origin_mode=single_lineage, and domain_reach=multi_domain. The selected combination better preserves the mechanism-specific formative lineages and calibrated scope; broader present-day use is not treated as proof of additional historical origin.
Review outcome: Reconciled after independent review; high confidence.
Notes¶
[n1] Referential integrity is the database guarantee that every foreign-key reference points at a row that actually exists. A migration frequently breaks it precisely because the load copies values without re-validating the pointers, which is why "the rows all came across" and "the references still resolve" are two different claims — and only the second is what this check proves. ↩