feat(server): document and guard migration ORDER maintenance (#30997)

feat(server): add a migrations ORDER manifest

docs/docs/developer/database-migrations.md

@@ -10,6 +10,13 @@ mise //server:migrations generate <migration-name>
 
 2. Check if the migration file makes sense.
 3. Move the migration file to folder `./server/src/schema/migrations` in your code editor.
+4. Run the command
+
+```bash
+mise //server:migrations sync-order
+```
+
+The last step adds the migration to the `ORDER` manifest, which records the order migrations run in. It is committed so that two branches adding a migration conflict in git instead of silently merging out of order, which would stop the server from starting for anyone who ran them in the wrong order.
 
 The server will automatically detect `*.ts` file changes and restart. Part of the server start-up process includes running any new migrations, so it will be applied immediately.
 

server/mise.toml

@@ -78,4 +78,5 @@ run = [
 run = [
   { task = ":ci-unit" },
   { task = ":ci-medium" },
+  { task = ":migrations", args = ["verify-order"] },
 ]

server/package.json

@@ -31,6 +31,8 @@
     "migrations:create": "sql-tools -u ${DB_URL:-postgres://postgres:postgres@localhost:5432/immich} migrations create",
     "migrations:run": "sql-tools -u ${DB_URL:-postgres://postgres:postgres@localhost:5432/immich} migrations run",
     "migrations:revert": "sql-tools -u ${DB_URL:-postgres://postgres:postgres@localhost:5432/immich} migrations revert",
+    "migrations:sync-order": "sql-tools migrations sync-order",
+    "migrations:verify-order": "sql-tools migrations verify-order",
     "schema:drop": "sql-tools -u ${DB_URL:-postgres://postgres:postgres@localhost:5432/immich} query 'DROP schema public cascade; CREATE schema public;'",
     "schema:reset": "pnpm run schema:drop && pnpm run migrations:run",
     "email:dev": "email dev -p 3050 --dir src/emails"