Kostenloses Supabase-Backup per GitHub Action, mit Haken

Dein Supabase-Projekt ist auf dem Gratis-Tarif, also wird nirgendwohin etwas kopiert, oder es ist auf Pro, und jede Kopie liegt in dem Konto, um dessen Verlust du dir Sorgen machst. In einem Thread genau darüber hat jemand gesagt, die Antwort sei eine Supabase-Backup-GitHub-Action: eine kleine Datei in einem Repository, die jede Nacht deine Datenbank dumpt und nichts kostet.

Der Rat war richtig. Supabase veröffentlicht den Workflow selbst, und für viele Apps ist er das, was du diese Woche einrichten solltest. Hier ist der Teil, den diese Threads auslassen: Er kostet kein Geld und hat trotzdem einen Preis. Jeder Lauf lädt deine ganze Datenbank herunter, und Supabase misst diesen Download.

Stell es dir wie das Datenvolumen in deinem Handyvertrag vor. Dein Tarif bringt ein monatliches Kontingent mit, alles, was deine App tut, zehrt davon, und ein Backup ist ein großer Download im selben Vertrag. Auf dem Gratis-Tarif braucht eine nächtliche Kopie einer Datenbank nahe an ihrem Größenlimit das ganze Monatskontingent in etwa zehn Tagen auf. Das und ein Connection String, den GitHub nicht erreicht, sind die beiden Dinge zwischen dir und einem funktionierenden Backup, und keines davon steht auf der Seite von Supabase.

Kann ich Supabase kostenlos mit einer GitHub Action sichern?

Ja, und Supabase dokumentiert, wie. Seine Seite zu automatischen Backups mit GitHub Actions zeigt einen Workflow, der die Supabase CLI installiert, deine Rollen, dein Schema und deine Daten in drei Dateien dumpt und sie nach Zeitplan zurück ins Repository committet.

GitHub verlangt dafür ebenfalls nichts, in Grenzen. Ein privates Repository auf GitHub Free bekommt 2.000 Actions-Minuten im Monat, und ein nächtlicher Dump einer kleinen Datenbank verbraucht davon einen kleinen Teil.

Was du bekommst, ist eine Kopie, die Supabase jede Nacht verlässt und auf den Servern einer anderen Firma landet. Genau das können dir die eigenen Backups von Supabase nicht geben, denn die Tageskopien auf einem bezahlten Tarif bleiben in dem Konto, das sie schützen.

Die richtige Antwort ist es, wenn drei Dinge zutreffen. Deine App liegt schon in einem GitHub-Repository, was der Fall ist, wenn du in Lovable oder einem ähnlichen Builder die GitHub-Synchronisierung eingeschaltet hast. Eine YAML-Datei zu bearbeiten macht dir keine Sorgen. Und deine Datenbank ist klein im Verhältnis zum Egress-Kontingent deines Tarifs. Die ersten beiden weißt du schon. Das dritte ist Rechnerei und hat weiter unten einen eigenen Abschnitt.

Der Workflow, mit Zeitplan und Secret

Speichere das als .github/workflows/supabase-backup.yml in einem privaten Repository, in dem sonst nichts liegt:

name: supabase-backup

on:
  schedule:
    - cron: '17 3 * * *' # jeden Tag um 03:17 UTC
  workflow_dispatch:

jobs:
  backup:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    env:
      SUPABASE_DB_URL: ${{ secrets.SUPABASE_DB_URL }}
    steps:
      - uses: actions/checkout@v7
      - uses: supabase/setup-cli@v3
        with:
          version: latest
      - name: Back up roles
        run: supabase db dump --db-url "$SUPABASE_DB_URL" -f roles.sql --role-only
      - name: Back up schema
        run: supabase db dump --db-url "$SUPABASE_DB_URL" -f schema.sql
      - name: Back up data
        run: >
          supabase db dump --db-url "$SUPABASE_DB_URL" -f data.sql --use-copy --data-only
          -x "storage.buckets_vectors" -x "storage.vector_indexes"
      - uses: stefanzweifel/git-auto-commit-action@v7
        with:
          commit_message: Supabase backup

Es ist der Workflow von Supabase mit drei Änderungen.

• Er läuft nach Zeitplan und wenn du den Knopf drückst, sonst nie. Die Version von Supabase läuft außerdem bei jedem Push und jedem Pull Request auf main. Jeder Lauf ist ein vollständiger Download deiner Datenbank, und in einem Repository, das auch deine App enthält, würde jede Änderung, die du auslieferst, ein Backup an Kontingent kosten.
• Er läuft um 03:17, nicht zur vollen Stunde. GitHub schreibt, dass geplante Läufe zu Beginn jeder Stunde verzögert werden können und dass bei genug Last manche Jobs in der Warteschlange verworfen werden. Das Beispiel von Supabase nutzt 0 0 * * *, also die volle Stunde. Die Zeiten sind UTC, solange du keine timezone angibst, und jede Minute außer 0 geht.
• Die Datenzeile entspricht der aktuellen Anleitung zu Backup und Restore von Supabase, die zwei -x-Ausschlüsse enthält, die auf der Workflow-Seite fehlen. Die Dateien, die du aufbewahrst, sind dann die, für die die Restore-Anleitung von Supabase geschrieben ist.

Dann das Secret. Öffne im Repository Settings, dann Secrets and variables, dann Actions, und leg ein Repository-Secret namens SUPABASE_DB_URL an. Was hineingehört, entscheidet darüber, ob das alles funktioniert, deshalb bekommt es den nächsten Abschnitt für sich.

Sobald es gespeichert ist, starte den Workflow einmal von Hand im Actions-Tab, damit der erste Lauf passiert, während du zusiehst. workflow_dispatch ist die Zeile, die dir den Button Run workflow gibt.

Welcher Connection String gehört ins Secret?

Der Session-Pooler-String, über den Connect-Button oben in deinem Supabase-Projekt. Nimm ihn, auch wenn die Workflow-Seite von Supabase in ihrem Beispiel die direkte Verbindung zeigt.

Der Grund ist IPv6, die neuere Art von Internetadresse. Die direkte Verbindung von Supabase, der Host, der mit db. beginnt und auf supabase.co endet, nutzt standardmäßig IPv6, und dieselbe Seite führt GitHub Actions unter den Diensten, die nur IPv4 annehmen. Der Runner bekommt eine Adresse, zu der er keinen Weg hat, und der erste Dump scheitert, bevor ein Byte geschrieben ist. Der Fehler sagt, der Hostname ließ sich nicht auflösen oder das Netzwerk sei nicht erreichbar, oft mit einer langen Adresse voller Doppelpunkte daneben. Diese Adresse ist die IPv6-Adresse. Es liest sich wie ein falsches Passwort oder eine Datenbank, die ausgefallen ist, und die eigentliche Ursache ist ein Netz, in dem der Runner nicht ist.

Die Anleitung zu Backup und Restore von Supabase sagt, standardmäßig den Session-Pooler-String zu nehmen und den direkten nur, wenn dein Netz IPv6 unterstützt oder du für das IPv4-Add-on bezahlst. Den Pooler-String erkennst du an drei Dingen: Sein Benutzername ist postgres. gefolgt von der Referenz deines Projekts, sein Host endet auf pooler.supabase.com, und sein Port ist 5432.

Das Passwort darin ist dein Datenbankpasswort, das beim Anlegen des Projekts festgelegt wurde, kein API-Schlüssel. Wenn es niemand aufgeschrieben hat, kannst du es bei Supabase unter Database Settings zurücksetzen; alles andere, was sich mit dem alten verbindet, funktioniert dann nicht mehr, bis es das neue bekommt.

Dieser String kann jede Zeile deiner Datenbank lesen und ändern. Er lebt im Secret und nirgends sonst: nie in der Workflow-Datei, nie in einer Commit-Nachricht und nie in einem KI-Assistenten, dem du ihn zusammen mit der Fehlermeldung eingefügt hast, nach der du fragen wolltest.

Zählt ein Supabase-Backup gegen mein Egress?

Ja, vollständig. Supabase rechnet als Egress ab, also als ausgehenden Datenverkehr, was irgendeiner seiner Dienste nach außen schickt, und ein Dump über den Pooler läuft als Shared Pooler Egress im selben Kontingent wie dein API-Verkehr, deine Datei-Downloads und alles andere, was deine App ausliefert.

Zurück zum Handyvertrag. Das Kontingent setzt sich jeden Abrechnungsmonat zurück, jeder Dienst, den deine App nutzt, zehrt davon, und ein Backup ist ein weiterer großer Download. Es ist außerdem ein Familientarif: Supabase wendet das Kontingent auf deine ganze Organisation an, also teilen sich alle Projekte darin das eine Kontingent.

Am 26. September 2026 nannte die Preisseite von Supabase für den Gratis-Tarif 5 GB Egress im Monat und ein Limit von 500 MB für die Datenbank jedes Projekts, für den Pro-Tarif 250 GB Egress. Auf dem Gratis-Tarif gibt es noch einmal 5 GB für Cached Egress, das Dateien aus dem CDN von Supabase abdeckt, und ein Backup berührt es nie. Die übrigen Limits des Gratis-Tarifs und was jedes davon tut, wenn du es überschreitest, haben einen eigenen Artikel.

Überschreitest du das Kontingent auf dem Gratis-Tarif, kommt keine Rechnung. Supabase benachrichtigt dich und gibt dir eine Schonfrist, und wenn du weiter darüber liegst, schränkt es jedes Projekt der Organisation ein. Laut Supabase kann das heißen: API-Anfragen, die mit einem 402-Fehler beantwortet werden, eine Datenbank im Nur-Lese-Modus oder pausierte Projekte. Für eine App mit Kunden ist das ein Ausfall, den dein Backup ausgelöst hat.

Das gilt für jedes Backup, das Supabase verlässt, auch für das, das wir verkaufen. Eine Kopie außerhalb des Kontos muss heruntergeladen werden, um dorthin zu kommen.

Wie oft sollte das Backup laufen?

So oft, wie dein Kontingent es bezahlt, und das läuft auf eine einzige Multiplikation hinaus: die Größe deiner Datenbank mal die Läufe im Monat.

Supabase zeigt die Größe deiner Datenbank im Database-Report unter Observability in deinem Projekt. Ein Dump ist nicht genau so groß. Er lässt Indizes weg, die aus ihren Definitionen neu aufgebaut werden, und er schreibt jeden Wert als Text. Zum Planen ist er nah genug dran, und es ist die Zahl, die du nachschlagen kannst.

Ein Monat hat etwa 4,3 Wochen, daher kommen die letzten beiden Spalten.

Auf dem Gratis-Tarif verbrauchen die unteren beiden Tageswerte mehr als das ganze Monatskontingent, bevor deine App eine einzige Anfrage beantwortet hat. Ein täglicher Zeitplan braucht die vollen 5 GB bei etwa 160 MB auf, und der Verkehr deiner App kommt aus demselben Kontingent, also lies auf der Usage-Seite deiner Organisation das Egress des letzten Monats nach, bevor du wählst. Wöchentlich passt bei jeder Größe, die der Gratis-Tarif erlaubt.

Die Cron-Zeile ist das Einzige, was du änderst:

17 3 * * *      jeden Tag um 03:17 UTC
17 3 * * 1,4    montags und donnerstags
17 3 * * 0      sonntags

Auf Pro spielt die Rechnung kaum noch eine Rolle. 250 GB im Monat bezahlen einen täglichen Dump eines Projekts bis etwa 8 GB, und das ist der Speicherplatz, den der Pro-Tarif pro Projekt enthält.

Warum scheitert mein Workflow mit einem pg_dump-Versionsfehler?

Weil das pg_dump, das er ausgeführt hat, älter ist als deine Datenbank. Das passiert nur einem Workflow, der pg_dump direkt aufruft statt über die Supabase CLI. Die CLI bringt ihr eigenes pg_dump mit, und das ist ein Grund, warum der Workflow oben sie nutzt.

Der ubuntu-latest-Runner von GitHub kommt mit installiertem PostgreSQL 16. Supabase-Projekte können auf Postgres 17 laufen, und Postgres dokumentiert, dass pg_dumpnicht von einem Server dumpt, der eine neuere Hauptversion hat als es selbst, und sich lieber weigert, als eine fehlerhafte Datei zu riskieren. Der Lauf bricht ab mit:

pg_dump: error: aborting because of server version mismatch
pg_dump: detail: server version: 17.…; pg_dump version: 16.…

Die Version deines Projekts steht unter Project Settings, dann General, falls du sie prüfen willst. An deinen Zugangsdaten ist nichts falsch.

Die Lösung hat zwei Schritte. Füge das eigene Paket-Repository von PostgreSQL hinzu, damit der Runner den Client in Version 17 installieren kann, und ruf diesen Client dann über seinen vollen Pfad auf:

- name: Install the Postgres 17 client
  run: |
    sudo apt-get install -y postgresql-common
    sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh -y
    sudo apt-get install -y postgresql-client-17
- name: Back up
  run: /usr/lib/postgresql/17/bin/pg_dump "$SUPABASE_DB_URL" …

Behalte die Argumente, die du schon hattest, hinter dem Connection String. Der volle Pfad ist wichtig: Auf Ubuntu ist das einfache pg_dump ein Wrapper, der eine Version für dich auswählt, und auf dem Runner liegt schon eine PostgreSQL-16-Installation, die er auswählen kann.

Auch das pg_dump der CLI hat eine Version, und die kommt nicht aus deinem Projekt. Liegt keine supabase/config.toml neben dem Workflow, wie in einem Repository, das sonst nichts enthält, nimmt die CLI pg_dump 17. Bei einem Projekt, das noch auf Postgres 15 läuft, enthält die data.sql dann SET transaction_timeout = 0, eine Einstellung, die Postgres 15 nicht kennt, und das Einspielen bricht in jeder Postgres-15-Datenbank an dieser Zeile ab, auch im Projekt, aus dem die Datei stammt. Wir haben das am 4. Oktober 2026 mit pg_dump 17.11 und Postgres 15.19 nachgestellt. Läuft dein Projekt auf 15, ergänze im env-Block des Jobs eine Zeile, damit die CLI das passende pg_dump nimmt:

env:
  SUPABASE_DB_URL: ${{ secrets.SUPABASE_DB_URL }}
  SUPABASE_DB_MAJOR_VERSION: '15'

Das Backup selbst läuft so oder so ohne Fehler durch, ohne diese Zeile zeigt sich der Unterschied also erst an dem Tag, an dem du die Datei einspielst.

Kann ich das Backup in mein Repository committen?

In ein privates, ja. Genau das macht der Workflow von Supabase, und seine Seite sagt zweimal, dass du deine Daten nie in ein öffentliches Repository sichern sollst.

Drei Dinge über ein Repository als Zuhause für eine Datenbank, keines davon steht auf dieser Seite:

• Wer das Repository lesen kann, kann deine Nutzer lesen. data.sql enthält jede Zeile: E-Mail-Adressen, Namen, was auch immer deine Tabellen speichern, und auch deine Konten. Deshalb bekommt der Workflow ein eigenes Repository, in dem sonst niemand ist, und nicht das, in dem der Code deiner App liegt, das dein Builder vielleicht synchronisiert und in das eines Tages ein Freelancer eingeladen wird.
• Die Kopie jeder Nacht bleibt in der Historie. Git behält jede Version jeder Datei. Bittet jemand aus deiner Kundschaft darum, das eigene Konto zu löschen, steht die Zeile weiterhin in jedem früheren Commit dieses Repositorys, bis du dessen Historie umschreibst.
• Bei 100 MiB ist Schluss. GitHub warnt bei Dateien über 50 MiB und blockiert Dateien über 100 MiB, und dieselbe Seite sagt, dass Git nicht für große SQL-Dateien gemacht ist. In der Nacht, in der data.sql diese Grenze überschreitet, scheitert der Commit-Schritt, und jeder Lauf danach scheitert genauso.

Wenn du in die Nähe kommst, kann derselbe Workflow die drei Dateien in einen Storage-Bucket hochladen, der dir gehört, statt sie zu committen. Oder es ist der Punkt, an dem es nicht mehr billig ist, das selbst zu machen, und dort beginnt der letzte Abschnitt.

Was kopiert der Workflow nicht?

Deine hochgeladenen Dateien. Supabase Storage bewahrt jede Datei außerhalb der Datenbank auf und eine Zeile, die sie beschreibt, darin, also enthält der Dump die Zeile und nicht das Bild. Storage sichern ist eine eigene Aufgabe, auf jedem Weg, den es gibt.

Deine Nutzer sind drin. Der Daten-Dump geht durch das auth-Schema, in dem deine Konten liegen, und eine Suche in data.sql nach auth.users zeigt sie. Das Projekt rund um die Datenbank ist es nicht: Edge Functions, Auth-Provider-Einstellungen, API-Schlüssel und Secrets sind Konfiguration, keine Daten, und die Liste dessen, was in keiner der beiden Kopien ist, liest du am besten, bevor du sie brauchst.

Heißt ein grüner Lauf, dass das Backup funktioniert hat?

Er heißt, dass der Job ohne Fehler zu Ende lief, und das ist eine kleinere Aussage. Drei ganz verschiedene Ergebnisse enden mit demselben grünen Haken:

1. Ein guter Dump des richtigen Projekts.
2. Ein Dump des falschen Projekts, weil im Secret der String einer Staging-Kopie steht.
3. Ein Dump ohne eine einzige Zeile, weil jemand die Datenzeile bearbeitet hat und --data-only verloren ging, womit sie wieder zum Schema-Dump wird.

Ein Ergebnis hinterlässt gar keine Spur. Ein geplanter Lauf, den GitHub unter Last verwirft, taucht nicht als Fehler auf, weil es keinen Lauf gibt, der scheitern könnte. Und wenn ein Lauf scheitert, schickt GitHub die Nachricht an die Person, die die Cron-Zeile zuletzt bearbeitet hat. Hat ein Freelancer das für dich eingerichtet, landet die E-Mail über dein Backup dort.

Nur eine Wiederherstellung unterscheidet sie. Spiel die drei Dateien in ein Wegwerf-Projekt bei Supabase oder ein lokales ein, vergleich die Zeilenzahlen der Tabellen, die dir wichtig sind, mit den echten, und melde dich als echter Nutzer an. Wie du ein Supabase-Backup wiederherstellst enthält die Befehle, in der Reihenfolge, die Supabase angibt. Mach es jetzt einmal und dann jedes Mal wieder, wenn du den Workflow änderst.

Du kannst die Wiederherstellung und das Zählen auch jedem Lauf überlassen. Wir haben eine Version dieses Workflows als quelloffene GitHub Action veröffentlicht, Reeve-page/supabase-backup-action. Sie erstellt dieselben drei Dumps, bewahrt die Kopie als Artefakt des Workflows oder in einem S3- oder R2-Bucket auf, spielt sie danach in eine Wegwerf-Datenbank von Supabase auf dem Runner ein und vergleicht die Zeilenzahl jeder Tabelle mit der Datei. Grün wird der Lauf nur, wenn jede Tabelle mit den Zeilen zurückkam, die die Datei enthält:

- uses: Reeve-page/supabase-backup-action@v1
  with:
    db-url: ${{ secrets.SUPABASE_DB_URL }}

Sie ist kostenlos und steht unter der MIT-Lizenz. Jeder Lauf lädt weiterhin die ganze Datenbank herunter, die Egress-Rechnung oben gilt also unverändert, und die Anmeldung testest du weiterhin selbst.

Wann sollte ich aufhören, das selbst zu machen?

Wenn die Rechnung nicht mehr aufgeht, wenn die Datei dem Repository entwächst oder wenn niemand die Kopien wiederherstellt. Eines davon reicht.

• Deine Datenbank ist dem Gratis-Kontingent entwachsen. Pro hebt das Egress auf 250 GB und bringt die eigenen täglichen Backups von Supabase mit, sieben Tage aufbewahrt, die sich per Klick wiederherstellen lassen. Lass den Workflow daneben weiterlaufen, denn diese Kopien liegen im Konto.
• data.sql steuert auf 100 MiB zu. Sie in einen Bucket umzuziehen heißt mehr YAML und mehr, das jemand am Laufen halten muss.
• Niemand hat je eine Kopie wiederhergestellt. Der Workflow schreibt weiter Dateien, ob sie sich öffnen lassen oder nicht.
• Deine Nutzer laden Dateien hoch. Die erreicht der Workflow nicht, und der Job, der es tut, ist ein zweiter, den jemand am Leben halten muss.

Wo Reeve Care passt

Care zieht die Kopie nach Zeitplan, bewahrt sie außerhalb deines Supabase-Kontos auf und prüft jede Kopie, bevor sie zählt.

• Täglich bei Care und öfter bei den Tarifen darüber, ohne etwas in deinem Repository und ohne Connection String in einer CI.
• Zurückgelesen und gezählt. Jede Kopie wird geöffnet und mit dem verglichen, was hineinging, und das Datum in deinem Dashboard ist die letzte Kopie, die diese Prüfung bestanden hat, nie der letzte Lauf.
• Deine Konten sind drin, und deine hochgeladenen Dateien kommen mit, sobald du einen Storage-Zugang verbindest.
• Wiederherstellen ist ein Klick, und bevor irgendetwas ersetzt wird, wird eine Kopie des aktuellen Zustands gezogen.
• Jede Kopie lässt sich als Zip herunterladen, mit schema.sql, data.sql und roles.sql, denselben drei Dateien, die dieser Workflow macht, dazu die Zeilenzahl jeder Tabelle.

Care bewahrt eine Kopie deiner Supabase-Datenbank auf. Kopie, Prüfung und Wiederherstellung sind Schritt für Schritt auf der Seite zu Supabase-Backups gezeichnet, und was jeder Tarif enthält, steht auf der Preisseite.

Was du diese Woche tun solltest

Bevor du diesen Tab schließt, öffne bei Supabase die Usage-Seite deiner Organisation und lies das Egress des letzten Monats ab. Diese Zahl neben der Größe deiner Datenbank bestimmt deine Cron-Zeile. Und wenn du den kostenlosen Weg noch gegen die bezahlten abwägst, die vier Arten von Supabase-Backup-Tools stehen dort nebeneinander.