PhuongDeveloper/landingpage

Supabase

Kernprinzipien

1. Supabase ändert sich häufig – überprüfen Sie vor der Implementierung immer das Changelog und die aktuellen Docs. 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 (eine kurze Zusammenfassung – kein schwerer Abruf), suchen Sie nach breaking-change-Tags, die für Ihre Aufgabe relevant sind, und folgen Sie dem verlinkten Artikel für alle zutreffenden Änderungen. Schlagen Sie dann das relevante Thema mit den unten stehenden Methoden zum Zugriff auf die Dokumentation nach.

2. Überprüfen Sie Ihre Arbeit. Nachdem Sie einen Fix implementiert haben, führen Sie eine Testabfrage aus, um zu bestätigen, dass die Änderung funktioniert. Ein Fix ohne Verifizierung ist unvollständig.

3. Erholen Sie sich von Fehlern, vermeiden Sie Endlosschleifen. 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 relevanten Logs an, falls verfügbar. 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 prüfen, bevor Sie fortfahren.

4. Tabellen für die Data API freigeben: Abhängig von den Data API-Einstellungen des Benutzers werden neu erstellte Tabellen möglicherweise nicht automatisch über die Data (REST) API verfügbar gemacht. Wenn dies der Fall ist, muss den Rollen anon und authenticated 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 per SQL erstellte Tabelle unerwartet nicht zugänglich ist, überprüfen Sie seine Data API-Einstellungen und ob den Rollen Zugriff über explizite GRANT-SQL gewährt wurde. Wenn Sie öffentlichen Zugriff (anon/authenticated) gewähren, aktivieren Sie immer auch RLS. Siehe Tabelle für die Data API freigeben für den vollständigen Einrichtungsworkflow.

5. RLS in offengelegten Schemas. Aktivieren Sie RLS für jede Tabelle in jedem offengelegten Schema, einschließlich public standardmäßig. Dies ist in Supabase kritisch, da Tabellen in offengelegten Schemas über die Data API erreichbar sein können, wenn die Rollen anon/authenticated Zugriff haben (siehe Tabelle für die Data API freigeben). Für private Schemas bevorzugen Sie RLS als Verteidigung in der Tiefe. Nachdem Sie RLS aktiviert haben, erstellen Sie Richtlinien, die zum tatsächlichen Zugriffsmodell passen, anstatt standardmäßig für jede Tabelle dasselbe auth.uid()-Muster zu verwenden.

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 Autorisierungslogik. Speichern Sie Autorisierungsdaten stattdessen in raw_app_meta_data / app_metadata.
  • Das Löschen eines Benutzers macht vorhandene Zugriffstoken nicht ungültig. Melden Sie sich zuerst ab oder widerrufen Sie Sitzungen, halten Sie die JWT-Ablaufzeit für vertrauliche Apps kurz, und validieren Sie für strenge Garantien die session_id gegen auth.sessions bei vertraulichen 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 erneuert wird.

• API-Schlüssel und Client-Exposition

  • Setzen Sie den service_role- oder Secret-Key niemals in öffentlichen Clients aus. Bevorzugen Sie veröffentlichbare Schlüssel für Frontend-Code. Legacy-anon-Schlüssel sind nur aus Kompatibilitätsgründen vorhanden. In Next.js wird jede NEXT_PUBLIC_-Umgebungsvariable an den Browser gesendet.
  • Verwenden Sie eingeschränkte persönliche Zugriffstoken für die Management-API, die CLI und den MCP-Server. 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 eingeschränktes Token erstellen, das auf die Organisationen, Projekte und Berechtigungen beschränkt ist, die die Aufgabe benötigt. Der Leitfaden zu persönlichen Zugriffstoken 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 privilegierte Datenbankcodes

  • Views umgehen RLS standardmäßig. Verwenden Sie in Postgres 15 und höher CREATE VIEW ... WITH (security_invoker = true). Schützen Sie in älteren Postgres-Versionen Ihre Views, indem Sie den Zugriff für die Rollen anon und authenticated entziehen oder sie in ein nicht offengelegtes 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. Über die Veralterung hinaus 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 – sie 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 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 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), halten Sie die Funktion in einem nicht offengelegten Schema, fügen Sie immer eine auth.uid()-Prüfung im Funktionskörper ein und führen Sie supabase db advisors nach Änderungen aus.

• Speicherzugriffskontrolle

  • Storage-Upsert erfordert INSERT + SELECT + UPDATE. Die Gewährung von nur INSERT erlaubt neue Uploads, aber das Ersetzen von Dateien (Upsert) schlägt stillschweigend fehl. Sie benötigen alle drei.

• Abhängigkeits- und Lieferkettensicherheit

  • Fixieren Sie immer Paketversionen und committen Sie Sperrdateien, wenn Sie Supabase-Pakete installieren (supabase-js, @supabase/ssr, supabase-py usw.). Siehe npm-Sicherheitsleitfaden für die vollständige Checkliste.

Holen Sie für Sicherheitsbedenken, die hier nicht 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 übergeordneten Befehle
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-Flow von supabase login erstellt ein klassisches Token mit vollem Kontozugriff. Setzen Sie in CI stattdessen SUPABASE_ACCESS_TOKEN auf ein eingeschränktes persönliches Zugriffstoken. Es hat Vorrang vor jeder gespeicherten Anmeldung. Befehle, die eine Verbindung mit dem Datenbankpasswort herstellen (--password oder SUPABASE_DB_PASSWORD, z.B. supabase db push), sind nicht durch die Berechtigungen des Tokens eingeschränkt.
• Erstellen Sie in imperativen Migrationsprojekten zuerst neue manuell erstellte 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" weiter unten.

Versionsprüfung und Upgrade: Führen Sie supabase --version zur Überprüfung aus. 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 im MCP-Setup-Leitfaden.

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 „Verbindung abgelehnt" 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-Flow 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-Flow nicht ausgeführt werden kann, stattdessen ein eingeschränktes persönliches Zugriffstoken im Authorization: Bearer-Header.

4. Überprüfen Sie die Berechtigungen des eingeschränkten Tokens: Wenn ein Tool mit „Sie haben keine Berechtigung, diese Aktion auszuführen" fehlschlägt, während ein eingeschränktes 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 zu persönlichen Zugriffstoken.

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. Docs-Seiten als Markdown abrufen – jede Docs-Seite 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 aufrufen sollen.

Schemaänderungen vornehmen und committen

Entscheiden Sie zuerst, welchen Schema-Workflow das Projekt verwendet.

Option A: Deklarative Schemas

Verwenden Sie dies, 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 Leitfaden für deklarative Datenbankschemas.

Option B: Imperative Migrationen

Verwenden Sie dies, wenn das Projekt keine deklarativen Schemas verwendet.

Verwenden Sie execute_sql (MCP) oder supabase db query (CLI), um Schemaänderungen vorzunehmen. Diese führen SQL direkt auf der Datenbank aus, ohne Migrationseinträge 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 Migrationseintrag, was bedeutet, dass Sie nicht iterieren können, und supabase db diff / supabase db pull leere oder inkonsistente Unterschiede erzeugen. Wenn Sie es verwenden, bleiben Sie bei dem SQL hängen, das Sie beim ersten Versuch übergeben haben.

Wenn Sie bereit sind, Ihre Änderungen an eine Migrationsdatei zu committen:

1. Advisors ausführen → 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. Migration generieren → supabase db pull <description-name> --local --yes
4. Überprüfen → supabase migration list --local

Fehlerbehebung

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, unerwartete Blockierung durch RLS oder einen Fehler von einem Supabase-Dienst wie Auth, Realtime, Edge Functions oder Storage, müssen Sie die Supabase-Dokumentation Monitoring und Debugging abrufen, bevor Sie eine Diagnose stellen oder eine Lösung vorschlagen, anstatt aus dem Gedächtnis zu arbeiten. Dieselben Docs behandeln auch Leistungsoptimierungen, wie langsame Abfragen und fehlende Indizes.

Referenzhandbücher

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