Supabase CLI Anleitung für Entwickler (2026)

Kurz gesagt

Supabase CLI führt einen vollständigen Supabase-Stack auf Ihrem Computer mit Docker aus: PostgreSQL, Auth, Storage und Edge Functions. Installieren Sie es mit brew install supabase/tap/supabase, führen Sie supabase init und supabase start aus, um eine lokale Umgebung einzurichten, und verwenden Sie dann supabase db push und supabase functions deploy, um in die Produktion zu deployen. Es ist der schnellste Weg, Supabase-Backends zu erstellen und zu testen, ohne die Cloud zu berühren.

Einführung

73 % der Backend-Fehler werden in der Produktion entdeckt, weil Entwickler lokale Tests überspringen. Mit der Supabase CLI gibt es dafür keine Ausrede mehr. Sie erhalten eine vollständige, produktionsäquivalente Umgebung, die in weniger als 5 Minuten auf Ihrem Computer läuft.

Hier ist das eigentliche Problem: Die meisten Entwickler testen entweder direkt in der Produktion (riskant) oder verbringen Stunden damit, lokale Umgebungen zu konfigurieren, die nie ganz mit der Cloud übereinstimmen (frustrierend). Die Supabase CLI löst beides. Sie bietet Ihnen einen Docker-basierten lokalen Stack, der die Produktion exakt widerspiegelt, sodass das, was lokal funktioniert, auch in der Produktion funktioniert.

Testen Sie Ihre Supabase APIs mit Apidog – kostenlos

Am Ende dieses Leitfadens werden Sie in der Lage sein:

• In wenigen Minuten eine komplette lokale Supabase-Umgebung einrichten
• Datenbankschema-Änderungen mit versionskontrollierten Migrationen verwalten
• Edge Functions lokal erstellen und testen, bevor sie bereitgestellt werden
• Mit einem einzigen Befehl in die Produktion deployen

Warum die lokale Supabase-Entwicklung ohne CLI scheitert

Wenn Sie versucht haben, eine Supabase-App ohne die CLI zu erstellen, kennen Sie den Schmerz. Hier sind drei Szenarien, die ständig auftreten.

Die „Test in Produktion“-Falle. Sie nehmen eine Schemaänderung direkt im Supabase-Dashboard vor. Es funktioniert. Sie pushen Ihr Frontend. Drei Tage später zieht ein Teamkollege das Repository und seine App stürzt ab, weil seine Datenbank die neue Spalte nicht enthält.

Die Umgebungsinkonsistenz. Sie richten eine lokale PostgreSQL-Instanz ein, erstellen Ihr Supabase-Schema manuell neu und verbringen zwei Stunden damit, zu debuggen, warum Row Level Security-Richtlinien lokal anders funktionieren. Sie verhalten sich nicht anders. Sie haben eine Richtlinie übersehen.

Das „funktioniert auf meinem Rechner“-Problem. Ihre Edge Function funktioniert im Supabase-Dashboard-Editor, schlägt aber in der Produktion fehl, weil Sie mit fest codierten Werten statt mit echten Umgebungsvariablen getestet haben.

Dies sind keine Randfälle. Schema-Drift (lokale und entfernte Datenbanken geraten aus dem Gleichgewicht) ist das am häufigsten gemeldete Problem für Teams, die Supabase verwenden. Die CLI behebt alle drei Probleme:

• Migrationen halten Schema-Änderungen versionskontrolliert und reproduzierbar
• Der lokale Docker-Stack spiegelt die Produktion exakt wider: gleiche PostgreSQL-Version, gleiche RLS-Engine
• Lokales Funktions-Serving testet Edge Functions mit echten Umgebungsvariablen

Wie Supabase CLI funktioniert

Der lokale Stack

Wenn Sie supabase start ausführen, startet die CLI einen Docker Compose Stack mit diesen Diensten:

Dies ist derselbe Stack, der in Supabase Cloud läuft. Auf Ihrem Computer.

Installation

macOS:

brew install supabase/tap/supabase

Windows (Scoop):

scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
scoop install supabase

Linux / npm:

npm install -g supabase

Überprüfen, ob es funktioniert hat:

supabase --version
# supabase 1.x.x

supabase start

Projekteinrichtung

mkdir my-project && cd my-project
supabase init

Dies erstellt:

supabase/
├── config.toml       # Ports, Auth-Einstellungen, Speicher-Konfiguration
├── seed.sql          # Entwicklungsdaten, die bei jedem DB-Reset geladen werden
└── migrations/       # Schema-Versionshistorie

Lokalen Stack starten

supabase start

Der erste Durchlauf lädt etwa 1 GB an Docker-Images herunter. Danach dauern die Starts etwa 10 Sekunden.

API URL: http://localhost:54321
DB URL:  postgresql://postgres:postgres@localhost:54322/postgres
Studio:  http://localhost:54323
anon key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Kopieren Sie den anon key in Ihre .env.local-Datei. Sie benötigen ihn für Ihr Frontend.

Datenbankverwaltung mit Migrationen

Migrationen sind der Kern des CLI-Workflows. Jede Schemaänderung wird zu einer versionskontrollierten SQL-Datei, die in Git verfolgt wird. Kein „Wer hat wann die Datenbank geändert“ mehr.

Erste Migration erstellen

supabase migration new create_posts_table
# Creates: supabase/migrations/20260324120000_create_posts_table.sql

Bearbeiten Sie die Datei:

-- Create posts table with RLS from the start
CREATE TABLE posts (
  id          UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  user_id     UUID REFERENCES auth.users(id) ON DELETE CASCADE NOT NULL,
  title       TEXT NOT NULL,
  content     TEXT,
  published   BOOLEAN DEFAULT false,
  created_at  TIMESTAMPTZ DEFAULT NOW(),
  updated_at  TIMESTAMPTZ DEFAULT NOW()
);

-- Enable Row Level Security
ALTER TABLE posts ENABLE ROW LEVEL SECURITY;

-- Anyone can read published posts
CREATE POLICY "Anyone can read published posts"
  ON posts FOR SELECT
  USING (published = true);

-- Users manage their own posts
CREATE POLICY "Users manage own posts"
  ON posts FOR ALL
  USING (auth.uid() = user_id);

-- Auto-update updated_at on every change
CREATE OR REPLACE FUNCTION update_updated_at()
RETURNS TRIGGER AS $$
BEGIN
  NEW.updated_at = NOW();
  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER posts_updated_at
  BEFORE UPDATE ON posts
  FOR EACH ROW EXECUTE FUNCTION update_updated_at();

Wenden Sie sie an:

supabase migration up

TypeScript-Typen generieren

Nach jeder Schemaänderung generieren Sie Ihre Typen neu:

supabase gen types typescript --local > src/types/database.ts

Ihr Frontend erhält volle Typsicherheit:

import { Database } from '@/types/database'

type Post = Database['public']['Tables']['posts']['Row']
type NewPost = Database['public']['Tables']['posts']['Insert']

// Ihr Editor fängt nun Typfehler vor der Laufzeit ab
const createPost = async (post: NewPost) => {
  const { data, error } = await supabase
    .from('posts')
    .insert(post)
    .select()
    .single()
  return data
}

Entwicklungsdaten seeden

Bearbeiten Sie supabase/seed.sql:

-- Testbenutzer (umgeht die Authentifizierung für die lokale Entwicklung)
INSERT INTO auth.users (id, email) VALUES
  ('00000000-0000-0000-0000-000000000001', 'alice@example.com'),
  ('00000000-0000-0000-0000-000000000002', 'bob@example.com');

-- Test-Beiträge
INSERT INTO posts (user_id, title, content, published) VALUES
  ('00000000-0000-0000-0000-000000000001', 'Getting started with Supabase', 'Here is what I learned...', true),
  ('00000000-0000-0000-0000-000000000002', 'Draft: API design patterns', 'Work in progress...', false);

Jederzeit zurücksetzen und neu seeden:

supabase db reset

Dies löscht alles, führt alle Migrationen erneut aus und lädt Ihre Seed-Daten. Führen Sie dies jeden Morgen aus, um neu zu beginnen.

Supabase APIs mit Apidog testen

Sobald Ihr lokales Supabase läuft, haben Sie eine voll funktionsfähige REST-API unter http://localhost:54321. Supabase generiert automatisch Endpunkte für jede Tabelle über PostgREST. Das manuelle Testen dieser mit Curl wird schnell mühsam, besonders wenn Sie RLS-Richtlinien mit verschiedenen Benutzer-Tokens testen müssen.

Apidog verbindet sich direkt mit Ihrer lokalen Supabase-Instanz. Sie können:

• Anfragen als wiederverwendbare Sammlungen speichern
• Denselben Endpunkt als verschiedene Benutzer testen, indem Sie Umgebungen wechseln
• Assertionen hinzufügen („Antwort enthält mindestens 1 Beitrag“) und diese als Testsuite ausführen
• API-Dokumentation automatisch mit Ihrem Team teilen

Apidog mit lokalem Supabase einrichten:

1. Ein neues Projekt in Apidog erstellen
2. Basis-URL festlegen: http://localhost:54321
3. Umgebungsvariable hinzufügen: anon_key = Ihr-lokaler-anon-key
4. Authorization-Header hinzufügen: Bearer {{anon_key}}

Den Posts-Endpunkt testen:

GET http://localhost:54321/rest/v1/posts?published=eq.true
Authorization: Bearer {{anon_key}}
apikey: {{anon_key}}

Speichern Sie dies als Anfrage, fügen Sie eine Assertion hinzu, dass die Antwort mindestens einen Beitrag enthält, und führen Sie sie jedes Mal aus, wenn Sie Ihre RLS-Richtlinien ändern. Sie werden fehlerhafte Richtlinien abfangen, bevor sie in Produktion gelangen.

Beginnen Sie mit dem Testen Ihrer Supabase APIs mit Apidog

Edge Functions: lokal erstellen und testen

Edge Functions laufen auf Deno am Edge, nahe bei Ihren Benutzern. Sie sind perfekt für Webhooks, Hintergrundaufgaben und API-Endpunkte, die serverseitige Logik benötigen.

Eine Funktion erstellen

supabase functions new send-welcome-email

Dies erstellt supabase/functions/send-welcome-email/index.ts:

import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'

serve(async (req) => {
  const { user_id } = await req.json()

  // Dienstrolle umgeht RLS – mit Vorsicht verwenden
  const supabase = createClient(
    Deno.env.get('SUPABASE_URL')!,
    Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
  )

  const { data: profile } = await supabase
    .from('profiles')
    .select('email, full_name')
    .eq('id', user_id)
    .single()

  // Ihre E-Mail-Sende-Logik hier
  console.log(`Sending welcome email to ${profile?.email}`)

  return new Response(
    JSON.stringify({ success: true }),
    { headers: { 'Content-Type': 'application/json' } }
  )
})

Lokal mit Hot Reload testen

supabase functions serve

Der Funktionsserver überwacht Dateiänderungen und lädt automatisch neu. Testen Sie es:

curl -X POST http://localhost:54321/functions/v1/send-welcome-email \
  -H "Authorization: Bearer YOUR_ANON_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "00000000-0000-0000-0000-000000000001"}'

In die Produktion deployen

# Eine Funktion deployen
supabase functions deploy send-welcome-email

# Alle Funktionen deployen
supabase functions deploy

Fortgeschrittene Techniken und bewährte Ansätze

Geheimnisverwaltung

Hinterlegen Sie API-Schlüssel niemals fest in Ihren Funktionen. Verwenden Sie Geheimnisse:

# Produktionsgeheimnisse setzen
supabase secrets set RESEND_API_KEY=re_xxx STRIPE_KEY=sk_live_xxx

# Alle Geheimnisse auflisten
supabase secrets list

# Ein Geheimnis entfernen
supabase secrets unset STRIPE_KEY

Greifen Sie in Funktionen darauf zu:

const resendKey = Deno.env.get('RESEND_API_KEY')
// Niemals: const resendKey = 're_xxx'

Datenbank-Branching

Arbeiten Sie an einer größeren Schemaänderung? Erstellen Sie einen isolierten Branch:

supabase branches create feature-payments
supabase branches switch feature-payments

# Änderungen vornehmen, testen, dann zusammenführen
supabase branches merge feature-payments

Dies hält Ihre Hauptentwicklungsdatenbank sauber, während Sie experimentieren.

Häufige Fehler, die vermieden werden sollten

Datenbank direkt im Studio bearbeiten. Verwenden Sie immer Migrationen. Direkte Bearbeitungen werden nicht verfolgt und stehen Ihren Teamkollegen nicht zur Verfügung.

.env-Dateien committen. Verwenden Sie supabase secrets set für die Produktion. Fügen Sie .env* zu Ihrer .gitignore hinzu.

supabase db reset nach dem Pull übergehen. Wenn Sie Änderungen von Teamkollegen pullen, müssen deren neue Migrationen lokal ausgeführt werden. Setzen Sie zurück, um sie anzuwenden.

Typen nach Schemaänderungen nicht regenerieren. Ihre TypeScript-Typen werden hinfällig, sobald Sie eine Spalte hinzufügen. Machen Sie die Typgenerierung zu einem Teil Ihres Migrations-Workflows.

Funktionen ohne lokale Tests deployen. Führen Sie immer supabase functions serve aus und testen Sie mit echten Anfragen, bevor Sie deployen.

Dienstrollen-Schlüssel im Frontend-Code verwenden. Der Dienstrollen-Schlüssel umgeht RLS. Er gehört nur in Edge Functions und serverseitigen Code, niemals in Ihren Browser.

Performance-Tipps

# Dienste überspringen, die Sie nicht benötigen, um Speicher zu sparen
supabase start --exclude-studio --exclude-inbucket

# Überprüfen, was Ressourcen verbraucht
docker stats

Alternativen und Vergleiche

Der lokale Emulator von Firebase eignet sich gut für schnelles Prototyping, bietet Ihnen aber keine echte PostgreSQL-Instanz. Das Branching-Modell von PlanetScale ist hervorragend für Schemaänderungen, aber Sie arbeiten immer gegen die Cloud. Die Supabase CLI gewinnt für Teams, die eine vollständig quelloffene, PostgreSQL-native lokale Entwicklungserfahrung wünschen.

Praxisbeispiele

SaaS-Anwendung mit Multi-Tenant-Daten. Ein Fintech-Startup verwaltet 47 Migrationen über drei Umgebungen (Dev, Staging, Prod). RLS-Richtlinien werden lokal mit verschiedenen Benutzerrollen getestet, bevor Code in Produktion geht. Ergebnis: null schema-bezogene Produktionsvorfälle in sechs Monaten.

E-Commerce-Auftragsverarbeitung. Ein E-Commerce-Team verwendet Edge Functions für die Stripe-Webhook-Verarbeitung. Sie testen Webhook-Payloads lokal mit supabase functions serve und echten Stripe-Test-Events. Die Bereitstellungszeit sank von 2 Stunden auf 15 Minuten.

Backend für mobile Apps. Ein React Native-Team generiert nach jeder Migration TypeScript-Typen und teilt diese als internes npm-Paket. Frontend und Backend bleiben automatisch synchron. Keine Fragen mehr im Slack wie „Welche Felder gibt dieser Endpunkt zurück?“.

Zusammenfassung

Hier ist, was Sie jetzt tun können:

• Eine komplette lokale Supabase-Umgebung in wenigen Minuten einrichten
• Migrationen verwenden, um jede Schemaänderung versionskontrolliert zu verwalten
• Edge Functions lokal mit Hot Reload testen
• TypeScript-Typen automatisch aus Ihrem Schema generieren
• Mit supabase db push und supabase functions deploy deployen
• Ihre APIs mit Apidog testen, bevor Sie sie in Produktion nehmen

Der Workflow zahlt sich sofort aus. Ihr Team liefert schneller, fängt Fehler früher ab und hat nie wieder mit Schema-Drift zu tun.

Ihre nächsten Schritte:

1. Installieren: brew install supabase/tap/supabase
2. Führen Sie supabase init in Ihrem Projekt aus
3. Erstellen Sie Ihre erste Migration
4. Apidog einrichten, um Ihre lokalen Endpunkte zu testen
5. Mit Vertrauen in die Produktion deployen

Testen Sie Ihre Supabase APIs mit Apidog – kostenlos

Häufig gestellte Fragen (FAQ)

Benötige ich Docker, um Supabase CLI zu verwenden?Ja. Docker Desktop muss ausgeführt werden, bevor supabase start verwendet wird. Die CLI verwendet Docker Compose, um den vollständigen Stack lokal auszuführen. Wenn Docker nicht ausgeführt wird, erhalten Sie die Fehlermeldung „Cannot connect to Docker daemon“ (Kann keine Verbindung zum Docker-Daemon herstellen).

Wie synchronisiere ich meine lokale Datenbank mit der Produktion?Verwenden Sie supabase db pull, um eine Migration von Ihrem Remote-Schema zu generieren, und dann supabase db push, um lokale Migrationen auf die Produktion anzuwenden. Führen Sie supabase db reset lokal aus, nachdem Sie gepullt haben, um sicherzustellen, dass Ihre Umgebung übereinstimmt.

Kann ich Supabase CLI ohne ein Supabase Cloud-Konto verwenden?Ja. Sie können die CLI vollständig lokal für die Entwicklung ohne Cloud-Konto verwenden. Sie benötigen supabase login und supabase link nur, wenn Sie bereit sind, in die Produktion zu deployen.

Wie gehe ich mit Migrationskonflikten in einem Team um?Pullen Sie die neuesten Git-Änderungen und führen Sie supabase db reset aus, bevor Sie neue Migrationen erstellen. Verwenden Sie aussagekräftige Migrationsnamen und kommunizieren Sie mit Ihrem Team, wenn Sie breaking schema changes vornehmen.

Was ist der Unterschied zwischen supabase db push und supabase migration up?supabase migration up wendet ausstehende Migrationen auf Ihre lokale Datenbank an. supabase db push wendet sie auf Ihr Remote- (Produktions-) Projekt an. Testen Sie immer zuerst lokal.

Kann ich Supabase CLI mit einem bestehenden Projekt verwenden?Ja. Führen Sie supabase link --project-ref IHRE_PROJEKT_ID aus, um eine Verknüpfung zu einem bestehenden Projekt herzustellen, und dann supabase db pull, um Migrationen aus Ihrem aktuellen Remote-Schema zu generieren.

Wie teste ich RLS-Richtlinien lokal?Verwenden Sie Supabase Studio unter http://localhost:54323, um zwischen Benutzerrollen zu wechseln, oder testen Sie über die API mit verschiedenen JWT-Tokens. Apidog macht dies einfach: Erstellen Sie mehrere Umgebungen mit unterschiedlichen Benutzer-Tokens und führen Sie dieselben Anfragen als verschiedene Benutzer aus.

Ist Supabase CLI kostenlos?Ja. Die CLI ist kostenlos und quelloffen. Die lokale Entwicklung kostet nichts. Sie zahlen nur für Supabase Cloud-Ressourcen, wenn Sie in die Produktion deployen.