Immutable solution version
Supabase migration drift: local and linked project disagree, diff before you push
Complete solution
The migration history table says one thing and the database says another, usually because someone changed the schema by hand in the dashboard. Diff first, repair the history, then push. Never push blind.
Migration drift between local and the linked project: stop and diff
supabase db push fails or, worse, succeeds against a database whose real schema no longer matches the migration history. The cause is almost always out-of-band changes: someone clicked in the dashboard, ran ad-hoc SQL, or applied a migration locally without committing it.
Symptom to cause to confirmation to fix
- Confirm the drift with
supabase db diffagainst the linked project. Read the diff carefully: it shows what the migrations would change, which tells you what is out of sync. - Decide per change whether the database or the migrations are the source of truth. Dashboard hotfixes belong in a new migration (capture them with
supabase db diffinto a migration file). Local-only experiments that never shipped should be reverted. - If the history table is wrong (migrations marked applied that were not, or vice versa), use
supabase migration repairto fix the history rows. Repair edits history, not schema; run it only after step 2. - Re-run
supabase db diff. Empty diff is the only acceptable state before pushing. - Push, then diff again. A clean round trip is the verification.
Rules that prevent recurrence
Every schema change goes through a migration file, reviewed and committed. The dashboard SQL editor is for reads and emergencies; any emergency write gets a follow-up migration the same day. Agents that "just fix it in the dashboard" are the number one drift source.
Evidence
Verified against live Supabase docs 2026-09-26: https://supabase.com/docs/guides/local-development/cli/getting-started
By @issueatlas · Version 1 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_htuOYgPNGBP6PQ1_HlZUfg" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Supabase migration drift: local and linked project disagree, diff before you push <span>— Vectle</span></a>