Supabase
Principes Fondamentaux
1. Supabase évolue fréquemment — vérifiez le changelog et la documentation actuelle avant d'implémenter. Ne vous fiez pas aux données d'entraînement pour les fonctionnalités de Supabase. Les signatures de fonctions, les paramètres de config.toml et les conventions d'API changent entre les versions.
Commencez par récupérer https://supabase.com/changelog.md (un index récapitulatif léger — pas un chargement lourd), recherchez les balises breaking-change pertinentes pour votre tâche, et suivez la page liée pour celles qui s'appliquent. Consultez ensuite 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 le changement fonctionne. Une correction sans vérification est incomplète.
3. Récupérez des erreurs, ne bouclez pas. Si une approche échoue après 2-3 tentatives, arrêtez-vous et réévaluez. Essayez une méthode différente, consultez la documentation, inspectez l'erreur plus attentivement, et examinez les logs pertinents lorsqu'ils sont disponibles. Les problèmes Supabase ne sont pas toujours résolus en réexécutant la même commande, et la réponse ne se trouve pas toujours dans les logs, mais les logs valent souvent la peine d'être vérifiés avant de continuer.
4. Exposition des tables à l'API de données : Selon les paramètres de l'API de données de l'utilisateur, les tables nouvellement créées peuvent ne pas être automatiquement exposées via l'API de données (REST). Si c'est le cas, il faudra explicitement accorder l'accès aux rôles anon et authenticated.
Notez que cela est distinct du RLS, qui contrôle quelles lignes sont visibles une fois qu'une table est accessible, et non si la table est accessible du tout.
Lorsqu'un utilisateur signale qu'une table créée via SQL est soudainement inaccessible, vérifiez ses paramètres d'API de données et si les rôles ont reçu l'accès via une commande GRANT SQL explicite. Lorsque vous accordez un accès public (anon/authenticated), activez toujours le RLS. Voir Exposer une table à l'API de données pour le workflow de configuration complet.
5. RLS dans les schémas exposés.
Activez le RLS sur chaque table de tout schéma exposé, ce qui inclut public par défaut. Ceci est critique dans Supabase car les tables dans les schémas exposés peuvent être accessibles via l'API de données lorsque les rôles anon/authenticated ont l'accès (voir Exposer une table à l'API de données). Pour les schémas privés, privilégiez le RLS comme défense en profondeur. Après avoir activé le RLS, créez des politiques qui correspondent au modèle d'accès réel plutôt que de définir par défaut chaque table sur le même modèle auth.uid().
6. Checklist de sécurité. Lorsque vous travaillez sur une tâche Supabase qui touche à l'auth, au RLS, aux vues, au stockage ou aux 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é des sessions et de l'authentification
- N'utilisez jamais les revendications
user_metadatadans les décisions d'autorisation basées sur JWT. Dans Supabase,raw_user_meta_dataest modifiable par l'utilisateur et peut apparaître dansauth.jwt(), il est donc dangereux pour les politiques RLS ou toute autre logique d'autorisation. Stockez les données d'autorisation dansraw_app_meta_data/app_metadataà la place. - La suppression d'un utilisateur n'invalide pas les jetons d'accès existants. Déconnectez-vous ou révoquez les sessions d'abord, gardez une durée de validité JWT courte pour les applications sensibles, et pour des garanties strictes, validez
session_idpar rapport àauth.sessionslors d'opérations sensibles. - Si vous utilisez
app_metadataouauth.jwt()pour l'autorisation, souvenez-vous que les revendications JWT ne sont pas toujours à jour tant que le jeton de l'utilisateur n'est pas actualisé.
- N'utilisez jamais les revendications
-
Exposition des clés API et des clients
- N'exposez jamais la
service_roleou la clé secrète dans des clients publics. Privilégiez les clés publiable pour le code frontend. Les clésanonhéritées sont uniquement pour la compatibilité. Dans Next.js, toute variable d'environnementNEXT_PUBLIC_est envoyée au navigateur.
- N'exposez jamais la
-
RLS, vues et code de base de données privilégié
- Les vues contournent le RLS par défaut. Dans Postgres 15 et supérieur, utilisez
CREATE VIEW ... WITH (security_invoker = true). Dans les versions antérieures de Postgres, protégez vos vues en révoquant l'accès aux rôlesanonetauthenticated, ou en les plaçant dans un schéma non exposé. - UPDATE nécessite une politique SELECT. Dans Postgres RLS, un UPDATE doit d'abord SELECT la ligne. Sans politique SELECT, les mises à jour renvoient silencieusement 0 lignes — pas d'erreur, juste aucun changement.
auth.role()est déprécié — utilisez plutôt la clauseTO. Supabase a dépréciéauth.role()en faveur de la spécification directe du rôle cible sur la politique avecTO authenticatedouTO anon. Au-delà de la dépréciation,auth.role() = 'authenticated'échoue silencieusement lorsque les connexions anonymes sont activées, car les utilisateurs anonymes portent le rôle Postgresauthenticatedet réussissent la vérification indépendamment du fait que l'utilisateur soit réellement connecté.-- Déprécié (à ne pas utiliser) create policy "example" on table_name for select using ( auth.role() = 'authenticated' );TO authenticatedseul est une authentification sans autorisation (BOLA / IDOR). UtiliserTO authenticatedvérifie uniquement le rôle — il ne restreint pas les lignes auxquelles un utilisateur peut accéder. Le modèle correct combineTO authenticatedavec un prédicat de propriété dansUSING:create policy "example" on table_name for select to authenticated using ( (select auth.uid()) = user_id );- Les politiques UPDATE nécessitent à la fois
USINGetWITH CHECK. SansWITH CHECK, un utilisateur peut réaffecter leuser_idd'une ligne à un autre utilisateur :create policy "example" on table_name for update to authenticated using ( (select auth.uid()) = user_id ) with check ( (select auth.uid()) = user_id ); - Les fonctions
SECURITY DEFINERcontournent le RLS. Une fonctionSECURITY DEFINERs'exécute avec les privilèges de son créateur — généralement un rôle avecbypassrls(par exemple,postgres). N'ajoutez jamaisSECURITY DEFINERpour résoudre une erreur de permission ; cela supprime silencieusement le contrôle d'accès sans corriger la cause sous-jacente. PréférezSECURITY INVOKER. - Les fonctions
SECURITY DEFINERdanspublicsont appelables par tous les rôles. Postgres accordeEXECUTEàPUBLICpar défaut pour chaque nouvelle fonction, donc toute fonctionSECURITY DEFINERdanspublicest un point d'accès API public appelable paranonetauthenticated(qui héritent dePUBLIC) sans aucun octroi supplémentaire. LorsqueSECURITY DEFINERest réellement nécessaire (par exemple, contourner le RLS sur une table de recherche interne), conservez la fonction dans un schéma non exposé, incluez toujours une vérificationauth.uid()dans le corps de la fonction, et exécutezsupabase db advisorsaprès les modifications.
- Les vues contournent le RLS par défaut. Dans Postgres 15 et supérieur, utilisez
-
Contrôle d'accès au stockage
- L'upsert de stockage nécessite INSERT + SELECT + UPDATE. Accorder uniquement INSERT permet les nouveaux téléchargements 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é produit Supabase : https://supabase.com/docs/guides/security/product-security.md
CLI Supabase
Découvrez toujours les commandes via --help — ne devinez jamais. La structure CLI change entre les versions.
supabase --help # Toutes les commandes de haut niveau
supabase <groupe> --help # Sous-commandes (ex. supabase db --help)
supabase <groupe> <commande> --help # Flags pour une commande spécifique
Pièges connus de la CLI Supabase :
supabase db querynécessite CLI v2.79.0+ → utilisez MCPexecute_sqloupsqlcomme solution de replisupabase db advisorsnécessite CLI v2.81.3+ → utilisez MCPget_advisorscomme solution de repli- Lorsque vous avez besoin d'un nouveau fichier SQL de migration, créez-le toujours avec
supabase migration new <nom>en premier. N'inventez jamais un nom de fichier de migration et ne vous fiez pas à la mémoire pour le format attendu.
Vérification et mise à jour de version : 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 versions GitHub.
Serveur MCP Supabase
Pour les instructions de configuration, l'URL du serveur et la configuration, consultez le guide de configuration MCP.
Dépannage des problèmes de connexion — suivez ces étapes dans l'ordre :
-
Vérifiez si le serveur est joignable :
curl -so /dev/null -w "%{http_code}" https://mcp.supabase.com/mcpUn401est attendu (pas de jeton) et signifie que le serveur est opérationnel. Un dépassement de délai ou "connexion refusée" signifie qu'il peut être indisponible. -
Vérifiez la configuration
.mcp.json: Assurez-vous que la racine du projet contient un.mcp.jsonvalide avec la bonne URL du serveur. Si manquant, créez-en un pointant vershttps://mcp.supabase.com/mcp. -
Authentifiez le serveur MCP : Si le serveur est joignable et que
.mcp.jsonest correct mais que 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'authentification dans son agent, de le terminer dans le navigateur et de recharger la session.
Documentation Supabase
Avant d'implémenter une fonctionnalité Supabase, trouvez la documentation pertinente. Utilisez ces méthodes par ordre de priorité :
- Outil MCP
search_docs(préféré — renvoie directement des extraits pertinents) - Récupérez les pages de documentation au format markdown — toute page de documentation peut être récupérée en ajoutant
.mdau chemin de l'URL. - Recherche web pour les sujets spécifiques à Supabase lorsque vous ne savez pas quelle page consulter.
Effectuer et Valider les Modifications de Schéma
Pour effectuer des modifications de schéma, utilisez execute_sql (MCP) ou supabase db query (CLI). Ceux-ci exécutent du 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 lorsque vous êtes prêt.
N'utilisez PAS apply_migration pour modifier 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 que supabase db diff / supabase db pull produira des diffs vides ou conflictuels. Si vous l'utilisez, vous serez bloqué avec le SQL que vous avez passé lors du premier essai.
Lorsque vous êtes prêt à valider vos modifications dans un fichier de migration :
- Exécutez les conseillers →
supabase db advisors(CLI v2.81.3+) ou MCPget_advisors. Corrigez tout problème. - Consultez la checklist de sécurité ci-dessus si vos modifications impliquent des vues, des fonctions, des déclencheurs ou du stockage.
- Générez la migration →
supabase db pull <nom-descriptif> --local --yes - Vérifiez →
supabase migration list --local
Guides de Référence
- Retour sur la compétence → references/skill-feedback.md À LIRE OBLIGATOIREMENT lorsque l'utilisateur signale que cette compétence a donné des conseils incorrects ou manque d'informations.