Skip to main content
Use this when a Supabase project should keep Supabase paths and platform-managed schemas while supaschema owns generation, safety gates, generated outputs, and guarded apply orchestration. In this setup, supaschema sync uses the Supabase CLI adapter by default. The existing Supabase CLI project link, access token, project ref, and database password remain the credential lane. Use supabase db push directly only when a separate deployment process intentionally owns apply.

​
Use this when

  • The repository already has a supabase/ directory.
  • Migrations should stay in supabase/migrations.
  • Schema files should live in supabase/schemas.
  • Platform schemas such as auth, storage, and realtime should stay protected.

​
Do this

Use the scaffolded Supabase defaults or set the same paths in supaschema.config.json:
Generate, check, and apply through guarded sync:
The installed default lets target config select at most one target for bare sync. For remote deploys, set one remote target to mode: "auto" and provide the target’s approval environment variable in the deployment job. Multiple automatic targets are refused before any runner can mutate a database. Use --target <name> only for an explicit one-target operator override.

​
Verify

Use bare PostgreSQL plus Supabase stubs for disposable verification:
Before adopting an existing project, confirm the tree and database agree:

Docker-free diff

Generate Supabase migrations without a local stack.

Sync command

Run safety gates, target reconciliation, and selected runner apply.

Migrations command

Reconcile disk files with applied history.

RLS safety

Review policy predicate changes explicitly.
Last modified on June 24, 2026