Supabase Cloud zu Self-Hosted migrieren: vollständiger Ablauf

Sie möchten den Umzug nicht als einmaligen Datenbankimport riskieren? WZ-IT führt die Supabase-Migration ab 3.490 € mit Assessment, Testmigration, Cutover und dokumentiertem Rückfallpunkt durch.

Eine Migration von Supabase Cloud zu Self-Hosted Supabase besteht aus mehreren miteinander verbundenen Umzügen. PostgreSQL ist der Kern, aber Auth, Storage, Functions, Secrets, Realtime und die Anwendungskonfiguration müssen ebenfalls auf das Ziel zeigen.

Die offizielle Supabase-Anleitung beschreibt den Datenbanktransfer. Sie weist ausdrücklich darauf hin, dass Storage-Objekte und Edge Functions nicht durch diesen Datenbankprozess migriert werden. Für eine produktive Anwendung ist deshalb ein vollständigeres Runbook erforderlich.

1. Bestand vor dem Umzug erfassen

Vor dem ersten Export sollten mindestens diese Informationen vorliegen:

• PostgreSQL-Version, Datenbankgröße und Änderungsrate
• aktive Extensions und eigene Rollen
• Schemas, Views, Functions, Trigger und Cronjobs
• Auth-Provider, MFA, SMTP und Redirect-URLs
• Nutzerzahl und aktive Sessions
• Storage-Buckets, Objektzahl, Gesamtvolumen und Policies
• Edge Functions, Secrets, Webhooks und externe APIs
• Realtime-, Broadcast- und Presence-Nutzung
• Pooling, direkte Datenbankverbindungen und Domains
• Frontends, Mobile Apps, Server und Automationen
• gewünschtes RPO, RTO und Wartungsfenster

Zusätzlich gehört eine Feature-Matrix Cloud gegen Self-Hosted in das Assessment. Branching, Managed Backups/PITR und bestimmte Plattformfunktionen sind auf dem Ziel nicht automatisch verfügbar.

2. Zielumgebung kompatibel vorbereiten

Der Ziel-Stack sollte vor dem Import vollständig laufen. Dazu gehören:

• versionierter Supabase-Self-Hosted-Stack
• kompatible PostgreSQL-Version und Extensions
• TLS, Firewall und geschützter Studio-Zugriff
• SMTP und Auth-Provider
• Storage-Backend und ausreichende Kapazität
• Backup für PostgreSQL, Storage, Konfiguration und Functions
• Monitoring, Logs und Alarmierung
• Domains, Pooling und Netzwerkzugänge

Supabase weist darauf hin, dass Cloud und Self-Hosted unterschiedliche PostgreSQL- oder Dienstversionen verwenden können. Eine Testwiederherstellung deckt inkompatible Settings, Tabellen oder Extensions auf, bevor das Produktionsfenster beginnt.

3. Rollen, Schema und Daten exportieren

Die offizielle Restore-Anleitung verwendet drei getrennte Exporte:

supabase db dump --db-url "$DATABASE_URL" -f roles.sql --role-only
supabase db dump --db-url "$DATABASE_URL" -f schema.sql
supabase db dump --db-url "$DATABASE_URL" -f data.sql --use-copy --data-only

Die Supabase CLI nutzt intern pg_dump, filtert aber reservierte Rollen und interne Schemas passend zur Plattform. Ein ungefilterter direkter pg_dump kann beim Restore an Eigentümern oder Plattformrollen scheitern.

Eigene Login-Rollen benötigen nach dem Restore neue Passwörter, weil die Dumps diese nicht enthalten.

4. Testrestore durchführen

Rollen, Schema und Daten werden in der vorgesehenen Reihenfolge wiederhergestellt. Der Testlauf sollte nicht nur mit „psql ohne Fehler“ enden. Zu prüfen sind:

• Tabellen- und Zeilenzahlen
• Constraints, Indizes und Sequenzen
• Views, Trigger und Datenbankfunktionen
• Extensions und Versionen
• Eigentümer und Grants
• RLS-Policies
• zentrale Abfragen und Performance
• Migrationshistorie der Anwendung

Abweichungen gehören in ein Protokoll. Der Testlauf liefert außerdem eine realistische Transferdauer für das Wartungsfenster.

5. Auth separat behandeln

Auth-Daten liegen teilweise in PostgreSQL und können mit dem Datenbestand übernommen werden. Die Umgebung benötigt trotzdem neue oder bestätigte Konfiguration:

• Site URL und erlaubte Redirects
• OAuth-Provider und deren Callback-URLs
• SMTP, Absender und Templates
• JWT-Schlüssel und Token-Gültigkeit
• anonyme und öffentliche Anmeldung
• MFA und Captcha

Die offizielle Dokumentation weist darauf hin, dass andere JWT-Secrets bestehende Tokens ungültig machen. In diesem Fall müssen Nutzer sich neu anmelden. OAuth-Konfigurationen in Google, Apple, GitHub oder anderen Providern müssen auf den neuen Hostnamen zeigen.

6. Storage-Objekte migrieren

Ein Datenbankdump überträgt Tabellen und Storage-Metadaten, nicht die Dateiinhalte. Der Storage-Umzug benötigt einen eigenen Prozess:

1. Buckets, Policies und Metadaten erfassen.
2. Objekte vollständig aus der Quelle lesen.
3. Dateien in das Ziel-Backend übertragen.
4. Pfade, Größe, Prüfsummen und Objektzahl vergleichen.
5. öffentliche und signierte Zugriffswege testen.

Bei großen Buckets kann der Storage-Transfer länger dauern als der Datenbankumzug. Eine inkrementelle Strategie muss dann gesondert geplant werden.

7. Functions, Secrets und Integrationen neu bereitstellen

Edge Functions werden als Quellcode und Deploymentartefakte behandelt. Zu migrieren sind:

• Function-Code und Imports
• Umgebungsvariablen und Secrets
• Webhook-Endpunkte
• Cron- oder Queue-Auslöser
• JWT-Prüfung und Service-Role-Nutzung
• externe API-Zugänge

Self-hosted Functions laufen auf der eigenen Deno-Runtime und nicht automatisch über das globale Edge-Netz der Cloud. Latenz, Skalierung und Timeouts müssen passend zum Ziel getestet werden.

8. Anwendung gegen das Ziel testen

Vor dem Cutover wird eine Staging-Version der Anwendung mit dem Ziel verbunden. Die Abnahme umfasst mindestens:

• Registrierung, Login, Logout und Passwort-Reset
• OAuth und E-Mail-Flows
• Lesen, Schreiben, Ändern und Löschen je Rolle
• RLS-Negativtests zwischen Nutzern und Mandanten
• Upload, Download und signierte Storage-URLs
• Realtime-Verbindungen
• Functions und Webhooks
• direkte Server- und Pooling-Verbindungen

Erst diese Tests zeigen, ob das Backend als Gesamtsystem funktioniert.

9. Cutover und Rückfallweg

Der finale Ablauf wird aus dem Testlauf abgeleitet:

1. Änderungssperre oder kontrollierte Schreibpause aktivieren.
2. finalen Daten- und Storage-Transfer durchführen.
3. Mengen und kritische Daten prüfen.
4. Secrets, URLs und Anwendung auf das Ziel umstellen.
5. Smoke Tests und fachliche Abnahme durchführen.
6. Quelle für das vereinbarte Rückfallfenster unverändert halten.

Ein Rückfall ist nur möglich, wenn geklärt ist, wie neue Schreibvorgänge nach der Umschaltung behandelt werden. Bei komplexen Anwendungen kann dafür eine inkrementelle Synchronisation nötig sein, die nicht zum Standardumfang gehört.

Nach der Migration beginnt der Betrieb

Self-Hosting verlagert die Verantwortung. Direkt nach dem Cutover sollten folgende Punkte aktiv sein:

• Monitoring und Alarmierung
• Datenbank- und Storage-Backups
• dokumentierter Restore
• Update- und Patchprozess
• Kapazitätskontrolle
• Incident-Zuständigkeit
• regelmäßige RLS- und Konfigurationsprüfung

WZ-IT kann diese Aufgaben nach der Migration als Managed Supabase Service übernehmen.

Quellen

• Supabase: Restore a Platform Project to Self-Hosted
• Supabase: Transfer from Cloud to Self-Hosted
• Supabase: Self-Hosted Functions
• Supabase: Database Backups