From 1a95d81a3fb46f344b0d0dcdad8c4f83ccaec204 Mon Sep 17 00:00:00 2001 From: Lucas Berger Date: Wed, 10 Jun 2026 09:16:30 -0400 Subject: [PATCH] docs(quick-260610-cr8-01): repoint deployment.md to generate+migrate, warn against push - Step 3: replace drizzle-kit push command with drizzle-kit migrate - Step 3: rewrite description from 'push schema once' to 'apply committed migrations' - Step 3: add warning callout explaining MariaDB false-truncate foot-gun - Step 3: add note on db:generate workflow for future schema changes - Step 6: change push reference to drizzle-kit migrate (Step 3) --- docs/deployment.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/docs/deployment.md b/docs/deployment.md index 2cc36c2..12aa843 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -140,17 +140,27 @@ APP_PASSWORD_ENCRYPTION_KEY=<64-hex> ## Step 3 — Apply the database schema -The image does not auto-migrate. Bring up MariaDB and push the Drizzle schema once: +The image does not auto-migrate. Bring up MariaDB and apply the committed migrations once: + +> **WARNING — do NOT use the `push` subcommand of drizzle-kit on this MariaDB.** +> The `mysql` dialect misreads MariaDB 11.x metadata and schedules a false truncate/recreate +> that **wipes data**. The `push` workflow has been removed from the project scripts for this +> reason. Always use the committed-migration path: `db:generate` to author a new migration +> (diffs `schema.ts` against committed JSON snapshots, never the live DB), `db:migrate` to apply it. ```bash docker compose up -d mariadb # from the repo root, host-side (dev override exposes 3306): docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d mariadb DB_HOST=127.0.0.1 DB_PORT=3306 DB_USER=familysync DB_NAME=familysync DB_PASSWORD= \ - pnpm --filter @familysync/api exec drizzle-kit push + pnpm --filter @familysync/api exec drizzle-kit migrate # verify: SHOW TABLES; -> users, member_credentials, calendars, calendar_events ``` +To author a future schema change: edit `apps/api/src/db/schema.ts`, run +`pnpm --filter @familysync/api run db:generate` (diffs schema against committed snapshots — no DB +connection needed), commit the generated SQL, then apply with `db:migrate`. + --- ## Step 4 — Pangolin route + Newt connector @@ -203,7 +213,7 @@ Then proceed to Gate 2 verification through the public URL. 3. Add the `newt` service to the production compose (or run as a separate Unraid container) bound to the production Pangolin site. 4. Use a named Docker volume for `mariadb_data` on the array (not a throwaway volume). -5. `docker compose up -d --build`, then `drizzle-kit push` once (Step 3) against the prod DB. +5. `docker compose up -d --build`, then `drizzle-kit migrate` once (Step 3) against the prod DB. 6. Register the **production** Authelia client (`client_id: familysync`, prod redirect URI) if you used `familysync-dev` for Mode A.