sync: auto-sync from GURU-5070 at 2026-06-10 20:18:48

Author: Mike Swanson
Machine: GURU-5070
Timestamp: 2026-06-10 20:18:48

.claude/memory/reference_sqlx_migrations_immutable.md

@@ -0,0 +1,33 @@
+---
+name: reference_sqlx_migrations_immutable
+description: 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.
+metadata:
+  type: reference
+---
+
+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>`
+  then `sudo systemctl start <svc>`.