Migration workflow

Migrations are plain SQL files in supabase/migrations/, applied in filename order. The Supabase CLI is a workspace devDependency; scripts/supa wraps it.

Caution

Per-git-branch isolation is currently disabled (free Supabase plan — see Branching & deployment). Every branch targets the same shared movement-mapping-dev project directly, so ./scripts/supa db push from a feature branch applies for real, immediately, to the project everyone else’s local dev also points at. Coordinate schema changes accordingly.

Authoring a migration

pnpm db:new add_something      # creates a timestamped .sql file
# edit the new file
./scripts/supa db push         # applies it to the shared dev project

pnpm db:migrate is a shortcut for scripts/supa db push. Run the app against the same project with ./scripts/supa pnpm dev.

The safety guard

scripts/supa previously refused migrations on protected branches (main/master/dev/develop). That guard is temporarily disabled — since every branch already targets the same shared project with no isolation, blocking main added friction without adding real safety. db push/db reset/etc. now run on any branch, including main; take care to know what you’re applying. The guard is commented out in scripts/supa and will be re-enabled alongside real per-branch isolation once the project moves to Supabase Pro.

Who can apply where

Action	Developer	CI
Apply to movement-mapping-dev (from a feature branch)	✅	✅
Apply to movement-mapping-prod	❌	✅
Author new migrations	✅	✅

Validating locally (optional)

The migrations reference auth.users and auth.uid() (provided by Supabase). To test them against a throwaway Postgres, create a small auth stub (schema auth; table auth.users(id uuid primary key); function auth.uid()), then apply the files in order with psql -v ON_ERROR_STOP=1.

If you change the schema, also update Database schema.