Communitygithub.com

Supabase-Skill

Verwende diesen Skill für jede Aufgabe, die Supabase betrifft. Auslöser: Supabase-Produkte (Datenbank, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues); Client-Bibliotheken und SSR-Integrationen (supabase-js, @supabase/ssr) in Next.js, React, SvelteKit, Astro, Remix; Authentifizierungsprobleme (Login, Logout, Sessions, JWT, Cookies, getSession, getUser, getClaims, RLS); Supabase CLI oder MCP-Server; Schema-Änderungen, Migrationen, deklarative Schemata, Sicherheitsaudits, Postgres-Erweiterungen (pg_graphql, pg_cron, pg_vector); Debugging und Fehlerbehebung bei unerwartetem Verhalten in Supabase-Projekten (HTTP-Fehler, Postgres-Fehler, RLS-Überraschungen, Zugriffsverweigerung, Schema-Cache-Probleme, Timeouts, Edge Function-Abstürze, Realtime-Ausfälle, Storage-Fehler) und das Lesen oder Abfragen von Logs (Logs Explorer, ClickHouse).

Was ist Supabase-Skill?

Dieser Skill bietet umfassende, auf dem neuesten Stand gehaltene Richtlinien für die Arbeit mit Supabase. Er behandelt Kernprinzipien wie die Überprüfung des Changelogs vor der Implementierung, die Verifizierung von Änderungen und eine systematische Fehlerbehebung. Ein besonderer Schwerpunkt liegt auf der Sicherheit: Der Skill enthält eine detaillierte Checkliste zu Authentifizierung, API-Schlüsseln, RLS (Row-Level Security), Datenbankansichten, gespeicherten Funktionen und Storage-Zugriffskontrolle. Der Skill unterstützt Entwickler auf allen relevanten Plattformen, darunter Node.js, Next.js, React, SvelteKit, Astro und Remix, sowie die Supabase CLI und den MCP-Server. Er erklärt, wie deklarative und imperative Schema-Workflows verwendet werden, und gibt Anleitungen zum Debuggen von Fehlern in allen Supabase-Diensten, inklusive dem Abrufen der offiziellen Monitoring- und Debugging-Dokumentation. Die Beschreibung enthält zudem praktische Befehle und Links zu den entsprechenden Dokumentationsseiten, wobei Markdown-Strukturen wie Überschriften, Tabellen, Zitate und Codeblöcke erhalten bleiben.

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Supabase

Kernprinzipien

1. Supabase ändert sich häufig – vor der Implementierung gegen das Changelog und die aktuellen Dokumentationen prüfen. Verlassen Sie sich nicht auf Trainingsdaten für Supabase-Funktionen. Funktionssignaturen, config.toml-Einstellungen und API-Konventionen ändern sich zwischen Versionen.

Rufen Sie zunächst https://supabase.com/changelog.md ab (eine leichte Zusammenfassung – kein schwerer Abruf), suchen Sie nach breaking-change-Tags, die für Ihre Aufgabe relevant sind, und folgen Sie der verlinkten Seite für alle zutreffenden Änderungen. Schlagen Sie dann das relevante Thema mit den unten aufgeführten Methoden zum Zugriff auf die Dokumentation nach.

2. Überprüfen Sie Ihre Arbeit. Führen Sie nach der Implementierung einer Korrektur eine Testabfrage durch, um zu bestätigen, dass die Änderung funktioniert. Eine Korrektur ohne Überprüfung ist unvollständig.

3. Aus Fehlern lernen, nicht in Schleifen verharren. Wenn ein Ansatz nach 2-3 Versuchen fehlschlägt, stoppen Sie und überdenken Sie ihn. Versuchen Sie eine andere Methode, überprüfen Sie die Dokumentation, untersuchen Sie den Fehler genauer und sehen Sie sich die verfügbaren Logs an. Supabase-Probleme werden nicht immer durch wiederholtes Ausführen desselben Befehls gelöst, und die Antwort ist nicht immer in den Logs zu finden, aber es lohnt sich oft, die Logs zu überprüfen, bevor Sie fortfahren.

4. Tabellen für die Daten-API freigeben: Abhängig von den Daten-API-Einstellungen des Benutzers werden neu erstellte Tabellen möglicherweise nicht automatisch über die Daten-API (REST) verfügbar gemacht. Wenn dies der Fall ist, muss den Rollen anon und authenticated explizit Zugriff gewährt werden.

Beachten Sie, dass dies getrennt von RLS zu betrachten ist. RLS steuert, welche Zeilen sichtbar sind, sobald eine Tabelle zugänglich ist, und nicht, ob die Tabelle überhaupt zugänglich ist.

Wenn ein Benutzer meldet, dass eine per SQL erstellte Tabelle unerwartet nicht zugänglich ist, überprüfen Sie seine Daten-API-Einstellungen und ob den Rollen der Zugriff über explizites GRANT SQL gewährt wurde. Wenn Sie öffentlichen (anon/authenticated) Zugriff gewähren, aktivieren Sie immer auch RLS. Siehe Freigeben einer Tabelle für die Daten-API für den vollständigen Einrichtungsablauf.

5. RLS in freigegebenen Schemata. Aktivieren Sie RLS für jede Tabelle in jedem freigegebenen Schema, einschließlich public standardmäßig. Dies ist in Supabase kritisch, da Tabellen in freigegebenen Schemata über die Daten-API erreichbar sein können, wenn die Rollen anon/authenticated Zugriff haben (siehe Freigeben einer Tabelle für die Daten-API). Für private Schemata bevorzugen Sie RLS als Verteidigung in der Tiefe. Erstellen Sie nach dem Aktivieren von RLS Richtlinien, die dem tatsächlichen Zugriffsmodell entsprechen, anstatt jede Tabelle standardmäßig auf dasselbe auth.uid()-Muster zu setzen.

6. Sicherheitscheckliste. Wenn Sie an einer Supabase-Aufgabe arbeiten, die Auth, RLS, Views, Storage oder Benutzerdaten betrifft, gehen Sie diese Checkliste durch. Dies sind Supabase-spezifische Sicherheitsfallen, die stillschweigend Schwachstellen schaffen:

  • Authentifizierungs- und Sitzungssicherheit

    • Verwenden Sie niemals user_metadata-Claims in JWT-basierten Autorisierungsentscheidungen. In Supabase ist raw_user_meta_data vom Benutzer bearbeitbar und kann in auth.jwt() erscheinen, daher ist es unsicher für RLS-Richtlinien oder andere Autorisierungslogik. Speichern Sie Autorisierungsdaten stattdessen in raw_app_meta_data / app_metadata.
    • Das Löschen eines Benutzers macht vorhandene Zugriffstokens nicht ungültig. Melden Sie sich zuerst ab oder widerrufen Sie Sitzungen, halten Sie die JWT-Ablaufzeit für sensible Apps kurz, und validieren Sie für strenge Garantien session_id gegen auth.sessions bei sensiblen Operationen.
    • Wenn Sie app_metadata oder auth.jwt() zur Autorisierung verwenden, denken Sie daran, dass JWT-Claims nicht immer aktuell sind, bis das Token des Benutzers aktualisiert wird.
  • API-Schlüssel und Client-Exposition

    • Setzen Sie den service_role- oder Secret-Key niemals in öffentlichen Clients offen. Bevorzugen Sie veröffentlichbare Schlüssel für Frontend-Code. Legacy-anon-Schlüssel dienen nur der Kompatibilität. In Next.js wird jede NEXT_PUBLIC_-Umgebungsvariable an den Browser gesendet.
    • Verwenden Sie für die Management-API, CLI und den MCP-Server bereichsbezogene persönliche Zugriffstokens. Ein klassisches persönliches Zugriffstoken trägt den vollständigen Kontozugriff des Benutzers auf jede Organisation und jedes Projekt. Für Skripte, CI und Agenten lassen Sie den Benutzer ein bereichsbezogenes Token erstellen, das auf die Organisationen, Projekte und Berechtigungen beschränkt ist, die die Aufgabe benötigt. Der Leitfaden für persönliche Zugriffstokens listet die Berechtigung auf, die jeder Management-API-Endpunkt und jedes MCP-Tool benötigt. Schlagen Sie Berechtigungen dort nach, anstatt zu raten.
  • RLS, Views und privilegierter Datenbankcode

    • Views umgehen RLS standardmäßig. Verwenden Sie in Postgres 15 und höher CREATE VIEW ... WITH (security_invoker = true). Schützen Sie in älteren Versionen von Postgres Ihre Views, indem Sie den Zugriff für die Rollen anon und authenticated entziehen oder sie in ein nicht freigegebenes Schema legen.
    • UPDATE erfordert eine SELECT-Richtlinie. In Postgres RLS muss ein UPDATE zuerst die Zeile SELECTEN. Ohne eine SELECT-Richtlinie geben Updates stillschweigend 0 Zeilen zurück – kein Fehler, nur keine Änderung.
    • auth.role() ist veraltet – verwenden Sie stattdessen die TO-Klausel. Supabase hat auth.role() zugunsten der direkten Angabe der Zielrolle in der Richtlinie mit TO authenticated oder TO anon als veraltet erklärt. Abgesehen von der Veraltung bricht auth.role() = 'authenticated'' stillschweigend, wenn anonyme Anmeldungen aktiviert sind, da anonyme Benutzer die Postgres-Rolle authenticated` tragen und die Prüfung unabhängig davon bestehen, ob der Benutzer tatsächlich angemeldet ist.
      -- Veraltet (nicht verwenden)
      create policy "example" on table_name for select
      using ( auth.role() = 'authenticated' );
      
    • TO authenticated allein ist Authentifizierung ohne Autorisierung (BOLA / IDOR). Die Verwendung von TO authenticated prüft nur die Rolle – sie schränkt nicht ein, auf welche Zeilen ein Benutzer zugreifen kann. Das korrekte Muster kombiniert TO authenticated mit einem Besitzprädikat in USING:
      create policy "example" on table_name for select
      to authenticated
      using ( (select auth.uid()) = user_id );
      
    • UPDATE-Richtlinien erfordern sowohl USING als auch WITH CHECK. Ohne WITH CHECK kann ein Benutzer die user_id einer Zeile einem anderen Benutzer zuweisen:
      create policy "example" on table_name for update
      to authenticated
      using ( (select auth.uid()) = user_id )
      with check ( (select auth.uid()) = user_id );
      
    • SECURITY DEFINER-Funktionen umgehen RLS. Eine SECURITY DEFINER-Funktion läuft mit den Rechten ihres Erstellers – typischerweise eine Rolle mit bypassrls (z.B. postgres). Fügen Sie niemals SECURITY DEFINER hinzu, um einen Berechtigungsfehler zu beheben; es entfernt stillschweigend die Zugriffskontrolle, ohne die eigentliche Ursache zu beheben. Bevorzugen Sie SECURITY INVOKER.
    • SECURITY DEFINER-Funktionen in public sind für alle Rollen aufrufbar. Postgres gewährt standardmäßig EXECUTE an PUBLIC für jede neue Funktion, daher ist jede SECURITY DEFINER-Funktion in public ein öffentlicher API-Endpunkt, der von anon und authenticated (die von PUBLIC erben) ohne zusätzliche Berechtigung aufgerufen werden kann. Wenn SECURITY DEFINER wirklich benötigt wird (z.B. zur Umgehung von RLS in einer internen Nachschlagetabelle), behalten Sie die Funktion in einem nicht freigegebenen Schema, fügen Sie immer eine auth.uid()-Prüfung im Funktionsrumpf hinzu und führen Sie supabase db advisors nach Änderungen aus.
  • Storage-Zugriffskontrolle

    • Storage-Upsert erfordert INSERT + SELECT + UPDATE. Die Gewährung von nur INSERT ermöglicht neue Uploads, aber das Ersetzen von Dateien (Upsert) schlägt stillschweigend fehl. Sie benötigen alle drei.
  • Abhängigkeits- und Supply-Chain-Sicherheit

    • Fixieren Sie immer Paketversionen und committen Sie Lockfiles bei der Installation von Supabase-Paketen (supabase-js, @supabase/ssr, supabase-py usw.). Siehe die npm-Sicherheitsanleitung für die vollständige Checkliste.

Für Sicherheitsbedenken, die oben nicht abgedeckt sind, rufen Sie den Supabase-Produktsicherheitsindex ab: https://supabase.com/docs/guides/security/product-security.md

Supabase CLI

Entdecken Sie Befehle immer über --help – raten Sie niemals. Die CLI-Struktur ändert sich zwischen den Versionen.

supabase --help                    # Alle Befehle der obersten Ebene
supabase <group> --help            # Unterbefehle (z.B. supabase db --help)
supabase <group> <command> --help  # Flags für einen bestimmten Befehl

Bekannte Fallstricke der Supabase CLI:

  • supabase db query erfordert CLI v2.79.0+ → verwenden Sie als Fallback MCP execute_sql oder psql
  • supabase db advisors erfordert CLI v2.81.3+ → verwenden Sie als Fallback MCP get_advisors
  • Der Browser-Ablauf von supabase login erstellt ein klassisches Token mit vollem Kontozugriff. Setzen Sie in CI stattdessen SUPABASE_ACCESS_TOKEN auf ein bereichsbezogenes persönliches Zugriffstoken. Es hat Vorrang vor jedem gespeicherten Login. Befehle, die eine Verbindung mit dem Datenbankkennwort herstellen (--password oder SUPABASE_DB_PASSWORD, z.B. supabase db push), unterliegen nicht den Berechtigungen des Tokens.
  • Erstellen Sie in imperativen Migrationsprojekten zuerst neue manuell verfasste Migrationsdateien mit supabase migration new <name>. Erfinden Sie niemals einen Migrationsdateinamen oder verlassen Sie sich auf Ihr Gedächtnis für das erwartete Format. Deklarative Schema-Projekte generieren Migrationen aus supabase/schemas/; siehe „Schemaänderungen vornehmen und committen“ unten.

Versionsprüfung und Upgrade: Führen Sie supabase --version aus, um zu prüfen. Informationen zu CLI-Changelogs und versionsspezifischen Funktionen finden Sie in der CLI-Dokumentation oder in den GitHub-Releases.

Supabase MCP Server

Einrichtungsanweisungen, Server-URL und Konfiguration finden Sie in der MCP-Einrichtungsanleitung.

Fehlerbehebung bei Verbindungsproblemen – führen Sie diese Schritte der Reihe nach aus:

  1. Prüfen Sie, ob der Server erreichbar ist: curl -so /dev/null -w "%{http_code}" https://mcp.supabase.com/mcp Ein 401 ist zu erwarten (kein Token) und bedeutet, dass der Server läuft. Timeout oder „connection refused“ bedeutet, dass er möglicherweise ausgefallen ist.

  2. Überprüfen Sie die .mcp.json-Konfiguration: Stellen Sie sicher, dass das Projektstammverzeichnis eine gültige .mcp.json mit der korrekten Server-URL enthält. Wenn sie fehlt, erstellen Sie eine, die auf https://mcp.supabase.com/mcp verweist.

  3. Authentifizieren Sie den MCP-Server: Wenn der Server erreichbar und .mcp.json korrekt ist, die Tools aber nicht sichtbar sind, muss sich der Benutzer authentifizieren. Der Supabase MCP-Server verwendet OAuth 2.1 – weisen Sie den Benutzer an, den Auth-Ablauf in seinem Agenten auszulösen, ihn im Browser abzuschließen und die Sitzung neu zu laden. Übergeben Sie in CI oder anderen Umgebungen, in denen der Browser-Ablauf nicht ausgeführt werden kann, stattdessen ein bereichsbezogenes persönliches Zugriffstoken im Authorization: Bearer-Header.

  4. Überprüfen Sie die Berechtigungen des bereichsbezogenen Tokens: Wenn ein Tool mit „Sie haben keine Berechtigung, diese Aktion auszuführen“ fehlschlägt, während ein bereichsbezogenes persönliches Zugriffstoken verwendet wird, fehlt dem Token die Berechtigung für dieses Tool oder das Projekt liegt außerhalb des Token-Bereichs. Überprüfen Sie die erforderliche Berechtigung des Tools im Leitfaden für persönliche Zugriffstokens.

Supabase Dokumentation

Bevor Sie eine Supabase-Funktion implementieren, finden Sie die relevante Dokumentation. Verwenden Sie diese Methoden in der angegebenen Prioritätsreihenfolge:

  1. MCP search_docs-Tool (bevorzugt – gibt relevante Ausschnitte direkt zurück)
  2. Dokumentationsseiten als Markdown abrufen – jede Dokumentationsseite kann durch Anhängen von .md an den URL-Pfad abgerufen werden.
  3. Websuche nach Supabase-spezifischen Themen, wenn Sie nicht wissen, welche Seite Sie ansehen sollen.

Schemaänderungen vornehmen und committen

Entscheiden Sie zunächst, welchen Schema-Workflow das Projekt verwendet.

Option A: Deklarative Schemata

Verwenden Sie diese Option, wenn supabase/schemas/ existiert oder config.toml schema_paths setzt. Bearbeiten Sie den gewünschten Schema-Status in diesen Dateien und generieren und überprüfen Sie dann die Migration. Beginnen Sie nicht damit, eine Migration von Hand zu schreiben. Siehe den Leitfaden für deklarative Datenbankschemata.

Option B: Imperative Migrationen

Verwenden Sie diese Option, wenn das Projekt keine deklarativen Schemata verwendet.

Verwenden Sie zum Vornehmen von Schemaänderungen execute_sql (MCP) oder supabase db query (CLI). Diese führen SQL direkt auf der Datenbank aus, ohne Einträge im Migrationsverlauf zu erstellen, sodass Sie frei iterieren und bei Bedarf eine saubere Migration generieren können.

Verwenden Sie NICHT apply_migration, um ein lokales Datenbankschema zu ändern – es schreibt bei jedem Aufruf einen Eintrag im Migrationsverlauf, was bedeutet, dass Sie nicht iterieren können und supabase db diff / supabase db pull leere oder widersprüchliche Diffs erzeugen. Wenn Sie es verwenden, bleiben Sie bei dem SQL hängen, das Sie beim ersten Versuch übergeben haben.

Wenn Sie bereit zum Committen Ihrer Änderungen in eine Migrationsdatei sind:

  1. Führen Sie die Advisors aus → supabase db advisors (CLI v2.81.3+) oder MCP get_advisors. Beheben Sie alle Probleme.
  2. Überprüfen Sie die obige Sicherheitscheckliste, wenn Ihre Änderungen Views, Funktionen, Trigger oder Storage betreffen.
  3. Generieren Sie die Migration → supabase db pull <beschreibender-name> --local --yes
  4. Überprüfen Sie → supabase migration list --local

Debugging

Wenn Sie bei einer Supabase-bezogenen Anfrage einen Fehler erhalten, z.B. einen Fehlercode von der Supabase REST API, der Postgres-Datenbank oder PostgREST, ein leeres Ergebnis, eine unerwartete Blockierung durch RLS oder einen Fehler von einem Supabase-Dienst wie Auth, Realtime, Edge Functions oder Storage, müssen Sie die Supabase- Überwachungs- und Debugging-Dokumentation abrufen, bevor Sie eine Diagnose stellen oder einen Lösungsvorschlag machen, anstatt aus dem Gedächtnis zu arbeiten. Dieselbe Dokumentation behandelt auch Leistungsoptimierungen, wie langsame Abfragen und fehlende Indizes.

Referenzleitfäden

  • Skill-Feedback → references/skill-feedback.md MUSS gelesen werden, wenn der Benutzer meldet, dass dieser Skill falsche Anleitungen gegeben hat oder Informationen fehlen.

Individual skills in this repo

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

Verwandte Skills