Zum Inhalt springen

Deployment

Backups und Wiederherstellung

Rebase sichert eine Postgres-Datenbank mit pg_dump und stellt sie mit pg_restore wieder her. Sie können ein Backup manuell erstellen, eines mit einem Cron-Job planen, Ihre vorhandenen Backups über die CLI oder das Studio-Backups-Werkzeug auflisten und in eine frische Datenbank wiederherstellen, ohne die laufende zu berühren.

# Back up to a local directory (custom format, compressed)
rebase db backup --out ./backups
# Back up straight to private object storage
rebase db backup --out s3://my-private-bucket/backups
# List what you have
rebase db backups list
# Restore into a FRESH database (does not touch the live one)
rebase db restore ./backups/rebase-app-20260714T030000Z.dump \
--create-db --target-db app_restored

Die Datenbank ist diejenige, die jeder andere rebase db-Befehl auflöst, in derselben Reihenfolge: --database-url, DATABASE_URL in der Shell, der Branch, zu dem der Checkout gewechselt hat, DATABASE_URL in .env, Postgres in Docker (--docker oder das letzte rebase dev --docker), dann die verwaltete Entwicklungsdatenbank, die restore verweigert.

Ein relatives --out, der Standard ./backups und ein Dump-Pfad, den Sie rebase db restore übergeben, werden alle gegen das Verzeichnis aufgelöst, aus dem Sie rebase ausführen, normalerweise das Projekt-Root, sodass sich rebase db backup und rebase db backups list an einem Ort treffen. Ein relatives BACKUP_DESTINATION wird gegen das Backend-Verzeichnis aufgelöst, wo der Server es ebenfalls liest. Alle drei Befehle verweigern eine Option, die sie nicht kennen, bevor irgendetwas läuft, und nennen die, die Sie vermutlich meinten. Das Passwort geht in PGPASSWORD an pg_dump, pg_dumpall und pg_restore, nie in deren Befehlszeile, sodass keine Fehlermeldung und keine Prozessliste es zeigt.

rebase db backup führt pg_dump im Custom-Format aus (-Fc), das komprimiert ist und selektiv wiederhergestellt werden kann. Dateien werden rebase-<db>-<YYYYMMDD>T<HHMMSS>Z.dump genannt; der UTC-Zeitstempel im Namen ist das, wonach Retention und Auflistung sortieren.

Option Beschreibung
--out, -o Ein lokaler Pfad, oder eine s3://bucket/prefix- / gs://bucket/prefix-URL. Standardmäßig $BACKUP_DESTINATION, dann ./backups in dem Verzeichnis, aus dem Sie rebase ausführen.
--exclude-schema <s> Ein Schema aus dem Dump auslassen (wiederholbar). Ein Muster, das auf rebase passt, wird verweigert — siehe unten.
--no-owner Eigentumsbefehle auslassen, zum Wiederherstellen als andere Rolle.
--enable-row-security Als Admin-Subjekt dumpen, statt an Row-Level Security zu scheitern. Kann einen unvollständigen Dump erzeugen — siehe Row-Level Security.
--row-security-role <r> Die Rolle, als die mit dem obigen Flag gelesen wird. Standardmäßig admin.

Ein Dump wird validiert, bevor der Befehl Erfolg meldet: pg_restore --list muss das gesamte Archiv lesen können.

Für s3://-Ziele baut die CLI ihren Storage-Client aus denselben S3_*-Variablen, die Ihr Backend verwendet (S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_REGION, S3_ENDPOINT, S3_FORCE_PATH_STYLE).

Jedes Backup schreibt eine zweite Datei neben dem Dump: rebase-<db>-<…>Z.globals.sql, erzeugt von pg_dumpall --globals-only --no-role-passwords. Ein pg_dump pro Datenbank kann cluster-weite Rollen nicht einschließen, und die Grants und Row-Level-Security-Policies des Dumps benennen eine — rebase_user. In ein neues Postgres ohne sie wiederhergestellt, scheitert das erste GRANT an diese Rolle, und die Wiederherstellung stoppt.

Halten Sie die beiden Dateien zusammen. Die CLI lädt sie hoch und stellt sie als Paar wieder her, ein geplantes Backup bereinigt sie als Einheit, und rebase db restore sucht die .globals.sql im selben Verzeichnis oder Präfix wie die .dump. Rollen werden ohne Passwörter neu angelegt; setzen Sie diese nach einer Wiederherstellung in einen neuen Cluster erneut. PG_DUMPALL_PATH verweist auf ein bestimmtes pg_dumpall-Binary.

Die gesamte Datenbank, einschließlich des rebase-Schemas. Dieses Schema enthält jedes Benutzerkonto und den Rest der Authentifizierung, API-Schlüssel, Entitätshistorie, die Job-Warteschlange, Cron-Logs sowie die Funktionen, die Ihre RLS-Policies und Change-Capture-Trigger aufrufen. Ein Dump ohne dieses Schema hat keine Benutzer und kann überhaupt nicht in eine leere Datenbank wiederhergestellt werden: Die Tabellen, die er enthält, besitzen Policies, die Funktionen aufrufen, die er nicht enthält.

Deshalb verweigert rebase db backup ein --exclude-schema, das nach den eigenen Musterregeln von pg_dump (reb* und * eingeschlossen) auf rebase passt, bevor es irgendetwas ausführt. Diese Regeln reichen Syntax regulärer Ausdrücke außerhalb doppelter Anführungszeichen durch, daher werden auch [r]ebase und audit|rebase verweigert, und der Server wird zu jedem Muster befragt, bevor pg_dump läuft, mit derselben Engine für reguläre Ausdrücke, die die eigene Abfrage von pg_dump verwendet.

Weil er jedes Passwort und jeden Schlüssel-Hash enthält, werden ein lokaler Dump und seine .globals.sql nur für ihren Eigentümer lesbar (0600) angelegt, bevor pg_dump in sie schreibt; die lokalen Dateien eines geplanten Backups ebenfalls.

Ein geplantes Backup ist ein Cron-Job, der die Datenbank dumpt, das Ergebnis nach BACKUP_DESTINATION hochlädt und alte Backups bereinigt. Legen Sie eine Datei in backend/crons/ ab, die einen Standardexport bereitstellt:

// backend/crons/backup.ts
import { backupStorageFromEnv, type StorageController } from "@rebasepro/server";
import { createBackupCron, backupCronConfigFromEnv } from "@rebasepro/server-postgres";
const resolved = backupCronConfigFromEnv(process.env);
if (resolved.error) throw new Error(resolved.error);
function backupStorage(): StorageController | undefined {
const destination = resolved.config?.destination;
if (!destination || destination.kind === "local") return undefined; // local: written to disk directly
// The same S3_* (or application-default GCS) client the CLI and the Backups panel build.
return backupStorageFromEnv(destination, process.env);
}
// With BACKUP_SCHEDULE unset, export a disabled job so discovery still works.
export default resolved.config
? createBackupCron({ ...resolved.config, storage: backupStorage() })
: createBackupCron({
schedule: "0 3 * * *",
connectionString: process.env.DATABASE_URL ?? "",
destination: { kind: "local", path: "./backups" },
enabled: false
});

Der Storage-Controller wird übergeben, statt aus dem Kontext des Jobs übernommen zu werden, weil rebase.storage im Kontext die clientseitige Storage-API ist, kein Controller für den Backup-Bucket.

Ein Backup unterliegt nicht den Upload-Limits des Controllers. maxFileSize (50 MB, sofern nicht gesetzt) und allowedMimeTypes gelten für das, was Benutzer hochladen; ein Dump beliebiger Größe wird also hochgeladen, ebenso einer, der über den Controller geschrieben wird, der die Dateien Ihrer App ausliefert.

Variable Bedeutung
BACKUP_SCHEDULE Cron-Ausdruck, z. B. 0 3 * * * für täglich 03:00 Uhr. Nicht gesetzt schaltet geplante Backups aus.
BACKUP_DESTINATION Ein lokaler Pfad, oder s3://bucket/prefix / gs://bucket/prefix.
BACKUP_RETENTION_DAYS Backups löschen, die älter als so viele Tage sind. Nicht gesetzt oder 0 behält alles.
BACKUP_KEEP_MINIMUM Immer mindestens so viele aktuelle Backups behalten, egal wie alt — damit ein langer Ausfall nicht alles bereinigt.

Jeder neue Dump wird validiert, bevor irgendetwas bereinigt wird, sodass ein beschädigter Dump niemals der Grund sein kann, warum Ihr letztes gutes Backup gelöscht wurde. Die Bereinigung betrifft nur Dateien, deren Namen dem Backup-Muster entsprechen; alles andere, das sich den Bucket oder das Präfix teilt, bleibt unberührt.

Der Cron-Job führt pg_dump innerhalb des Serverprozesses aus. Das offizielle Runtime-Image (rebasepro/server, siehe Self-Hosting) liefert die PostgreSQL-18-Client-Tools dafür mit. Überall sonst — ein VPS, Ihr eigenes Image — installieren Sie die Client-Tools selbst (siehe nächster Abschnitt).

pg_dump und pg_restore müssen dieselbe Hauptversion wie der Server haben, oder neuer sein. rebase db backup und rebase db restore prüfen die Hauptversion des Clients gegen die server_version_num des laufenden Servers, bevor sie dumpen oder wiederherstellen, und stoppen mit der Abhilfe, wenn sie nicht zusammenpassen oder das Binary fehlt:

✗ Client tool is Postgres 15 but the server is Postgres 16. pg_dump/pg_restore
must be the same major version as the server or newer. Install Postgres 16
client tools.

Installieren Sie sie mit brew install libpq oder apt-get install postgresql-client-18 (aus dem PostgreSQL-apt-Repository, in dem Debians eigenes älter ist), oder verweisen Sie mit PG_DUMP_PATH, PG_RESTORE_PATH und PG_DUMPALL_PATH auf ein bestimmtes Binary. restore --clean führt außerdem psql aus, das mit ihnen ausgeliefert wird; PSQL_PATH nennt ein anderes.

Row-Level Security, und der Dump, der still und leise unvollständig ist

Abschnitt betitelt „Row-Level Security, und der Dump, der still und leise unvollständig ist“

Bei einem verwalteten Postgres — Cloud SQL, RDS und die übrigen — gibt es keinen Superuser, den man vergeben könnte, daher besitzt die Rolle, mit der Sie sich verbinden, meist keine Ihrer Tabellen und hat kein BYPASSRLS. Row-Level Security gilt für sie, und pg_dump verweigert:

pg_dump: error: query failed: ERROR: query would be affected by row-level
security policy for table "company_leads"

Diese Verweigerung ist das sichere Ergebnis. --enable-row-security von Hand zu pg_dump hinzuzufügen ist das gefährliche: Es gelingt, es endet mit Exit-Code 0, und der Dump enthält still und leise nur die Zeilen, die die Policies der dumpenden Rolle zulassen. Zwei echte Auswege:

  1. Gewähren Sie der dumpenden Rolle BYPASSRLS, oder machen Sie sie zum Eigentümer der Tabellen. Der Dump enthält dann jede Zeile.

    ALTER ROLE my_backup_role BYPASSRLS;
  2. rebase db backup --enable-row-security. Rebase setzt app.uid und app.user_roles, sodass die generierte admin_full_access-Policy den Dump zulässt, und gibt eine Warnung aus, die sagt, was Sie dafür eingetauscht haben: Eine Tabelle, deren Policies keine Admin-Regel enthalten, kommt unvollständig heraus, und nichts weist darauf hin.

rebase db restore <backup> [--target-db <name>] [--create-db] [--clean] [--yes]

restore führt pg_restore aus, und das ist destruktiv, daher läuft es nie automatisch: Ohne --yes fragt es interaktiv nach einem yes, und in einer nicht interaktiven Shell stoppt es und sagt, dass --yes zu übergeben ist. <backup> ist ein lokales .dump oder ein s3://…- / gs://…-Key, der zuerst herunterladen wird.

In eine Datenbank, die bereits enthält, was das Backup anlegt, braucht es --clean: Ohne das Flag verweigert es, bevor irgendetwas läuft, nennt die Schemas und Tabellen, die im Weg sind, und sagt, dass --clean zu übergeben oder mit --create-db --target-db <name> in eine neue Datenbank wiederherzustellen ist. Es verweigert die verwaltete Entwicklungsdatenbank, die die COPY-Daten eines Dumps nicht annehmen kann; stellen Sie stattdessen mit --docker in Postgres in Docker wieder her.

Mit --clean ersetzt die Wiederherstellung, was das Backup enthält, als eine einzige Transaktion. Sie löscht jedes Schema, das das Backup anlegt, vollständig (rebase etwa), und jede Tabelle, die das Backup in einem Schema anlegt, das es nicht anlegt (public), mit CASCADE, und stellt dann den Dump in derselben Transaktion wieder her. Bevor sie nachfragt, nennt sie, was dabei gelöscht wird, das das Backup nicht enthält, etwa rebase.atlas_schema_revisions aus rebase db migrate, eine Funktion, einen Typ oder eine Sequenz in einem ersetzten Schema oder eine View oder einen Fremdschlüssel an anderer Stelle, die auf eine der Tabellen des Backups verweisen. Eine Wiederherstellung, die irgendwo anhält, wird zurückgerollt, und sie sagt, dass die Datenbank enthält, was sie vorher enthielt. Sie spielt den Dump über psql ein, das mit pg_restore ausgeliefert wird (PSQL_PATH nennt ein anderes), und wartet höchstens 15 Sekunden auf eine Sperre, die ein laufendes rebase dev halten kann. --continue-on-error führt weiterhin das eigene --clean von pg_restore aus.

Vor der Wiederherstellung legt es die Cluster-Rollen aus der .globals.sql des Backups neu an — eine bereits vorhandene Rolle wird übersprungen, nicht als Fehler gewertet —, damit die Grants und Policies des Dumps greifen. Danach hält es beim ersten Fehler an (--exit-on-error, oder ON_ERROR_STOP unter --clean): Eine Wiederherstellung, die ein gescheitertes GRANT protokolliert hätte und fortgefahren wäre, würde Erfolg melden, während Row-Level Security nicht durchgesetzt ist. Ohne eine .globals.sql neben dem Backup warnt es, dass Rollen fehlen könnten.

Option Beschreibung
--target-db <name> In diese Datenbank wiederherstellen statt in die aus DATABASE_URL.
--create-db Die Zieldatenbank zuerst anlegen, falls sie nicht existiert.
--clean Ersetzt, was das Backup enthält, in einer Transaktion mit der Wiederherstellung: seine Schemas vollständig und seine Tabellen an anderer Stelle. Sagt zuerst, was dabei über das Backup hinaus gelöscht wird.
--no-owner Das im Dump festgehaltene Eigentum ignorieren.
--continue-on-error Fehler protokollieren und fortfahren. Kann RLS unerzwungen zurücklassen; verwenden Sie dies nur, wenn Sie wissen, warum.
--yes, -y Die Bestätigung überspringen.

Das sichere Verfahren ist, neben der laufenden Datenbank wiederherzustellen, sie zu prüfen und die App erst danach umzustellen:

  1. rebase db restore <backup> --create-db --target-db app_restored
  2. Richten Sie einen Wegwerf-Prozess (oder psql) auf app_restored und prüfen Sie Zeilenzahlen, eine Anmeldung und die Tabellen, die Ihnen am wichtigsten sind.
  3. Richten Sie DATABASE_URL darauf um, oder benennen Sie die Datenbanken um, während eines kurzen Wartungsfensters.
  4. Stellen Sie Ihre hochgeladenen Dateien aus deren eigenem Backup wieder her, so nah wie möglich am selben Zeitpunkt.

Studios Backups-Werkzeug, in der Gruppe Datenbank, listet die Backups unter BACKUP_DESTINATION, neueste zuerst, mit Zeitpunkt (und, bei einem lokalen Ziel, mit Größe). Download lädt den Dump; Roles file lädt dessen .globals.sql. Laden Sie beide herunter und halten Sie sie in einem Verzeichnis zusammen. Ein Backup, das als No roles file markiert ist, hat kein Sidecar: Legen Sie seine Rollen von Hand neu an, bevor Sie es in ein neues Postgres wiederherstellen.

Über der Liste meldet das Werkzeug den geplanten Backup-Job und seinen letzten Lauf. Ein fehlgeschlagener Lauf wird als Fehler mit seiner Meldung angezeigt, sodass ein nächtliches Backup, das nicht laufen kann, dort sichtbar ist, wo die Backups aufgeführt sind, nicht nur im Cron-Jobs-Werkzeug.

Was das Werkzeug über den Job sagt:

  • Last scheduled backup ist der letzte Lauf, den der Zeitplan ausgeführt hat. Ein seitdem von Hand gestarteter Lauf (Run Now im Cron-Jobs-Werkzeug) bekommt eine eigene Zeile, sodass ein erfolgreicher Testlauf kein fehlgeschlagenes nächtliches Backup verdecken kann und ein fehlgeschlagener nicht als das nächtliche gemeldet wird.
  • Bei einem mit enabled: false deklarierten Job zeigt das Werkzeug geplante Backups als aus an. Das exportiert die obige Cron-Datei, solange BACKUP_SCHEDULE nicht gesetzt ist, und das Setzen von BACKUP_SCHEDULE schaltet sie ein. Pausiert bedeutet, dass ein Admin den Job im Cron-Jobs-Werkzeug pausiert hat, und ihn dort fortzusetzen schaltet sie wieder ein.
  • Ein Job, den der Scheduler wegen eines ungültigen Zeitplans, einer ungültigen Zeitzone oder eines ungültigen Timeouts abgelehnt hat, wird mit dem Grund gemeldet. Er läuft nie, bis seine Cron-Datei korrigiert ist.
  • Wenn der Ausführungsverlauf in rebase.cron_logs nicht gelesen werden kann, sagt das Werkzeug genau das, statt zu melden, dass das Backup noch nicht gelaufen ist.

Die Liste wird von dem Server-Prozess gelesen, der GET /api/admin/backups beantwortet, und das ist nicht immer der Prozess, der den Zeitplan ausführt:

  • Ein s3://-Ziel wird über einen Client für diesen Bucket aufgelistet und heruntergeladen, gebaut aus denselben S3_*-Variablen, die der Backup-Cron verwendet. Ein gs://-Ziel verwendet Application Default Credentials. Geben Sie sie jedem Prozess, der /api/admin bedient, einschließlich der api-Rolle eines aufgeteilten Deployments, nicht nur dem, der den Cron ausführt. Ein Ziel, das der Prozess nicht lesen kann, antwortet mit 503 samt Ziel und Grund, und das Werkzeug zeigt dies statt einer leeren Liste an.
  • Ein lokaler Pfad ist die eigene Festplatte dieses Prozesses. Wenn der Zeitplan in einem anderen Prozess läuft (ein api mit REBASE_CRON_SCHEDULER=false neben einem worker), meldet das Werkzeug, dass es die Festplatte dieses Prozesses auflistet: Die geplanten Backups erscheinen dort nur, wenn beide Prozesse dasselbe Verzeichnis einbinden. Ein aufgeteiltes Deployment sollte in Object Storage sichern.

Downloads streamen über GET /api/admin/backups/download?key=…, nur für Admins, sodass der Bucket niemals öffentlich sein muss; ein Key außerhalb des Präfixes des Ziels wird abgelehnt. Mit nicht gesetztem BACKUP_DESTINATION meldet das Werkzeug, dass keine Backups konfiguriert sind.

Ein Browser kann bei einem Download keinen Authorization-Header setzen, daher fragen Studio und das SDK zuerst nach einem Link. POST /api/admin/backups/download-url mit { "key": "…" } (derselbe Admin-Scope und dieselben Key-Prüfungen wie beim Download) antwortet mit { url, token, expiresIn }: eine URL, deren Token den Header ersetzt, für genau dieses eine Backup am aktuellen Ziel, 60 Sekunden lang. Das Token wird überall sonst abgelehnt — als Sitzung, als Storage-Download-Token, für ein anderes Backup — und sobald es abläuft. Der Browser streamt den Dump dann direkt auf die Festplatte, sodass ein Backup von der Größe Ihrer Datenbank nie in einen Tab passen muss.

// In a browser: the browser saves the file.
await client.backups.download(key);
// Anywhere: a link that needs no header, for 60 seconds.
const { url } = await client.backups.downloadUrl(key);
// In Node: stream the bytes to a file.
import { createWriteStream } from "node:fs";
import { Readable } from "node:stream";
import { pipeline } from "node:stream/promises";
const { stream, name } = await client.backups.stream(key);
await pipeline(Readable.fromWeb(stream), createWriteStream(name));

backups.download(key) speichert die Datei in einem Browser und wirft anderswo einen Fehler; verwenden Sie stream(key) in Node. Gegen einen Server ohne Download-Links (einen älter als 0.25 oder einen ohne JWT-Secret zum Signieren) fällt download() darauf zurück, die Bytes selbst zu lesen.

Ein Backup enthält alle Ihre Daten, einschließlich Zugangsdaten und personenbezogener Daten.

  • Verwenden Sie niemals einen öffentlichen Bucket. Halten Sie den Zugriff privat und protokollieren Sie ihn.
  • Schalten Sie Verschlüsselung im Ruhezustand ein: S3-Server-Side-Encryption, GCS-Standardverschlüsselung, oder Festplattenverschlüsselung für ein lokales Verzeichnis.
  • Beschränken Sie, wer den Backup-Speicherort lesen kann, und rotieren Sie dessen Zugangsdaten.
  • Bevorzugen Sie einen eigenen Bucket, getrennt von Benutzer-Uploads.

Ein pg_dump-Backup stellt den Zeitpunkt wieder her, zu dem der Dump lief. Um auf eine beliebige Sekunde dazwischen wiederherzustellen, braucht es WAL-Archivierung und Basis-Backups, die die Open-Source-Distribution nicht für Sie ausführt. Wenn Sie dies selbst hosten müssen, führen Sie pgBackRest oder wal-g neben Ihrem Postgres aus und behalten Sie diese Dumps als zweite, portable Kopie.