Communitygithub.com

Futurists2023/supabase

Utilisez cette compétence pour toute tâche impliquant Supabase. Déclencheurs : produits Supabase (Base de données, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues) ; intégrations client et SSR (supabase-js, @supabase/ssr) dans Next.js, React, SvelteKit, Astro, Remix ; problèmes d'authentification (connexion, déconnexion, sessions, JWT, cookies, getSession, getUser, getClaims, RLS) ; CLI Supabase ou serveur MCP ; modifications de schéma, migrations, schémas déclaratifs, audits de sécurité, extensions Postgres (pg_graphql, pg_cron, pg_vector) ; débogage et résolution d'erreurs ou de comportements inattendus sur des projets Supabase (erreurs HTTP, erreurs Postgres, surprises RLS, permission refusée, problèmes de cache de schéma, timeouts, crashs de Edge Function, pertes Realtime, échecs Storage) et lecture ou interrogation des logs (Logs Explorer, ClickHouse).

Qu'est-ce que supabase ?

Cette compétence est un guide de référence complet pour les développeurs travaillant avec la plateforme Supabase, couvrant tous ses composants clés : base de données, authentification, Edge Functions, Realtime, Storage, vecteurs, Cron, files d'attente et intégrations client pour les frameworks modernes (Next.js, React, SvelteKit, Astro, Remix). Elle fournit des principes fondamentaux essentiels, notamment la vérification systématique des changelogs et de la documentation à jour avant toute implémentation, des checklists de sécurité détaillées pour éviter les pièges courants (comme l'utilisation de `user_metadata` dans les politiques RLS, les risques liés aux vues qui contournent RLS par défaut, ou les fonctions SECURITY DEFINER), et des directives précises pour l'utilisation de la CLI Supabase et du serveur MCP. La compétence détaille deux workflows de gestion de schéma (déclaratif et impératif), un processus de débogage structuré basé sur la documentation officielle, et des instructions pour la génération et la validation des migrations. Elle est conçue pour les agents d'IA qui doivent interagir avec des projets Supabase, en leur fournissant des règles et des vérifications à suivre pour garantir des implémentations correctes et sécurisées. Toutes les modifications de schéma doivent d'abord être testées avec `execute_sql` (MCP) ou `supabase db query` (CLI), avant d'être commitées dans un fichier de migration via `supabase db pull`. Les politiques RLS doivent être créées avec `TO authenticated` ou `TO anon` et des prédicats de propriété appropriés.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Futurists2023/tiktok/tree/HEAD/.agents/skills/supabase

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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_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 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 tant que le jeton de l'utilisateur n'est pas actualisé.
  • Exposition des clés API et du client

    • N'exposez jamais la clé service_role ou la clé 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 là que pour la compatibilité. Dans Next.js, toute variable d'environnement NEXT_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.
  • 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ôles anon et authenticated, 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 clause TO à la place. Supabase a rendu obsolète auth.role() en faveur de la spécification directe du rôle cible sur la politique avec TO authenticated ou TO 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 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 — cela ne restreint 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éaffecter 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 le 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 corriger 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 d'API public appelable par anon et authenticated (qui héritent de PUBLIC) sans aucun privilège supplémentaire. Lorsque SECURITY DEFINER est 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érification auth.uid() dans le corps de la fonction, et exécutez supabase db advisors après avoir effectué des modifications.
  • 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.

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 query nécessite CLI v2.79.0+ → utilisez MCP execute_sql ou psql comme solution de repli
  • supabase db advisors nécessite CLI v2.81.3+ → utilisez MCP get_advisors comme solution de repli
  • Le flux navigateur de supabase login crée un jeton classique avec un accès complet au compte. Dans l'CI, définissez plutôt SUPABASE_ACCESS_TOKEN sur 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 (--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 à 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 de supabase/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 :

  1. Vérifiez si le serveur est accessible : curl -so /dev/null -w "%{http_code}" https://mcp.supabase.com/mcp Une 401 est 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.

  2. Vérifiez la configuration .mcp.json : Vérifiez que la racine du projet contient un .mcp.json valide avec l'URL correcte du serveur. Si absent, créez-en un pointant vers https://mcp.supabase.com/mcp.

  3. 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 — 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ête Authorization: Bearer à la place.

  4. 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é :

  1. Outil MCP search_docs (préféré — renvoie des extraits pertinents directement)
  2. Récupérez les pages de documentation au format markdown — n'importe quelle page de documentation peut être récupérée en ajoutant .md au chemin de l'URL.
  3. 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 :

  1. Exécutez les advisors → supabase db advisors (CLI v2.81.3+) ou MCP get_advisors. Corrigez tout problème.
  2. 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.
  3. Générez la migration → supabase db pull <nom-descriptif> --local --yes
  4. 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.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Skills associés