link,[object Object]
ACQM Docs

Appearance

Database Lifecycle & Migrations ​

Purpose: How we manage schema changes, seeding, backups, and rollbacks. Audience: Developer, Admin Prerequisites: Supabase CLI; linked project; local stack if needed.

Link & start

bash
supabase login
supabase link --project-ref YOUR_SUPABASE_PROJECT_REF
supabase start   # local stack

Create migrations

bash
# Diff local DB against remote or current schema snapshot
supabase db diff -f 2025XXXX_add_feature

# Or create an empty migration file
supabase migration new add_feature_table

Apply migrations

bash
# Local
supabase db reset        # drops DB and re-applies migrations + seed
# Or
supabase db push         # apply migrations without reset

# Remote (be cautious)
supabase db push --linked

Seed data

bash
# Seed scripts
psql < supabase/seed.sql        # basic seed
psql < supabase/seed.full.sql   # full seed (if needed)

Backups & snapshots

  • Files: supabase/backups/remote-schema.sql, supabase/backups/remote-data.sql
  • Export current schema/data from Supabase dashboard or CLI
  • Keep compressed backups under supabase/backups/ for reproducibility

Edge Functions deploy

bash
supabase functions deploy <name>
# list
supabase functions list

Policies (RLS)

  • Maintain policy changes in migrations
  • Validate via psql and unit tests (see docs/architecture/access-control.md for patterns)

Checklist before pushing remote

  • Migrations re-run cleanly on a fresh DB (supabase db reset)
  • Seeds apply without errors
  • RLS allows app flows (guest browse, user updates, admin views)
  • Add relevant indexes for new filters (see docs/architecture/search-indexing.md)

Rollback plan

  • Keep prior backups timestamped
  • Revert to a prior migration commit and db reset locally to confirm
  • For remote rollback, apply a reversing migration (down migration) or restore from backup

Redaction & secrets

  • Do not commit project ref or keys in docs/code; use placeholders
  • Rotate credentials after migration windows where required