docs: fill migration-workflow gaps found in final review

CLAUDE.md:
- Add the one-time `prisma migrate resolve --applied 0_init` baseline
  step that must run before the first `migrate deploy` against any
  environment (o2switch production included) whose conversion_jobs
  table predates Prisma. Without it, migrate deploy tries to
  CREATE TABLE against a table that already exists and fails, leaving
  migration history stuck.
- Document the actual, tested result of `prisma migrate dev` against
  the local dev DB: it fails with P3014 because convert_user lacks
  CREATE DATABASE/DROP DATABASE privileges needed for the shadow
  database. Document the verified fallback (`migrate diff
  --from-migrations ... --to-schema-datamodel ...` + manual migration
  folder + `migrate resolve --applied`) as the supported way to create
  new migrations here.

README.md:
- Local development step 2 referenced the deleted db/schema.sql;
  replaced with the real `prisma migrate deploy` invocation, which
  creates conversion_jobs fresh on an empty local database. Reordered
  so `npm install` runs first, since the migrate command needs
  node_modules/@prisma/client.
- Deployment on o2switch: added the same one-time baseline step
  (clearly marked, not to be repeated) before the first migrate
  deploy on that server, and added `prisma migrate deploy` to the
  "every subsequent deployment" checklist, after npm install and
  before restarting the app.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
2026-07-31 01:54:23 +02:00
co-authored by Claude Sonnet 5
parent c42fe68b36
commit 3c0de7e742
2 changed files with 26 additions and 5 deletions
+6 -3
View File
@@ -3,8 +3,8 @@
## Local development
1. Copy `.env.example` to `.env` and fill in your local MariaDB credentials.
2. Apply the schema: `mysql -h <host> -u <user> -p <database> < db/schema.sql`
3. Install dependencies: `npm install`
2. Install dependencies: `npm install`
3. Export those same `DB_HOST`/`DB_USER`/`DB_PASSWORD`/`DB_NAME` values from `.env` into your shell, then apply the schema with Prisma Migrate (creates the `conversion_jobs` table fresh, since a new local database starts empty): `DATABASE_URL=$(node scripts/printDatabaseUrl.js) npx prisma migrate deploy`
4. Run the API: `npm start`
5. Run the worker (separate terminal): `npm run worker`
6. Run tests: `npm test` (requires the same MariaDB reachable via your `.env` vars, exported into the shell)
@@ -19,4 +19,7 @@
6. Add a cPanel cron job to run the cleanup script periodically, e.g. every 15 minutes:
`*/15 * * * * cd /home/gaan6043/convert.ombrora.com-node && /home/gaan6043/nodevenv/convert.ombrora.com-node/24/bin/node src/cleanup.js > /dev/null`
(adjust the path and node binary location to match your actual account — check with `which node` over SSH).
7. On every subsequent deployment: pull changes, `npm install`, `npm run build` (frontend), then restart the Passenger app from cPanel and `pm2 restart convert-worker`.
7. **ONE-TIME, before ever running `prisma migrate deploy` on this server:** the o2switch database already has the `conversion_jobs` table (created by hand, before this project used Prisma), but no `_prisma_migrations` tracking table. Running `migrate deploy` first would try to `CREATE TABLE conversion_jobs` again and fail with a "table already exists" MySQL error, leaving Prisma's migration history stuck and needing manual recovery. Avoid that by baselining the existing table once, ever, on this server, before step 8's `migrate deploy` runs for the first time:
`DATABASE_URL=$(node scripts/printDatabaseUrl.js) npx prisma migrate resolve --applied 0_init`
Do **not** repeat this step on later deployments — after this one-time run, `migrate deploy` (step 8) is the correct command going forward.
8. On every subsequent deployment: pull changes, `npm install`, apply any pending migrations with `DATABASE_URL=$(node scripts/printDatabaseUrl.js) npx prisma migrate deploy`, `npm run build` (frontend), then restart the Passenger app from cPanel and `pm2 restart convert-worker`.