Supabase Declarative Schema Tutorial: Database as Code
This Supabase declarative schema tutorial shows the database-as-code workflow: schema files, pg-delta diffs, drift detection in CI, and safe production deploys.
Last updated: 2026-10-10 You changed a column in the Supabase dashboard at 2 AM to fix a production bug. Three weeks later, a teammate's migration fails because their local database does not have your column. Nobody knows which change came first. The migration history says everything is applied, production disagrees, and now you are diffing schemas by hand at midnight. This is the tax on the classic migration-files workflow: the database is mutable state that lives outside your code, and every out-of-band edit is a landmine. Supabase declarative schemas flip the model — you describe the desired database state in SQL files, and the tooling figures out the diff. Your schema becomes code: reviewable, versioned, and drift-detectable. This tutorial builds that workflow end to end. If you are new to the stack overall, our complete Flutter and Supabase guide is the better starting point; this one assumes a working Supabase project. What you'll learn in this Supabase declarative schema tutorial What declarative schemas are and how they differ from classic migration files How to set up the declarative workflow and generate schema files from an existing database The daily loop: edit SQL files, diff with pg-delta, review the generated migration, apply it How to catch schema drift in CI before it reaches production How to deploy declarative changes to production without fear When to use declarative schemas vs classic migrations (and when to mix them) The five mistakes that break the declarative workflow Migration files vs database as code: the pain you're feeling The classic workflow is imperative: every schema change is a timestamped migration file describing *how* to get from the old state to the new one ( alter table ... add column ... ). It works until reality…