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'apprentissage pour les fonctionnalités Supabase. Les signatures de fonctions, 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 téléchargement lourd), recherchez les tags breaking-change pertinents pour votre tâche, et suivez la page liée pour ceux qui s'appliquent. 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. Essayez une méthode différente, consultez la documentation, inspectez l'erreur plus attentivement et examinez les logs pertinents si 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 est souvent utile de vérifier les logs avant de continuer.

4. Exposition des tables à l'API Data : Selon les paramètres de l'API Data 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 devront se voir explicitement accorder l'accès.

Notez que ceci 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 en SQL est inaccessible de manière inattendue, vérifiez ses paramètres d'API Data et si les rôles ont obtenu l'accès via une instruction SQL GRANT explicite. Lorsque vous accordez un accès public (anon/authenticated), activez toujours le RLS également. Voir Exposition d'une Table à l'API Data pour le workflow de configuration complet.

5. RLS dans les schémas exposés. Activez RLS sur chaque table de tout schéma exposé, ce qui inclut public par défaut. Ceci est crucial dans Supabase car les tables dans les schémas exposés peuvent être atteintes via l'API Data lorsque les rôles anon/authenticated y ont accès (voir Exposition d'une Table à l'API Data). Pour les schémas privés, privilégiez RLS comme défense en profondeur. Après avoir activé 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'authentification, 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é de l'authentification et des sessions
- N'utilisez jamais les revendications user_metadata dans 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(), il est donc dangereux pour les politiques RLS ou toute autre logique d'autorisation. Stockez les données d'autorisation dans raw_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 date d'expiration JWT courte pour les applications sensibles, et pour des garanties strictes, validez session_id par rapport à auth.sessions sur les opérations sensibles.
- Si vous utilisez app_metadata ou auth.jwt() pour l'autorisation, rappelez-vous que les revendications JWT ne sont pas toujours fraîches jusqu'à ce que le jeton de l'utilisateur soit rafraîchi.
Exposition de la clé API et du client
- N'exposez jamais la clé service_role ou secrète dans les clients publics. Préférez les clés publiable pour le code frontend. Les clés anon héritées ne sont que pour la compatibilité. Dans Next.js, toute variable d'environnement NEXT_PUBLIC_ est envoyée au navigateur.
- Utilisez des jetons d'accès personnels limités 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, pour chaque organisation et projet. Pour les scripts, CI et agents, demandez à l'utilisateur de créer un jeton limité aux organisations, projets et autorisations dont la tâche a besoin. Le guide des jetons d'accès personnels répertorie l'autorisation requise pour chaque point de terminaison de l'API de gestion et outil MCP. Consultez ces autorisations là-bas plutôt que de deviner.
RLS, vues et code de base de données privilégié
- Les vues contournent RLS par défaut. Dans Postgres 15 et supérieur, 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 politique SELECT. Dans RLS Postgres, un 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 plutôt la clause TO. Supabase a déprécié auth.role() au profit de la spécification directe du rôle cible sur la politique avec TO authenticated ou TO 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 Postgres authenticated et 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 authenticated seul est une authentification sans autorisation (BOLA / IDOR). Utiliser TO authenticated ne vérifie que le rôle — il ne limite pas les lignes auxquelles un utilisateur peut accéder. Le modèle correct combine TO authenticated avec un prédicat de propriété dans USING :
```
create policy "example" on table_name for select
to authenticated
using ( (select auth.uid()) = user_id );
```
- Les politiques UPDATE nécessitent à la fois USING et WITH CHECK. Sans WITH CHECK, un utilisateur peut réattribuer le user_id d'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 DEFINER contournent RLS. Une fonction SECURITY DEFINER s'exécute avec les privilèges de son créateur — généralement un rôle avec bypassrls (par exemple, postgres). N'ajoutez jamais SECURITY DEFINER pour résoudre une erreur de permission ; cela supprime silencieusement le contrôle d'accès sans résoudre la cause sous-jacente. Préférez SECURITY INVOKER.
- Les fonctions SECURITY DEFINER dans public sont appelables par tous les rôles. Postgres accorde EXECUTE à PUBLIC par défaut pour chaque nouvelle fonction, donc toute fonction SECURITY DEFINER dans public est un point de terminaison d'API public appelable par anon et authenticated (qui héritent de PUBLIC) sans aucun privilège supplémentaire. Lorsque SECURITY DEFINER est vraiment nécessaire (par exemple, pour contourner RLS sur une table de recherche interne), conservez la fonction dans un schéma non exposé, incluez toujours une vérification auth.uid() dans le corps de la fonction, et exécutez supabase db advisors après avoir effectué les modifications.
Contrôle d'accès au stockage
- Storage upsert nécessite INSERT + SELECT + UPDATE. Accorder uniquement INSERT permet les nouveaux téléversements, 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 lockfiles lors de l'installation des packages Supabase (supabase-js, @supabase/ssr, supabase-py, etc.). Consultez le guide de sécurité npm pour la checklist complète.

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 <groupe> --help            # Sous-commandes (par exemple, supabase db --help)
supabase <groupe> <commande> --help  # Drapeaux pour une commande spécifique

Pièges connus de la CLI Supabase :

supabase db query nécessite CLI v2.79.0+ → utilisez MCP execute_sql ou psql comme solution de secours
supabase db advisors nécessite CLI v2.81.3+ → utilisez MCP get_advisors comme solution de secours
Le flux navigateur de supabase login crée un jeton classique avec un accès complet au compte. En CI, définissez plutôt SUPABASE_ACCESS_TOKEN sur un jeton d'accès personnel limité. Il prime sur toute connexion sauvegardée. Les commandes qui se connectent avec le mot de passe de la base de données (--password ou SUPABASE_DB_PASSWORD, par exemple supabase 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 manuellement avec supabase migration new <nom>. N'inventez jamais un nom de fichier de migration et ne vous fiez pas à la mémoire pour le format attendu. Les projets de schéma déclaratif génèrent des migrations à partir de supabase/schemas/ ; voir "Réalisation et Validation des Modifications de Schéma" ci-dessous.

Vérification de version et mise à niveau : 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, 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 accessible : curl -so /dev/null -w "%{http_code}" https://mcp.supabase.com/mcp Un 401 est attendu (pas de jeton) et signifie que le serveur fonctionne. Un timeout ou "connection refused" signifie qu'il peut être en panne.
Vérifiez la configuration .mcp.json : Vérifiez que la racine du projet contient un .mcp.json valide avec l'URL correcte du serveur. S'il manque, créez-en un pointant vers https://mcp.supabase.com/mcp.
Authentifiez le serveur MCP : Si le serveur est accessible et que .mcp.json est correct mais que les outils ne sont pas visibles, l'utilisateur doit s'authentifier. Le serveur MCP Supabase utilise OAuth 2.1 — demandez à l'utilisateur de déclencher le flux d'authentification dans son agent, de le terminer dans le navigateur et de recharger la session. En CI ou dans d'autres environnements où le flux navigateur ne peut pas être exécuté, transmettez un jeton d'accès personnel limité dans l'en-tête Authorization: Bearer à la place.
Vérifiez les autorisations du jeton limité : Si un outil échoue avec "Vous n'avez pas l'autorisation d'effectuer cette action" lors de l'utilisation d'un jeton d'accès personnel limité, le jeton ne dispose pas de l'autorisation de cet outil ou le projet sort de la portée du jeton. Vérifiez l'autorisation requise par l'outil dans le guide des jetons d'accès personnels.

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 en markdown — toute page de documentation peut être récupérée en ajoutant .md au chemin de l'URL.
Recherche web pour des sujets spécifiques à Supabase lorsque vous ne savez pas quelle page consulter.

Réalisation et Validation des Modifications de Schéma

Commencez par déterminer quel workflow de schéma le projet utilise.

Option A : Schémas déclaratifs

Utilisez cette option 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 cette option 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). Ces commandes 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 locale — il é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 différences vides ou conflictuelles. Si vous l'utilisez, vous serez bloqué avec le SQL que vous avez passé au premier essai.

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 MCP get_advisors. Corrigez tout problème.
Examinez 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

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 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

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 qu'il manque des informations.

PhuongDeveloper/landingpage

Qu'est-ce que landingpage ?

Demander à votre IA préférée

Documentation