From eaf2398c7ac66675f0e4b470c1db7f7315ccf65e Mon Sep 17 00:00:00 2001 From: rob thijssen Date: Wed, 22 Apr 2026 12:36:52 +0300 Subject: [PATCH] docs(generic): document migration immutability and sequential versioning MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Migrations are sequentially numbered and frozen once committed. Editing an already-landed migration causes checksum divergence and migration-runner failures at deploy time — new changes must go in new files. Call this out explicitly so contributors don't quietly break a service by "fixing" a prior migration in place. Co-Authored-By: Claude Opus 4.7 (1M context) --- generic.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/generic.md b/generic.md index 2be58dc..ef2bb33 100644 --- a/generic.md +++ b/generic.md @@ -180,7 +180,9 @@ Default for any app with a central data store. - Connection is **mTLS with passwordless auth**. Host-level client certificates issued by the internal step-ca, with cert CN → pg role mapping via `pg_ident.conf`. - No passwords in config files, ever. Connection strings reference cert paths. - Migrations via `sqlx-cli` or `refinery`; migration files live in `crates/-data/migrations/`. +- **Migrations are sequentially versioned and immutable once committed.** File naming follows the tool's convention (`V0001__init.sql`, `V0002__add_users.sql`, … for refinery; `0001_init.sql`, `0002_add_users.sql`, … for sqlx). Each new schema change lands as a **new** file with the next sequence number — **never** edit a migration that has already been committed, even if it hasn't been deployed yet, because checksums diverge and the migration runner will refuse to start (or worse, leave production out of sync with dev). - Schema changes are forward-only in production. Destructive migrations require a dedicated maintenance window and an explicit plan. +- If you catch a bug in a recently-added migration *before* it's been merged or deployed anywhere, amending is fine — but the moment it's landed on `main` or run against any database, treat it as frozen and write a follow-up migration to correct the mistake. - Use `sqlx` with compile-time query checking (`sqlx prepare`) and commit the generated `.sqlx/` offline query cache so CI builds don't need a live database. - **Agentic contributors working in a project with a Postgres dependency will usually have MCP access to a Postgres MCP server scoped to that project's database(s).** Prefer using the MCP server to inspect schema, verify query shapes against real tables, and sanity-check migrations before applying them — don't guess at column names or types when you can look them up. The scope is limited to the project's own databases; don't assume access to unrelated ones.