Migration Scripts: Excavating Artifacts Without Damaging Them

Opening Scene

When a fragile artifact needs to move from where it was found to the lab where it can actually be studied, no one just yanks it out of the ground. The excavation team documents its exact position, supports it from underneath, sometimes encases it in plaster before it’s lifted at all, moving it deliberately, in a sequence designed specifically to prevent the one thing that can’t be undone: damage in transit. The artifact matters too much to move carelessly, even for a few meters.

In Plain English

A migration script is the code that transforms existing data from an old schema shape into a new one — reformatting a field, splitting a column, backfilling a default, restructuring a relationship. Where a breaking change is the fault line, a migration script is the deliberate excavation work that carries data safely across it, when crossing it genuinely can’t be avoided. Done carefully, it preserves everything of value in the data while adapting its shape. Done carelessly, it’s exactly how data gets silently damaged or lost mid-transition.

The Old Way

Before migration scripts were treated as first-class, carefully reviewed artifacts in their own right:

Migrations were frequently written as one-off, throwaway scripts, run once by hand, with no record kept of exactly what transformation had been applied.
There was often no tested rollback path if a migration went wrong partway through, leaving data in an inconsistent, half-migrated state with no clean way back.
Migrations rarely got the same review and testing rigor as application code, even though a bad migration could silently corrupt far more data than a bad application bug ever would.

Treating a migration with the same deliberate care an excavation team gives a fragile artifact is exactly the discipline this article is about.

What’s Changing (and Why AI Is the Reason)

Migration scripts are increasingly version-controlled, code-reviewed, and tested against realistic data before running against production, rather than executed as one-off manual scripts.
This connects to the excavation-and-catalog discipline covered later in this series’ look at the schema registry, where a migration’s target version becomes a documented, traceable destination rather than an ad hoc goal.
AI training pipelines depend on migrated historical data being transformed correctly, not just successfully — a migration that runs without error but silently reshapes values incorrectly can poison a model’s understanding of the past just as effectively as one that fails outright.

The Metaphor, Fully Extended

Moving a Fragile Artifact	Migration Script Concept
Documenting an artifact’s exact position before moving it	Recording exactly what data looked like before migration
Supporting and encasing the artifact for transit	Testing a migration thoroughly before running it against real data
A planned, deliberate sequence of movements	A reviewed, version-controlled migration script
A clear plan for what to do if something goes wrong mid-move	A tested rollback path if a migration fails partway through

For Beginners: What to Actually Do

Practice writing migrations as reviewable, version-controlled code rather than one-off scripts run by hand and then discarded.
Always test a migration against a realistic copy of the data before running it against anything that matters.
Get in the habit of asking, before running any migration, what the rollback plan is if something goes wrong partway through.

For Practitioners and Leaders: The Deeper Layer

Require the same code review and testing rigor for migration scripts that your team already applies to application code, since a bad migration is often more damaging.
Track migrations against their target schema version explicitly, so there’s a clear, traceable record of what changed and why.
Prioritize correctness verification, not just successful execution, for migrations touching data destined for AI training pipelines, where silent reshaping is as dangerous as an outright failure.

Quick Recap

A migration script transforms existing data from an old schema shape into a new one, deliberately and safely.
Historically, migrations were often one-off scripts with no rollback plan and little review.
Treating migrations as reviewed, version-controlled code prevents the silent damage careless migrations can cause.
AI training pipelines need migrations that are correct, not just successful, since silent errors can poison a model’s understanding of history.

Where This Fits in the Series

Article 6 covered the fault line a breaking change creates. This article covered the careful excavation work — migration scripts — that carries data safely across it. Article 8 looks at where every documented layer, and every migration between them, actually gets recorded: the schema registry.