Probleme bei Migrationen von PostgreSQL zu AlloyDB for PostgreSQL diagnostizieren

Während der Laufzeit des Migrationsjobs können Fehler auftreten.

  • Einige Fehler, z. B. ein falsches Passwort für die Quelldatenbank, können behoben werden. Der Migrationsjob wird dann automatisch fortgesetzt.
  • Einige sind nicht wiederherstellbar, z. B. Datenbeschädigung oder Schemainkompatibilitäten. In diesem Fall muss der Migrationsjob von vorn gestartet werden.

Wenn ein Fehler auftritt, ändert sich der Status des Migrationsjobs in Failed und der Unterstatus spiegelt den letzten Status vor dem Fehler wider.

Rufen Sie zur Fehlerbehebung den fehlgeschlagenen Migrationsjob auf, um den Fehler zu sehen, und folgen Sie den Schritten in der Fehlermeldung.

Wenn Sie weitere Details zum Fehler aufrufen möchten, rufen Sie Cloud Monitoring über den Link im Migrationsjob auf. Die Logs werden nach dem jeweiligen Migrationsjob gefiltert.

In der folgenden Tabelle sind häufige Probleme und ihre Lösungen aufgeführt:

Problem Mögliche Ursache Lösungsvorschlag
Wenn Sie zu einem vorhandenen Zielcluster migrieren, erhalten Sie die folgende Fehlermeldung: The destination cluster contains existing data or user defined entities (for example databases, tables, or functions). You can only migrate to empty clusters. Clear your destination cluster and retry the migration job. Ihr AlloyDB for PostgreSQL-Zielcluster enthält zusätzliche Nutzerdaten. Sie können nur zu vorhandenen Clustern migrieren, die leer sind. Siehe Bekannte Einschränkungen. Löschen Sie die in Konflikt stehenden oder zusätzlichen Daten aus dem Zielcluster und versuchen Sie es noch einmal. Weitere Informationen finden Sie unter Zusätzliche Daten aus dem vorhandenen Zielcluster löschen.
Fehler beim Herstellen einer Verbindung zur Quelldatenbankinstanz. Es gab ein Verbindungsproblem zwischen der Quelldatenbankinstanz und dem AlloyDB for PostgreSQL-Zielcluster. Folgen Sie der Anleitung unter Debugging der Verbindung.
Der Migrationsjob konnte aufgrund inkompatibler Quell- und Zieldatenbankversionen nicht ausgeführt werden. Die Kombination aus Quell- und Zieldatenbankversion wird nicht unterstützt. Insbesondere ist die angegebene Quelldatenbankversion nicht mit der Zieldatenbankversion kompatibel. Achten Sie darauf, dass die Zieldatenbankversion dieselbe oder eine neuere unterstützte Hauptversion als die Quelldatenbankversion ist. Erstellen Sie dann einen neuen Migrationsjob.
Datendefinitionssprachen (DDLs) oder Datenbearbeitungssprachen (DMLs) sind auf der Quelle blockiert. DDLs, die die ACCESS EXCLUSIVE-Sperre erfordern und während der Phase des vollständigen Dumps ausgeführt werden, werden blockiert.

Während der ersten Synchronisierung (vollständiger Dump) sollten DDLs oder Programme, die ACCESS EXCLUSIVE-Sperren wie ALTER TABLE oder DROP TABLE erfordern, für die Tabellen vermieden werden. Andernfalls warten die DDLs oder Programme, bis die erste Synchronisierung abgeschlossen ist.

Wenn sich eine Tabelle beispielsweise noch im ersten Synchronisierungsprozess befindet und ein ALTER TABLE-Befehl für dieselbe Tabelle ausgeführt wird, wird der Befehl nicht ausgeführt und nachfolgende DDL- und DML-Befehle werden blockiert, bis die erste Synchronisierung abgeschlossen ist.
Fehlermeldung: No pglogical extension installed on databases (X) Auf mindestens einer Quelldatenbank ist pglogical nicht installiert. Folgen Sie dieser Anleitung, um pglogical in den Datenbanken der Quellinstanz zu installieren.
Bei der Migration zu PostgreSQL Version 15 tritt nach mehreren aufeinanderfolgenden Verbindungsversuchen eines der folgenden Symptome auf: Dieses Problem wird häufig auf das Deadlock-Problem in der pglogical-Erweiterung zurückgeführt. Weitere Informationen finden Sie im pglogical-Issue Tracker auf GitHub. Wiederholen Sie den Migrationsjob oder migrieren Sie zuerst zu einer PostgreSQL-Zwischenversion. Weitere Informationen finden Sie unter Fehlermeldung: Cannot connect to invalid database.
Fehlermeldung: Replication user 'x' doesn't have sufficient privileges. Der Nutzer, der Database Migration Service verwendet, hat nicht die erforderlichen Berechtigungen, um den angegebenen Vorgang auszuführen. Folgen Sie dieser Anleitung, um sicherzustellen, dass dieser Nutzer die erforderlichen Berechtigungen hat.
Fehlermeldung: Unable to connect to source database server. Database Migration Service kann keine Verbindung zum Quelldatenbankserver herstellen. Prüfen Sie, ob die Quell- und Zieldatenbankinstanzen miteinander kommunizieren können und ob Sie alle erforderlichen Voraussetzungen erfüllt haben, die beim Definieren der Einstellungen für den Migrationsjob angezeigt wurden.
Fehlermeldung: The source database 'wal_level' configuration must be equal to 'logical'. Der wal_level für die Quelldatenbank ist auf einen anderen Wert als logical festgelegt. Legen Sie den Wert wal_level auf logical fest. Weitere Informationen finden Sie unter WAL-Ebene konfigurieren.
Fehlermeldung: The source database 'max_replication_slots' configuration is not sufficient. Der Parameter max_replication_slots wurde nicht richtig konfiguriert. Folgen Sie dieser Anleitung, um diesen Parameter richtig festzulegen.
Fehlermeldung: The source database 'max_wal_senders' configuration is not sufficient. Der Parameter max_wal_senders wurde nicht richtig konfiguriert. Folgen Sie dieser Anleitung, um diesen Parameter richtig festzulegen.
Fehlermeldung: The source database 'max_worker_processes' configuration is not sufficient. Der Parameter max_worker_processes wurde nicht richtig konfiguriert. Folgen Sie dieser Anleitung, um diesen Parameter richtig festzulegen.

Fehlermeldung: Cleanup may have failed on source due to error: generic::unknown: failed to connect to on-premises database.

ODER

Fehlermeldung: Error promoting EM replica: finished drop replication with errors.

Die für die Replikation erforderlichen Einstellungen können während der Hochstufung eines Migrationsjobs nicht bereinigt werden.

Führen Sie für jede Datenbank Befehle als Nutzer mit der Berechtigung superuser aus.

Weitere Informationen zu den auszuführenden Befehlen finden Sie unter Replikationsslots bereinigen.

Fehlermeldung: x509 certificate signed by unknown authority.

Das CA-Quellzertifikat, das für Database Migration Service bereitgestellt wird, enthält möglicherweise nur das Root-Zertifikat. Für das Quellzertifikat sind jedoch sowohl das Root-Zertifikat als auch alle Zwischenzertifikate erforderlich.

Bei Amazon RDS kann dieses Problem beispielsweise auftreten, wenn ein eigenständiges Root-Zertifikat anstelle eines Zertifikat-Bundles verwendet wird.

Erstellen Sie ein kombiniertes Quell-CA-Zertifikat, das sowohl das Root-Zertifikat als auch alle erforderlichen Zwischenzertifikate enthält.

Verwenden Sie für Amazon RDS-Quellen ein Zertifikatspaket, das sowohl die Zwischen- als auch die Root-Zertifikate enthält. Weitere Informationen finden Sie in der Amazon RDS-Dokumentation unter Zertifikat-Bundles herunterladen.

Fehlermeldung: ERROR: Out of shared memory HINT: You might need to increase max_locks_per_transaction.

Der für den Parameter max_locks_per_transaction festgelegte Wert ist nicht ausreichend. Legen Sie den Wert für diesen Parameter auf mindestens {max_number_of_tables_per_database}/(max_connections + max_prepared_transactions) fest.

Fehlermeldung: ERROR: no data left in message.

Das pglogical-Paket ist auf der Quellinstanz nicht korrekt installiert. Weitere Informationen zur ordnungsgemäßen Installation dieses Pakets finden Sie unter Quelldatenbank konfigurieren.

Fehlermeldung: Cannot assign TransactionIds during recovery.

Die konfigurierte Quelle befindet sich im Wiederherstellungsmodus. Konfigurieren Sie eine Quelle, die sich nicht im Wiederherstellungsmodus befindet.
Der vollständige Dump ist langsam. Die primäre Instanz des AlloyDB for PostgreSQL-Zielclusters ist beim Importieren großer Datenmengen aus der Quelldatenbank möglicherweise langsam.
  • Wählen Sie für die primäre AlloyDB for PostgreSQL-Zielinstanz eine höhere Maschinenstufe aus, um die maximal verfügbare Netzwerkbandbreite und CPU-Kapazität zu erhalten.
  • Passen Sie das Flag max_wal_size des Ziels an. In der Regel ist 32 GB oder 64 GB ein guter Wert für dieses Flag. Wenn Sie dieses Flag aktualisieren, müssen Sie den Datenbankserver nicht neu starten.
Fehlermeldung: subscriber {subscriber_name} initialization failed during nonrecoverable step (d), please try the setup again

Der Migrationsjob ist während der Phase des vollständigen Dumps fehlgeschlagen und kann nicht wiederhergestellt werden. Die Quelldatenbankinstanz wurde neu gestartet oder befand sich im Wiederherstellungsmodus oder die Replikationsverbindungen wurden beendet, weil der Wert für den Parameter wal_sender_timeout nicht ausreichte.

So finden Sie die Ursache des Problems:

  1. Rufen Sie in der Google Cloud Console die Seite Log-Explorer auf:
  2. Wählen Sie in der Ressourcenliste Ihre AlloyDB for PostgreSQL-Instanz aus. Eine Liste der neuesten Logs für die Instanz wird angezeigt.
  3. Wählen Sie aus den Logdateinamen postgres.log aus.
  4. Legen Sie den Schweregrad des Logs auf alle Stufen über Warning fest. Die ersten Fehlerlogs können die Ursache des Fehlers sein.
  • Achten Sie darauf, dass Database Migration Service während der vollständigen Dump-Phase immer eine Verbindung zur Quelldatenbankinstanz herstellen kann.
  • Prüfen Sie, ob der Wert des Parameters wal_sender_timeout in der Quelldatenbankinstanz auf eine größere Zahl (z. B. 0) festgelegt ist.
  • Starten Sie den Migrationsjob neu und versuchen Sie es dann noch einmal.
Fehlermeldung: ERROR: unknown column name {column_name}

Eine Spalte wurde einer replizierten Tabelle auf dem primären Knoten, aber nicht auf dem Replikatknoten hinzugefügt.

Bei kontinuierlichen Migrationen werden nur Änderungen der Datenbearbeitungssprache (Data Manipulation Language, DML) automatisch aktualisiert. Sie müssen Änderungen an der Datendefinitionssprache (DDL) verwalten, damit die Quell- und Zieldatenbanken kompatibel bleiben. Dafür gibt es zwei Möglichkeiten:

  • Beenden Sie Schreibvorgänge in die Quelldatenbank und führen Sie die DDL-Befehle sowohl auf der Quelle als auch auf dem Ziel aus. Bevor Sie die DDL-Befehle auf dem Ziel ausführen, weisen Sie dem AlloyDB for PostgreSQL-Nutzer, der die DDL-Änderungen anwendet, die Rolle alloydbexternalsync zu.
  • Verwenden Sie pglogical.replicate_ddl_command, um DDL-Befehle an einem konsistenten Punkt auf der Quelle und dem Ziel auszuführen. Der Nutzer, der die Befehle ausführt, muss sowohl auf der Quelle als auch auf dem Ziel denselben Nutzernamen haben und der Superuser oder der Inhaber des migrierten Artefakts (z. B. der Tabelle, Sequenz, Ansicht oder Datenbank) sein.

Beispiele für die Verwendung von pglogical.replicate_ddl_command finden Sie unter Kontinuierliche Migration.
Fehlermeldung: ERROR: cannot truncate a table referenced in a foreign key constraint

Ein Nutzer hat versucht, eine Tabelle mit einer Fremdschlüsseleinschränkung zu kürzen.

Entfernen Sie zuerst die Fremdschlüsseleinschränkung und kürzen Sie dann die Tabelle.
Fehlermeldung: ERROR: connection to other side has died

Die Replikationsverbindung wurde beendet, weil für den Parameter wal_sender_timeout ein unzureichender Wert festgelegt wurde. Der Fehler tritt normalerweise während der Replikationsphase nach dem erfolgreichen ersten Dump auf.

Erhöhen Sie gegebenenfalls den Wert des Parameters wal_sender_timeout oder deaktivieren Sie das Zeitlimitverfahren, indem Sie den Wert in der Quelldatenbankinstanz auf 0 setzen.
Warnmeldung: migration job test configuration has returned the following warnings: Some table(s) have limited support.

Die Quelle enthält Tabellen mit eingeschränkter Unterstützung, z. B. Tabellen ohne Primärschlüssel.

Dies ist eine Warnmeldung. Sie können mit der Migration fortfahren. Beachten Sie jedoch, dass bei Standardmigrationen für Tabellen ohne Primärschlüssel nur der erste Snapshot und die INSERT-Anweisungen während der CDC-Phase (Change Data Capture) repliziert werden. UPDATE- und DELETE-Anweisungen werden nicht repliziert. Weitere Informationen finden Sie unter Quelldatenbank konfigurieren.

Wenn Sie ausgewählte Datenbanken migrieren und der Migrationsjob keine Daten in eine oder mehrere Datenbanken replizieren kann, wird in der Liste der Datenbanken der Status Fehlgeschlagen angezeigt. Verschiedene Fehler bei Migrationsjobs.

Klicken Sie in der Spalte Fehler auf Fehler ansehen und beheben Sie die Fehler. Sie können die fehlerhaften Datenbanken auch aus dem Migrationsjob entfernen.

Weitere Informationen zum Entfernen einer fehlgeschlagenen Datenbank aus einem Migrationsjob finden Sie unter Migrationsjobs verwalten.

Zusätzliche Daten aus dem vorhandenen Zielcluster löschen

Wenn Sie zu einem vorhandenen Zielcluster migrieren, erhalten Sie die folgende Fehlermeldung: The destination cluster contains existing data or user defined entities (for example databases, tables, or functions). You can only migrate to empty clusters. Clear your destination cluster and retry the migration job.

Dieses Problem kann auftreten, wenn der Zielcluster zusätzliche Daten enthält. Sie können nur zu vorhandenen Clustern migrieren, die leer sind. Siehe Bekannte Einschränkungen.

Lösungsvorschlag

Löschen Sie die in Konflikt stehenden oder zusätzlichen Daten aus dem Zielcluster und starten Sie den Migrationsjob noch einmal. Gehen Sie dazu so vor:

  1. Beenden Sie den Migrationsjob.
  2. Stellen Sie eine Verbindung zur primären Instanz des AlloyDB for PostgreSQL-Zielclusters her. Verwenden Sie dazu psql oder AlloyDB Studio.
  3. Entfernen Sie zusätzliche Daten aus den Datenbanken des Zielclusters. Ihr Ziel darf nur Systemkonfigurationsdaten enthalten. Zieldatenbanken dürfen keine Nutzerdaten (z. B. benutzerdefinierte Tabellen oder Routinen) enthalten. Es gibt verschiedene SQL-Anweisungen, die Sie in Ihren Datenbanken ausführen können, um Nicht-Systemdaten zu finden:

    Beispiel für eine SQL-Anweisung zum Abrufen von Nicht-Systemdatenbanken (zum Maximieren klicken)

    SELECT datname FROM pg_catalog.pg_database
WHERE datname NOT IN ('alloydbadmin', 'template1', 'template0', 'postgres');

    Beispiel für eine SQL-Anweisung zum Abrufen von Nicht-Systemdaten in der Datenbank postgres (zum Maximieren klicken)

    Die Datenbank postgres ist eine Systemdatenbank, kann aber auch Nicht-Systemdaten enthalten. Achten Sie darauf, diese Anweisungen für die Datenbank postgres auszuführen. Wenn Sie den psql-Client verwenden, um eine Verbindung zum Zielcluster herzustellen, können Sie mit dem Befehl \connect {database_name_here} zu einer anderen Datenbank wechseln, ohne die Verbindung zurückzusetzen.

    SELECT table_schema, table_name FROM information_schema.tables
WHERE table_schema != 'information_schema' AND table_schema not like 'pg\_%';

SELECT routine_schema, routine_name FROM information_schema.routines
WHERE routine_schema != 'information_schema' AND routine_schema not like 'pg\_%';

SELECT extname FROM pg_extension WHERE extname NOT IN ('plpgsql', 'alloydb_utility');
  4. Löschen Sie alle nicht systemeigenen Datenbanken, Benutzertabellen und benutzerdefinierten Funktionen, die im vorherigen Schritt identifiziert wurden.
  5. Migrationsjob starten

Replikationsslots bereinigen

Ihnen wird eine der folgenden Meldungen angezeigt:

  • Cleanup may have failed on source due to error: generic::unknown: failed to connect to on-premises database.
  • Error promoting EM replica: finished drop replication with errors.

Mögliche Ursache

Wenn Sie einen AlloyDB for PostgreSQL-Zielcluster hochstufen und die Quellinstanz nicht vom AlloyDB for PostgreSQL-Cluster aus erreichbar ist (z. B. weil die Quellinstanz nicht ausgeführt wird oder Sie den AlloyDB for PostgreSQL-Cluster aus der Zulassungsliste der Quellinstanzen entfernt haben), können die für die Replikation erforderlichen Einstellungen während des Hochstufens eines Migrationsjobs nicht bereinigt werden. Sie müssen die Replikationsslots manuell bereinigen.

Lösungsvorschlag

Führen Sie für jede Datenbank die folgenden Befehle als Nutzer mit der Berechtigung superuser aus:

  1. Rufen Sie die Namen der Replikations-Slots aus der Fehlermeldung ab und führen Sie dann den folgenden Befehl aus, um die Slots nacheinander zu löschen:

    SELECT pg_drop_replication_slot('slot_name');

  2. Wenn die Namen der Replikations-Slots in der Fehlermeldung nicht verfügbar sind, führen Sie den folgenden Befehl aus, um die vorhandenen Replikations-Slots abzufragen:

    SELECT pg_drop_replication_slot(slot_name) FROM pg_replication_slots WHERE slot_name LIKE '%alloydb%' AND active = 'f';

  3. Wenn keine AlloyDB for PostgreSQL-Replikate die Quellinstanz verwenden, führen Sie den folgenden Befehl aus, um die pglogical-Einstellungen zu bereinigen:

    SELECT pglogical.drop_node(node_name) FROM pglogical.node WHERE node_name LIKE '%alloydb%';

  4. Wenn die Erweiterung pglogical nicht mehr benötigt wird, führen Sie den folgenden Befehl aus, um sie zu deinstallieren:

    DROP EXTENSION IF EXISTS pglogical;

Fehlermeldung: Cannot connect to invalid database

Bei der Migration zu PostgreSQL Version 15 tritt nach mehreren aufeinanderfolgenden Verbindungsversuchen eines der folgenden Symptome auf:

Mögliche Ursache

Dieses Problem wird häufig auf das Deadlock-Problem in der Erweiterung pglogical zurückgeführt. Weitere Informationen finden Sie im pglogical-Issue Tracker auf GitHub.

Lösungsvorschlag

Führen Sie den Migrationsjob noch einmal mit einem neuen Zielcluster aus.

Löschen Sie den Zielcluster, in dem das Problem aufgetreten ist, und erstellen Sie den Migrationsjob neu. Gehen Sie so vor:

  1. Löschen Sie den fehlgeschlagenen Migrationsjob. Weitere Informationen finden Sie unter Migrationsjob prüfen.
  2. Löschen Sie den Zielcluster, in dem das Problem aufgetreten ist. Weitere Informationen finden Sie unter AlloyDB-Clusterverwaltung.
  3. Erstellen Sie den Migrationsjob neu. Weitere Informationen finden Sie unter Migrationsjob erstellen.
Zu einer Zwischenversion migrieren

Ziehen Sie eine Migration zu einer früheren PostgreSQL-Version wie PostgreSQL 14 in Betracht. Nach einer erfolgreichen Migration können Sie ein Upgrade auf die gewünschte PostgreSQL 15-Instanz durchführen. Weitere Informationen finden Sie in der AlloyDB for PostgreSQL-Dokumentation unter Hauptversion einer Datenbank aktualisieren.

Verwaiste AlloyDB for PostgreSQL-Cluster im Bootstrapping-Modus löschen

In seltenen Fällen kann es vorkommen, dass Ihr Migrationsjob gelöscht wurde, der zugehörige AlloyDB for PostgreSQL-Cluster jedoch nicht und sich noch im Bootstrapping-Modus befindet. Sie können den Cluster mit dem Befehl gcloud alloydb clusters delete und der Option --force löschen:

gcloud alloydb clusters delete CLUSTER_ID \
    --region=REGION_ID \
    --force

Das Löschen eines Bootstrapping-Clusters, während er von einem aktiven Migrationsjob verwendet wird, führt zu einem undefinierten Verhalten.

Nutzer und Rollen verwalten

Vorhandene Nutzer migrieren

Derzeit unterstützt Database Migration Service die automatische Migration vorhandener Nutzer und Rollen von einer Quellinstanz zu einem AlloyDB for PostgreSQL-Zielcluster nicht. Sie können diese Migration verwalten, indem Sie die Nutzer in AlloyDB for PostgreSQL manuell erstellen.

Informationen zum Nutzer alloydbexternalsync

Während einer Standardmigration gehören alle Datenbankobjekte im AlloyDB for PostgreSQL-Replikat dem Nutzer alloydbexternalsync. Bei Schnellstartmigrationen wird der Nutzer postgres verwendet. Nachdem die Daten migriert und der Migrationsjob hochgestuft wurde, können Sie die Eigentümerschaft der Objekte auf andere Anwendungsnutzer übertragen. Gehen Sie dazu so vor:

  • Führen Sie den Befehl GRANT alloydbexternalsync TO USER; aus:
  • Führen Sie in jeder Datenbank den Befehl REASSIGN OWNED BY alloydbexternalsync TO USER; aus.
  • Führen Sie den Befehl DROP ROLE alloydbexternalsync; aus, um den Nutzer alloydbexternalsync zu entfernen.