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 istraw_user_meta_datavom Benutzer bearbeitbar und kann inauth.jwt()erscheinen, daher ist es unsicher für RLS-Richtlinien oder andere Autorisierungslogik. Speichern Sie Autorisierungsdaten stattdessen inraw_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_idgegenauth.sessionsbei sensiblen Operationen. - Wenn Sie
app_metadataoderauth.jwt()zur Autorisierung verwenden, denken Sie daran, dass JWT-Claims nicht immer aktuell sind, bis das Token des Benutzers aktualisiert wird.
- Verwenden Sie niemals
-
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 jedeNEXT_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.
- Setzen Sie den
-
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 Rollenanonundauthenticatedentziehen 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 dieTO-Klausel. Supabase hatauth.role()zugunsten der direkten Angabe der Zielrolle in der Richtlinie mitTO authenticatedoderTO anonals veraltet erklärt. Abgesehen von der Veraltung brichtauth.role() = 'authenticated'' stillschweigend, wenn anonyme Anmeldungen aktiviert sind, da anonyme Benutzer die Postgres-Rolleauthenticated` 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 authenticatedallein ist Authentifizierung ohne Autorisierung (BOLA / IDOR). Die Verwendung vonTO authenticatedprüft nur die Rolle – sie schränkt nicht ein, auf welche Zeilen ein Benutzer zugreifen kann. Das korrekte Muster kombiniertTO authenticatedmit einem Besitzprädikat inUSING:create policy "example" on table_name for select to authenticated using ( (select auth.uid()) = user_id );- UPDATE-Richtlinien erfordern sowohl
USINGals auchWITH CHECK. OhneWITH CHECKkann ein Benutzer dieuser_ideiner 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. EineSECURITY DEFINER-Funktion läuft mit den Rechten ihres Erstellers – typischerweise eine Rolle mitbypassrls(z.B.postgres). Fügen Sie niemalsSECURITY DEFINERhinzu, um einen Berechtigungsfehler zu beheben; es entfernt stillschweigend die Zugriffskontrolle, ohne die eigentliche Ursache zu beheben. Bevorzugen SieSECURITY INVOKER.SECURITY DEFINER-Funktionen inpublicsind für alle Rollen aufrufbar. Postgres gewährt standardmäßigEXECUTEanPUBLICfür jede neue Funktion, daher ist jedeSECURITY DEFINER-Funktion inpublicein öffentlicher API-Endpunkt, der vonanonundauthenticated(die vonPUBLICerben) ohne zusätzliche Berechtigung aufgerufen werden kann. WennSECURITY DEFINERwirklich 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 eineauth.uid()-Prüfung im Funktionsrumpf hinzu und führen Siesupabase db advisorsnach Änderungen aus.
- Views umgehen RLS standardmäßig. Verwenden Sie in Postgres 15 und höher
-
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-pyusw.). Siehe die npm-Sicherheitsanleitung für die vollständige Checkliste.
- Fixieren Sie immer Paketversionen und committen Sie Lockfiles bei der Installation von Supabase-Paketen (
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 queryerfordert CLI v2.79.0+ → verwenden Sie als Fallback MCPexecute_sqloderpsqlsupabase db advisorserfordert CLI v2.81.3+ → verwenden Sie als Fallback MCPget_advisors- Der Browser-Ablauf von
supabase loginerstellt ein klassisches Token mit vollem Kontozugriff. Setzen Sie in CI stattdessenSUPABASE_ACCESS_TOKENauf ein bereichsbezogenes persönliches Zugriffstoken. Es hat Vorrang vor jedem gespeicherten Login. Befehle, die eine Verbindung mit dem Datenbankkennwort herstellen (--passwordoderSUPABASE_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 aussupabase/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:
-
Prüfen Sie, ob der Server erreichbar ist:
curl -so /dev/null -w "%{http_code}" https://mcp.supabase.com/mcpEin401ist zu erwarten (kein Token) und bedeutet, dass der Server läuft. Timeout oder „connection refused“ bedeutet, dass er möglicherweise ausgefallen ist. -
Überprüfen Sie die
.mcp.json-Konfiguration: Stellen Sie sicher, dass das Projektstammverzeichnis eine gültige.mcp.jsonmit der korrekten Server-URL enthält. Wenn sie fehlt, erstellen Sie eine, die aufhttps://mcp.supabase.com/mcpverweist. -
Authentifizieren Sie den MCP-Server: Wenn der Server erreichbar und
.mcp.jsonkorrekt 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 imAuthorization: Bearer-Header. -
Ü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:
- MCP
search_docs-Tool (bevorzugt – gibt relevante Ausschnitte direkt zurück) - Dokumentationsseiten als Markdown abrufen – jede Dokumentationsseite kann durch Anhängen von
.mdan den URL-Pfad abgerufen werden. - 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:
- Führen Sie die Advisors aus →
supabase db advisors(CLI v2.81.3+) oder MCPget_advisors. Beheben Sie alle Probleme. - Überprüfen Sie die obige Sicherheitscheckliste, wenn Ihre Änderungen Views, Funktionen, Trigger oder Storage betreffen.
- Generieren Sie die Migration →
supabase db pull <beschreibender-name> --local --yes - Ü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.