Declarative Schemas | Supabase Features

Declarative schemas define your desired database structure in SQL files alongside your application code. Edit the files, generate a migration, review it, and apply it.

Declarative Schemas 2.0 runs on Supabase's open source diff engine, pg-delta. It covers gaps in the legacy migra engine, including column privileges, security_invoker on views, and publication membership.

The CLI loads your schema files into one temporary Postgres database and replays your migration history into another. pg-delta compares their system catalogs to generate a migration. This comparison never reads your live database.

pg-delta is still in alpha. New CLI projects get it from supabase init. Existing projects turn it on with [experimental.pgdelta] and enabled = true in config.toml.

Key benefits

Version-controlled schema: Keep your schema in supabase/schemas/ and review changes alongside your application code.
Smaller schema diffs: A one-line change to a view appears as one changed line in the schema file. Review the generated migration too before applying it.
Fewer merge conflicts: Separate files for tables, views, and functions help developers work on different objects independently.
Broader coverage: Generate changes for RLS policies, grants, views, partitions, publications, domains, and comments. If your schema includes something the engine cannot track, such as a custom operator or text search configuration, it reports a warning.
Automatic dependency ordering: The engine orders statements for you. You no longer hand-order files in schema_paths.
Supabase-aware diffs: Supabase-managed objects stay out. Your customizations, including profile triggers on auth.users, stay in.

Use cases

Declarative schemas help teams maintain databases with many views, functions, and policies. Developers can edit definitions in place and generate migrations in CI. Existing projects can export their database into schema files to adopt the same workflow.

Supabase CLI workflow

Declarative schemas are part of the Supabase CLI:

Define your schema in SQL files under supabase/schemas/. One file per table works well but the layout is up to you.
Run supabase db schema declarative sync --no-apply to generate a migration for review.
Review the generated SQL, including any statements the CLI flags as destructive.
Apply the migration locally with supabase migration up and push it with supabase db push.
Schema files are plain SQL. Editor tooling such as the Postgres Language Server works on them.

Frequently asked questions

How do declarative schemas differ from migrations?

Migrations record incremental changes. Declarative schemas describe the state you want. The CLI compares your schema files with your migration history and writes plain SQL migrations in supabase/migrations/. Hand-written migrations keep working alongside them.

Do I need to write my own migration files?

The CLI generates schema migrations, but some changes need manual edits. A renamed column, for example, comes out as a drop followed by an add. Review and adjust the migration to preserve your data. Data changes still need seed files or hand-written migrations.

Can I use declarative schemas with my existing projects?

Yes. Turn on pg-delta first. If the project has no migration history, run supabase db pull to create a baseline. Run supabase db schema declarative generate --linked to export your database into SQL files under supabase/schemas/. Then edit, generate, review, and apply as usual. See the docs for adopting declarative schemas on the legacy engine.

What changes if I already use declarative schemas on migra?

Turn on pg-delta in config.toml and remove schema_paths. Run supabase db pull to capture any objects missing from your migration history. Then switch your scripts from supabase db diff to supabase db schema declarative sync. Follow the diff engines guide for the full procedure. Projects that don't opt in keep using migra.

Are there any limitations to declarative schemas?

pg-delta does not diff application data or Storage buckets. Buckets are rows in storage.buckets. RLS policies on storage.objects are schema objects and are included in diffs.

The engine does not orchestrate zero-downtime rollouts. See known caveats for unsupported objects and extension-specific behavior.

Does pg-delta work outside Supabase?

Yes. pg-delta is open source under the PostgreSQL License and ships on npm as @supabase/pg-delta. Point it at any two Postgres databases from version 14 through 18. It writes the migration between them. The engine is at supabase/pg-delta.

Get started with the Declarative Schemas documentation.