2.2 KiB
name, description, metadata
| name | description | metadata | ||
|---|---|---|---|---|
| reference_sqlx_migrations_immutable | NEVER edit an already-applied sqlx migration file — even a comment. sqlx::migrate! checksums each file at compile time and validates against _sqlx_migrations at startup; a changed checksum crash-loops the server with "migration N was previously applied but has been modified". Code review MUST flag any edit to an applied migration. |
|
GuruRMM and GuruConnect both apply DB migrations at server startup via sqlx::migrate!()
(embedded at COMPILE time from server/migrations/). sqlx stores a checksum of each migration
in the _sqlx_migrations table when it first applies it, and on every startup re-validates the
embedded migration files' checksums against that table.
Editing an already-applied migration file — even just a COMMENT — changes its checksum and the server fails to boot:
ERROR Failed to run migrations: migration 8 was previously applied but has been modified
systemd then crash-loops it and eventually trips the start-limit ("Start request repeated too quickly").
Incident 2026-06-01 (GuruConnect): a one-line ON CONFLICT fix in server/src/db/machines.rs
was bundled with a comment-only edit to server/migrations/008_machine_uid.sql. The code fix was
correct, but the migration comment edit took the relay down for ~6 min on deploy. Both the Coding
Agent and the Code Review Agent explicitly judged the comment edit "zero runtime effect" — WRONG.
Rules:
- Applied migrations are immutable. Never touch them. To change schema, write a NEW migration.
- If documentation about a migration needs fixing, put it in code comments / docs, NOT the migration file.
- Code review must reject ANY diff that touches a file under
server/migrations/that has already been applied in prod (or require a brand-new migration instead). - Recovery: restore the migration's exact original bytes (
git checkout <prev> -- path/to/NNN.sql), rebuild (sqlx embeds at compile time, so a rebuild is required), restart. If systemd shows "Start request repeated too quickly", clear the limiter first:sudo systemctl reset-failed <svc>thensudo systemctl start <svc>.