How to review an AI-written database migration

For an AI-written database migration, review the sequence of states the system will actually pass through. Ask whether the old application can run with the new schema, whether new code can run before every row is backfilled, and what happens if the deploy stops halfway. A migration file that works on an empty test database answers none of those questions.

Consider a PR that adds account_id to orders and eventually makes it required. Existing orders have no value for that column. A safe review has to account for the code, data, and deployment order, not just the ALTER TABLE statement.

Write down the rollout sequence

Ask the author to name each deployable step: add a nullable column, write it for new orders, backfill existing orders, verify the result, switch reads if needed, and only then enforce NOT NULL. The exact sequence depends on the repository and database. The point is to make each intermediate state explicit so you can check it against the real deploy process.

Look for the application version that is live while the migration runs. If old code continues to insert orders without account_id, a NOT NULL constraint in the first deploy can break writes. If new code reads the column before the backfill completes, it needs a defined behavior for null rows. Ask which step makes every writer compatible and which step removes that temporary behavior.

Review Assist's Intent Document records requirements and assumptions, while its guided tour anchors the explanation to changed hunks. Use those as a map: find the migration, every writer, every reader, and any deployment configuration changed by the PR. An anchored tour is an explanation of the diff, not proof that the rollout order is safe.

Check the backfill against real data

For orders.account_id, ask where the value comes from for historical orders. Is there a reliable relationship to an account, or are some rows genuinely ambiguous? Do not approve a default account ID merely because it makes the constraint pass. The owner of the data rule needs to decide what those rows mean.

Inspect how the backfill runs on the expected table size. A single transaction over millions of rows may hold locks or create more load than the release window allows. A batched job needs a stable cursor, a way to resume, and idempotent updates so a retry does not overwrite a corrected value. Ask for the query or job and the expected row count; then check the actual database's locking and migration behavior rather than assuming one engine's behavior applies to another.

Verification should name the invariant, not just say that the migration ran. For this example, useful evidence is a count of orders still missing account_id, a check that every populated value points to the intended account, and a test that writes continue while old and new application versions overlap. If those checks have not run, keep them visible as open work. The guide to reviewing an untested path covers how to make that gap actionable.

Ask what can be reversed

Rollback is different at each step. Before enforcing the constraint, reverting application code may be possible if the old version ignores the added nullable column. After new writes depend on it, or after a column is dropped, rolling back code can lose behavior or data. Ask the author to state the last reversible step and the recovery action beyond it, including whether the team would roll forward instead of running a down migration.

Be especially cautious when a PR combines adding, backfilling, enforcing, and deleting old fields in one release. Separating those steps gives reviewers a chance to observe data before removing the compatibility path. If the team intentionally ships them together, the PR should explain its deployment guarantees and failure recovery, with an owner accepting that risk.

Use the review to request one concrete proof

Read verification.performed and verification.not_verified in the committed document or guided review. Match each claimed check to the final code and to the migration state it exercises. Review Assist's local validator checks document structure, diff coverage, staleness, cross-references, and likely secret patterns. The GitHub App recounts coverage on the PR. Neither check runs the migration or proves that a backfill is correct.

A useful comment on the example would be: “The first deploy adds account_id as required, but the currently deployed writer still inserts without it. Can we add it nullable first, show the backfill query and remaining-null count, then enforce the constraint after all writers have changed? Please also state how we recover if the backfill stops halfway.” That request names the failure mode, evidence, and rollout decision.

Before approval, you should be able to point to a compatible sequence, a rule for historical rows, evidence for the transitional state, and a recovery plan. If one is missing, ask for that specific piece. A generic database migration checklist will not settle a question that depends on this repository's deploy order and data.