34 lines
2.2 KiB
Markdown
34 lines
2.2 KiB
Markdown
---
|
|
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>`.
|