The migration that almost ate a taxonomy

A client's platform depended on one database table nobody had looked at closely in years. It held the industry taxonomy the entire application used to categorize and route data. The table's own documentation called it "empty (verified)."

That line was wrong. And a routine migration was about to trust it.

#The setup

The client was running a production database migration, the kind of change that looks routine on paper: alter some structure, move some data, ship it. The migration script came with its own safety claims already written in, including a note that the table in question, the one holding the taxonomy, was empty and therefore safe to touch without a special backup pass.

Nothing about the migration looked unusual. That's exactly the kind of change that gets rubber-stamped.

#What we caught

Before anything ran against production, we checked the migration's safety claims against the live database itself, not against what the documentation said, against what was actually there.

It wasn't empty. The table held the authoritative industry taxonomy the client's platform depended on to function. If the migration had run as written, that data would have been gone, along with every downstream process that relied on it to categorize and route information correctly.

The gap wasn't a bug in the migration logic. The logic was fine. The problem was a false claim about the state of the data it was about to touch, and nobody had verified that claim before it became the basis for a production change.

#What we did about it

We held the migration. No partial run, no "let's just see what happens." It stopped until the underlying claim was fixed, not just noted.

Then we:

1. Added a proper backup pass for the table, which the original migration plan had skipped because it assumed there was nothing there to back up.
2. Corrected the migration to include the real dataset instead of proceeding as if the table were empty.
3. Had the corrected migration independently re-verified before it touched production, so the fix itself wasn't running on the same kind of unverified confidence that caused the problem in the first place.

Only after that re-verification did the migration run.

#Why this is the whole point

Nothing about this required exotic tooling. It required checking a documented claim against reality before treating it as true, and having a process in place that makes that check the default, not something that only happens if someone happens to think of it.

That's the discipline behind how we work: no claim ships on confidence alone. Documentation, comments, and even a migration's own stated assumptions get verified against what the system is actually doing before anything touches production. It's the same posture we bring to takeovers of software nobody currently understands, and to ongoing operations for clients who need someone watching the plumbing continuously, not on a sprint schedule.

The client never saw an outage, a data-loss incident, or a scramble to reconstruct a taxonomy from backups that didn't exist. They saw a migration that shipped a day later than planned, with a note explaining why. That's the trade we make on purpose, every time.