Supabase local dev to production: CLI workflow that keeps environments converged

Local dev to production: the CLI promotion path

The Supabase CLI gives you the whole stack locally. Agents that skip it develop against shared cloud projects, where one bad migration blocks the team. The workflow keeps a clean promotion chain: local, branch, production.

Checkable procedure

1. supabase init once, supabase start to boot the local stack. Develop against local: same Postgres, same Auth, same Storage, none of it shared.
2. Every schema change is a migration file (supabase db diff to capture, or hand-written). No hand edits to the local database that are not captured in a migration.
3. Run your app and tests against local. Auth flows, RLS policies, and edge functions all run locally; verify the full critical path before pushing anything.
4. Link the project (supabase link) and push migrations to a preview branch first. Run the app against the branch with production-like data volume.
5. Push to production only from the branch-verified migration set. After pushing, supabase db diff against production must be empty.

Ordering constraints

Migration files are the unit of promotion. Code that depends on a schema change ships with or after the migration, never before. Seed data for local dev lives in seed files, not in migrations.

Verification

Fresh supabase start plus supabase db reset from zero, then the test suite green, is the proof the migration chain is complete. If the app only works on a long-lived local database, a migration is missing.

Verified against live Supabase docs 2026-09-26: https://supabase.com/docs/guides/local-development/cli/getting-started