A migration is a conversation with old decisions

Moving data sounds like moving information from one place to another. In practice it is a long negotiation with years of choices nobody wrote down.

On paper, a data migration is simple. Read from the old system, write to the new one, check the totals. The plan fits on an index card.

The reality is that every field in the old system is a decision someone made under pressure, years ago, that then hardened into a rule. A status code that means three different things depending on the year. A date column that is sometimes a date and sometimes a note. A customer who exists twice because a merger was handled quickly. None of this was careless. It was the reasonable thing to do at the time, and the organisation has been running on it ever since.

So we do not move everything at once and hope. We move it in small, verified stages, and after each one we reconcile: does the old system and the new system now tell the same story about this slice of the world? Where they disagree, we stop and find out why. Usually the answer is interesting, and occasionally it changes the plan.

The migration is finished when the two systems agree — not when the script runs without error.