Exporter des bases de données de Spanner vers Avro

Cette page explique comment exporter des bases de données Spanner avec la console Google Cloud. Exporter une base de données Spanner à l'aide de l'API REST ou de l'gcloud spanner de ligne de commande, suivez les instructions Avant de commencer de cette page, puis consultez les des instructions détaillées dans Spanner vers Cloud Storage Avro dans le Documentation Dataflow. Le processus d'exportation utilise Dataflow et écrit les données dans un dossier d'un bucket Cloud Storage. Le dossier obtenu contient un ensemble Fichiers Avro et fichiers manifestes JSON.

Avant de commencer

Pour exporter une base de données Spanner, vous devez d'abord activer Spanner, Cloud Storage, API Compute Engine et Dataflow:

Activer les API

Vous devez également disposer d'un quota suffisant, ainsi que des autorisations IAM requises.

Exigences en matière de quota

Voici les conditions de quota applicables aux jobs d'exportation:

• Spanner: aucune la capacité de calcul requise pour exporter une base de données, d'ajouter de la capacité de calcul afin que votre job se termine dans une quantité raisonnable de temps. Pour en savoir plus, consultez Optimiser les missions.
• Cloud Storage: Pour procéder à l'exportation, vous devez créer un bucket pour vos fichiers exportés si : vous n'en avez pas encore. Vous pouvez le faire dans la console Google Cloud, soit via la page Cloud Storage, soit lors de la création de votre exportation sur la page Spanner. Il n'est pas nécessaire de spécifier une taille pour ce bucket.
• Dataflow : les tâches d'exportation sont soumises aux mêmes exigences que les autres tâches Dataflow en ce qui concerne les quotas Compute Engine, aussi bien pour l'utilisation de processeurs et d'espace disque que pour le nombre d'adresses IP.

• Compute Engine : avant d'exécuter une tâche d'exportation, vous devez définir les quotas initiaux Compute Engine utilisés par Dataflow. Ces quotas représentent le nombre maximal de ressources que vous permettez à Dataflow d'utiliser pour votre tâche. Les valeurs de départ recommandées sont les suivantes :

  • Processeurs : 200
  • Adresses IP en cours d'utilisation : 200
  • Disque persistant standard : 50 To

  En règle générale, vous n'avez aucun autre ajustement à effectuer. Dataflow gère l'autoscaling de sorte que vous n'ayez à payer que pour les ressources effectivement utilisées lors de l'exportation. S'il apparaît que votre tâche pourrait utiliser davantage de ressources, l'interface utilisateur de Dataflow affiche une icône d'avertissement, mais cela n'empêche normalement pas la tâche d'aboutir.

Exigences IAM

Pour exporter une base de données, vous devez également disposer de rôles IAM accordant des autorisations suffisantes pour utiliser tous les services impliqués dans une tâche d'exportation. Pour en savoir plus sur l'attribution de rôles et d'autorisations, consultez la page Appliquez des rôles IAM.

Pour exporter une base de données, vous avez besoin des rôles suivants :

• Au niveau du projet Google Cloud :
  • Lecteur Spanner (roles/spanner.viewer)
  • Administrateur Dataflow (roles/dataflow.admin)
  • Administrateur de l'espace de stockage (roles/storage.admin)
• Au niveau de l'instance ou de la base de données Spanner, ou au niveau Au niveau du projet Google Cloud: <ph type="x-smartling-placeholder">
  </ph>
  • Lecteur de bases de données Spanner (roles/spanner.databaseReader)
  • Administrateur de bases de données Spanner (roles/spanner.databaseAdmin)

Pour utiliser les ressources de calcul indépendantes de Spanner Data Boost lors d'une exportation, procédez comme suit : vous devez aussi disposer du rôle IAM spanner.databases.useDataBoost l'autorisation. Pour en savoir plus, consultez Présentation de Data Boost

Exporter une base de données

Une fois que vous remplissez les conditions de quota et IAM décrites précédemment, vous pouvez exporter une base de données Spanner existante.

Pour exporter votre base de données Spanner vers un bucket Cloud Storage, procédez comme suit.

1. Accédez à la page Instances de Spanner.

   Accéder à la page Instances

2. Cliquez sur le nom de l'instance contenant votre base de données.

3. Cliquez sur l'élément de menu Importer/Exporter dans le volet de gauche, puis sur le bouton Exporter.

4. Sous Sélectionner l'emplacement de stockage de votre exportation, cliquez sur Parcourir.

5. Si vous ne possédez pas déjà un bucket Cloud Storage pour votre exportation :

   1. Cliquez sur Nouveau bucket .
   2. Saisissez un nom pour ce bucket. Les noms de buckets doivent être uniques dans Cloud Storage.
   3. Sélectionnez une classe de stockage et un emplacement par défaut, puis cliquez sur Créer.
   4. Cliquez sur le bucket pour le sélectionner.

   Si vous disposez déjà d'un bucket, sélectionnez-le dans la liste initiale ou cliquez sur Rechercher pour filtrer la liste, puis cliquez sur votre bucket pour le sélectionner.

6. Cliquez sur Sélectionner.

7. Sélectionnez la base de données à exporter dans le menu déroulant Sélectionner une base de données à exporter.

8. Facultatif: Pour exporter votre base de données à partir d'un moment antérieur, cochez la case et saisissez un code temporel.

9. Sélectionnez une région dans le menu déroulant Choisir une région pour la tâche d'exportation.

10. Facultatif: Pour chiffrer l'état du pipeline Dataflow avec une clé de chiffrement gérée par le client:

    1. Cliquez sur Afficher les options de chiffrement.
    2. Sélectionnez Utiliser une clé de chiffrement gérée par le client (CMEK).
    3. Sélectionnez votre clé dans la liste déroulante.

    Cette option n'affecte pas le chiffrement au niveau du bucket Cloud Storage de destination. Pour activer les CMEK pour votre bucket Cloud Storage, consultez Utilisez des CMEK avec Cloud Storage.

11. Facultatif: Pour exporter des données à l'aide de Spanner Data Boost, sélectionnez le paramètre Case à cocher Utiliser Spanner Data Boost. Pour en savoir plus, consultez Présentation de Data Boost

12. Cochez la case sous Confirmer les débits pour confirmer en plus de ceux liés à votre instance Spanner existante.

13. Cliquez sur Exporter.

    La console Google Cloud affiche la page Importation/Exportation de bases de données. Une ligne s'affiche alors pour votre job d'exportation dans les jobs d'importation/exportation. incluant le temps écoulé du job:

    

Lorsque la tâche se termine ou est interrompue, l'état est mis à jour dans la liste d'importation/exportation. Si la tâche a abouti, l'état Réussie s'affiche :

Si la tâche a échoué, l'état Échec s'affiche:

Pour afficher les détails de l'opération Dataflow correspondant à votre tâche, cliquez sur le nom de la tâche dans la colonne Nom de la tâche Dataflow.

En cas d'échec, consultez les journaux Dataflow de cette tâche pour connaître les détails de l'erreur.

Afin d'éviter une facturation Cloud Storage pour les fichiers créés par une tâche d'exportation ayant échoué, supprimez le dossier et ses fichiers. Pour en savoir plus, consultez l'article Consulter vos exporter pour savoir comment trouver le dossier.

Remarque sur l'exportation des colonnes générées et des flux de modifications

Les valeurs d'une colonne générée stockée ne sont pas exportées. La définition de colonne est exportée vers le schéma Avro en tant que champ d'enregistrement de type null, la définition de colonne comme propriétés personnalisées du champ. Jusqu'au remplissage l'opération d'une colonne nouvellement générée se termine, la colonne générée est ignoré comme s'il n'existait pas dans le schéma.

Les flux de modifications exportés sous forme de fichiers Avro ne contiennent que le schéma du des flux de modifications, et non des enregistrements de modifications de données.

Remarque sur l'exportation de séquences

Séquences (GoogleSQL, PostgreSQL) sont des objets de schéma que vous utilisez pour générer des valeurs d'entiers uniques. Spanner exporte chacun des objets de schéma vers le schéma Avro en tant que record, avec son genre de séquence, la plage ignorée et le compteur comme propriétés du domaine. Notez que pour éviter qu'une séquence soit réinitialisée et générée des valeurs en double après l'importation, lors de l'exportation du schéma, GET_INTERNAL_SEQUENCE_STATE() (GoogleSQL, PostgreSQL) capture le compteur de séquence. Spanner ajoute un tampon de 1 000 au compteur et écrit la nouvelle valeur de compteur dans le champ d'enregistrement. Ce évite les erreurs de valeur en double qui peuvent se produire après l'importation. S'il y a plus d'écritures dans la base de données source lors de l'exportation des données, vous devez ajuster le compteur de séquence réel en utilisant ALTER SEQUENCE (GoogleSQL, PostgreSQL).

Lors de l'importation, la séquence commence à partir de ce nouveau compteur et non du compteur. qui se trouvent dans le schéma. Vous pouvez également utiliser ALTER SEQUENCE (GoogleSQL, PostgreSQL) pour mettre à jour la séquence avec un nouveau compteur.

Afficher votre exportation dans Cloud Storage

Pour afficher le dossier contenant votre base de données exportée dans le fichier Console Google Cloud, accédez au navigateur Cloud Storage et choisissez le bucket que vous avez sélectionné précédemment:

Accéder au navigateur Cloud Storage

Le bucket contient maintenant un dossier dans lequel se trouve la base de données exportée. Le nom du dossier commence par l'ID de votre instance, le nom de la base de données et l'horodatage de la tâche d'exportation. Le dossier contient :

• Un fichier spanner-export.json.
• Un fichier TableName-manifest.json pour chaque table de la base de données que vous avez exportée.

• Un ou plusieurs fichiers TableName.avro-#####-of-#####. Le premier nombre figurant dans l'extension .avro-#####-of-##### représente l'index du fichier Avro compté à partir de zéro, tandis que le second correspond au nombre de fichiers Avro générés pour chaque table.

  Par exemple, Songs.avro-00001-of-00002 est le deuxième des deux fichiers contenant les données de la table Songs.

• Un fichier ChangeStreamName-manifest.json pour chaque flux de modifications dans la base de données que vous exportées.

• ChangeStreamName.avro-00000-of-00001 pour chaque flux de modifications. Ce fichier contient des données vides avec uniquement le schéma Avro du flux de modifications.

Choisissez une région pour votre job d'importation

Vous pouvez choisir une autre région en fonction de l'emplacement bucket Cloud Storage. Pour éviter frais de transfert de données sortantes, choisissez une région correspond à l'emplacement de votre bucket Cloud Storage.

• Si l'emplacement de votre bucket Cloud Storage est une région, vous peuvent profiter de l'utilisation gratuite du réseau en choisissant la même région pour votre job d'importation, en supposant que cette région est disponible.

• Si l'emplacement de votre bucket Cloud Storage est birégional, vous pouvez profiter de l'utilisation gratuite du réseau en choisissant l'une des deux régions qui composent l'emplacement birégional de votre job d'importation, en supposant que l'une des régions est disponible.

• Si une région située dans la même zone géographique n'est pas disponible pour votre job d'importation ou si votre L'emplacement du bucket Cloud Storage est multirégional, des frais de transfert de données sortantes s'appliquent. Consulter Cloud Storage de transfert de données pour choisir une région qui entraîne le les frais de transfert de données les plus bas.

Exporter un sous-ensemble de tables

Si vous souhaitez exporter uniquement les données de certaines tables, l'intégralité de la base de données, vous pouvez les spécifier lors de l'exportation. Dans Spanner exporte alors l'intégralité du schéma de la base de données, y compris les données des tables que vous spécifiez, en laissant toutes les autres tables présentes, mais vide dans le fichier exporté.

Vous pouvez spécifier un sous-ensemble de tables à exporter à l'aide de la méthode page Dataflow de la console Google Cloud ou de la ligne de commande. (Le la page Spanner ne propose pas cette action.)

Si vous exportez les données d'une table qui est l'enfant d'une autre table, vous doit exporter son fichier parent les données de la table. Si les parents ne sont pas exportés, le job d'exportation échoue.

Pour exporter un sous-ensemble de tables, démarrez l'exportation à l'aide de la Dataflow Modèle Spanner vers Cloud Storage Avro spécifier les tables à l'aide de la page "Dataflow" de la console Google Cloud ou du Google Cloud CLI, comme décrit ci-dessous:

gcloud dataflow jobs run my-export-job \
--gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
--region=us-central1 \
--parameters='instanceId=test-instance,databaseId=example-db,tableNames=table1,outputDir=gs://my-gcs-bucket' \
--max-workers=10

 gcloud dataflow jobs run my-export-job \
--gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
--region=us-central1 \
--parameters='^|^instanceId=test-instance|databaseId=example-db|tableNames=table1,table2|outputDir=gs://my-gcs-bucket' \
--max-workers=10

gcloud dataflow jobs run my-export-job \
--gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
--region=us-central1 \
--parameters='instanceId=test-instance,databaseId=example-db,tableNames=Songs,shouldExportRelatedTables=true,outputDir=gs://my-gcs-bucket' \
--max-workers=10

Afficher ou dépanner des jobs dans l'interface utilisateur de Dataflow

Après avoir démarré un job d'exportation, vous pouvez en afficher les détails, y compris dans la section "Dataflow" de la console Google Cloud.

Afficher les détails d'un job Dataflow

Pour afficher les détails des tâches d'importation/exportation exécutées au cours de la dernière semaine, y compris les tâches en cours d'exécution :

1. Accédez à la page Présentation de la base de données correspondant à la base de données.
2. Cliquez sur l'élément de menu du volet Importations/Exportations à gauche. La page Importations/Exportations de la base de données affiche la liste des tâches récentes.

3. Sur la page Importations/Exportations de la base de données, cliquez sur le nom de la tâche dans la colonne Nom de la tâche Dataflow :

   

   La console Google Cloud affiche les détails de Dataflow d'un projet.

Pour afficher une tâche que vous avez exécutée il y a plus d'une semaine :

1. Accédez à la page des jobs Dataflow dans la console Google Cloud.

   Accéder à la page Tâches

2. Recherchez votre tâche dans la liste, puis cliquez sur son nom.

   La console Google Cloud affiche les détails de Dataflow d'un projet.

Afficher les journaux Dataflow associés à votre job

Pour afficher les journaux d'une tâche Dataflow, accédez à la page des détails de la tâche comme décrit ci-dessus, puis cliquez sur Journaux à droite du nom de la tâche.

Si une tâche échoue, recherchez les erreurs dans les journaux. Si des erreurs ont été enregistrées, leur nombre s'affiche à côté du bouton Logs (Journaux) :

Pour afficher les erreurs relatives à une tâche :

1. Cliquez sur le nombre d'erreurs affiché à côté du bouton Logs (Journaux).

   La console Google Cloud affiche les journaux du job. Vous devrez éventuellement faire défiler l'affichage pour voir les erreurs.

2. Repérez les entrées signalées par l'icône d'erreur .

3. Cliquez sur une entrée de journal pour développer son contenu.

Pour en savoir plus sur la résolution des problèmes liés aux jobs Dataflow, consultez la page Résolvez les problèmes liés à votre pipeline.

Résoudre les problèmes d'échec des tâches d'exportation

Si les erreurs suivantes s'affichent dans les journaux de vos tâches :

com.google.cloud.spanner.SpannerException: NOT_FOUND: Session not found

--or--

com.google.cloud.spanner.SpannerException: DEADLINE_EXCEEDED: Deadline expired before operation could complete.

Vérifiez la latence de lecture de 99% dans la l'onglet Surveillance de votre base de données Spanner dans console Google Cloud. Si elle affiche des valeurs élevées (plusieurs secondes), cela signifie que l'instance est surchargée, ce qui entraîne l'expiration et l'échec de la lecture.

L'une des causes de latence élevée est que le job Dataflow s'exécute sur un nombre trop important ce qui entraîne une charge excessive sur l'instance Spanner.

• Si vous utilisez la console Dataflow, le paramètre Nombre maximal de nœuds de calcul se trouve dans la section Paramètres facultatifs de la page Créer une tâche à partir d'un modèle.

• Si vous utilisez gcloud, spécifiez l'argument max-workers. Exemple :

  gcloud dataflow jobs run my-export-job \
  --gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
  --region=us-central1 \
  --parameters='instanceId=test-instance,databaseId=example-db,outputDir=gs://my-gcs-bucket' \
  --max-workers=10
  

Optimiser les tâches d'exportation lentes

Si vous avez adopté les paramètres initiaux suggérés plus haut, vous n'avez en principe aucun autre réglage à effectuer. Voici toutefois quelques possibilités d'optimisation supplémentaires à envisager si l'exécution de votre tâche est lente :

• Optimisez le job et l'emplacement des données: exécutez votre job Dataflow. dans la même région que celle où votre instance Spanner et bucket Cloud Storage.

• Assurez-vous que les ressources Dataflow sont suffisantes: si le quotas Compute Engine pertinents limiter les ressources de votre job Dataflow, Page Dataflow dans la console Google Cloud affiche une icône d'avertissement et journal messages:

  

  Dans ce cas, l'augmentation des quotas en termes de processeurs, d'adresses IP en cours d'utilisation et de disques persistants standards peut accélérer l'exécution de votre tâche, mais également augmenter les frais facturés pour Compute Engine.

• Vérifiez l'utilisation du processeur Spanner: si vous constatez que le processeur de l'instance est supérieure à 65%, vous pouvez augmentez la capacité de calcul de cette instance. La capacité augmente Spanner et le job devrait s'accélérer, mais les frais engendrés Spanner.

Facteurs qui influent sur les performances des tâches d'exportation

Plusieurs facteurs influent sur le temps nécessaire pour mener à bien une tâche d'exportation.

• Taille de la base de données Spanner: le traitement de davantage de données prend plus de temps et des ressources.

• Schéma de base de données Spanner, y compris:

  • Le nombre de tables
  • Taille des lignes
  • Le nombre d'index secondaires
  • Le nombre de clés étrangères
  • Nombre de flux de modifications

• Emplacement des données: les données sont transférées entre Spanner et Cloud Storage avec Dataflow. Dans l'idéal, ces trois composants doivent se trouver dans la même région. Dans le cas contraire, le déplacement des données entre les régions ralentit l'exécution de la tâche.

• Nombre de nœuds de calcul Dataflow : les nœuds de calcul Dataflow optimaux sont nécessaires pour de bonnes performances. En utilisant l'autoscaling, Dataflow choisit le nombre de nœuds de calcul pour la tâche en fonction de la quantité de travail à effectuer. Le nombre de nœuds de calcul sera toutefois limité par les quotas en matière de processeurs, d'adresses IP en cours d'utilisation et de disques persistants standards. L'interface utilisateur de Dataflow affiche une icône d'avertissement lorsque des limites de quota sont atteintes. Dans ce cas, la progression est ralentie, mais la tâche doit néanmoins aboutir.

• Charge existante sur Spanner: Une tâche d'exportation ajoute généralement une légère charge sur une instance Spanner Compute Engine. Si cette instance présentait déjà une charge importante, l'exécution de la tâche est ralentie.

• Quantité de capacité de calcul Spanner: si l'utilisation du processeur pour l'instance est supérieure à 65%, le job s'exécute plus lentement.