Résoudre les problèmes de migration

Ce document vous aide à résoudre les problèmes courants lors de la migration de votre entrepôt de données (comme Teradata, Amazon Redshift, Oracle ou Apache Hive) vers BigQuery. Il aborde notamment les problèmes liés à l'évaluation de la migration, à la traduction SQL interactive et par lot, et à la génération de métadonnées à l'aide de l'outil d'extraction en ligne de commande dwh-migration-dumper.

Pour examiner les détails d'exécution des jobs, les codes d'erreur et l'utilisation des emplacements pour les requêtes et les jobs migrés, vous pouvez également interroger la vue INFORMATION_SCHEMA.JOBS.

Évaluation de la migration

Les sections suivantes décrivent les problèmes courants et les techniques de dépannage permettant de migrer votre entrepôt de données vers BigQuery.

Erreurs de l'outil dwh-migration-dumper

Pour résoudre les erreurs et les avertissements dans la sortie du terminal de l'outil dwh-migration-dumper survenues lors de l'extraction des métadonnées ou des journaux de requête, consultez la page Résoudre les problèmes liés aux métadonnées.

Erreurs de migration Hive

Les sections suivantes décrivent les problèmes courants que vous pouvez rencontrer lorsque vous envisagez de migrer votre entrepôt de données de Hive vers BigQuery.

Le hook de journalisation d'extraction des journaux de requêtes hadoop-migration-assessment écrit les messages de journal de débogage dans vos journaux hive-server2. Si vous rencontrez des problèmes, consultez les journaux de débogage du hook de journalisation qui contient la chaîne MigrationAssessmentLoggingHook.

Gérer l'erreur ClassNotFoundException.

Cette erreur peut être due à une localisation incorrecte du fichier JAR du hook de journalisation. Assurez-vous d'avoir ajouté le fichier JAR dans le dossier auxlib sur le cluster Hive. Vous pouvez également spécifier le chemin d'accès complet au fichier JAR dans la propriété hive.aux.jars.path (par exemple, file://AUXLIB_PATH/HiveMigrationAssessmentQueryLogsHooks_deploy.jar).

Les sous-dossiers n'apparaissent pas dans le dossier configuré

Ce problème peut être dû à une mauvaise configuration ou à des problèmes lors de l'initialisation du hook de journalisation.

Recherchez, parmi vos journaux de débogage hive-server2, les messages suivants du hook de journalisation :

Unable to initialize logger, logging disabled

Log dir configuration key 'dwhassessment.hook.base-directory' is not set,
logging disabled.

Error while trying to set permission

Examinez les détails du problème et vérifiez si vous devez corriger certains points.

Les fichiers n'apparaissent pas dans le dossier

Ce problème peut être dû à des problèmes rencontrés lors du traitement d'un événement ou lors d'une opération d'écriture dans un fichier.

Recherchez, parmi vos journaux de débogage hive-server2, les messages suivants du hook de journalisation :

Failed to close writer for file

Got exception while processing event

Error writing record for query

Examinez les détails du problème et vérifiez si vous devez corriger certains points.

Il manque certains événements de requête

Ce problème peut être causé par le débordement de la file d'attente des threads du hook de journalisation.

Recherchez, parmi vos journaux de débogage hive-server2, le message suivant du hook de journalisation :

Writer queue is full. Ignoring event

Si vous trouvez de tels messages, envisagez d'augmenter le paramètre dwhassessment.hook.queue.capacity.

Traduction SQL interactive

Les sections suivantes décrivent les erreurs courantes rencontrées lors de l'utilisation du traducteur SQL interactif.

Problèmes de traduction RelationNotFound ou AttributeNotFound

Après avoir traduit une requête à l'aide du traducteur SQL interactif, vous pouvez rencontrer un échec de traduction avec l'erreur RelationNotFound ou AttributeNotFound.

Pour trouver les traductions ayant échoué, accédez à la page Détails de la traduction dans BigQuery de la console Google Cloud , puis ouvrez l'onglet Messages du journal.

Pour garantir une traduction plus précise, vous pouvez saisir les instructions LDD (langage de définition de données) pour toutes les tables utilisées dans une requête avant la requête elle-même. Par exemple, si vous souhaitez traduire la requête Amazon Redshift select table1.field1, table2.field1 from table1, table2 where table1.id = table2.id;, saisissez les instructions SQL suivantes dans le traducteur SQL interactif :

create table schema1.table1 (id int, field1 int, field2 varchar(16));
create table schema1.table2 (id int, field1 varchar(30), field2 date);

select table1.field1, table2.field1
from table1, table2
where table1.id = table2.id;

Résoudre les problèmes de traduction avec Gemini

Pour corriger les tâches de traduction ayant échoué avec les erreurs RelationNotFound ou AttributeNotFound, vous pouvez également utiliser Gemini pour résoudre ces problèmes :

  1. Dans BigQuery de la console Google Cloud , accédez à la page Détails de la traduction, puis ouvrez l'onglet Messages du journal.
  2. Cliquez sur la requête qui comporte le message RelationNotFound ou AttributeNotFound dans la colonne Catégorie.
  3. Cliquez sur Correction suggérée.
  4. Cliquez sur Appliquer.
  5. Pour retraduire la requête, cliquez sur Traduire.

Traduction SQL par lot

Les sections suivantes décrivent les erreurs courantes rencontrées lors de l'utilisation du traducteur SQL par lot.

Problèmes de traduction RelationNotFound ou AttributeNotFound

Après avoir traduit une requête à l'aide du traducteur SQL par lot, il est possible que la traduction échoue et que l'erreur RelationNotFound ou AttributeNotFound s'affiche.

Pour trouver les traductions ayant échoué, accédez à la page Détails de la traduction dans BigQuery de la console Google Cloud , puis ouvrez l'onglet Messages du journal.

La traduction fonctionne mieux avec des LDD de métadonnées. Lorsque les définitions d'objets SQL sont introuvables, le moteur de traduction génère des erreurs RelationNotFound ou AttributeNotFound. Nous vous recommandons d'utiliser l'extracteur de métadonnées pour générer des packages de métadonnées afin de vous assurer que toutes les définitions d'objets sont présentes. L'ajout de métadonnées est la première étape recommandée pour résoudre la plupart des erreurs de traduction, car cela permet souvent de corriger de nombreuses autres erreurs causées indirectement par un manque de métadonnées.

Pour en savoir plus, consultez Générer des métadonnées pour la traduction et l'évaluation.

Résoudre les problèmes de traduction avec Gemini

Pour corriger les tâches de traduction ayant échoué avec les erreurs RelationNotFound ou AttributeNotFound, vous pouvez également utiliser Gemini pour résoudre ces problèmes :

  1. Accédez à la page Détails de la traduction et ouvrez l'onglet Messages du journal.
  2. Cliquez sur la requête qui comporte le message RelationNotFound ou AttributeNotFound dans la colonne Catégorie.

  3. Pour accéder au fichier et à la ligne contenant l'erreur dans l'onglet "Code", cliquez sur

    message d'erreur.

  4. Dans la colonne Action, cliquez sur Correction suggérée.

  5. Sélectionnez l'une des options suivantes : Appliquer ou Appliquer et relancer.

    • Pour copier le fichier de schéma généré du répertoire de sortie vers le répertoire d'entrée, cliquez sur Appliquer.
    • Pour copier le fichier de schéma généré du répertoire de sortie vers le répertoire d'entrée et ouvrir une fenêtre de réexécution, cliquez sur Appliquer et réexécuter.

Générer des métadonnées pour la traduction et l'évaluation

Les sections suivantes décrivent certains problèmes courants et des techniques de dépannage pour l'outil dwh-migration-dumper.

Erreur de mémoire insuffisante

L'erreur java.lang.OutOfMemoryError dans la sortie du terminal de l'outil dwh-migration-dumper est souvent liée à une mémoire insuffisante pour traiter les données récupérées. Pour résoudre ce problème, augmentez la mémoire disponible ou réduisez le nombre de threads de traitement.

Vous pouvez augmenter la mémoire maximale en exportant la variable d'environnement JAVA_OPTS :

Linux

export JAVA_OPTS="-Xmx4G"

Windows 

set JAVA_OPTS="-Xmx4G"

Vous pouvez réduire le nombre de threads de traitement (32 par défaut) en incluant la valeur de l'option --thread-pool-size. Cette option n'est compatible qu'avec les connecteurs hiveql et redshift* :

dwh-migration-dumper --thread-pool-size=1

Gérer une erreur WARN...Task failed

Il est possible que l'erreur WARN [main] o.c.a.d.MetadataDumper [MetadataDumper.java:107] Task failed: … s'affiche dans la sortie du terminal de l'outil dwh-migration-dumper. L'outil d'extraction envoie plusieurs requêtes au système source, et la sortie de chaque requête est écrite dans son propre fichier. L'affichage de ce problème indique que l'une de ces requêtes a échoué. Cependant, l'échec d'une requête n'empêche pas l'exécution des autres requêtes. Si vous voyez plusieurs erreurs WARN, consultez les détails du problème et vérifiez si vous devez corriger certains éléments pour que la requête s'exécute correctement. Par exemple, si l'utilisateur de base de données que vous avez spécifié lors de l'exécution de l'outil d'extraction ne dispose pas des autorisations nécessaires pour lire toutes les métadonnées, réessayez avec un utilisateur disposant des autorisations appropriées.

Fichier ZIP corrompu

Pour valider le fichier ZIP de l'outil dwh-migration-dumper, téléchargez le fichier SHA256SUMS.txt et exécutez la commande suivante :

Bash 

sha256sum --check SHA256SUMS.txt

Le résultat OK confirme la réussite de la vérification de la somme de contrôle. Tout autre message indique une erreur de validation :

  • FAILED: computed checksum did NOT match : le fichier ZIP est corrompu et doit être téléchargé à nouveau.
  • FAILED: listed file could not be read : la version du fichier ZIP est introuvable. Téléchargez les fichiers de somme de contrôle et ZIP à partir de la même version et placez-les dans le même répertoire.

Windows PowerShell 

(Get-FileHash RELEASE_ZIP_FILENAME).Hash -eq ((Get-Content SHA256SUMS.txt) -Split " ")[0]

Remplacez RELEASE_ZIP_FILENAME par le nom du fichier ZIP téléchargé correspondant à la version de l'outil d'extraction en ligne de commande dwh-migration-dumper (par exemple, dwh-migration-tools-v1.0.52.zip).

Le résultat True confirme la réussite de la vérification de la somme de contrôle.

Le résultat False indique une erreur de validation. Téléchargez les fichiers de somme de contrôle et ZIP à partir de la même version et placez-les dans le même répertoire.

L'extraction des journaux de requêtes Teradata est lente

Pour améliorer les performances des tables de jointure spécifiées par les options -Dteradata-logs.query-logs-table et -Dteradata-logs.sql-logs-table, vous pouvez inclure une colonne supplémentaire de type DATE dans la condition JOIN. Cette colonne doit être définie dans les deux tables et faire partie de l'index principal partitionné. Pour inclure cette colonne, utilisez l'option -Dteradata-logs.log-date-column.

L'exemple suivant montre comment utiliser l'option -Dteradata-logs.log-date-column :

Bash

dwh-migration-dumper \
  -Dteradata-logs.query-logs-table=historicdb.ArchivedQryLogV \
  -Dteradata-logs.sql-logs-table=historicdb.ArchivedDBQLSqlTbl \
  -Dteradata-logs.log-date-column=ArchiveLogDate

Windows PowerShell

dwh-migration-dumper `
  "-Dteradata-logs.query-logs-table=historicdb.ArchivedQryLogV" `
  "-Dteradata-logs.sql-logs-table=historicdb.ArchivedDBQLSqlTbl" `
  "-Dteradata-logs.log-date-column=ArchiveLogDate"

Limite de taille des lignes Teradata dépassée

La taille des lignes Teradata version 15 est limitée à 64 Ko. Si la limite est dépassée, l'outil d'extraction échoue et affiche le message suivant :

[Error 9804] [SQLState HY000] Response Row size or Constant Row size overflow

Pour résoudre cette erreur, augmentez la limite de lignes à 1 Mo ou divisez les lignes en plusieurs lignes :

  • Installez et activez la fonctionnalité "1MB Perm and Response Rows" et le logiciel TTU actuel. Pour en savoir plus, consultez la section Message de base de données Teradata 9804.
  • Divisez le long texte de requête en plusieurs lignes à l'aide des options -Dteradata.metadata.max-text-length et -Dteradata-logs.max-sql-length.

La commande suivante montre comment utiliser l'option -Dteradata.metadata.max-text-length pour diviser un long texte de requête en plusieurs lignes comportant au maximum 10 000 caractères chacune :

Bash

dwh-migration-dumper \
  --connector teradata \
  -Dteradata.metadata.max-text-length=10000

Windows PowerShell

dwh-migration-dumper `
  --connector teradata `
  "-Dteradata.metadata.max-text-length=10000"

La commande suivante montre comment utiliser l'option -Dteradata-logs.max-sql-length pour diviser un long texte de requête en plusieurs lignes comportant au maximum 10 000 caractères chacune :

Bash

dwh-migration-dumper \
  --connector teradata-logs \
  -Dteradata-logs.max-sql-length=10000

Windows PowerShell

dwh-migration-dumper `
  --connector teradata-logs `
  "-Dteradata-logs.max-sql-length=10000"

Problème de connexion Oracle

Dans les cas courants, comme un mot de passe ou un nom d'hôte non valides, l'outil dwh-migration-dumper affiche un message d'erreur pertinent décrivant le problème à la racine. Toutefois, dans certains cas, le message d'erreur renvoyé par le serveur Oracle peut être générique et difficile à examiner.

L'un de ces problèmes est IO Error: Got minus one from a read call. Cette erreur indique que la connexion au serveur Oracle a été établie, mais que le serveur n'a pas accepté le client et a fermé la connexion. Ce problème se produit généralement lorsque le serveur n'accepte que les connexions TCPS. Par défaut, l'outil dwh-migration-dumper utilise le protocole TCP. Pour résoudre ce problème, vous devez remplacer l'URL de connexion JDBC Oracle.

Au lieu de fournir les indicateurs oracle-service, host et port, vous pouvez résoudre ce problème en fournissant l'indicateur url au format suivant : jdbc:oracle:thin:@tcps://HOST_NAME:PORT/ORACLE_SERVICE. En général, le numéro de port TCPS utilisé par le serveur Oracle est 2484.

L'exemple suivant montre comment spécifier l'URL de connexion dans la commande :

dwh-migration-dumper \
  --connector oracle-stats \
  --url "jdbc:oracle:thin:@tcps://HOST_NAME:PORT/ORACLE_SERVICE" \
  --assessment \
  --driver "JDBC_DRIVER_PATH" \
  --user "USER" \
  --password

En plus de modifier le protocole de connexion en TCPS, vous devrez peut-être fournir la configuration SSL trustStore requise pour vérifier le certificat du serveur Oracle. Une configuration SSL manquante entraîne un message d'erreur Unable to find valid certification path. Pour résoudre ce problème, définissez la variable d'environnement JAVA_OPTS :

set JAVA_OPTS=-Djavax.net.ssl.trustStore="JKS_FILE_LOCATION" -Djavax.net.ssl.trustStoreType=JKS -Djavax.net.ssl.trustStorePassword="PASSWORD"

Selon la configuration de votre serveur Oracle, vous devrez peut-être également fournir la configuration keyStore. Pour en savoir plus sur les options de configuration, consultez SSL With Oracle JDBC Driver (SSL avec le pilote Oracle JDBC).

Étapes suivantes