supabase-db-push-history-desync

Vécu projet : ayari.racing Date : Avril 2026 Stack : Supabase, Supabase CLI, MCP Supabase

Contexte

Projet Supabase avec des migrations committées en local (supabase/migrations/) et une DB distante. Les migrations peuvent être appliquées par plusieurs canaux : la CLI (supabase db push), le dashboard Supabase, un MCP, ou un script de CI. Le jour où tu essaies d'appliquer une nouvelle migration locale avec la CLI, elle refuse :

Remote migration versions not found in local migrations directory.

Make sure your local git repo is up-to-date. If the error persists, try repairing the migration history table:
supabase migration repair --status reverted 20260408131750 20260410170850 20260419162212

And update local migrations to match remote database:
supabase db pull

Problème

supabase db push ne fait PAS que pousser les migrations locales — il valide d'abord la cohérence de l'historique entier entre supabase/migrations/ (local) et supabase_migrations.schema_migrations (distant). Dès qu'une migration distante n'a pas d'équivalent local (appliquée via dashboard, par un autre dev, par un CI tiers…), la CLI refuse d'appliquer quoi que ce soit, même une migration totalement indépendante.

Les commandes proposées par la CLI (migration repair + db pull) impliquent de modifier l'historique de migration côté serveur, ou de tirer en local des migrations distantes dont on ne sait pas toujours ce qu'elles font — risqué sur un projet actif, surtout en solo.

Solution

Utiliser le MCP Supabase (mcp__claude_ai_Supabase__apply_migration) qui applique directement le SQL et enregistre la migration dans schema_migrations sans valider l'historique global.

apply_migration({
  project_id: "xxx",
  name: "add_column_foo",
  query: "ALTER TABLE bar ADD COLUMN foo int NOT NULL DEFAULT 0;"
})

Résultat : {"success": true}. Le SQL est exécuté, la ligne schema_migrations est créée, l'historique distant s'enrichit d'une ligne de plus (qui n'existe pas en local), et on peut continuer à travailler.

Le fichier SQL reste committé dans supabase/migrations/ (référence pour git + bootstrap de nouveaux environnements), mais la CLI n'est plus le point d'application.

Pourquoi

Le MCP fait une opération minimaliste : exec SQL + insert into schema_migrations. La CLI fait la même chose plus une validation de cohérence d'historique. Cette validation sert la symétrie parfaite attendue en équipe disciplinée (tout passe par le repo), mais devient contre-productive dès que plusieurs canaux d'écriture coexistent — ce qui est le cas sur la plupart des projets réels où le dashboard Supabase est utilisé ponctuellement (RLS, ajouts de colonnes rapides, setup initial…).

Un canal = un seul point d'entrée possible = CLI safe. Plusieurs canaux = historique divergent probable = CLI bloquée = MCP nécessaire.

Points d'attention

• Commiter le fichier local SQL. Même si le MCP fait l'application, le fichier dans supabase/migrations/ sert de référence git et permet à un nouveau dev de reconstruire la DB (via db pull + replay) sur son environnement. Sans ce fichier, la migration n'est documentée nulle part côté repo.
• Pour réaligner plus tard : supabase db pull pour tirer les migrations distantes manquantes. À faire quand le workflow le permet, pas d'urgence tant que le MCP fonctionne.
• supabase migration repair --status reverted — proposé par la CLI — marque les migrations distantes comme « revertées » dans schema_migrations. À ne lancer qu'en étant CERTAIN que les migrations listées n'existent plus réellement sur la DB. Sinon, tu corromps l'historique de manière subtile.
• Applicable au MCP officiel Anthropic. Si tu utilises une autre intégration MCP Supabase ou une API REST maison, vérifie qu'elle insère bien dans schema_migrations — sinon la prochaine db push ne verra pas ta migration comme appliquée et tentera de la rejouer.

Dernière mise à jour : avril 2026