evolving-database-schemas
Guides changing a stored schema without breaking a running version: expand, migrate, verify, then contract, each step shipped and proven before the next, with migrations explicit and reversible until the contract.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- evolving-database-schemas
- description
- Guides changing a stored schema without breaking a running version: expand, migrate, verify, then contract, each step shipped and proven before the next, with migrations explicit and reversible until the contract.
- when_to_use
- Use when designing or writing a change that adds, renames, splits, or removes a column, table, index, or constraint, or that backfills stored data.
- compatibility
- Requires read access to the schema, its migrations, and the code that reads and writes the store.
03 SKILL.md 正文
Evolving Database Schemas
The standards own the rules. Release Cutover requires migrations to be explicit, never run at startup, and a release that carries one to wait for an expand, migrate, and verify sequence that keeps the previous version able to read. Test-Driven Development governs the tests each step adds. This skill covers the judgement of sequencing a schema change so that both the old and the new version of the code keep working at every moment.
Two Versions Run at Once
During any rollout the previous version and the new one read and write the same store, and a rollback brings the previous version back. A schema change is safe only when every version that can be running at that moment understands the store. Renaming a column in one step breaks whichever version expects the other name.
Expand, Migrate, Verify, Contract
- Expand. Add the new shape beside the old: a new nullable column, a new table, a new index built without blocking writes. Nothing reads it yet, and the previous version ignores it. This release is safe to roll back.
- Migrate. Ship code that writes both shapes, then backfill existing rows in bounded, idempotent batches that can stop and resume. Reads still come from the old shape.
- Verify. Prove the shapes agree with a deterministic check, such as matching counts or a query that finds no row where they differ, then switch reads to the new shape in its own release.
- Contract. Only once no running or rollback-eligible version reads the old shape, remove it in a later release. This is the one step that cannot be rolled back, so it waits until the verification has held through a release.
Each step is its own release, and each is proven before the next begins. Collapsing two steps into one release removes the point at which the previous version could still run.
Make Each Migration Explicit and Testable
A migration is a named, ordered, checked-in artifact the release declares, run by a deliberate command, never as a side effect of a process starting. Test it test-first against a copy of the schema at the version it starts from: the migration fails before it exists and passes after, and a second run changes nothing. A data backfill also gets a test that its result matches the verification query.
Constraints Come Last
A new not-null, unique, or foreign-key constraint is added only after the data already satisfies it, and is validated separately from being declared where the store allows, so adding it does not lock the table while it scans.
Before Calling It Ready
- the change is split into expand, migrate, verify, and contract releases, each named;
- every running and rollback-eligible version understands the store at each step;
- every migration is explicit, ordered, tested from its starting schema, and safe to run twice;
- the verification is a command with an expected result, not an inspection; and
- the contract step waits until no version that reads the old shape can run again.
04 同仓库更多 Skills
writing-browser-e2e-tests
Guides writing browser end-to-end tests that find elements as users do, wait on what the action produced, keep page knowledge in page objects, organize one feature per file, and run scenario-backed suites from generated specs.
usability-heuristic-evaluation
Guides judging a running interface as a first-time user would, without its specifications: citing a named principle for every finding, walking each task step, reading labels and addresses for scent, and rating severity.
tooling-nx
Guides Nx workspace work under the Nx standard: selecting projects by the graph, adding a target only where a capability exists, tracing a stale cached pass to its missing input, and answering a module-boundary finding.
programming-typescript
Guides the procedure for writing or changing TypeScript: loading the TypeScript standard first, driving each increment test-first, finding which rule a decision falls under, and confirming the gates before handing off.
programming-shell
Guides shell work under the shell standards: checking the declared dialect first, deciding whether logic belongs in shell at all, tracing where exit-on-error does not reach, and testing the script as its callers run it.
programming-javascript
Guides JavaScript work under the JavaScript standard: confirming the file is type-checked, typing through JSDoc, validating input the checker cannot see, and noticing floating promises and swallowed errors before handing off.