Database migration review

Why reviewed migrations still break deployments

A migration and the code that uses it can both be correct. The failure happens during the rollout, while old and new versions of the service share one database.

A change to a migrations directory, a SQL file, or a schema file adds the datastore compatibility domain to the review. The review then asks which readers and writers will meet the new schema, and when.

Dropping a column too early

Take an illustrative pull request that removes the legacy_status column and the code that read it. The tests pass against the new schema.

In production, the service deploys with a rolling update on ECS. Tasks from the previous task definition serve traffic until their replacements are healthy, and they still select legacy_status.

A finding names the query the pull request removes and the rollout setting that keeps the old tasks running. It suggests splitting the change across two releases: stop reading the column, then drop it.

What the review relies on

The code comes from the exact commit under review, including the lines it removes. Rollout facts come from your environment, such as ECS services and task definitions, Kubernetes deployments, or Cloud Run revisions.

Proofline reads database configuration from the cloud control plane, such as RDS and Cloud SQL instance settings and versions. It does not connect to your database or read its rows.

Without one of these facts, the review reports as incomplete and names the source it lacks. See how a review works.

Questions

Does Proofline connect to my database?

No. Proofline reads database configuration from the cloud control plane, such as RDS and Cloud SQL settings. It never reads your rows.

Which migration tools does Proofline support?

Proofline reviews the migration files in the pull request, whatever tool runs them. A change to a migrations directory, a SQL file, or a schema file brings datastore compatibility into the review.

What is an expand and contract migration?

An expand and contract migration splits a breaking schema change across releases. First add the new structure and move the code to it. Remove the old structure only after no running version uses it.