Diagnostiquer les problèmes liés aux migrations homogènes vers Cloud SQL pour PostgreSQL

Le processus de tâche de migration peut entraîner des erreurs pendant l'exécution.

  • Certaines erreurs, telles qu'un mot de passe incorrect dans la base de données source, peuvent être récupérées, ce qui signifie qu'elles peuvent être corrigées et que la tâche de migration reprend automatiquement.
  • Certaines ne peuvent pas être récupérées, comme les erreurs de réplication des données, ce qui signifie que le job de migration doit être redémarré depuis le début.

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

Pour résoudre une erreur, accédez à la tâche de migration ayant échoué pour afficher l'erreur et suivez la procédure décrite dans le message d'erreur.

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

Le tableau suivant contient quelques exemples de problèmes et la manière de les résoudre:

Pour ce problème... Le problème peut être... Essayez ce qui suit...
Lorsque vous effectuez une migration vers une instance de destination existante, le message d'erreur suivant s'affiche : The destination instance contains existing data or user defined entities (for example databases, tables, or functions). You can only migrate to empty instances. Clear your destination instance and retry the migration job. Votre instance Cloud SQL de destination contient des données supplémentaires. Vous ne pouvez migrer que vers des instances existantes vides. Consultez la section Limites connues. Promuvez votre instance de destination pour en faire une instance en lecture/écriture, supprimez les données supplémentaires, puis réessayez la tâche de migration. Consultez la section Supprimer les données supplémentaires de votre instance de destination existante.
Échec de la connexion à l'instance de base de données source. Un problème de connectivité s'est produit entre l'instance de base de données source et l'instance de destination. Suivez la procédure décrite dans Déboguer la connectivité.
Échec de l'exécution de la tâche de migration en raison de versions de base de données source et de destination incompatibles. La combinaison des versions de base de données source et de destination n'est pas prise en charge. 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 d'une version majeure à celle de la base de données source. Créez ensuite une tâche de migration.
Les langages de définition de données (LDD) ou de manipulation de données (LMD) sont bloqués sur la source. Les LDD qui nécessitent le verrouillage ACCESS EXCLUSIVE et qui s'exécutent pendant la phase de vidage complet sont bloqués.

Lors du processus de synchronisation initial (vidage 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 DDL ou les programmes attendront que la synchronisation initiale soit terminée.

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 sera pas exécutée et les commandes DDL et DML ultérieures seront bloquées jusqu'à la fin de la synchronisation initiale.
Message d'erreur: No pglogical extension installed on databases (X) pglogical n'est pas installé dans une ou plusieurs bases de données sources. Suivez ces consignes pour installer pglogical sur les bases de données de l'instance source.
Lors de la migration vers la version 15 de PostgreSQL, 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 d'interblocage dans l'extension pglogical. Pour en savoir plus, consultez l' outil Issue Tracker 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 la section Message d'erreur: Cannot connect to invalid database.
Message d'erreur: Replication user 'x' doesn't have sufficient privileges. L'utilisateur qui utilise Database Migration Service ne dispose pas des droits nécessaires pour effectuer l'opération désignée. Suivez ces consignes pour vous assurer que cet utilisateur dispose des droits nécessaires.
Message d'erreur: Unable to connect to source database server. Database Migration Service ne parvient pas à établir de connexion avec le 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'affichent lorsque vous définissez vos paramètres pour la tâche 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.
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. Pour définir correctement ce paramètre, suivez ces consignes.
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. Pour définir correctement ce paramètre, suivez ces consignes.
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. Pour définir correctement ce paramètre, suivez ces consignes.

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'une tâche de migration.

Pour chaque base de données, exécutez des 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 peut contenir que le certificat racine. Toutefois, le certificat source nécessite à la fois le certificat racine et les éventuels certificats intermédiaires.

Par exemple, pour Amazon Relational Database Service, l'utilisation du certificat rds-ca-2019-root.pem peut entraîner ce problème.

Créez un certificat d'autorité de certification source combiné qui contient à la fois le certificat racine et tous les certificats intermédiaires requis.

Pour le cas d'utilisation Amazon Relational Database Service, au lieu du certificat rds-ca-2019-root.pem, utilisez le certificat rds-combined-ca-bundle.pem.

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 correctement installé sur l'instance source. Pour savoir comment installer correctement ce package, consultez Installer le package pglogical sur l'instance source.

Message d'erreur: Cannot assign TransactionIds during recovery.

La source configurée est en mode récupération. Configurez une source qui n'est pas en mode de récupération.
Le dump complet est lent. L'importation de grandes quantités de données à partir de la base de données source peut être lente dans la destination Cloud SQL.
  • Lorsque vous créez la destination, définissez la taille du disque de données de manière à ce qu'elle soit proche de la taille finale. La phase de vidage complet utilise une charge de travail intensive en écriture d'E/S, et une taille de disque plus importante améliore les performances d'E/S. Pour en savoir plus, consultez la page Performances des options de stockage de blocs.
  • Choisissez un niveau supérieur pour la destination Cloud SQL afin d'obtenir la bande passante réseau et disque maximale disponible.
  • Ajustez l'indicateur max_wal_size de la destination Cloud SQL. En règle générale, 32 Go ou 64 Go est une bonne valeur à définir pour cet indicateur. Vous n'avez pas besoin de redémarrer le serveur pour mettre à jour cet indicateur.
Message d'erreur: subscriber {subscriber_name} initialization failed during nonrecoverable step (d), please try the setup again

La tâche de migration a échoué lors de la phase de vidage complet et n'est pas récupérable. 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 pris fin en raison d'une valeur insuffisante définie pour le paramètre wal_sender_timeout.

Pour identifier l'origine 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 dupliquée Cloud SQL. Une liste des journaux les plus récents pour le réplica se présente.
  3. Dans la liste des 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 à l'origine 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 la tâche 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 réplicatif.

Seules les modifications du langage de manipulation de données (LMD) sont automatiquement mises à jour lors des migrations continues. Il incombe à l'utilisateur de gérer les modifications du langage de définition de données (LDD) pour que les bases de données source et de destination restent compatibles. Vous pouvez procéder de deux manières différentes:

  • Arrêtez les opérations d'écriture sur la base de données source, puis exécutez les commandes LDD sur la source et la destination. Avant d'exécuter les commandes LDD sur la destination, accordez le rôle cloudsqlexternalsync à l'utilisateur Cloud SQL qui applique les modifications apportées au LDD.
  • Utilisez pglogical.replicate_ddl_command pour autoriser l'exécution des commandes DDL sur la source et la destination en un point cohérent. L'utilisateur qui exécute les commandes doit avoir le même nom d'utilisateur à la source et à la destination. Il doit également être le super-utilisateur ou le propriétaire de l'artefact migré (par exemple, la table, la séquence, la vue ou la base de données).

    • Consultez la section 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

L'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 en raison d'une valeur insuffisante définie pour wal_sender_timeout parameter. L'erreur se produit généralement pendant la phase de réplication après le succès 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 contient 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 continuer la migration, mais notez que les entités non compatibles (par exemple, les tables sans clé primaire) ne sont pas migrées. Pour en savoir plus, consultez Configurer vos bases de données sources.

Supprimer les données supplémentaires de votre instance de destination existante

Lorsque vous effectuez une migration vers une instance de destination existante, le message d'erreur suivant s'affiche : The destination instance contains existing data or user defined entities (for example databases, tables, or functions). You can only migrate to empty instances. Clear your destination instance and retry the migration job.

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

Solutions possibles

Supprimez les données supplémentaires de votre instance de destination et redémarrez la tâche de migration en procédant comme suit:

  1. Arrêtez la tâche de migration.
  2. À ce stade, votre instance Cloud SQL de destination est en mode "lecture seule". Promouvoir l'instance de destination pour obtenir un accès en écriture.
  3. Connectez-vous à l'instance Cloud SQL de destination.
  4. Supprimez les données supplémentaires des bases de données de vos instances 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). Vous pouvez exécuter différentes instructions SQL sur vos bases de données pour rechercher des données non système, par exemple:

    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 ('cloudsqladmin', '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. Assurez-vous d'exécuter ces instructions sur la base de données postgres. Si vous utilisez le client psql pour vous connecter à l'instance 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 != 'plpgsql';
  5. Démarrez la tâche 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

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

Solutions possibles

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

  1. Obtenez 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 '%cloudsql%' and active = 'f';

  3. Si aucun réplica Cloud SQL n'utilise 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 'cloudsql';

  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 la version 15 de PostgreSQL, 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

Exécuter à nouveau la tâche de migration avec une nouvelle instance de destination

Essayez de supprimer la base de données de destination où le problème s'est produit, puis de recréer votre tâche de migration. Procédez comme suit :

  1. Supprimez l'instance de destination où vous avez rencontré les problèmes. Consultez la section Supprimer des instances dans la documentation Cloud SQL pour PostgreSQL.
  2. Supprimez la tâche de migration ayant échoué. Consultez Examiner une tâche de migration.
  3. Recréez votre tâche de migration. Consultez Créer une tâche 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 essayer de passer à l'instance PostgreSQL 15 souhaitée. Consultez la section Mettre à niveau la version majeure de la base de données en migrant les données dans la documentation Cloud SQL pour PostgreSQL.

Gérer les utilisateurs et les rôles

Migrer les utilisateurs existants

Actuellement, Database Migration Service ne permet pas de migrer les utilisateurs existants d'une instance source vers une instance Cloud SQL de destination. Vous pouvez gérer cette migration en créant manuellement les utilisateurs dans Cloud SQL.

À propos de l'utilisateur cloudsqlexternalsync

Lors de la migration, tous les objets du réplica Cloud SQL appartiennent à l'utilisateur cloudsqlexternalsync. Une fois les données migrées, vous pouvez modifier la propriété des objets pour d'autres utilisateurs en procédant comme suit:

  • Exécutez la commande GRANT cloudsqlexternalsync to {USER}.
  • Sur chaque base de données, exécutez la commande reassign owned by cloudsqlexternalsync to {USER};.
  • Pour supprimer l'utilisateur cloudsqlexternalsync, exécutez la commande drop role cloudsqlexternalsync.

Importer des données dans une nouvelle instance Cloud SQL

Si vous exportez d'abord des données à partir d'une instance Cloud SQL que Database Migration Service a migrée vers Cloud Storage, puis que vous importez les données depuis Cloud Storage vers une instance Cloud SQL autonome, l'importation peut échouer, car l'utilisateur cloudsqlexternalsync n'existe pas sur l'instance de destination.

Pour atténuer le problème, créez l'utilisateur cloudsqlexternalsync sur l'instance de destination ou supprimez-le de l'instance migrée.