Diagnostiquer les problèmes lors des migrations de PostgreSQL vers AlloyDB pour PostgreSQL

Le processus de job de migration peut générer des erreurs lors de l'exécution.

  • Certaines erreurs, telles qu'un mot de passe incorrect sur la base de données source, sont récupérables, ce qui signifie qu'elles peuvent être corrigées et que le job de migration reprend automatiquement.
  • Certaines sont irrécupérables, comme la corruption des données ou les incompatibilités de schéma, ce qui signifie que le job de migration doit être redémarré depuis le début.

Lorsqu'une erreur se produit, l'état du job de migration passe à Failed, et le sous-état reflète le dernier état avant l'échec.

Pour résoudre une erreur, accédez au job de migration qui a échoué pour afficher l'erreur, puis suivez les étapes décrites dans le message d'erreur.

Pour en savoir plus sur l'erreur, accédez à Cloud Monitoring à l'aide du lien figurant sur le job de migration. Les journaux sont filtrés en fonction du job de migration spécifique.

Le tableau suivant répertorie les problèmes courants et leurs solutions :

Pour ce problème... Le problème peut être... Essayez ce qui suit...
Lorsque vous migrez vers un cluster de destination existant, vous recevez le message d'erreur suivant : 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. Votre cluster AlloyDB pour PostgreSQL de destination contient des données utilisateur supplémentaires. Vous ne pouvez migrer que vers des clusters existants vides. Consultez Limites connues. Effacez les données supplémentaires ou en conflit de votre cluster de destination, puis relancez le job de migration. Consultez Effacer les données supplémentaires de votre cluster de destination existant.
Échec de la connexion à l'instance de base de données source. Un problème de connectivité est survenu entre l'instance de base de données source et le cluster AlloyDB pour PostgreSQL de destination. Suivez la procédure décrite dans Déboguer la connectivité.
Échec de l'exécution du job de migration en raison de l'incompatibilité des versions des bases de données source et de destination. La combinaison des versions de base de données source et de destination n'est pas compatible. Plus précisément, la version de la base de données source fournie n'est pas compatible avec la version de la base de données de destination. Assurez-vous que la version de la base de données de destination est identique ou supérieure à la version majeure de la base de données source. Ensuite, créez un job de migration.
Les langages de définition de données (LDD) ou les langages de manipulation de données (LMD) sont bloqués sur la source. Les LDD qui nécessitent le verrou ACCESS EXCLUSIVE et qui sont en cours d'exécution pendant la phase de vidage complet sont bloqués.

Pendant le processus de synchronisation initial (dump complet), les LDD ou les programmes nécessitant des verrous ACCESS EXCLUSIVE tels que ALTER TABLE ou DROP TABLE doivent être évités sur les tables. Sinon, les LDD ou les programmes attendent la fin de la synchronisation initiale.

Par exemple, si une table est toujours en cours de synchronisation initiale et qu'une commande ALTER TABLE est exécutée sur la même table, la commande ne s'exécute pas, et les commandes LDD et LMD suivantes sont bloquées jusqu'à la fin de la synchronisation initiale.
Message d'erreur : No pglogical extension installed on databases (X) pglogical n'est pas installé sur une ou plusieurs bases de données sources. Suivez ces instructions pour installer pglogical sur les bases de données de l'instance source.
Lors de la migration vers PostgreSQL version 15, après plusieurs tentatives de connexion ultérieures, l'un des symptômes suivants se produit : Ce problème est souvent attribué au problème de blocage dans l'extension pglogical. Pour en savoir plus, consultez l'outil de suivi des problèmes pglogical sur GitHub. Réessayez le job de migration ou migrez d'abord vers une version intermédiaire de PostgreSQL. Pour en savoir plus, consultez Message d'erreur : Cannot connect to invalid database.
Message d'erreur : Replication user 'x' doesn't have sufficient privileges. L'utilisateur de Database Migration Service ne dispose pas des droits requis pour effectuer l'opération désignée. Suivez ces consignes pour vous assurer que cet utilisateur dispose des droits requis.
Message d'erreur : Unable to connect to source database server. Database Migration Service ne parvient pas à établir de connexion au serveur de base de données source. Assurez-vous que les instances de base de données source et de destination peuvent communiquer entre elles et que vous avez rempli toutes les conditions préalables requises qui s'affichaient lorsque vous avez défini les paramètres du job de migration.
Message d'erreur : The source database 'wal_level' configuration must be equal to 'logical'. La valeur wal_level de la base de données source est définie sur une valeur autre que logical. Définissez wal_level sur logical. Consultez Configuration du niveau WAL.
Message d'erreur : The source database 'max_replication_slots' configuration is not sufficient. Le paramètre max_replication_slots n'a pas été configuré correctement. Suivez ces consignes pour définir correctement ce paramètre.
Message d'erreur : The source database 'max_wal_senders' configuration is not sufficient. Le paramètre max_wal_senders n'a pas été configuré correctement. Suivez ces consignes pour définir correctement ce paramètre.
Message d'erreur : The source database 'max_worker_processes' configuration is not sufficient. Le paramètre max_worker_processes n'a pas été configuré correctement. Suivez ces consignes pour définir correctement ce paramètre.

Message d'erreur : Cleanup may have failed on source due to error: generic::unknown: failed to connect to on-premises database.

OU

Message d'erreur : Error promoting EM replica: finished drop replication with errors.

Les paramètres nécessaires à la réplication ne peuvent pas être nettoyés lors de la promotion d'un job de migration.

Pour chaque base de données, exécutez les commandes en tant qu'utilisateur disposant du droit superuser.

Pour en savoir plus sur les commandes à exécuter, consultez Nettoyer les emplacements de réplication.

Message d'erreur : x509 certificate signed by unknown authority.

Le certificat CA source fourni à Database Migration Service ne contient peut-être que le certificat racine. Toutefois, le certificat source nécessite à la fois le certificat racine et tous les certificats intermédiaires.

Par exemple, pour Amazon RDS, l'utilisation d'un certificat racine autonome au lieu d'un bundle de certificats peut entraîner ce problème.

Créez un certificat CA source combiné contenant à la fois le certificat racine et tous les certificats intermédiaires requis.

Pour les sources Amazon RDS, utilisez un bundle de certificats qui inclut à la fois les certificats intermédiaires et racine. Pour en savoir plus, consultez Télécharger des bundles de certificats dans la documentation Amazon RDS.

Message d'erreur : ERROR: Out of shared memory HINT: You might need to increase max_locks_per_transaction.

La valeur définie pour le paramètre max_locks_per_transaction n'est pas suffisante. Définissez la valeur de ce paramètre sur au moins {max_number_of_tables_per_database}/(max_connections + max_prepared_transactions).

Message d'erreur : ERROR: no data left in message.

Le package pglogical n'est pas installé correctement sur l'instance source. Pour savoir comment installer correctement ce package, consultez Configurer votre base de données source.

Message d'erreur : Cannot assign TransactionIds during recovery.

La source configurée est en mode de récupération. Configurez une source qui n'est pas en mode de récupération.
Le vidage complet est lent. L'instance principale du cluster de destination AlloyDB pour PostgreSQL peut être lente à importer des données volumineuses à partir de la base de données source.
  • Choisissez un niveau de machine plus élevé pour l'instance principale AlloyDB pour PostgreSQL de destination afin d'obtenir la bande passante réseau et la capacité de processeur maximales disponibles.
  • Réglez l'option max_wal_size de la destination. En général, 32 Go ou 64 Go est une bonne valeur pour cette option. La mise à jour de cette option ne nécessite pas de redémarrer le serveur de base de données.
Message d'erreur : subscriber {subscriber_name} initialization failed during nonrecoverable step (d), please try the setup again

Le job de migration a échoué pendant la phase de vidage complet et ne peut pas être récupéré. L'instance de base de données source a été redémarrée ou était en mode de récupération, ou les connexions de réplication ont été interrompues en raison d'une valeur insuffisante définie pour le paramètre wal_sender_timeout.

Pour trouver la cause principale du problème :

  1. Accédez à la page Explorateur de journaux dans la console Google Cloud .
  2. Dans la liste des ressources, sélectionnez votre instance AlloyDB pour PostgreSQL. La liste des journaux les plus récents de l'instance s'affiche.
  3. Dans les noms de fichiers journaux, sélectionnez postgres.log.
  4. Définissez le niveau de gravité du journal sur tous les niveaux supérieurs à Warning. Les premiers journaux d'erreurs peuvent être la cause principale de l'échec.
  • Assurez-vous que Database Migration Service peut toujours se connecter à l'instance de base de données source pendant la phase de vidage complet.
  • Vérifiez si la valeur du paramètre wal_sender_timeout est définie sur un nombre plus élevé (par exemple, 0) sur l'instance de base de données source.
  • Redémarrez le job de migration, puis réessayez.
Message d'erreur : ERROR: unknown column name {column_name}

Une colonne a été ajoutée à une table répliquée sur le nœud principal, mais pas sur le nœud de l'instance répliquée.

Seules les modifications apportées au langage de manipulation de données (LMD) sont mises à jour automatiquement lors des migrations continues. Vous devez gérer les modifications du langage de définition de données (LDD) afin que les bases de données source et de destination restent compatibles. Pour ce faire, vous avez deux possibilités :

  • Arrêtez les écritures dans la base de données source et exécutez les commandes LDD sur la source et la destination. Avant d'exécuter les commandes LDD sur la destination, attribuez le rôle alloydbexternalsync à l'utilisateur AlloyDB pour PostgreSQL qui applique les modifications LDD.
  • Utilisez pglogical.replicate_ddl_command pour permettre l'exécution des commandes LDD sur la source et la destination à un point cohérent. L'utilisateur qui exécute les commandes doit avoir le même nom d'utilisateur sur la source et la destination, et doit être le super-utilisateur ou le propriétaire de l'artefact en cours de migration (par exemple, la table, la séquence, la vue ou la base de données).

Consultez Migration continue pour obtenir des exemples d'utilisation de pglogical.replicate_ddl_command.
Message d'erreur : ERROR: cannot truncate a table referenced in a foreign key constraint

Un utilisateur a tenté de tronquer une table comportant une contrainte de clé étrangère.

Supprimez d'abord la contrainte de clé étrangère, puis tronquez la table.
Message d'erreur : ERROR: connection to other side has died

La connexion de réplication a pris fin, car la valeur définie pour le paramètre wal_sender_timeout était insuffisante. L'erreur se produit généralement pendant la phase de réplication, après la réussite du vidage initial.

Envisagez d'augmenter la valeur du paramètre wal_sender_timeout ou de désactiver le mécanisme de délai avant expiration en définissant sa valeur sur 0 sur l'instance de base de données source.
Message d'avertissement : migration job test configuration has returned the following warnings: Some table(s) have limited support.

La source comporte des tables dont la compatibilité est limitée, par exemple des tables sans clé primaire.

Il s'agit d'un message d'avertissement. Vous pouvez poursuivre la migration, mais notez que dans les migrations standards, les tables sans clé primaire ne répliquent que l'instantané initial et les instructions INSERT pendant la phase de capture des données modifiées (CDC). Les instructions UPDATE et DELETE ne sont pas répliquées. Pour en savoir plus, consultez Configurer votre base de données source.

Lorsque vous migrez des bases de données sélectionnées et que le job de migration ne parvient pas à répliquer les données vers une ou plusieurs bases de données, l'état Échec s'affiche dans la liste des bases de données. Diverses erreurs de job de migration.

Dans la colonne Erreurs, cliquez sur Afficher les erreurs et corrigez-les. Vous pouvez également supprimer les bases de données en échec du job de migration.

Pour en savoir plus sur la suppression d'une base de données défaillante d'un job de migration, consultez Gérer les jobs de migration.

Effacer les données supplémentaires de votre cluster de destination existant

Lorsque vous effectuez une migration vers un cluster de destination existant, vous recevez le message d'erreur suivant : 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.

Ce problème peut se produire si votre cluster de destination contient des données supplémentaires. Vous ne pouvez migrer que vers des clusters existants vides. Consultez la section Limites connues.

Solutions possibles

Effacez les données conflictuelles ou supplémentaires de votre cluster de destination, puis redémarrez le job de migration en procédant comme suit :

  1. Arrêtez le job de migration.
  2. Connectez-vous à l'instance principale de votre cluster AlloyDB pour PostgreSQL de destination à l'aide de psql ou d'AlloyDB Studio.
  3. Supprimez les données supplémentaires des bases de données de votre cluster de destination. Votre destination ne peut contenir que des données de configuration système. Les bases de données de destination ne peuvent pas contenir de données utilisateur (telles que des tables ou des routines définies par l'utilisateur). Vous pouvez exécuter différentes instructions SQL sur vos bases de données pour trouver des données non système :

    Exemple d'instruction SQL pour récupérer des bases de données non système (cliquez pour développer)

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

    Exemple d'instruction SQL pour récupérer des données non système dans la base de données postgres (cliquez pour développer)

    La base de données postgres est une base de données système, mais elle peut contenir des données non système. Veillez à exécuter ces instructions sur la base de données postgres. Si vous utilisez le client psql pour vous connecter au cluster de destination, vous pouvez passer à une autre base de données sans réinitialiser votre connexion à l'aide de la commande \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. Supprimez les bases de données non système, les tables utilisateur et les fonctions définies par l'utilisateur identifiées à l'étape précédente.
  5. Démarrez le job de migration.

Nettoyer les emplacements de réplication

L'un des messages suivants s'affiche :

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

Cause possible

Lors de la promotion d'un cluster de destination AlloyDB pour PostgreSQL, si l'instance source n'est pas accessible depuis le cluster AlloyDB pour PostgreSQL (par exemple, si l'instance source n'est pas en cours d'exécution ou si vous avez supprimé le cluster AlloyDB pour PostgreSQL de la liste d'autorisation des instances sources), les paramètres nécessaires à la réplication ne peuvent pas être nettoyés pendant la promotion d'un job de migration. Vous devez nettoyer les emplacements de réplication manuellement.

Solutions possibles

Pour chaque base de données, exécutez les commandes suivantes en tant qu'utilisateur disposant du droit superuser :

  1. Récupérez les noms des emplacements de réplication à partir du message d'erreur, puis exécutez la commande suivante pour supprimer les emplacements un par un :

    SELECT pg_drop_replication_slot('slot_name');

  2. Si les noms des emplacements de réplication ne sont pas disponibles dans le message d'erreur, exécutez la commande suivante pour interroger les emplacements de réplication existants :

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

  3. S'il n'existe aucune instance répliquée AlloyDB pour PostgreSQL utilisant l'instance source, exécutez la commande suivante pour nettoyer les paramètres pglogical :

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

  4. Si l'extension pglogical n'est plus nécessaire, exécutez la commande suivante pour la désinstaller :

    DROP EXTENSION IF EXISTS pglogical;

Message d'erreur : Cannot connect to invalid database

Lors de la migration vers PostgreSQL 15, après plusieurs tentatives de connexion ultérieures, l'un des symptômes suivants se produit :

Cause possible

Ce problème est souvent attribué au problème de blocage dans l'extension pglogical. Pour en savoir plus, consultez l'outil de suivi des problèmes pglogical sur GitHub.

Solutions possibles

Réexécutez le job de migration avec un nouveau cluster de destination

Essayez de supprimer le cluster de destination où vous avez rencontré le problème, puis recréez votre job de migration. Procédez comme suit :

  1. Supprimez le job de migration ayant échoué. Consultez Examiner un job de migration.
  2. Supprimez le cluster de destination où vous avez rencontré le problème. Consultez Gestion des clusters AlloyDB.
  3. Recréez votre job de migration. Consultez Créer un job de migration.
Migrer vers une version intermédiaire

Envisagez de migrer vers une version antérieure de PostgreSQL, telle que PostgreSQL 14. Une fois la migration terminée, vous pouvez passer à l'instance PostgreSQL 15 souhaitée. Consultez Mettre à niveau une version majeure de base de données dans la documentation AlloyDB pour PostgreSQL.

Supprimer les clusters AlloyDB pour PostgreSQL orphelins en mode d'amorçage

Dans de rares cas, il est possible que votre job de migration ait été supprimé, mais pas le cluster AlloyDB pour PostgreSQL associé, qui est toujours en mode d'amorçage. Vous pouvez supprimer le cluster à l'aide de la commande gcloud alloydb clusters delete avec l'option --force :

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

Notez que la suppression d'un cluster d'amorçage alors qu'il est utilisé par un job de migration actif entraîne un comportement non défini.

Gérer les utilisateurs et les rôles

Migrer des utilisateurs existants

Actuellement, Database Migration Service ne permet pas de migrer automatiquement les utilisateurs et les rôles existants d'une instance source vers un cluster AlloyDB pour PostgreSQL de destination. Vous pouvez gérer cette migration en créant manuellement les utilisateurs dans AlloyDB pour PostgreSQL.

À propos de l'utilisateur alloydbexternalsync

Lors d'une migration standard, tous les objets de base de données de l'instance répliquée AlloyDB pour PostgreSQL appartiennent à l'utilisateur alloydbexternalsync (les migrations de démarrage rapide utilisent l'utilisateur postgres). Une fois les données migrées et le job de migration promu, vous pouvez transférer la propriété des objets à d'autres utilisateurs de l'application en procédant comme suit :

  • Exécutez la commande GRANT alloydbexternalsync TO USER;.
  • Sur chaque base de données, exécutez la commande REASSIGN OWNED BY alloydbexternalsync TO USER;.
  • Pour supprimer l'utilisateur alloydbexternalsync, exécutez la commande DROP ROLE alloydbexternalsync;.