0
Challenge · 40Schema as Code

Migrations & forward-only history

Toolingused in ~100% of apps

Right now your schema exists because you clicked things into being in Studio, or typed a `create table` in the SQL editor and moved on. That works exactly once, on exactly one machine. The moment a teammate clones the repo, or CI spins up a fresh database, or you need to answer "why does staging disagree with production" — you need the schema to be something a computer can rebuild from nothing, not something only you remember doing.

Core idea. A migration is a small, timestamped SQL file that runs exactly once, in order, on every database that adopts it — and Postgres records that it ran in a history table so it is never re-executed. That single fact — ALREADY RAN, TRACKED, NEVER REPEATED — is also why you can never edit an applied migration: doing so does nothing on machines that already ran it, and something different on machines that have not. The fix for a mistake is always a new migration, never a rewritten one.
Playground, this isn't a screenshot
supabase/migrations/a migration is a script that already ran, not a live definition
Your laptop — already ran 001-003
  1. 001_create_posts.sql ✓ applied
  2. 002_add_is_public.sql ✓ applied
  3. 003_add_like_count.sql ✓ applied
posts.like_count : int
New teammate's clone — runs migrations from zero
  1. 001_create_posts.sql ✓ applied
  2. 002_add_is_public.sql ✓ applied
  3. 003_add_like_count.sql ✓ applied
posts.like_count : int
Identical migration files, applied in the identical order. Both machines land on int. This is the boring, correct case.
The rule: a migration file is a script Postgres runs exactly once per database, tracked in schema_migrations. Editing an already-applied one changes nothing for anyone who already ran it, and changes everything for anyone who has not — which is precisely how a fleet of "identical" clones ends up with silently different schemas.
↑ play a little first, then dig in