Supabase-Kompetenz

Supabase

Kernprinzipien

1. Supabase ändert sich häufig — überprüfen Sie vor der Implementierung die Änderungsprotokolle und die aktuellen Dokumente. Verlassen Sie sich nicht auf Trainingsdaten für Supabase-Funktionen. Funktionssignaturen, config.toml-Einstellungen und API-Konventionen ändern sich zwischen den Versionen.

Rufen Sie zuerst https://supabase.com/changelog.md ab (ein leichtgewichtiger Zusammenfassungsindex — kein großer Abruf), durchsuchen Sie ihn nach breaking-change-Tags, die für Ihre Aufgabe relevant sind, und folgen Sie der verlinkten Seite, falls zutreffend. Schlagen Sie dann das relevante Thema mit den unten stehenden Dokumentationszugriffsmethoden nach.

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

3. Erholen Sie sich von Fehlern, wiederholen Sie sie nicht. 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, falls verfügbar, die relevanten Protokolle an. Probleme mit Supabase werden nicht immer durch erneutes Ausführen desselben Befehls gelöst, und die Antwort ist nicht immer in den Protokollen zu finden, aber die Protokolle sind oft eine Überprüfung wert, bevor Sie fortfahren.

4. Tabellen für die Daten-API verfügbar machen: 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. In diesem Fall muss den anon- und authenticated-Rollen explizit Zugriff gewährt werden.

Beachten Sie, dass dies unabhängig von RLS ist, das 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 mit SQL erstellte Tabelle unerwartet nicht zugänglich ist, überprüfen Sie seine Daten-API-Einstellungen und ob den Rollen über explizite GRANT-SQLs Zugriff gewährt wurde. Wenn Sie öffentlichen Zugriff (anon/authenticated) gewähren, aktivieren Sie immer auch RLS. Siehe Verfügbarmachen einer Tabelle für die Daten-API für den vollständigen Einrichtungsworkflow.

5. RLS in exponierten Schemata. Aktivieren Sie RLS für jede Tabelle in jedem exponierten Schema, was standardmäßig public umfasst. Dies ist in Supabase kritisch, da Tabellen in exponierten Schemata über die Daten-API erreichbar sein können, wenn die Rollen anon/authenticated Zugriff haben (siehe Verfügbarmachen einer Tabelle für die Daten-API). Für private Schemata bevorzugen Sie RLS als Sicherheitsmaßnahme mit Verteidigung in der Tiefe. Erstellen Sie nach der Aktivierung von RLS Richtlinien, die dem tatsächlichen Zugriffsmodell entsprechen, anstatt jede Tabelle 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 erzeugen:

• Auth- 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 Autorisierungslogiken. 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-Gültigkeitsdauer für sensible Apps kurz und validieren Sie für strenge Garantien bei sensiblen Operationen die session_id gegen auth.sessions.
  • Wenn Sie app_metadata oder auth.jwt() für die Autorisierung verwenden, denken Sie daran, dass JWT-Claims erst dann frisch sind, wenn der Token des Benutzers aktualisiert wird.

• API-Schlüssel und Client-Exposition

  • Machen Sie den service_role oder geheimen Schlüssel niemals in öffentlichen Clients verfügbar. Bevorzugen Sie veröffentlichte Schlüssel für Frontend-Code. Legacy-anon-Schlüssel sind nur für die Kompatibilität. In Next.js wird jede NEXT_PUBLIC_-Umgebungsvariable an den Browser gesendet.

• RLS, Views und privilegierter Datenbankcode

  • Views umgehen standardmäßig RLS. Verwenden Sie in Postgres 15 und höher CREATE VIEW ... WITH (security_invoker = true). In älteren Versionen von Postgres schützen Sie Ihre Views, indem Sie den Zugriff für die Rollen anon und authenticated entziehen oder sie in ein nicht exponiertes 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 veraltet. 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 bestehen, unabhängig davon, 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 – es schränkt nicht ein, auf welche Zeilen ein Benutzer zugreifen kann. Das korrekte Muster kombiniert TO authenticated mit einem Eigentumsprä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 wird mit den Berechtigungen ihres Erstellers ausgeführt — typischerweise einer 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 zugrunde liegende Ursache zu beheben. Bevorzugen Sie SECURITY INVOKER.
  • SECURITY DEFINER-Funktionen in public sind von allen 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 Gewährung aufgerufen werden kann. Wenn SECURITY DEFINER wirklich benötigt wird (z. B. Umgehung von RLS in einer internen Nachschlagetabelle), behalten Sie die Funktion in einem nicht exponierten Schema, fügen Sie immer eine auth.uid()-Prüfung im Funktionsrumpf ein und führen Sie supabase db advisors nach Änderungen aus.

• Speicherzugriffskontrolle

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

Rufen Sie bei Sicherheitsbedenken, die nicht oben abgedeckt sind, 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 Top-Level-Befehle
supabase <group> --help            # Unterbefehle (z. B. supabase db --help)
supabase <group> <command> --help  # Flags für einen bestimmten Befehl

Bekannte Fallstricke des 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
• Wenn Sie eine neue Migrations-SQL-Datei benötigen, erstellen Sie diese immer zuerst mit supabase migration new <name>. Erfinden Sie niemals einen Migrationsdateinamen oder verlassen Sie sich auf das Gedächtnis für das erwartete Format.

Versionsprüfung und Upgrade: Führen Sie supabase --version aus, um die Version zu überprüfen. Für CLI-Änderungsprotokolle und versionsspezifische Funktionen konsultieren Sie die CLI-Dokumentation oder die GitHub-Releases.

Supabase MCP Server

Anweisungen zur Einrichtung, Server-URL und Konfiguration finden Sie im MCP-Einrichtungsleitfaden.

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

1. Überprüfen Sie, ob der Server erreichbar ist: curl -so /dev/null -w "%{http_code}" https://mcp.supabase.com/mcp Ein 401 wird erwartet (kein Token) und bedeutet, dass der Server läuft. Zeitüberschreitung 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 ist und .mcp.json korrekt ist, aber die Tools nicht sichtbar sind, muss sich der Benutzer authentifizieren. Der Supabase MCP Server verwendet OAuth 2.1 — bitten Sie den Benutzer, den Authentifizierungsablauf in seinem Agenten auszulösen, ihn im Browser abzuschließen und die Sitzung neu zu laden.

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 festschreiben

Verwenden Sie für Schemaänderungen execute_sql (MCP) oder supabase db query (CLI). Diese führen SQL direkt in der Datenbank aus, ohne Einträge im Migrationsverlauf zu erstellen, sodass Sie frei iterieren können und bei Bedarf eine saubere Migration erzeugen 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 Diff-Ergebnisse liefern wird. Wenn Sie es verwenden, bleiben Sie auf das SQL beschränkt, das Sie beim ersten Versuch übergeben haben.

Wenn Sie bereit sind, Ihre Änderungen in einer Migrationsdatei festzuschreiben:

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 <descriptive-name> --local --yes
4. Überprüfen → supabase migration list --local

Referenzleitfäden

• Rückmeldung zur Kompetenz → references/skill-feedback.md MUSS gelesen werden, wenn der Benutzer meldet, dass diese Kompetenz falsche Anweisungen gegeben hat oder Informationen fehlen.