Use ordered SQLite migrations (Refs #75)

docs/development/README.md

@@ -220,6 +220,22 @@ retained across restarts; interrupted transactions roll back and retry on startu
 The one-time vacuum needs disk space for a temporary database copy. **Do not
 remove `cherry.db-wal` to recover from an interrupted upgrade.**
 
+Database upgrades are ordered in `src/lib/server/db/migrations.ts` and tracked by
+SQLite's `PRAGMA user_version`. Startup applies only pending versions, including
+host, authentication and game-file schemas, before serving requests or starting
+workers. Databases from older releases begin at version 0; the compatibility
+steps honor their existing migration markers so completed backfills are preserved.
+An application cannot open a database with a newer version than it supports.
+
+For a schema or data upgrade, append a consecutive version to that list. Do not
+edit an applied migration or rely on changing `schema.sql` to upgrade databases.
+Each step and its version commit in one transaction. Table rebuilds can select
+`foreign-keys-off`, which disables enforcement before the transaction and checks
+references before committing. The resumable incremental-vacuum step uses
+`autocommit` because SQLite forbids `VACUUM` inside a transaction; its version is
+recorded only after the rebuild and host preparation boundary recovery succeed.
+Connection tuning and query optimization still run on every open.
+
 The controller uses a 128 MiB page cache; each reader worker uses 32 MiB.
 Main-database migrations use 16 MiB with memory mapping disabled. Temporary
 storage stays disk-backed. Containers use `/data/.sqlite-tmp` for scratch files;