Cette page explique comment préparer les fichiers Avro que vous avez exportés à partir de bases de données autres que Spanner, puis les importer dans Spanner. Ces procédures incluent des informations pour les bases de données utilisant les dialectes GoogleSQL et PostgreSQL. Si vous souhaitez importer une base de données Spanner que vous avez précédemment exportée, consultez la page Importer des fichiers Avro Spanner.
Le processus utilise Dataflow. Il importe les données d'un bucket Cloud Storage contenant un ensemble de fichiers Avro et un fichier manifeste JSON qui spécifie les tables de destination et les fichiers Avro qui renseignent chaque table.
Avant de commencer
Pour importer une base de données Spanner, vous devez d'abord activer les API Spanner, Cloud Storage, Compute Engine et Dataflow :
Rôles requis pour activer les API
Pour activer les API, vous avez besoin du rôle IAM Administrateur d'utilisation du service (roles/serviceusage.serviceUsageAdmin), qui
contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer
des rôles.
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'importation :
- Spanner : vous devez disposer d'une capacité de calcul suffisante pour prendre en charge la quantité de données que vous importez. Aucune capacité de calcul supplémentaire n'est requise pour importer 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 importations, vous devez disposer d'un bucket contenant les fichiers que vous avez exportés auparavant. Il n'est pas nécessaire de spécifier une taille pour ce bucket.
- Dataflow : les tâches d'importation 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'importation, vous devez définir les quotas initiaux Compute Engine utilisés par Dataflow. Ces quotas représentent les quantités maximales de ressources que Dataflow pourra 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 assure un autoscaling qui vous permet de ne payer que pour les ressources réellement utilisées lors de l'importation. 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 votre compte de service de nœud de calcul Dataflow :
- Lecteur Cloud Spanner (
roles/spanner.viewer) - Nœud de calcul Dataflow (
roles/dataflow.worker) - Administrateur de l'espace de stockage (
roles/storage.admin) - Lecteur de bases de données Spanner (
roles/spanner.databaseReader) - Administrateur de bases de données (
roles/spanner.databaseAdmin)
Exporter des données depuis une base de données autre que Spanner vers des fichiers Avro
Le processus d'importation apporte des données issues de fichiers Avro situés dans un bucket Cloud Storage. Vous pouvez exporter des données au format Avro depuis n'importe quelle source et utiliser toutes les méthodes disponibles pour le faire.
Pour exporter des données depuis une base de données autre que Spanner vers des fichiers Avro, procédez comme suit :
Tenez compte des points suivants lorsque vous exportez vos données :
- Vous pouvez exporter les données à l'aide de n'importe lequel des types primitifs Avro, ainsi qu'avec le type complexe Tableau.
Chaque colonne de vos fichiers Avro doit utiliser l'un des types de colonne suivants :
ARRAYBOOLBYTES*DOUBLEFLOATINTLONG†STRING‡
* Une colonne de type
BYTESpermet d'importer un type SpannerNUMERIC. Pour en savoir plus, consultez la section Mappages recommandés ci-dessous .†, ‡ Vous pouvez importer un type
LONGstockant un horodatage ou un typeSTRINGstockant un horodatage en tant que type SpannerTIMESTAMP. Pour en savoir plus, consultez la section Mappages recommandés ci-dessous.Il n'est pas nécessaire d'inclure ou de générer des métadonnées lorsque vous exportez les fichiers Avro.
Il n'est pas nécessaire de suivre une convention d'attribution de noms particulière pour vos fichiers.
Si vous n'exportez pas vos fichiers directement vers Cloud Storage, vous devez les importer dans un bucket Cloud Storage. Pour obtenir des instructions détaillées, consultez Importer des objets dans votre bucket Cloud Storage.
Importer des fichiers Avro depuis des bases de données autres que Spanner vers Spanner
Pour importer des fichiers Avro depuis une base de données autre que Spanner vers Spanner, procédez comme suit :
- Créez des tables cibles et définissez le schéma de votre base de données Spanner.
- Créez un fichier
spanner-export.jsondans votre bucket Cloud Storage. - Exécutez une tâche d'importation Dataflow à l'aide de gcloud CLI.
Étape 1 : Créer le schéma de votre base de données Spanner
Avant d'exécuter votre importation, vous devez créer la table cible dans Spanner et en définir le schéma.
Vous devez créer un schéma qui utilise le type de colonne approprié pour chaque colonne des fichiers Avro.
Mappages recommandés
GoogleSQL
| Type de colonne Avro | Type de colonne Spanner |
|---|---|
ARRAY |
ARRAY |
BOOL |
BOOL |
BYTES |
|
DOUBLE |
FLOAT64 |
FLOAT |
FLOAT64 |
INT |
INT64 |
LONG |
|
STRING |
|
PostgreSQL
| Type de colonne Avro | Type de colonne Spanner |
|---|---|
ARRAY |
ARRAY |
BOOL |
BOOLEAN |
BYTES |
|
DOUBLE |
DOUBLE PRECISION |
FLOAT |
DOUBLE PRECISION |
INT |
BIGINT |
LONG |
|
STRING |
|
Étape 2 : Créer un fichier spanner-export.json
Vous devez également créer un fichier nommé spanner-export.json dans votre bucket Cloud Storage. Ce fichier spécifie le dialecte de la base de données et contient un tableau tables qui répertorie les noms et emplacements des fichiers de données pour chaque table.
Le contenu du fichier a le format suivant :
{ "tables": [ { "name": "TABLE1", "dataFiles": [ "RELATIVE/PATH/TO/TABLE1_FILE1", "RELATIVE/PATH/TO/TABLE1_FILE2" ] }, { "name": "TABLE2", "dataFiles": ["RELATIVE/PATH/TO/TABLE2_FILE1"] } ], "dialect":"DATABASE_DIALECT" }
Où DATABASE_DIALECT = {GOOGLE_STANDARD_SQL | POSTGRESQL}
Si l'élément de dialecte est omis, le dialecte par défaut est GOOGLE_STANDARD_SQL.
Étape 3 : Exécuter une tâche d'importation Dataflow à l'aide de gcloud CLI
Pour démarrer votre tâche d'importation, suivez les instructions permettant d'utiliser Google Cloud CLI et d'exécuter une tâche avec le modèle Avro vers Spanner.
Après avoir démarré une tâche d'importation, vous pouvez afficher les détails de cette tâche dans la Google Cloud console.
Une fois la tâche d'importation terminée, ajoutez les éventuels index secondaires et clés étrangères.
Sélectionner une région pour votre tâche d'importation
Vous pouvez être amené à choisir une région différente en fonction de l'emplacement de votre bucket Cloud Storage. Pour éviter les frais de transfert de données sortantes, choisissez une région qui correspond à 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 sans frais 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 double, vous pouvez bénéficier de l'utilisation sans frais du réseau en choisissant l'une des deux régions qui composent la région double pour votre tâche d'importation, à condition que l'une des régions soit disponible.
- Si aucune région colocalisée n'est disponible pour votre tâche d'importation ou si l'emplacement de votre bucket Cloud Storage est une région multiple, des frais de transfert de données sortantes s'appliquent. Consultez les tarifs de transfert de données Cloud Storage pour choisir une région qui générera le moins de frais de transfert de données.
Afficher ou dépanner des tâches dans l'interface utilisateur de Dataflow
Après avoir démarré une tâche d'importation, vous pouvez consulter les détails de cette tâche et les journaux associés dans la section Dataflow de la Google Cloud console.
Afficher les détails d'une tâche Dataflow
Pour afficher les détails des tâches d'importation ou d'exportation exécutées au cours de la dernière semaine, y compris les tâches en cours d'exécution :
- Accédez à la page Présentation de la base de données correspondant à la base de données.
- 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.
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 Google Cloud console 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 :
Accédez à la page des tâches Dataflow dans la Google Cloud console.
Recherchez votre tâche dans la liste, puis cliquez sur son nom.
La Google Cloud console 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) :
Pour afficher les erreurs relatives à une tâche :
Cliquez sur le nombre d'erreurs à côté de Logs.
La Google Cloud console affiche les journaux de la tâche. Vous devrez éventuellement faire défiler l'affichage pour voir les erreurs.
Repérez les entrées signalées par l'icône d'erreur
.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'importation 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.
Vérifiez la latence en écriture de 99% dans l' onglet Surveillance de votre base de données Spanner dans la Google Cloud console. Si elle affiche des valeurs élevées (plusieurs secondes), alors cela signifie que l'instance est surchargée, ce qui entraîne l'expiration et l'échec de l'écriture.
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 du nombre de nœuds de calcul Dataflow, au lieu d' utiliser l'onglet "Importations/Exportations" de la page d'informations de l'instance de votre base de données Spanner dans la Google Cloud console, vous devez démarrer l'importation à l'aide du modèle Dataflow Modèle Cloud Storage Avro vers Spanner et spécifier le nombre maximal de nœuds de calcul comme décrit ci-dessous :Console
Si vous utilisez la console Dataflow, le Nombre maximal de nœuds de calcul paramètre se trouve dans la section Paramètres facultatifs de la page Créer une tâche à partir d'un modèle.
gcloud
Exécutez la gcloud dataflow jobs run
commande et spécifiez l'argument max-workers. Exemple :
gcloud dataflow jobs run my-import-job \
--gcs-location='gs://dataflow-templates/latest/GCS_Avro_to_Cloud_Spanner' \
--region=us-central1 \
--parameters='instanceId=test-instance,databaseId=example-db,inputDir=gs://my-gcs-bucket' \
--max-workers=10 \
--network=network-123
Résoudre les problèmes de 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 la tâche 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 une tâche Dataflow et
spécifier un autre réseau ou sous-réseau.
Optimiser les tâches d'importation dont l'exécution est ralentie
Si vous avez adopté les paramètres initiaux suggérés dans initial settings, 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 la 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 Google Cloud console affiche une icône d'avertissement
ainsi qu'un message de journalisation :
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 associée à 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 affectant les performances des tâches d'importation
Plusieurs facteurs influent sur le temps nécessaire pour mener à bien une tâche d'importation.
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 :
- Le nombre de tables
- La taille des lignes
- Le nombre d'index secondaires
- Le nombre de clés étrangères
- Le nombre de flux de modifications
Emplacement des données : les données sont transférées de Spanner à Cloud Storage via 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. L'autoscaling peut surcharger Spanner, ce qui entraîne des erreurs lorsque le volume de données est particulièrement important.
Charge existante sur Spanner : une tâche d'importation ajoute une charge de processeur importante 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.
Régler les nœuds de calcul afin d'obtenir de bonnes performances pour l'importation
Lorsque vous démarrez une tâche d'importation Spanner, les nœuds de calcul Dataflow doivent être définis sur une valeur optimale pour optimiser les performances. Un trop grand nombre de nœuds de calcul peut surcharger Spanner, et un nombre trop faible de nœuds de calcul entraîne une baisse des performances d'importation.
Le nombre maximal de nœuds de calcul dépend fortement de la taille des données. Idéalement, l'utilisation totale du processeur associée à Spanner doit être comprise entre 70% et 90%. Cela permet d'obtenir un bon équilibre entre l'efficacité de Spanner et l'exécution d'une tâche sans erreur.
Pour atteindre cet objectif d'utilisation dans la majorité des schémas et des scénarios, nous recommandons un nombre maximal de processeurs virtuels de nœud de calcul compris entre 4 et 6 fois le nombre de nœuds Spanner.
Par exemple, pour une instance Spanner à 10 nœuds utilisant des nœuds de calcul n1-standard-2, vous devez définir un nombre maximal de nœuds de calcul sur 25, ce qui donne 50 processeurs virtuels.