Migrations & Drift

## What "schema from the mapping" means A mapping already carries almost everything a `CREATE TABLE` statement needs: which class maps to which table, which field to which column, the declared types and lengths, which field is the key, which associations imply a foreign key, and which fields must be unique. Because that information is machine-readable, most data-access layers can turn it around and **emit the schema instead of reading it**. The question every project has to answer is not whether the layer *can* do that, but **how much of the deployed database it is allowed to touch**, and that is what the modes express. Treat them as a ladder of intrusiveness rather than four unrelated options. ## The four modes | Mode | What it does at startup | Effect on stored rows | Where it belongs | |---|---|---|---| | **Re-create** | Drops the mapped objects and creates them again from the mapping | Everything in those tables is gone | A disposable local database, or a fresh database per test run | | **Auto-alter** | Compares, then applies missing pieces in place — typically additive | Rows survive; new columns arrive empty or defaulted | Local experimentation only; not a deployed environment | | **Validate-only** | Compares and reports; changes nothing; aborts startup on a mismatch | None | Deployed environments, as a drift gate | | **None** | No comparison and no change | None | Deployed environments where something else does the checking | Two of these write to the database and two do not, and that is the line that matters. Re-create and auto-alter are **generators**; validate-only and none are **passive**. ## Why the additive mode is not the safe middle ground Auto-alter looks like a compromise — it keeps your data and quietly fixes what is missing — and that impression is why it causes incidents. - **Nothing was reviewed.** The statements are computed at process start and executed immediately. No one read them, and nothing about the change was agreed before it ran. - **It only moves in one direction.** Because it typically adds rather than removes or narrows, everything the mapping stopped using stays behind: dead columns, stale indexes, constraints nobody wants. Drift accumulates precisely where the mode cannot clean it up. - **Names are invented.** Constraints and indexes it creates get generated names, so the deployed database ends up with objects nobody can refer to reliably later. - **Timing is whatever the process does.** The change runs when the application happens to start, with no consideration of table size or of traffic already hitting that table. - **Several instances may try at once.** When a deployment starts many copies of a service together, each one independently decides the schema needs altering. - **No record survives.** Afterwards there is no artifact saying what ran, so two environments can differ with nothing to compare. Re-create is more obviously dangerous and therefore, oddly, safer: nobody mistakes "drops every table" for something to leave enabled. ## Validate-only and none Validate-only is the mode most deployed services want. It performs the same structural comparison the generator would, then **refuses to start** rather than repairing anything. Its value is that a schema problem becomes one loud failure at startup instead of a confusing error the first time some rarely used query runs. Its limit is equally important: it checks **structure the mapping knows about**, not whether the stored data suits the new shape, and typically it does not object to extra columns the mapping never mentions. None is the honest choice when a separate gate already covers the same ground, or when the mapping deliberately describes only part of a larger shared database. ## The usual environment gradient 1. **Laptop / unit tests** — re-create against a throwaway database, because rebuilding from the mapping is faster than maintaining fixtures. 2. **Shared development or integration** — scripts, so the environment behaves like the real one. 3. **Staging and production** — reviewed migration scripts own the schema outright; the layer runs validate-only or none. ## What none of the modes do No mode moves data. Generation emits structure — tables, columns, keys, indexes — and never the statements that populate a new column or reshape existing values; designing that work is a separate concern. A generated schema also cannot express what the mapping does not model, such as storage options, partitioning or specialised index shapes. And a passing validation is not a guarantee that the rows in those tables are meaningful — only that the structure the mapping requires exists.