Supabase

Principes fondamentaux

1. Supabase change fréquemment — vérifiez par rapport au changelog et à la documentation actuelle avant d'implémenter. Ne vous fiez pas aux données d'entraînement pour les fonctionnalités Supabase. Les signatures de fonction, les paramètres config.toml et les conventions API changent entre les versions.

Commencez par récupérer https://supabase.com/changelog.md (un index de résumé léger — pas un gros téléchargement), scannez les balises breaking-change pertinentes pour votre tâche, et suivez la page liée pour celles qui s'appliquent. Ensuite, recherchez le sujet pertinent en utilisant les méthodes d'accès à la documentation ci-dessous.

2. Vérifiez votre travail. Après avoir implémenté une correction, exécutez une requête de test pour confirmer que la modification fonctionne. Une correction sans vérification est incomplète.

3. Récupérez-vous des erreurs, ne tournez pas en boucle. Si une approche échoue après 2-3 tentatives, arrêtez-vous et reconsidérez. Essayez une méthode différente, consultez la documentation, examinez l'erreur plus attentivement, et consultez les logs pertinents si disponibles. Les problèmes Supabase ne sont pas toujours résolus en relançant la même commande, et la réponse n'est pas toujours dans les logs, mais ils valent souvent la peine d'être vérifiés avant de continuer.

4. Exposer les tables à l'API Data : Selon les paramètres Data API de l'utilisateur, les tables nouvellement créées peuvent ne pas être automatiquement exposées via l'API Data (REST). Si c'est le cas, les rôles anon et authenticated doivent se voir accorder explicitement l'accès.

Notez que ceci est distinct de RLS, qui contrôle quelles lignes sont visibles une fois qu'une table est accessible, non si la table est accessible ou non.

Quand un utilisateur signale qu'une table créée en SQL est inaccessible de manière inattendue, vérifiez ses paramètres Data API et si les rôles se sont vu accorder l'accès via un GRANT SQL explicite. Quand vous accordez un accès public (anon/authenticated), activez toujours RLS aussi. Voir Exposing a Table to the Data API pour le flux de configuration complet.

5. RLS dans les schémas exposés. Activez RLS sur chaque table de tout schéma exposé, qui inclut public par défaut. C'est critique dans Supabase car les tables dans les schémas exposés peuvent être accessibles via l'API Data quand les rôles anon/authenticated ont accès (voir Exposing a Table to the Data API). Pour les schémas privés, préférez RLS comme défense en profondeur. Après activation de RLS, créez des policies qui correspondent au modèle d'accès réel plutôt que de dédier chaque table par défaut au même pattern auth.uid().

6. Checklist de sécurité. Quand vous travaillez sur toute tâche Supabase qui concerne l'auth, RLS, les vues, le storage ou les données utilisateur, parcourez cette checklist. Ce sont des pièges de sécurité spécifiques à Supabase qui créent silencieusement des vulnérabilités :

Sécurité de l'auth et de la session
- Ne n'utilisez jamais les claims user_metadata pour les décisions d'autorisation basées sur JWT. Dans Supabase, raw_user_meta_data est modifiable par l'utilisateur et peut apparaître dans auth.jwt(), donc c'est dangereux pour les policies RLS ou toute autre logique d'autorisation. Stockez plutôt les données d'autorisation dans raw_app_meta_data / app_metadata.
- Supprimer un utilisateur n'invalide pas les tokens d'accès existants. Déconnectez-vous ou révoquez d'abord les sessions, gardez l'expiration JWT courte pour les apps sensibles, et pour des garanties strictes validez session_id contre auth.sessions sur les opérations sensibles.
- Si vous utilisez app_metadata ou auth.jwt() pour l'autorisation, souvenez-vous que les claims JWT ne sont pas toujours frais jusqu'à ce que le token de l'utilisateur soit rafraîchi.
Exposition des clés API et client
- N'exposez jamais la clé service_role ou secret dans les clients publics. Préférez les clés publiables pour le code frontend. Les anciennes clés anon sont uniquement pour la compatibilité. Dans Next.js, toute variable d'env NEXT_PUBLIC_ est envoyée au navigateur.
RLS, vues et code de base de données privilégié
- Les vues contournent RLS par défaut. Dans Postgres 15 et au-dessus, utilisez CREATE VIEW ... WITH (security_invoker = true). Dans les versions plus anciennes de Postgres, protégez vos vues en révoquant l'accès des rôles anon et authenticated, ou en les plaçant dans un schéma non exposé.
- UPDATE nécessite une policy SELECT. Dans RLS Postgres, un UPDATE doit d'abord SELECT la ligne. Sans une policy SELECT, les mises à jour retournent silencieusement 0 lignes — pas d'erreur, juste aucun changement.
- Ne placez pas de fonctions security definer dans un schéma exposé. Gardez-les dans un schéma privé ou autrement non exposé.
Contrôle d'accès au storage
- Le storage upsert nécessite INSERT + SELECT + UPDATE. Accorder uniquement INSERT permet les nouveaux uploads mais le remplacement de fichier (upsert) échoue silencieusement. Vous avez besoin des trois.

Pour toute préoccupation de sécurité non couverte ci-dessus, récupérez l'index de sécurité des produits Supabase : https://supabase.com/docs/guides/security/product-security.md

CLI Supabase

Découvrez toujours les commandes via --help — ne devinez jamais. La structure du CLI change entre les versions.

supabase --help                    # Toutes les commandes de haut niveau
supabase <group> --help            # Sous-commandes (par ex. supabase db --help)
supabase <group> <command> --help  # Flags pour une commande spécifique

Pièges connus du CLI Supabase :

supabase db query nécessite CLI v2.79.0+ → utilisez MCP execute_sql ou psql comme fallback
supabase db advisors nécessite CLI v2.81.3+ → utilisez MCP get_advisors comme fallback
Quand vous avez besoin d'un nouveau fichier de migration SQL, créez-le toujours avec supabase migration new <name> d'abord. N'inventez jamais un nom de fichier de migration ou ne vous fiez à la mémoire pour le format attendu.

Vérification de version et mise à jour : Exécutez supabase --version pour vérifier. Pour les changelogs CLI et les fonctionnalités spécifiques aux versions, consultez la documentation CLI ou les releases GitHub.

Serveur MCP Supabase

Pour les instructions de configuration, l'URL du serveur et la configuration, voir le guide de configuration MCP.

Dépannage des problèmes de connexion — suivez ces étapes dans l'ordre :

Vérifiez si le serveur est accessible : curl -so /dev/null -w "%{http_code}" https://mcp.supabase.com/mcp Un 401 est attendu (pas de token) et signifie que le serveur est actif. Un timeout ou « connection refused » signifie qu'il peut être hors ligne.
Vérifiez la configuration .mcp.json : Vérifiez que la racine du projet a un .mcp.json valide avec l'URL du serveur correcte. S'il manque, créez-en un pointant vers https://mcp.supabase.com/mcp.
Authentifiez le serveur MCP : Si le serveur est accessible et .mcp.json est correct mais les outils ne sont pas visibles, l'utilisateur doit s'authentifier. Le serveur MCP Supabase utilise OAuth 2.1 — dites à l'utilisateur de déclencher le flux d'auth dans son agent, de le compléter dans le navigateur, et de recharger la session.

Documentation Supabase

Avant d'implémenter toute fonctionnalité Supabase, trouvez la documentation pertinente. Utilisez ces méthodes dans l'ordre de priorité :

Outil MCP search_docs (préféré — retourne les extraits pertinents directement)
Récupérez les pages de docs en markdown — toute page de docs peut être récupérée en ajoutant .md au chemin URL.
Recherche web pour les sujets spécifiques à Supabase quand vous ne savez pas quelle page regarder.

Effectuer et commiter les changements de schéma

Pour effectuer des changements de schéma, utilisez execute_sql (MCP) ou supabase db query (CLI). Ceux-ci exécutent SQL directement sur la base de données sans créer d'entrées d'historique de migration, vous pouvez donc itérer librement et générer une migration propre quand prêt.

N'utilisez PAS apply_migration pour changer un schéma de base de données local — cela écrit une entrée d'historique de migration à chaque appel, ce qui signifie que vous ne pouvez pas itérer, et supabase db diff / supabase db pull produiront des diffs vides ou conflictuels. Si vous l'utilisez, vous serez bloqué avec quel que soit le SQL que vous avez passé à la première tentative.

Quand vous êtes prêt à commiter vos changements dans un fichier de migration :

Exécutez les advisors → supabase db advisors (CLI v2.81.3+) ou MCP get_advisors. Corrigez les problèmes.
Consultez la Checklist de sécurité ci-dessus si vos changements impliquent des vues, des fonctions, des triggers ou du storage.
Générez la migration → supabase db pull <descriptive-name> --local --yes
Vérifiez → supabase migration list --local

Guides de référence

Skill Feedback → references/skill-feedback.md DOIT être lue quand l'utilisateur signale que cette skill a donné des conseils incorrects ou manque d'informations.