Exporter des bases de données de Spanner vers Avro

Cette page explique comment exporter des bases de données Spanner à l'aide de la console Google Cloud.

Pour exporter une base de données Spanner à l'aide de l'API REST ou de la Google Cloud CLI, suivez les étapes décrites dans la section Avant de commencer de cette page, puis consultez les instructions détaillées dans la section Spanner vers Cloud Storage Avro de la documentation Dataflow. Le processus d'exportation utilise Dataflow et écrit les données dans un dossier d'un bucket Cloud Storage. Le dossier résultant contient un ensemble de fichiers Avro et de fichiers manifestes JSON.

Avant de commencer

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

Enable the APIs

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

Exigences en matière de quota

Voici les exigences de quota concernant les tâches d'exportation:

  • Spanner: aucune capacité de calcul supplémentaire n'est requise pour exporter une base de données, mais il peut s'avérer nécessaire d'ajouter de la capacité de calcul pour que la tâche se termine dans un délai raisonnable. Pour en savoir plus, consultez la section Optimiser les tâches.
  • Cloud Storage : pour effectuer des exportations, vous devez créer un bucket pour vos fichiers exportés, si ce n'est pas déjà fait. Vous pouvez créer un bucket dans la console Google Cloud, soit sur 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 pas d'autres réglages à 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.

Rôles requis

Pour obtenir les autorisations nécessaires pour exporter une base de données, demandez à votre administrateur de vous accorder les rôles IAM suivants sur le compte de service de l'agent Dataflow:

Pour utiliser les ressources de calcul indépendantes de Spanner Data Boost lors d'une exportation, vous avez également besoin de l'autorisation IAM spanner.databases.useDataBoost. Pour en savoir plus, consultez la page Présentation de Data Boost.

Exporter une base de données

Une fois que vous avez satisfait aux exigences 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 Capture d'écran de l'élément d'interface utilisateur "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 Capture d'écran de l'élément d'interface utilisateur "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 à un moment antérieur, cochez la case correspondante, puis saisissez un horodatage.

  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 CMEK pour votre bucket Cloud Storage, consultez la page Utiliser CMEK avec Cloud Storage.

  11. Facultatif: Pour exporter à l'aide de Spanner Data Boost, cochez la case Utiliser Spanner Data Boost. Pour en savoir plus, consultez la page Présentation de Data Boost.

  12. Cochez la case située sous Confirmer les frais pour accepter la facturation de frais supplémentaires en plus des frais relatifs à votre instance Spanner existante.

  13. Cliquez sur Exporter.

    La console Google Cloud ouvre la page Importation/Exportation de base de données, qui affiche désormais une ligne de votre tâche d'exportation dans la liste des tâches d'importation/exportation, y compris le temps écoulé:

    Capture d'écran de la tâche en cours

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 :

Message de réussite de la tâche d'exportation

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

Message d'échec de la tâche d'exportation

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 savoir comment trouver le dossier, consultez la section Afficher votre exportation dans Cloud Storage.

Remarque concernant 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'à la fin de l'opération de remplissage d'une colonne générée, la colonne générée est ignorée comme si elle n'existait pas dans le schéma.

Les flux de modifications exportés en tant que fichiers Avro ne contiennent que le schéma des flux de modifications, et non les enregistrements de modification des données.

Remarque concernant l'exportation de séquences

Les séquences (GoogleSQL, PostgreSQL) sont des objets de schéma que vous utilisez pour générer des valeurs entières uniques. Spanner exporte chacun des objets de schéma vers le schéma Avro en tant que champ d'enregistrement, avec son type de séquence, sa plage ignorée et son compteur comme propriétés du champ. Notez que pour éviter qu'une séquence ne soit réinitialisée et ne génère des valeurs en double après l'importation, lors de l'exportation du schéma, la fonction GET_INTERNAL_SEQUENCE_STATE() (GoogleSQL, PostgreSQL) capture le compteur de séquence. Spanner ajoute un tampon de 1 000 à ce compteur et écrit la nouvelle valeur du compteur dans le champ d'enregistrement. Cette approche évite les erreurs de valeurs en double qui peuvent se produire après l'importation. Si davantage d'écritures sont effectuées dans la base de données source lors de l'exportation des données, vous devez ajuster le compteur de séquence réel à l'aide de l'instruction ALTER SEQUENCE (Google SQL, PostgreSQL).

Lors de l'importation, la séquence commence à partir de ce nouveau compteur au lieu du compteur trouvé dans le schéma. Vous pouvez également utiliser l'instruction 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 la base de données exportée dans la console Google Cloud, accédez au navigateur Cloud Storage et sélectionnez le bucket que vous avez sélectionné précédemment:

Accéder à la page Navigateur de stockage

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 de la base de données que vous avez exportée.

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

Choisir une région pour votre tâche d'importation

Vous pouvez être amené à choisir une région différente selon l'emplacement de votre bucket Cloud Storage. Pour éviter les frais de transfert de données sortants, choisissez une région correspondant à l'emplacement de votre bucket Cloud Storage.

  • Si l'emplacement de votre bucket Cloud Storage est une région, vous pouvez bénéficier de l'utilisation gratuite du réseau en choisissant la même région pour votre tâche d'importation, à condition que cette région soit disponible.

  • Si l'emplacement de votre bucket Cloud Storage est une région duale, vous pouvez bénéficier de l'utilisation gratuite du réseau en choisissant l'une des deux régions qui la composent pour votre tâche d'importation, à condition que l'une d'elles soit disponible.

  • Si une région colocalisée n'est pas disponible pour votre tâche d'importation ou si l'emplacement de votre bucket Cloud Storage est une région multirégionale, des frais de transfert de données sortants s'appliquent. Consultez les tarifs de transfert de données Cloud Storage pour choisir la région qui génère les frais de transfert de données les plus bas.

Exporter un sous-ensemble de tables

Si vous ne souhaitez exporter que les données de certaines tables et non l'ensemble de la base de données, vous pouvez spécifier ces tables lors de l'exportation. Dans ce cas, Spanner exporte l'intégralité du schéma de la base de données, y compris les données des tables que vous spécifiez, et laisse toutes les autres tables présentes, mais vides, dans le fichier exporté.

Vous pouvez spécifier un sous-ensemble de tables à exporter à l'aide de la page Dataflow dans la console Google Cloud ou de la CLI gcloud. (La page Spanner ne fournit pas cette action.)

Si vous exportez les données d'une table qui est l'enfant d'une autre table, vous devez également exporter les données de la table parente. Si les parents ne sont pas exportés, la tâche d'exportation échoue.

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

Si vous utilisez la page Dataflow dans la console Google Cloud, le paramètre Nom(s) de table Cloud Spanner se trouve dans la section Paramètres facultatifs de la page Créer une tâche à partir d'un modèle. Vous pouvez spécifier plusieurs tables dans un format séparé par une virgule.

Accéder à Dataflow

Exécutez la commande gcloud dataflow jobs run, puis spécifiez l'argument tableNames. 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,tableNames=table1,outputDir=gs://my-gcs-bucket' \
--max-workers=10 \
--network=network-123

Spécifier plusieurs tables dans gcloud nécessite une échappement d'argument de type dictionnaire. L'exemple suivant utilise '|' comme caractère d'échappement:

 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 \
--network=network-123

Le paramètre shouldExportRelatedTables est une option pratique pour exporter automatiquement toutes les tables parentes des tables choisies. Par exemple, dans cette hiérarchie de schéma avec les tables Singers, Albums et Songs, il vous suffit de spécifier Songs. L'option shouldExportRelatedTables exporte également Singers et Albums, car Songs est un descendant des deux.

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 \
--network=network-123

Afficher ou dépanner des tâches dans l'interface utilisateur de Dataflow

Après avoir démarré une tâche d'exportation, vous pouvez en afficher les détails, y compris les journaux, dans la section Dataflow de la console Google Cloud.

Afficher les détails d'une tâche Dataflow

Pour afficher les détails des tâches d'importation ou d'exportation que vous avez 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 :

    Message d'état de la tâche en cours

    La console Google Cloud affiche les détails de la tâche Dataflow.

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

  1. Accédez à la page des tâches Dataflow dans la console Google Cloud.

    Accéder aux tâches

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

    La console Google Cloud affiche les détails de la tâche Dataflow.

Afficher les journaux Dataflow correspondant à votre tâche

Pour afficher les journaux d'une tâche Dataflow, accédez à la page des détails de la tâche, 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) :

Exemple de nombre d'erreurs affiché à côté du bouton "Journaux"

Pour afficher les erreurs relatives à une tâche :

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

    La console Google Cloud affiche les journaux de la tâche. 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 Icône "Erreur".

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

Pour en savoir plus sur le dépannage lié aux tâches Dataflow, consultez la page Résoudre les problèmes liés à votre pipeline.

Résoudre les problèmes liés aux tâches d'exportation ayant échoué

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.

Dans la console Google Cloud, vérifiez la latence en lecture de 99% dans l'onglet Monitoring de votre base de données Spanner. 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.

Cette latence élevée peut s'expliquer notamment par le fait que la tâche Dataflow s'exécute à l'aide d'un trop grand nombre de nœuds de calcul, ce qui surcharge l'instance Spanner.

Pour spécifier une limite de nœuds de calcul Dataflow, au lieu d'utiliser l'onglet "Import/Export" (Importer/Exporter) sur la page d'informations sur l'instance de votre base de données Spanner dans la console Google Cloud, vous devez démarrer l'exportation à l'aide du modèle Spanner vers Cloud Storage Avro Dataflow et spécifier le nombre maximal de nœuds de calcul, comme décrit ci-dessous:

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.

Accéder à Dataflow

Exécutez la commande gcloud dataflow jobs run et 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 \
    --network=network-123

Résoudre une erreur réseau

L'erreur suivante peut se produire lorsque vous exportez vos bases de données Spanner:

Workflow failed. Causes: Error: Message: Invalid value for field
'resource.properties.networkInterfaces[0].subnetwork': ''. Network interface
must specify a subnet if the network resource is in custom subnet mode.
HTTP Code: 400

Cette erreur se produit, car Spanner part du principe que vous avez l'intention d'utiliser un réseau VPC en mode automatique nommé default dans le même projet que le job Dataflow. Si vous n'avez pas de réseau VPC par défaut dans le projet, ou si votre réseau VPC est en mode personnalisé, vous devez créer un job Dataflow et spécifier un autre réseau ou sous-réseau.

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 l'emplacement de la tâche et des données: exécutez votre tâche Dataflow dans la même région que celle où se trouvent votre instance Spanner et votre bucket Cloud Storage.

  • Veillez à ce que les ressources Dataflow soient suffisantes: si les ressources de votre tâche Dataflow sont limitées par certains quotas Compute Engine correspondants, la page Dataflow associée à cette tâche dans la console Google Cloud affiche une icône d'avertissement Icône Avertissement ainsi qu'un message de journalisation:

    Capture d'écran de l'avertissement de limite de quota

    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 qu'une instance présente un taux d'utilisation du processeur supérieur à 65%, vous pouvez augmenter la capacité de calcul pour cette instance. La capacité ajoute davantage de ressources Spanner et la tâche devrait accélérer, mais vous devrez payer plus de frais pour 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 temps de traitement et les ressources requises augmentent avec la quantité de données à traiter.

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

    • Nombre de tables
    • Taille des lignes
    • Nombre d'index secondaires
    • 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 à l'aide de 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 faible charge sur une instance Spanner. 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'instance présente un taux d'utilisation du processeur supérieur à 65%, l'exécution de la tâche est ralentie.