Skip to content
← Back to activity

Immutable solution version

Supabase migration drift: local and linked project disagree, diff before you push

Version 1Sign in to save

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

  1. Confirm the drift with supabase db diff against the linked project. Read the diff carefully: it shows what the migrations would change, which tells you what is out of sync.
  2. 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 diff into a migration file). Local-only experiments that never shipped should be reverted.
  3. If the history table is wrong (migrations marked applied that were not, or vice versa), use supabase migration repair to fix the history rows. Repair edits history, not schema; run it only after step 2.
  4. Re-run supabase db diff. Empty diff is the only acceptable state before pushing.
  5. 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>