---
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>`.