Cloud SQL zu PostgreSQL auf Hetzner migrieren

Cloud SQL aus Google Cloud herauslösen? WZ-IT begleitet die Google-Cloud-Migration zu Hetzner mit Zielarchitektur, Datenübernahme und Cutover-Plan. Erstgespräch vereinbaren

Eine Cloud-SQL-Datenbank ist nur ein Teil der Migration. Zusätzlich müssen Anmeldungen, Extensions, Anwendungen und der spätere Betrieb passen. Dieser Leitfaden behandelt Cloud SQL für PostgreSQL zu selbst betriebenem PostgreSQL auf einer Hetzner-VM, mit einem geplanten Schreibstopp. Er ist keine MySQL-Anleitung und enthält keinen auf einer Kundenumgebung durchgeführten Test.

Stand: 19.10.2026. Die Befehle sind Vorlagen für Bash. Hostnamen, Rollen, Datenbanknamen, Zertifikate und Pfade müssen vor der Probe ersetzt werden. Wir empfehlen zuerst eine isolierte Wiederherstellung und erst danach einen produktiven Ablauf mit dokumentierten Freigabekriterien.

Inhaltsverzeichnis

• Welcher Migrationsweg passt?
• Versionen, Rollen und Extensions prüfen
• Quellzugriff und Ziel vorbereiten
• Finalen Dump erstellen und wiederherstellen
• Daten und Anwendungsrechte prüfen
• Cutover und Rückfallweg festlegen
• Unser Vorgehen bei WZ-IT
• Weiterführende Guides

Welcher Migrationsweg passt?

Google dokumentiert den Export aus Cloud SQL mit pg_dump. Ein Dump ist ein Datenbankexport, kein Export des gesamten Google-Projekts. Für die Entscheidung empfehlen wir folgende Abgrenzung:

Logische Replikation ist kein vollständiger Datenbankklon: DDL und Sequenzstände werden nicht automatisch repliziert; Large Objects sind ebenfalls ausgenommen (PostgreSQL: Grenzen logischer Replikation). Die Cloud-SQL-Konfiguration gehört deshalb in einen eigenen Plan. Der vorliegende Ablauf richtet keine Replikation ein.

Für die Zielentscheidung empfehlen wir, Verantwortliche für Updates, Backups, Wiederherstellung, Monitoring und Störungen vor dem Umzug zu benennen. Eine VM-Bestellung ersetzt diese Betriebsplanung nicht. Der Cloud-Exit-Check ordnet diese Abhängigkeiten vor einer Beauftragung der Migration ein.

Versionen, Rollen und Extensions prüfen

Erheben Sie im Quellsystem mindestens:

SHOW server_version;
SELECT current_database(), pg_size_pretty(pg_database_size(current_database()));
SELECT extname, extversion FROM pg_extension ORDER BY extname;
SELECT schemaname, tablename, policyname, roles FROM pg_policies;
SELECT datname, pg_encoding_to_char(encoding), datcollate, datctype
FROM pg_database WHERE datname = current_database();

Die Major-Version von pg_dump darf nicht älter als die des Quellservers sein. Dumps sind für die Übertragung in neuere Versionen vorgesehen; ein Downgrade ist nicht zugesichert (pg_dump-Kompatibilität). Für diesen Ablauf empfehlen wir dieselbe unterstützte Major-Version am Ziel; ein Upgrade kann separat geplant werden. Verwenden Sie dafür pg_dump und pg_restore aus derselben Installation dieser Major-Version. Ein neueres pg_dump erzeugt nicht garantiert SQL für einen älteren Zielserver, auch wenn dessen Major-Version zur Quelle passt.

Cloud SQL unterstützt einen festgelegten Extension-Katalog. Seine Verfügbarkeit belegt nicht, dass dieselbe Erweiterung in identischer Version auf der Hetzner-VM installiert ist. Wir empfehlen, erforderliche Pakete und Preload-Einstellungen vor dem Restore einzurichten und das Ergebnis in der Probe zu dokumentieren.

Der Cloud-SQL-Administrator besitzt keine uneingeschränkten PostgreSQL-Superuser-Rechte; Cloud-SQL-Rollen und IAM-Anmeldungen werden am Ziel nicht automatisch nachgebildet. Ein einzelner pg_dump enthält keine clusterweiten Rollen (SQL-Dump). Übernehmen Sie daher keinen ungeprüften globalen Rollenexport mit Google-internen Konten.

Quellzugriff und Ziel vorbereiten

Das Beispiel nutzt den Cloud SQL Auth Proxy v2 auf dem Migrationsrechner, gebunden an Loopback. Voraussetzung sind installierter Proxy, aktivierte Cloud SQL Admin API, passende Google-Anmeldedaten und die IAM-Berechtigung zum Verbinden. Bei ausschließlich privater IP braucht der Rechner zusätzlich einen Netzwerkpfad zur VPC; der Proxy stellt ihn nicht her (Proxy-Konfiguration).

cloud-sql-proxy --address 127.0.0.1 --port 55432 PROJECT:REGION:INSTANCE

Für eine Verbindung über die private IP ergänzen Sie im Proxy-Befehl --private-ip; der Netzwerkpfad zur VPC bleibt Voraussetzung (private IP verwenden). Lassen Sie den Proxy in einem separaten Terminal laufen. Das Beispiel nutzt eine reguläre PostgreSQL-Kennwortanmeldung. Hinterlegen Sie das Kennwort in .pgpass oder über ein freigegebenes Secret-Verfahren, nicht im Shell-Befehl. Unter Unix muss die Passwortdatei restriktive Rechte haben, etwa chmod 600 ~/.pgpass (Passwortdatei).

Definieren Sie in der Bash-Sitzung Verbindungen ohne Kennwörter:

export SRC_DSN='host=127.0.0.1 port=55432 dbname=appdb user=export_user sslmode=disable'
export DST_ADMIN='host=db.internal.example dbname=postgres user=migration_admin sslmode=verify-full sslrootcert=/secure/target-ca.pem'
export DST_DSN='host=db.internal.example dbname=appdb_migration user=migration_admin sslmode=verify-full sslrootcert=/secure/target-ca.pem'

sslmode=disable gilt hier nur für den lokalen Hop zum Proxy; dessen Verbindung zu Cloud SQL ist TLS-geschützt. Am Ziel setzt das Beispiel einen erreichbaren privaten Host mit gültigem Zertifikat, passendem DNS-Namen und vorbereiteten Administrationsrechten voraus. Öffnen Sie PostgreSQL für diese Anleitung nicht allgemein ins Internet.

Legen Sie am Ziel eine dedizierte Eigentümerrolle an und erzeugen Sie eine neue, leere Datenbank. app_owner ist hier bewusst keine Login-Rolle. migration_admin muss die Rolle übernehmen dürfen. Das Encoding-/Locale-Konzept muss vorher feststehen; template0 ist die Grundlage für eine leere Datenbank.

psql "$DST_ADMIN" -X -v ON_ERROR_STOP=1   -c 'CREATE ROLE app_owner NOLOGIN;'
createdb --maintenance-db="$DST_ADMIN"   --template=template0 --owner=app_owner appdb_migration

Die Rolle nur einmal anlegen; existiert sie bereits, prüfen Sie ihre Attribute. Für eine erneute Probe verwenden Sie eine weitere leere Datenbank. Die gezeigte Eigentümervereinheitlichung passt nur, wenn mehrere ursprüngliche Besitzer fachlich auf eine Rolle abgebildet werden dürfen. Andernfalls ist vorab ein genauer Rollenplan erforderlich.

Inventarisieren Sie vor dem Restore alle in den Dump-Definitionen referenzierten Rollen und legen Sie diese gemäß Rollenplan am Ziel an. Die Abfrage von pg_policies oben erfasst die Zielrollen der RLS-Policies; prüfen Sie zusätzlich die Schemaausgabe des Archivs mit pg_restore --schema-only --no-owner --no-privileges --file=cloudsql-schema.sql cloudsql-final.dump, sobald der Dump vorliegt. Beispielsweise benötigt CREATE POLICY ... TO app_reader bereits beim Restore eine vorhandene Rolle app_reader (CREATE POLICY). Noch nicht benötigte Anmeldungen bleiben als NOLOGIN gesperrt. --no-privileges unterdrückt GRANT/REVOKE, nicht Policy-Definitionen (pg_restore). Zugangsdaten und zusätzliche Berechtigungen folgen nach dem Restore.

Finalen Dump erstellen und wiederherstellen

Vor dem finalen Dump empfehlen wir ein dokumentiertes Gate: Webanwendungen, Worker, Cronjobs, Importe und Administrationszugriffe stoppen; offene Schreibtransaktionen kontrollieren; Schemaänderungen sperren. Ein Read-only-Banner allein ist kein Nachweis, dass kein Prozess mehr schreibt.

pg_dump erstellt einen konsistenten Stand auch bei parallelem Betrieb. Spätere Änderungen enthält dieser Stand nicht (pg_dump). Im hier beschriebenen Verfahren bleibt deshalb die Quelle vom finalen Dump bis zur Freigabe des Ziels ohne Schreibzugriffe.

umask 077
pg_dump --dbname="$SRC_DSN" --format=custom   --file=cloudsql-final.dump
pg_restore --list cloudsql-final.dump > cloudsql-final.toc

Kontrollieren Sie Exit-Code und Fehlermeldungen nach jedem Befehl. Ohne erfolgreichen Dump nicht fortfahren. Der Exportbenutzer benötigt Zugriff auf alle zu sichernden Objekte. RLS ist besonders zu prüfen: Ein eingeschränkter Export darf nicht unbemerkt nur einen fachlichen Ausschnitt sichern (Row Security).

Das Custom-Archiv wird mit pg_restore eingelesen. In diesem Beispiel werden ursprüngliche Eigentümer und ACLs bewusst nicht wiederhergestellt, sondern dem vorbereiteten Rollenplan überlassen. --exit-on-error stoppt beim ersten SQL-Fehler (pg_restore-Optionen):

pg_restore --dbname="$DST_DSN" --role=app_owner   --no-owner --no-privileges --exit-on-error   cloudsql-final.dump

Es gibt hier kein --clean gegen eine vorhandene Produktionsdatenbank. Ein fehlgeschlagener Restore ist keine freigegebene Teildatenbank. Fehler beheben und auf einem neuen leeren Ziel erneut beginnen. Benötigt eine Extension privilegierte Installation, muss sie durch den Administrator passend vorbereitet werden; fehlende Objekte nicht durch pauschales Auskommentieren übergehen.

Das Archiv enthält Anwendungsdaten. Für Transfer und Ablage empfehlen wir verschlüsselte Verbindungen, beschränkte Zugriffe, Integritätsprüfung nach Übertragung und eine festgelegte Löschfrist. Die Beispiele führen Dump und Restore vom selben Migrationsrechner aus; ein zusätzlicher Dateitransfer ist dafür nicht erforderlich.

Daten und Anwendungsrechte prüfen

Nach dem Restore werden die bereits angelegten Anwendungsrollen um neue Zugangsdaten, benötigte Mitgliedschaften, Datenbank-/Schema-Rechte und Default Privileges ergänzt. Die mit --no-privileges ausgelassenen Rechte müssen bewusst ersetzt werden. Insbesondere darf die Anwendung nicht allein für die Migration dauerhaft als Administrator laufen.

Für die Abnahme empfehlen wir eine protokollierte Prüfliste:

Nach der Wiederherstellung sollten Optimizer-Statistiken aufgebaut werden (PostgreSQL: SQL-Dump wiederherstellen). Führen Sie die Analyse ausdrücklich als app_owner aus: Die Berechtigung zu SET ROLE bedeutet nicht automatisch Rechtevererbung (Rollenmitgliedschaften). Beispiel nach dem Restore:

psql "$DST_DSN" -X -v ON_ERROR_STOP=1 \
  -c 'SET ROLE app_owner;' \
  -c 'ANALYZE VERBOSE;'

SET ROLE und ANALYZE laufen in derselben psql-Sitzung (SET ROLE). ANALYZE VERBOSE baut Statistiken auf und meldet die bearbeiteten Tabellen; prüfen Sie Ausgaben und Warnungen auf übersprungene Anwendungstabellen und klären Sie fehlende Berechtigungen vor der Abnahme (ANALYZE). Datenbankgröße allein ist kein Nachweis inhaltlicher Gleichheit. Schreibtests der Probe gehören auf ein isoliertes Testziel. Das finale Ziel darf erst nach Freigabe produktive Änderungen annehmen.

Cutover und Rückfallweg festlegen

Wir empfehlen, vorab festzuhalten, wer die Freigabe erteilt und bei welchen Befunden abgebrochen wird. Der Ablauf für diesen Dump-Ansatz lautet:

1. Alle Schreiber stoppen und Quelle prüfen.
2. Finalen Dump erstellen, in ein leeres Ziel einlesen und Daten abnehmen.
3. Verbindungsdaten und Secrets der Anwendungen auf das Ziel umstellen.
4. Zunächst kontrollierte Prüfungen durchführen; Schreibfreigabe ausdrücklich erteilen.
5. Worker und Jobs geordnet aktivieren; Fehler, Verbindungen und Datenbanklast beobachten.

Rückfall vor der Schreibfreigabe: Wenn die Quelle unverändert ist und das Ziel keine neuen produktiven Daten angenommen hat, können Anwendungen nach Prüfung wieder zur Quelle zurückkehren.

Rückfall nach der Schreibfreigabe: Ein Zurücksetzen der Adresse allein würde die neuen Zieldaten ausblenden. Stoppen Sie erneut die Schreiber und entscheiden Sie über Rückübertragung beziehungsweise Abgleich. Ein solcher Rückweg muss vor dem Cutover geplant sein. Versprechen Sie keinen verlustfreien automatischen Rollback.

Die alte Instanz sollte nach unserer Empfehlung bis zur dokumentierten Abnahme gegen Schreibzugriffe geschützt verfügbar bleiben. Kündigung und Löschung sind ein eigener Schritt nach der Abnahme, mit geklärten Aufbewahrungs- und Sicherungsanforderungen.

Unser Vorgehen bei WZ-IT

Die Google-Cloud-Migration zu Hetzner umfasst die Einordnung von Cloud SQL im Zusammenhang mit den übrigen Diensten. Wir klären Zielarchitektur, Datenübernahme, Tests und Cutover. Der technische Schwerpunkt für die Datenbank liegt auf PostgreSQL; den optionalen laufenden Betrieb grenzen wir über Managed Operations ab. Umfang und Zuständigkeiten werden für die konkrete Umgebung festgelegt.

Weiterführende Guides

• AWS RDS und Aurora PostgreSQL zu Hetzner: anderer Quelldienst, ähnliche Werkzeugkette.
• Azure PostgreSQL zu Hetzner: Azure-spezifischer Ausgangspunkt.
• GCP-Egress und Hetzner-Traffic: Datenverkehr im Kostenbild einordnen.
• Migrationsübersicht: zugehörige Angebote und weitere Quellsysteme.

Cloud-SQL-Übernahme und Zielbetrieb planen. Besprechen Sie Datenbank, angebundene Anwendungen und Cutover-Bedingungen für Ihre GCP-Migration. Erstgespräch vereinbaren

Quellen

• Google Cloud: Export with pg_dump
• Google Cloud: Cloud SQL Auth Proxy
• Google Cloud: PostgreSQL users
• Google Cloud: Extensions
• Google Cloud: Logical replication
• PostgreSQL: pg_dump
• PostgreSQL: pg_restore
• PostgreSQL: createdb
• PostgreSQL: Password file
• PostgreSQL: SQL dump and restore
• PostgreSQL: pg_policies
• PostgreSQL: CREATE POLICY
• PostgreSQL: SET ROLE
• PostgreSQL: ANALYZE
• PostgreSQL: Role membership
• PostgreSQL: Row security
• PostgreSQL: Logical replication restrictions