Testing Migrations

deploy.sh

@@ -63,21 +63,44 @@
 #
 # Then set DB_USER=app and DB_PASS=<password> in ~/.env. Note the asymmetry:
 # the admin scripts here (backupDatabase.sh, applyLastBackup.sh,
-# applyScrapeSchema.sh) still connect as root with $PROD_DB_PASS.
+# migrateDatabase.sh) still connect as root with $PROD_DB_PASS.
 #
 # DELETE is genuinely required -- the scraper drops shell attachment rows for
 # dead links and purges expired cache entries.
 #
 # --- schema changes ------------------------------------------------------
 #
+# Schema is managed by Prisma, for migrations and scaffolding ONLY -- the
+# running server never imports it and still talks to MariaDB through raw SQL.
+# The schema lives in prisma/schema.prisma; migrations in prisma/migrations/.
+#
 # Because the app holds no DDL, a deploy that introduces schema changes needs
 # one manual step, run once per environment as a database admin:
 #
-#   ./applyScrapeSchema.sh
+#   nix-shell shell.nix --run ./migrateDatabase.sh
 #
-# It is idempotent, so re-running is safe. The API verifies the schema and the
-# grants at boot; if either is missing it logs the remedy and serves normally
-# with link previews disabled.
+# nix-shell is required: the prisma CLI comes from nixpkgs (prisma_7, 7.8.0),
+# not from node_modules. Alternatively add prisma_7 to the server's
+# environment.systemPackages and call the script directly.
+#
+# It is idempotent, so re-running is safe. On a database that predates Prisma
+# the script detects the missing migration history and baselines it
+# automatically (marking 0_init applied rather than executing it) -- it does
+# NOT need to be done by hand.
+#
+# The API verifies the schema and the grants at boot; if either is missing it
+# logs the remedy and serves normally with link previews disabled.
+#
+# NEVER run `prisma migrate dev`, `prisma migrate reset` or `prisma db push`.
+# The first wants a shadow database; the latter two can drop data.
+#
+# DATABASE_URL is composed by the script from the admin credentials in ~/.env
+# and is never read by the application.
+#
+# Note: _prisma_migrations lives inside the `application` database, so the
+# least-privilege `app` user can write migration history (its grant is
+# database-wide). It holds no DDL, so it cannot reshape tables -- narrowing
+# this further would mean per-table grants, which is a separate project.
 #
 
 set -euo pipefail