Declarative Schemas 2.0, Rebuilt on pg-delta: migrations that cover policies, grants, and views

[wendeh]

At Supabase Select on October 2 we shipped Declarative Schemas 2.0. The Supabase CLI now generates migrations with pg-delta, a Postgres diff engine we wrote and open sourced, in place of migra. Generated migrations now include RLS policy changes, grants, view settings, partitions, domains, and objects that extensions manage.

The workflow is the same: edit a file, generate the migration, review it, and apply it. New CLI projects get 2.0 by default. Existing projects opt in with one config block. pg-delta is in alpha, so breaking changes can land between releases.

What changed

Declarative schemas first launched in April 2025. You keep your schema in .sql files under supabase/schemas/ and the CLI writes the migration. The diff engine behind it, migra, left out some object kinds, so you had to check each generated migration for what was missing.

pg-delta replaces it. The CLI starts two throwaway Postgres databases, loads your schema files into one, and replays your migration history into the other. pg-delta then compares the two by reading the system catalog. It never reads your live database.

What's included

• Migrations cover RLS policy changes, grants, security_invoker on views, materialized views, column privileges, comments, partitions, publications, and domains
• Extension-owned objects are changed through the extension's own functions. pg_partman partitions and pgmq queue tables never come out as raw create table or drop table, and the CLI flags drops as destructive. A new pg_cron job comes out as cron.schedule_in_database, a removed job as cron.unschedule, and a changed job as both
• Object kinds the engine doesn't model are reported instead of skipped, and --strict-coverage fails CI on them
• Statements are ordered from a dependency graph built from the catalog, so you no longer hand-order files in schema_paths
• supabase db schema declarative generate --linked writes schema files from an existing database
• pg-delta also runs on its own against any Postgres 14 through 18, with no Supabase account

What it doesn't do yet

pg-delta generates schema changes, not data changes, and it doesn't diff Storage buckets. It also doesn't orchestrate zero-downtime rollouts. A renamed column comes out as a drop and an add, so review anything the CLI flags as destructive before you apply it.

Getting started

• You need Supabase CLI 2.119 or later. New projects get pg-delta from supabase init. For an existing project, add [experimental.pgdelta] with enabled = true to supabase/config.toml, then run supabase db schema declarative sync to write the migration. Projects without it keep running migra
• If you already use declarative schemas, expect one catch-up migration on your first supabase db pull
• If a change is already live on your linked project, run supabase db pull first so your migration history records it. Otherwise the next sync generates it again, and db push fails because the object already exists
• Blog post: https://supabase.com/blog/declarative-schemas-2-0-pg-delta
• Docs: https://supabase.com/docs/guides/local-development/declarative-database-schemas
• Repo: https://github.com/supabase/pg-toolbelt/tree/main/packages/pg-delta

Feedback welcome

Reply here with anything that looks wrong in a generated migration.
Earlier feedback from the public alpha is in discussion 44938: https://github.com/orgs/supabase/discussions/44938

[cekuu35]

This is a big one for the October 30 change specifically — grants and policies becoming first-class generated objects means the exact thing people are scrambling to audit manually (which grants exist, which policies scope them) is now declarative and diffable. Two questions on scope:

1. Does pg-delta diff ALTER DEFAULT PRIVILEGES state? After October 30, the default-privilege entries on a project decide what new tables inherit — if the declarative files can capture and generate those too, that's the cleanest version-controlled Oct 30 prep available (the "what will my next table get" question becomes reviewable in a PR instead of a pg_default_acl query).

2. How does the grants diff treat the platform-managed grants on storage/auth schemas? Presumably pg-delta diffs the schemas you declare, and managed schemas are out of scope — but worth stating explicitly for anyone hoping this also reconciles drift on managed objects (it's the #1 confusion in the grants-audit threads).

Also: the "review it" step in the workflow is doing a lot of quiet load-bearing work, and it's the step people skip. The failure mode we keep seeing in the wild is a generated migration that's correct but unread — someone reviews the first 20 lines of a 200-line grants diff and ships it. If the CLI could emit a summary header in the generated file ("+12 grants, -3 policies, 2 tables, 0 default-privilege changes"), review quality would go up the same way test summaries did.