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

TL;DR

Run your app and tests against local. Run the app against the branch with production-like data volume.

Steps

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.
6. 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.

When to use

You are seeing this: The Supabase CLI gives you the whole stack locally. Use this skill when you run into "Supabase local dev to production: CLI workflow that keeps environments converged".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

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