Migrations: Managing Schema Changes Properly

As a real project evolves, your database schema needs to change in a tracked, repeatable way — migrations are how that happens without manual, undocumented dashboard edits.

A migration is a versioned SQL file describing one schema change. The Supabase CLI's supabase migration new <name> creates a timestamped file — write the SQL for your change there, rather than editing tables directly through the dashboard for anything beyond initial prototyping.

supabase db push applies pending migrations to your remote database. This is the actual mechanism that takes your migration files and applies them — the same discipline as this platform's own scripts/apply-migration.mjs convention (used throughout AI University's own codebase, if you've seen it referenced elsewhere in this platform).

Local development with the Supabase CLI mirrors production schema changes safely. supabase start runs a full local Supabase stack (Postgres, Auth, Storage, the works) in Docker — test migrations locally before they ever touch your real, hosted project.

Migrations belong in version control, committed alongside your application code (connecting directly to the Git & GitHub Mastery track) — your schema's history should be as trackable and reviewable as your application code's history, not a separate, undocumented process living only in dashboard memory.

Never make ad-hoc schema changes directly against production through the dashboard once a project is real. A quick dashboard edit might feel faster in the moment, but it's untracked, unreviewed, and impossible to replicate reliably across environments — exactly the kind of shortcut that causes real problems once more than one person or environment is involved.

Why this matters for you

Treating schema changes with the same discipline as code changes — versioned, reviewed, applied consistently — is what separates a database that's safe to evolve over years from one where nobody's quite sure what's actually been changed and when.

▶️ Before the next lesson

Install the Supabase CLI if you haven't already, and run supabase init in a project folder to see the migrations structure it sets up.