Que fait supabase ?
Principes Fondamentaux
1. Supabase change 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 Supabase. Les signatures de fonctions, les paramètres config.toml et les conventions d'API changent entre les versions.
Commencez par récupérer https://supabase.com/changelog.md (un index de résumé léger — pas un téléchargement lourd), recherchez les balises breaking-change pertinentes pour votre tâche, et suivez la page liée pour toute balise applicable. Ensuite, consultez le sujet concerné 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 reconsidérez-la. 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 il vaut souvent la peine de vérifier les logs avant de continuer.
4. Exposition des tables à l'API de données : En fonction des 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). Dans ce cas, les rôles anon et authenticated devront se voir explicitement accorder l'accès.
Notez que cela est distinct du RLS, qui contrôle quelles lignes sont visibles une fois qu'une table est accessible, et non pas si la table est accessible du tout.
Lorsqu'un utilisateur signale qu'une table créée par SQL est inaccessible de manière inattendue, vérifiez ses paramètres d'API de données et si les rôles ont obtenu l'accès via un GRANT SQL explicite. Lorsque vous accordez un accès public (anon/authenticated), activez toujours le RLS également. 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 y ont accès (voir Exposer une table à l'API de données). Pour les schémas privés, préférez 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 motif auth.uid().
6. Liste de contrôle de sécurité. Lorsque vous travaillez sur une tâche Supabase qui touche à l'authentification, au RLS, aux vues, au stockage ou aux données utilisateur, parcourez cette liste de contrôle. Ce sont des pièges de sécurité spécifiques à Supabase qui créent silencieusement des vulnérabilités :
-
Sécurité de l'authentification et des sessions
- 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 d'abord les sessions, gardez une expiration JWT courte pour les applications sensibles, et pour des garanties strictes, validez
session_idpar rapport àauth.sessionssur les opérations sensibles. - Si vous utilisez
app_metadataouauth.jwt()pour l'autorisation, rappelez-vous que les revendications JWT ne sont pas toujours fraîches tant que le jeton de l'utilisateur n'est pas actualisé.
- N'utilisez jamais les revendications
-
Exposition des clés API et du client
- N'exposez jamais la clé
service_roleou la clé secrète dans les clients publics. Préférez les clés publiable pour le code frontend. Les clésanonhéritées ne sont là que pour la compatibilité. Dans Next.js, toute variable d'environnementNEXT_PUBLIC_est envoyée au navigateur. - Utilisez des jetons d'accès personnel à portée limitée pour l'API de gestion, la CLI et le serveur MCP. Un jeton d'accès personnel classique transporte l'accès complet au compte de l'utilisateur, sur chaque organisation et projet. Pour les scripts, l'CI et les agents, demandez à l'utilisateur de créer un jeton à portée limitée aux organisations, projets et autorisations dont la tâche a besoin. Le guide des jetons d'accès personnel répertorie l'autorisation requise pour chaque point d'API de gestion et outil MCP. Recherchez les autorisations là-bas plutôt que de deviner.
- N'exposez jamais la clé
-
RLS, vues et code de base de données privilégié
- Les vues contournent le RLS par défaut. Dans Postgres 15 et versions supérieures, utilisez
CREATE VIEW ... WITH (security_invoker = true). Dans les versions antérieures de Postgres, protégez vos vues en révoquant l'accès des rôlesanonetauthenticated, ou en les plaçant dans un schéma non exposé. - UPDATE nécessite une politique SELECT. Dans le RLS de Postgres, une UPDATE doit d'abord SELECTionner la ligne. Sans politique SELECT, les mises à jour renvoient silencieusement 0 lignes — pas d'erreur, juste aucun changement.
auth.role()est obsolète — utilisez la clauseTOà la place. Supabase a rendu obsolèteauth.role()en faveur de la spécification directe du rôle cible sur la politique avecTO authenticatedouTO anon. Au-delà de l'obsolescence,auth.role() = 'authenticated'échoue silencieusement lorsque les connexions anonymes sont activées, car les utilisateurs anonymes portent le rôle Postgresauthenticatedet réussissent le contrôle, que l'utilisateur soit réellement connecté ou non.-- Obsolète (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 authenticatedne vérifie que le rôle — cela 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 exemplepostgres). 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'API public appelable paranonetauthenticated(qui héritent dePUBLIC) sans aucun privilège 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 avoir effectué des modifications.
- Les vues contournent le RLS par défaut. Dans Postgres 15 et versions supérieures, utilisez
-
Contrôle d'accès au stockage
- L'upsert de stockage nécessite INSERT + SELECT + UPDATE. Accorder uniquement INSERT permet de nouveaux téléchargements, mais le remplacement de fichier (upsert) échoue silencieusement. Vous avez besoin des trois.
-
Sécurité des dépendances et de la chaîne d'approvisionnement
- Épinglez toujours les versions des packages et validez les fichiers de verrouillage lors de l'installation des packages Supabase (
supabase-js,@supabase/ssr,supabase-py, etc.). Voir le guide de sécurité npm pour la liste de contrôle complète.
- Épinglez toujours les versions des packages et validez les fichiers de verrouillage lors de l'installation des packages Supabase (
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 de la CLI change entre les versions.
supabase --help # Toutes les commandes de premier niveau
supabase <group> --help # Sous-commandes (ex : supabase db --help)
supabase <group> <command> --help # Drapeaux 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- Le flux navigateur de
supabase logincrée un jeton classique avec un accès complet au compte. Dans l'CI, définissez plutôtSUPABASE_ACCESS_TOKENsur un jeton d'accès personnel à portée limitée. Il prime sur toute connexion enregistrée. Les commandes qui se connectent avec le mot de passe de la base de données (--passwordouSUPABASE_DB_PASSWORD, par exemplesupabase db push) ne sont pas limitées par les autorisations du jeton. - Dans les projets de migration impératifs, créez d'abord de nouveaux fichiers de migration rédigés à la main avec
supabase migration new <name>. N'inventez jamais un nom de fichier de migration et ne vous fiez pas à votre mémoire pour le format attendu. Les projets de schéma déclaratif génèrent des migrations à partir desupabase/schemas/; voir « Effectuer et valider des modifications de schéma » ci-dessous.
Vérification et mise à niveau de la version : Exécutez supabase --version pour vérifier. Pour les changelogs de la CLI et les fonctionnalités spécifiques à une version, consultez la documentation CLI ou les versions 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/mcpUne401est attendue (pas de jeton) et signifie que le serveur est opérationnel. Un délai d'attente ou « connexion refusée » signifie qu'il peut être hors service. -
Vérifiez la configuration
.mcp.json: Vérifiez que la racine du projet contient un.mcp.jsonvalide avec l'URL correcte du serveur. Si absent, créez-en un pointant vershttps://mcp.supabase.com/mcp. -
Authentifiez le serveur MCP : Si le serveur est accessible 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. Dans l'CI ou d'autres environnements où le flux navigateur ne peut pas s'exécuter, transmettez un jeton d'accès personnel à portée limitée dans l'en-têteAuthorization: Bearerà la place. -
Vérifiez les autorisations du jeton à portée limitée : Si un outil échoue avec « Vous n'avez pas la permission d'effectuer cette action » lors de l'utilisation d'un jeton d'accès personnel à portée limitée, le jeton manque de l'autorisation de cet outil ou le projet est en dehors de la portée du jeton. Vérifiez l'autorisation requise par l'outil dans le guide des jetons d'accès personnel.
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 des extraits pertinents directement) - Récupérez les pages de documentation au format markdown — n'importe quelle page de documentation peut être récupérée en ajoutant
.mdau chemin de l'URL. - Recherche Web pour des sujets spécifiques à Supabase lorsque vous ne savez pas quelle page consulter.
Effectuer et valider des modifications de schéma
Décidez d'abord du workflow de schéma utilisé par le projet.
Option A : Schémas déclaratifs
Utilisez ceci lorsque supabase/schemas/ existe ou que config.toml définit schema_paths. Modifiez l'état de schéma souhaité dans ces fichiers, puis générez et examinez la migration. Ne commencez pas par rédiger une migration à la main. Voir le guide des schémas de base de données déclaratifs.
Option B : Migrations impératives
Utilisez ceci lorsque le projet n'utilise pas de schémas déclaratifs.
Pour effectuer des modifications de schéma, utilisez execute_sql (MCP) ou supabase db query (CLI). Celles-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 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 produiront des différences vides ou conflictuelles. Si vous l'utilisez, vous serez bloqué avec le SQL que vous avez passé lors de la première tentative.
Lorsque vous êtes prêt à valider vos modifications dans un fichier de migration :
- Exécutez les advisors →
supabase db advisors(CLI v2.81.3+) ou MCPget_advisors. Corrigez tout problème. - Examinez la liste de contrôle 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
Débogage
Lorsque vous obtenez une erreur sur une requête liée à Supabase, par exemple un code d'erreur de l'API REST Supabase, de la base de données Postgres ou de PostgREST, un résultat vide, un blocage inattendu par le RLS, ou une erreur d'un service Supabase comme Auth, Realtime, Edge Functions ou Storage, vous devez récupérer la documentation Surveillance et débogage de Supabase avant de diagnostiquer ou de proposer une correction, plutôt que de travailler de mémoire. Les mêmes documents couvrent également les optimisations de performances, telles que les requêtes lentes et les index manquants.
Guides de Référence
- Commentaires sur la compétence → references/skill-feedback.md DOIT être lu lorsque l'utilisateur signale que cette compétence a donné des conseils incorrects ou qu'il manque des informations.