0
Challenge · 41Schema as Code
Declarative schemas, db diff & drift
Toolingused in ~65% of apps
Hand-writing every ALTER TABLE is tedious and error-prone once a table has a dozen columns. So Supabase lets you write the schema you WANT — a create table statement describing the end state — and generates the migration for you with `db diff`. It is a genuinely good workflow. It is also quietly blind to an entire category of things you will assume it caught.
Core idea. A declarative schema file (supabase/schemas/*.sql) describes your desired end-state DDL; `supabase db diff -f name` compares it against a shadow database and writes the delta as an ordinary migration file. The diff engine (migra) reasons faithfully about tables, columns, indexes and functions — but it does not diff RLS policies, materialized views, a view's security_invoker setting, comments, partitions, or schema privileges, and it never touches data (DML) at all. Anything in that missed list must still be a hand-written migration; the generated migration is not a complete mirror of your declarative file.
poke it, drag it,
try to break it
try to break it
no slides here.
you drive.
you drive.
Playground, this isn't a screenshot
supabase db diff -f namewhat actually lands in the generated migration
supabase/schemas/posts.sql (desired state)
create policy "own posts" on posts for select using (...);→
generated migration
-- (nothing generated)
silently skippedNot captured. Write this policy in your declarative schema file and db diff produces NOTHING for it — no error, no migration line. The policy will never exist on any database unless you hand-write it into a migration yourself.
The rule: declarative schemas are honest about tables, columns, indexes and functions. For RLS policies, materialized views, view security settings, comments, partitions and grants — anything the diff engine does not model — the migration remains the source of truth, and you write it by hand.
↑ play a little first, then dig in