Key takeaways
- Review the migration for safety, not for style, and record the evidence behind the decision.
- Map additive and destructive changes separately, then check old and new code compatibility.
- Plan the backfill with a batch size, rate limit, stop condition, and a way to verify counts.
- Set a lock and timing budget from measured behavior, not from a remembered rule.
- Name the rollback limit and rehearse on a representative copy before the production window.
What the review must decide
A schema migration review decides whether a change can run safely, not whether the SQL looks elegant. The reviewer needs the affected tables, the expected row counts, the lock behavior, and the rollback path. Without those facts, the review becomes a style discussion while the real risk stays hidden. The decision should be recorded with the evidence that supported it.
The review also decides who owns each step. A migration may be written by the pod, approved by the buyer, and executed by a platform engineer. Naming those roles prevents the common failure where everyone assumes someone else has checked the backup. Write the names in the change record, not in a meeting note. The review is a decision record, not a performance review of the author.
Map the schema change
Describe each change in plain language: a new column, a dropped index, a changed type, or a new constraint. State which application versions read and write the table. Include the estimated size and the busiest time of day. A migration that is trivial on a small table can be dangerous on a large one.
Separate additive changes from destructive ones. Adding a nullable column is usually easier to reverse than dropping a column that still has readers. Renaming a column is a destructive change disguised as a small edit. Group the changes by risk so the reviewer can focus on the ones that can lose data.
Check compatibility in both directions
During a rolling deploy, old and new code run at the same time. The schema must support both versions for the length of the rollout. Check that old code can read the new shape and new code can tolerate the old shape. If either direction fails, the deploy needs a different sequence.
Write the compatibility window and the condition that ends it. A column can be removed only after every reader has moved. Record how the team will confirm that. A removal based on a search of the repository is not proof that no external consumer uses the field.
Plan the data backfill
A backfill is a separate change with its own risk. State the batch size, the rate limit, the retry behavior, and the stop condition. A backfill that runs without a limit can saturate a database that is also serving users. Keep it idempotent so a retry does not double-write.
Decide how to verify the backfill before it finishes. Compare counts, sample rows, and the application view of the data. Record the query and the expected result. If the numbers do not match, the plan should say whether to pause, roll back, or continue with a known gap.
Set the lock and timing budget
Ask what locks the migration takes and for how long. A brief lock on a hot table can still cause a visible outage. Check the database version because the same statement can behave differently across versions. Use the vendor documentation rather than a remembered rule.
Choose a window that matches the measured impact. Include time for the change, the verification, and the rollback decision. Do not schedule a migration at the end of a shift when the reviewer is about to leave. A change that needs a follow-up should not begin without the follow-up owner available.
Prepare the rollback
Define what rollback means for the schema and for the data. Some changes can be reversed with a statement, while others require a restore or a forward fix. State which case applies and how long the reverse takes. A backup that has never been restored is an assumption. A short lock is still a lock, and the queue behind it matters. Measure the wait, not only the statement duration.
Record the last safe point and the person who can authorize the reverse. If the migration already wrote data that the old schema cannot hold, a rollback may lose information. Say so before the change, not during the incident. The approver should accept that limit explicitly.
Assign evidence and approvals
Give the reviewer a small evidence pack: the migration file, the test run, the row counts, the lock estimate, and the rollback note. Link the ticket and the deploy record. The pack should be readable in a few minutes and complete enough to answer the obvious questions. The reviewer should be able to see the evidence without opening a second tool during the approval call.
Name the database owner, the application owner, and the person who will execute the change. If one person holds several roles, record that fact rather than pretending the separation exists. The review is stronger when the real decision path is visible. If the separation is impossible, say so and add a second check that covers the missing independence.
Rehearse and review
Run the migration against a representative copy before the production window. Use a data set with realistic size and distribution, not an empty schema. Time the run and watch the locks. If the rehearsal is not possible, reduce the scope or add a stronger stop condition.
After the change, compare the estimate with the actual time and impact. Record the surprises and update the review checklist. A migration review improves through specific corrections, not through a general promise to be more careful next time. Write the correction in the checklist so the next reviewer benefits from the same surprise.
Questions about assessing Philippine developers
Can a migration review happen after the code is written?
Yes, but the review should still happen before the production window. Early review is better because it can change the design while the change is still cheap to revise.
Who should approve a destructive change?
The database owner and the application owner should both accept the limit. If data can be lost, name the person who accepts that risk and record the reason.
What if a representative copy is not available?
Reduce the scope, add a stronger stop condition, or move the change to a maintenance window with more oversight. Do not treat an untested migration as routine.
