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=<value> \
-  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.