Diagnostica i problemi nelle migrazioni da PostgreSQL ad AlloyDB per PostgreSQL

Il processo del job di migrazione potrebbe generare errori durante il runtime.

  • Alcuni errori, come una password errata nel database di origine, sono recuperabili, il che significa che possono essere corretti e il job di migrazione riprende automaticamente.
  • Alcuni errori non sono recuperabili, come il danneggiamento dei dati o le incompatibilità dello schema, il che significa che il job di migrazione deve essere riavviato dall'inizio.

Quando si verifica un errore, lo stato del job di migrazione cambia in Failed e lo stato secondario riflette l'ultimo stato prima dell'errore.

Per risolvere un errore, vai al job di migrazione non riuscito per visualizzare l'errore e segui i passaggi descritti nel messaggio di errore.

Per visualizzare ulteriori dettagli sull'errore, vai a Cloud Monitoring utilizzando il link nel job di migrazione. I log vengono filtrati in base al job di migrazione specifico.

La tabella seguente elenca i problemi comuni e le relative soluzioni:

Per questo problema… Il problema potrebbe essere… Prova…
Quando esegui la migrazione a un cluster di destinazione esistente, ricevi il seguente messaggio di errore: 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. Il cluster AlloyDB per PostgreSQL di destinazione contiene dati utente aggiuntivi. Puoi eseguire la migrazione solo a cluster esistenti vuoti. Consulta le limitazioni note. Cancella i dati in conflitto o aggiuntivi dal cluster di destinazione e riprova a eseguire il job di migrazione. Consulta Cancella i dati aggiuntivi dal cluster di destinazione esistente.
Impossibile connettersi all'istanza del database di origine. Si è verificato un problema di connettività tra l'istanza del database di origine e il cluster AlloyDB per PostgreSQL di destinazione. Segui i passaggi descritti in Debug della connettività.
Esecuzione del job di migrazione non riuscita a causa di versioni dei database di origine e di destinazione incompatibili. Le versioni del database di origine e di destinazione non sono una combinazione supportata. In particolare, la versione del database di origine fornita non è compatibile con la versione del database di destinazione. Assicurati che la versione del database di destinazione sia la stessa o una versione principale supportata successiva rispetto alla versione del database di origine. Poi, crea un nuovo job di migrazione.
I linguaggi DDL (Data Definition Language) o DML (Data Manipulation Language) sono bloccati nell'origine. Le istruzioni DDL che richiedono il blocco ACCESS EXCLUSIVE e sono in esecuzione durante la fase di dump completo vengono bloccate.

Durante il processo di sincronizzazione iniziale (dump completo), è necessario evitare DDL o programmi che richiedono blocchi ACCESS EXCLUSIVE come ALTER TABLE o DROP TABLE sulle tabelle. In caso contrario, i DDL o i programmi attendono il completamento della sincronizzazione iniziale.

Ad esempio, se una tabella è ancora in fase di sincronizzazione iniziale e viene eseguito un comando ALTER TABLE sulla stessa tabella, il comando non verrà eseguito e i comandi DDL e DML successivi verranno bloccati fino al termine della sincronizzazione iniziale.
Messaggio di errore: No pglogical extension installed on databases (X) Uno o più database di origine non hanno pglogical installato. Segui queste linee guida per installare pglogical sui database nell'istanza di origine.
Durante la migrazione a PostgreSQL versione 15, dopo diversi tentativi di connessione successivi, si verifica uno dei seguenti sintomi: Questo problema è spesso attribuito al problema di deadlock nell'estensione pglogical. Per maggiori informazioni, consulta l'Issue Tracker di pglogical su GitHub. Riprova il job di migrazione o esegui prima la migrazione a una versione PostgreSQL intermedia. Per maggiori dettagli, consulta Messaggio di errore: Cannot connect to invalid database.
Messaggio di errore: Replication user 'x' doesn't have sufficient privileges. L'utente che utilizza Database Migration Service non dispone dei privilegi necessari per eseguire l'operazione designata. Segui queste linee guida per assicurarti che questo utente disponga dei privilegi richiesti.
Messaggio di errore: Unable to connect to source database server. Database Migration Service non riesce a stabilire una connessione al server del database di origine. Assicurati che le istanze di database di origine e di destinazione possano comunicare tra loro e di aver completato tutti i prerequisiti richiesti visualizzati quando hai definito le impostazioni per il job di migrazione.
Messaggio di errore: The source database 'wal_level' configuration must be equal to 'logical'. Il valore wal_level per il database di origine è impostato su un valore diverso da logical. Imposta wal_level su logical. Consulta la sezione Configurazione del livello WAL.
Messaggio di errore: The source database 'max_replication_slots' configuration is not sufficient. Il parametro max_replication_slots non è stato configurato correttamente. Segui queste linee guida per impostare correttamente questo parametro.
Messaggio di errore: The source database 'max_wal_senders' configuration is not sufficient. Il parametro max_wal_senders non è stato configurato correttamente. Segui queste linee guida per impostare correttamente questo parametro.
Messaggio di errore: The source database 'max_worker_processes' configuration is not sufficient. Il parametro max_worker_processes non è stato configurato correttamente. Segui queste linee guida per impostare correttamente questo parametro.

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

OPPURE

Messaggio di errore: Error promoting EM replica: finished drop replication with errors.

Le impostazioni necessarie per la replica non possono essere cancellate durante la promozione di un job di migrazione.

Per ogni database, esegui i comandi come utente con il privilegio superuser.

Per ulteriori informazioni sui comandi da eseguire, consulta Esegui la pulizia degli slot di replica.

Messaggio di errore: x509 certificate signed by unknown authority.

Il certificato CA di origine fornito a Database Migration Service potrebbe contenere solo il certificato radice. Tuttavia, il certificato di origine richiede sia il certificato radice sia eventuali certificati intermedi.

Ad esempio, per Amazon RDS, l'utilizzo di un certificato radice autonomo anziché di un bundle di certificati potrebbe causare questo problema.

Crea un certificato CA di origine combinato che contenga sia il certificato radice sia tutti i certificati intermedi richiesti.

Per le origini Amazon RDS, utilizza un bundle di certificati che includa sia i certificati intermedi sia quelli radice. Per saperne di più, consulta Scarica i bundle di certificati nella documentazione di Amazon RDS.

Messaggio di errore: ERROR: Out of shared memory HINT: You might need to increase max_locks_per_transaction.

Il valore impostato per il parametro max_locks_per_transaction non è sufficiente. Imposta il valore di questo parametro su almeno {max_number_of_tables_per_database}/(max_connections + max_prepared_transactions).

Messaggio di errore: ERROR: no data left in message.

Il pacchetto pglogical non è installato correttamente nell'istanza di origine. Per saperne di più su come installare correttamente questo pacchetto, consulta Configura il database di origine.

Messaggio di errore: Cannot assign TransactionIds during recovery.

La sorgente configurata è in modalità Recovery. Configura un'origine che non sia in modalità Recovery [Recovery mode].
Il dump completo è lento. L'istanza principale del cluster di destinazione AlloyDB per PostgreSQL potrebbe essere lenta nell'importazione di dati di grandi dimensioni dal database di origine.
  • Scegli un livello di macchina più elevato per l'istanza principale AlloyDB per PostgreSQL di destinazione per ottenere la larghezza di banda di rete e la capacità della CPU massime disponibili.
  • Ottimizza il flag max_wal_size della destinazione. In genere, 32 GB o 64 GB sono un buon valore da impostare per questo flag. L'aggiornamento di questo flag non richiede il riavvio del server di database.
Messaggio di errore: subscriber {subscriber_name} initialization failed during nonrecoverable step (d), please try the setup again

Il job di migrazione non è riuscito durante la fase di dump completo e non è recuperabile. L'istanza del database di origine è stata riavviata o era in modalità Recovery oppure le connessioni di replica sono terminate a causa di un valore insufficiente impostato per il parametro wal_sender_timeout.

Per trovare la causa principale del problema:

  1. Vai alla pagina Esplora log nella console Google Cloud .
  2. Nell'elenco delle risorse, seleziona l'istanza AlloyDB per PostgreSQL. Viene visualizzato un elenco dei log più recenti per l'istanza.
  3. Dai nomi dei file di log, seleziona postgres.log.
  4. Imposta il livello di gravità del log su tutti i livelli superiori a Warning. I primi log degli errori potrebbero essere la causa principale dell'errore.
  • Assicurati che Database Migration Service possa sempre connettersi all'istanza del database di origine durante la fase di dump completo.
  • Controlla se il valore del parametro wal_sender_timeout è impostato su un numero maggiore (ad esempio 0) nell'istanza del database di origine.
  • Riavvia il job di migrazione e riprova.
Messaggio di errore: ERROR: unknown column name {column_name}

È stata aggiunta una colonna a una tabella replicata sul nodo principale, ma non sul nodo di replica.

Durante le migrazioni continue, vengono aggiornate automaticamente solo le modifiche del data manipulation language (DML). Devi gestire le modifiche al Data Definition Language (DDL) in modo che i database di origine e di destinazione rimangano compatibili. Puoi farlo in due modi:

  • Interrompi le scritture nel database di origine ed esegui i comandi DDL sia sull'origine che sulla destinazione. Prima di eseguire i comandi DDL sulla destinazione, concedi il ruolo alloydbexternalsync all'utente AlloyDB per PostgreSQL che applica le modifiche DDL.
  • Utilizza pglogical.replicate_ddl_command per consentire l'esecuzione dei comandi DDL nell'origine e nella destinazione in un punto coerente. L'utente che esegue i comandi deve avere lo stesso nome utente sia nell'origine che nella destinazione e deve essere il super utente o il proprietario dell'artefatto di cui viene eseguita la migrazione (ad esempio, la tabella, la sequenza, la vista o il database).

Consulta Migrazione continua per trovare esempi di utilizzo di pglogical.replicate_ddl_command.
Messaggio di errore: ERROR: cannot truncate a table referenced in a foreign key constraint

Un utente ha tentato di troncare una tabella con un vincolo di chiave esterna.

Rimuovi prima il vincolo di chiave esterna, quindi tronca la tabella.
Messaggio di errore: ERROR: connection to other side has died

La connessione di replica è terminata a causa di un valore insufficiente impostato per il parametro wal_sender_timeout. L'errore si verifica in genere durante la fase di replica dopo l'esito positivo del dump iniziale.

Valuta la possibilità di aumentare il valore parametro wal_sender_timeout o di disattivare il meccanismo di timeout impostando il relativo valore su 0 nell'istanza del database di origine.
Messaggio di avviso: migration job test configuration has returned the following warnings: Some table(s) have limited support.

L'origine contiene tabelle con supporto limitato, ad esempio tabelle senza chiavi primarie.

Questo è un messaggio di avviso. Puoi procedere con la migrazione, ma tieni presente che nelle migrazioni standard, le tabelle senza chiavi primarie replicano solo lo snapshot iniziale e le istruzioni INSERT durante la fase Change Data Capture (CDC); le istruzioni UPDATE e DELETE non vengono replicate. Per saperne di più, consulta Configura il database di origine.

Quando esegui la migrazione dei database selezionati e il job di migrazione non è in grado di replicare i dati in uno o più database, nell'elenco dei database viene visualizzato lo stato Non riuscito. Vari errori dei job di migrazione.

Nella colonna Errori, fai clic su Visualizza errori e correggili. Puoi anche rimuovere i database non riusciti dal job di migrazione.

Per ulteriori informazioni sulla rimozione di un database non riuscito da un job di migrazione, consulta Gestisci i job di migrazione.

Cancella i dati aggiuntivi dal cluster di destinazione esistente

Quando esegui la migrazione a un cluster di destinazione esistente, ricevi il seguente messaggio di errore: 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.

Questo problema può verificarsi se il cluster di destinazione contiene dati aggiuntivi. Puoi eseguire la migrazione solo a cluster esistenti vuoti. Consulta Limitazioni note.

Da provare

Cancella i dati in conflitto o aggiuntivi dal cluster di destinazione e avvia nuovamente il job di migrazione seguendo questi passaggi:

  1. Interrompi il job di migrazione.
  2. Connettiti all'istanza principale del cluster AlloyDB per PostgreSQL di destinazione utilizzando psql o AlloyDB Studio.
  3. Rimuovi i dati aggiuntivi dai database del cluster di destinazione. La destinazione può contenere solo dati di configurazione del sistema. I database di destinazione non possono contenere dati utente (ad esempio tabelle o routine definite dall'utente). Esistono diverse istruzioni SQL che puoi eseguire sui tuoi database per trovare dati non di sistema:

    Istruzione SQL di esempio per recuperare i database non di sistema (fai clic per espandere)

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

    Esempio di istruzione SQL per recuperare dati non di sistema nel database postgres (fai clic per espandere)

    Il database postgres è un database di sistema, ma può contenere dati non di sistema. Assicurati di eseguire queste istruzioni sul database postgres. Se utilizzi il client psql per connetterti al cluster di destinazione, puoi passare a un altro database senza reimpostare la connessione utilizzando il comando \connect {database_name_here}.

    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. Elimina tutti i database non di sistema, le tabelle utente e le funzioni definite dall'utente identificati nel passaggio precedente.
  5. Avvia il job di migrazione.

Esegui la pulizia degli slot di replica

Viene visualizzato uno dei seguenti messaggi:

  • 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.

Il problema potrebbe essere

Quando promuovi un cluster di destinazione AlloyDB per PostgreSQL, se l'istanza di origine non è raggiungibile dal cluster AlloyDB per PostgreSQL (ad esempio, l'istanza di origine non è in esecuzione o hai rimosso il cluster AlloyDB per PostgreSQL dalla lista consentita delle istanze di origine), non è possibile eseguire la pulizia delle impostazioni necessarie per la replica durante la promozione di un job di migrazione. Devi eseguire la pulizia degli slot di replica manualmente.

Da provare

Per ogni database, esegui questi comandi come utente con il privilegio superuser:

  1. Recupera i nomi degli slot di replica dal messaggio di errore, quindi esegui il comando seguente per eliminare gli slot uno alla volta:

    SELECT pg_drop_replication_slot('slot_name');

  2. Se i nomi degli slot di replica non sono disponibili nel messaggio di errore, esegui questo comando per eseguire una query sugli slot di replica esistenti:

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

  3. Se non sono presenti repliche AlloyDB per PostgreSQL che utilizzano l'istanza di origine, esegui questo comando per pulire le impostazioni pglogical:

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

  4. Se l'estensione pglogical non è più necessaria, esegui questo comando per disinstallarla:

    DROP EXTENSION IF EXISTS pglogical;

Messaggio di errore: Cannot connect to invalid database

Durante la migrazione a PostgreSQL versione 15, dopo diversi tentativi di riconnessione successivi si verifica uno dei seguenti sintomi:

Il problema potrebbe essere

Questo problema è spesso attribuito al problema di deadlock nell'estensione pglogical. Per maggiori informazioni, consulta l'Issue Tracker di pglogical in GitHub.

Da provare

Esegui di nuovo il job di migrazione con un nuovo cluster di destinazione

Prova a eliminare il cluster di destinazione in cui si è verificato il problema e ricrea il job di migrazione. Segui questi passaggi:

  1. Elimina il job di migrazione non riuscito. Consulta Esamina un job di migrazione.
  2. Elimina il cluster di destinazione in cui hai riscontrato il problema. Consulta Gestione dei cluster AlloyDB.
  3. Ricrea il job di migrazione. Consulta Crea un job di migrazione.
Esegui la migrazione a una versione intermedia

Valuta la possibilità di eseguire la migrazione a una versione precedente di PostgreSQL, ad esempio PostgreSQL 14. Dopo una migrazione riuscita, puoi eseguire l'upgrade all'istanza PostgreSQL 15 desiderata. Consulta Esegui l'upgrade di una versione principale del database nella documentazione di AlloyDB per PostgreSQL.

Elimina i cluster AlloyDB per PostgreSQL orfani in modalità di bootstrap

In rari casi limite, potresti scoprire che il job di migrazione è stato eliminato, mentre il cluster AlloyDB per PostgreSQL associato non lo è ed è ancora in modalità di bootstrap. Puoi eliminare il cluster utilizzando il comando gcloud alloydb clusters delete con l'opzione --force:

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

Tieni presente che l'eliminazione di un cluster di bootstrap mentre è utilizzato da un job di migrazione attivo comporta un comportamento non definito.

Gestisci utenti e ruoli

Esegui la migrazione degli utenti esistenti

Al momento, Database Migration Service non supporta la migrazione automatica di utenti e ruoli esistenti da un'istanza di origine a un cluster AlloyDB per PostgreSQL di destinazione. Puoi gestire questa migrazione creando manualmente gli utenti in AlloyDB per PostgreSQL.

Informazioni sull'utente alloydbexternalsync

Durante una migrazione standard, tutti gli oggetti di database nella replica AlloyDB per PostgreSQL sono di proprietà dell'utente alloydbexternalsync (le migrazioni con avvio rapido utilizzano l'utente postgres). Una volta eseguita la migrazione dei dati e promosso il job di migrazione, puoi modificare la proprietà degli oggetti assegnandola ad altri utenti dell'applicazione completando i seguenti passaggi:

  • Esegui il comando GRANT alloydbexternalsync TO USER;.
  • In ogni database, esegui il comando REASSIGN OWNED BY alloydbexternalsync TO USER;.
  • Per rimuovere l'utente alloydbexternalsync, esegui il comando DROP ROLE alloydbexternalsync;.