Every migration project starts with the same sentence: "It should be straightforward — we just need to move it over." Six weeks later, the team is knee-deep in undocumented business logic, implicit data contracts, and a production freeze that nobody planned for.
We have run enough migrations to know that the danger is not technical. It is definitional. "Simple" means different things to different stakeholders, and those definitions rarely survive contact with the actual codebase.
What migration scoping actually looks like
Before writing a line of migration code, we spend time on three activities:
- Data archaeology. We read the schema — all of it — and document every foreign key, every nullable column that the application treats as non-null, and every column whose name does not match its actual usage.
- Traffic analysis. We look at query logs to find what is actually being called versus what the documentation says should be called.
- Rollback planning. We design the rollback before we design the migration. If you cannot reverse it safely, you cannot ship it safely.
This upfront investment typically adds two to three days to a scoping engagement. It has saved clients from multi-week production incidents more than once.