Sauci/docs/operations/database-migrations.md

Database migration safety

The standalone PostgreSQL schema is owned by ordered SQL files under apps/api/drizzle/. Hosted Supabase owns Auth only; its legacy product-data migrations and Edge Functions are retained as cutover history and are not a deployment target.

Required workflow

1. Add the next ordered SQL migration under apps/api/drizzle/.
2. Keep application, repository, shared-contract, and client changes in the same reviewed change where the schema contract requires them.
3. Run npm run verify:full against the dedicated loopback PostgreSQL service.
4. Run infra/backend/verify-production.sh for container and migration startup.
5. Merge to staging; the Dokploy migration service applies the committed files under an advisory lock before the API receives traffic.
6. Prove staging health and affected authenticated behavior before promoting the exact commit from staging to main.

Safety invariants

• Never point local integration tests, reset commands, or disposable verification at a remote database.
• Never deploy apps/supabase/migrations or apps/supabase/functions as part of the standalone backend release.
• Never execute DDL through MCP or provider SQL tools.
• Never edit migration history already applied to a persistent environment; add a forward migration.
• Back up PostgreSQL and private media together before a destructive production migration or data import, and prove restore separately.
• A failed migration must block API startup. Do not bypass the one-shot migrate service to force new code against an old schema.

Production data cutover has additional stop-source, final-sync, parity, legacy media, and authenticated-mobile checks in backend-cutover.md.