Modèle Sourcedb vers Spanner

Le modèle SourceDB vers Spanner est un pipeline par lots qui copie les données d'une base de données relationnelle vers une base de données Spanner existante. Ce pipeline utilise JDBC pour se connecter à la base de données relationnelle. Vous pouvez utiliser ce modèle pour copier des données de toute base de données relationnelle contenant les pilotes JDBC disponibles dans Spanner. Cette option n'est compatible qu'avec un ensemble limité de types MySQL.

Pour obtenir une couche supplémentaire de protection, vous pouvez également transmettre une clé Cloud KMS avec des paramètres de nom d'utilisateur, de mot de passe et de chaîne de connexion encodés en base64 et chiffrés avec la clé Cloud KMS. Pour en savoir plus sur le chiffrement des paramètres de nom d'utilisateur, de mot de passe et de chaîne de connexion, consultez la page sur le point de terminaison du chiffrement de l'API Cloud KMS.

Conditions requises pour ce pipeline

  • Les pilotes JDBC de la base de données relationnelle doivent être disponibles.
  • Les tables Spanner doivent exister avant l'exécution du pipeline.
  • Les tables Spanner doivent avoir un schéma compatible.
  • La base de données relationnelle doit être accessible à partir du sous-réseau dans lequel Dataflow est exécuté.

Paramètres de modèle

Paramètres obligatoires

  • sourceConfigURL : URL du fichier de configuration de la connexion source. Le format du fichier dépend du type de source. Pour Astra, il pointera vers un fichier de configuration de connexion Astra (exemple). Pour JDBC, il pointera vers un fichier de configuration du partitionnement JDBC (exemple). Pour Cassandra, il pointera vers un fichier de configuration du pilote Cassandra (exemple). Ce paramètre est obligatoire. Par exemple, gs://your-bucket/source-config.json. La valeur par défaut est vide.
  • instanceId : instance Cloud Spanner de destination.
  • databaseId : base de données Cloud Spanner de destination.
  • projectId : nom du projet Cloud Spanner.
  • outputDirectory : ce répertoire permet de vider les enregistrements défaillants/ignorés/filtrés lors d'une migration.

Paramètres facultatifs

  • sourceDbDialect : les valeurs possibles sont CASSANDRA, MYSQL, POSTGRESQL, ORACLE et SQLSERVER. La valeur par défaut est "MYSQL".
  • jdbcDriverJars : liste des fichiers JAR du pilote, séparés par une virgule. Exemple :gs://your-bucket/driver_jar1.jar,gs://your-bucket/driver_jar2.jar La valeur par défaut est vide.
  • jdbcDriverClassName : nom de classe du pilote JDBC. Exemple :com.mysql.jdbc.Driver La valeur par défaut est com.mysql.jdbc.Driver.
  • tables : tables à migrer depuis la source. La valeur par défaut est vide.
  • numPartitions : nombre de partitions. Ce paramètre, avec les limites inférieure et supérieure, forme des pas de partition pour les expressions de clause WHERE générées, qui sont utilisées pour diviser la colonne de partition de manière uniforme. Lorsque l'entrée est inférieure à 1, le nombre est défini sur 1. La valeur par défaut est 0.
  • fetchSize : nombre de lignes à extraire par page lue pour la source JDBC. Si elle n'est pas définie, elle est déduite automatiquement du type de machine du nœud de calcul et de la taille de ligne estimée, et revient à 50 000 lignes si elle ne peut pas être déduite (par exemple, lorsque le type de machine du nœud de calcul n'est pas spécifié). Si le dialecte source est MySQL, veuillez consulter la note ci-dessous. Cela s'est finalement traduit par un appel Statement.setFetchSize au niveau JDBC. Elle ne doit être utilisée que si la valeur par défaut génère des erreurs de mémoire.Remarque pour la source MySQL : FetchSize est ignoré par le connecteur MySQL, sauf si useCursorFetch=true fait également partie des propriétés de connexion. Pour le dialecte MySQL, le pipeline ajoute useCursorFetch=true aux propriétés de connexion par défaut, sauf si le paramètre fetchSize est explicitement défini sur 0.
  • spannerHost : point de terminaison Cloud Spanner à appeler dans le modèle. Exemple :https://batch-spanner.googleapis.com La valeur par défaut est https://spanner.googleapis.com.
  • maxConnections : configure le pool de connexions JDBC sur chaque nœud de calcul avec le nombre maximal de connexions. Indiquez un nombre négatif pour ne pas définir de limite. Exemple :-1 La valeur par défaut est 0.
  • sessionFilePath : chemin d'accès au fichier de session dans Cloud Storage contenant les informations de mappage de l'outil de migration Spanner. La valeur par défaut est vide.
  • transformationJarPath : emplacement du fichier JAR personnalisé dans Cloud Storage contenant la logique de transformation personnalisée pour le traitement des enregistrements. La valeur par défaut est vide.
  • transformationClassName : nom de classe complet avec une logique de transformation personnalisée. Ce champ est obligatoire si la valeur de transformationJarPath est spécifiée. La valeur par défaut est vide.
  • transformationCustomParameters : chaîne contenant les paramètres personnalisés à transmettre à la classe de transformation personnalisée. La valeur par défaut est vide.
  • insertOnlyModeForSpannerMutations : par défaut, le pipeline utilise des upserts pour écrire des lignes dans Spanner. Cela signifie que les lignes existantes seront écrasées. Si le mode InsertOnly est activé, des insertions sont utilisées à la place des upserts et les lignes existantes ne sont pas écrasées.
  • batchSizeForSpannerMutations : taille du lot en octets pour les mutations Spanner. Si la valeur est inférieure à 0, la valeur par défaut de SpannerIO d'Apache Beam (1 Mo) est utilisée. Définissez cette valeur sur 0 ou 10 pour désactiver le traitement par lot des mutations.
  • spannerPriority : priorité des requêtes pour les appels Cloud Spanner. La valeur doit être l'une des suivantes : [HIGH,MEDIUM,LOW]. La valeur par défaut est HIGH.
  • tableOverrides : il s'agit des remplacements de noms de tables de la source à Spanner. Ils sont écrits au format suivant : [{SourceTableName1, SpannerTableName1}, {SourceTableName2, SpannerTableName2}]. Cet exemple montre le mappage de la table "Singers" à "Vocalists" et de la table "Albums" à "Records". Exemple :[{Singers, Vocalists}, {Albums, Records}] La valeur par défaut est vide.
  • columnOverrides : il s'agit des remplacements de noms de colonnes de la source à Spanner. Ils sont écrits au format suivant : [{SourceTableName1.SourceColumnName1, SourceTableName1.SpannerColumnName1}, {SourceTableName2.SourceColumnName1, SourceTableName2.SpannerColumnName1}]. Notez que SourceTableName doit rester le même dans la paire source et Spanner. Pour remplacer les noms de tables, utilisez tableOverrides.L'exemple montre comment mapper SingerName à TalentName et AlbumName à RecordName dans les tables Singers et Albums, respectivement. Exemple :[{Singers.SingerName, Singers.TalentName}, {Albums.AlbumName, Albums.RecordName}] La valeur par défaut est vide.
  • schemaOverridesFilePath : fichier qui spécifie les remplacements de noms de tables et de colonnes de la source à Spanner. La valeur par défaut est vide.
  • uniformizationStageCountHint : indication du nombre d'étapes d'uniformisation. Actuellement, cela ne s'applique qu'aux sources basées sur JDBC, comme MySQL ou PostgreSQL. Laissez la valeur sur 0 ou sur la valeur par défaut pour désactiver l'uniformisation. Définissez cette valeur sur -1 pour un nombre d'étapes log(numPartition). Si votre espace de clés primaires source est réparti de manière uniforme (par exemple, une clé à incrémentation automatique avec des trous épars), il est préférable de le laisser désactivé. Si votre espace de clés n'est pas uniforme, vous pouvez rencontrer une VM en retard dans votre exécution Dataflow. Dans ce cas, vous pouvez le définir sur -1 pour activer l'uniformisation. Si vous définissez manuellement cette valeur sur une valeur autre que 0 ou -1, vous pourrez affiner le compromis entre la surcharge ajoutée par les étapes d'uniformisation et l'amélioration des performances due à une meilleure répartition du travail.
  • failureInjectionParameter : paramètre d'injection d'échec. Utilisé uniquement pour les tests. La valeur par défaut est vide.
  • maxCommitDelay : délai maximal de validation pour optimiser le débit en écriture dans Spanner. Définissez la valeur de référence https://cloud.google.com/spanner/docs/throughput-optimized-writes.Set sur -1 pour laisser Spanner choisir la valeur par défaut. Définissez une valeur positive pour remplacer le meilleur compromis entre débit et latence.La valeur par défaut est -1.
  • gcsOutputDirectory : ce répertoire est utilisé pour écrire les fichiers AVRO des enregistrements lus à partir de la source. Exemple :gs://your-bucket/your-path La valeur par défaut est vide.
  • disabledAlgorithms : algorithmes à désactiver, séparés par une virgule. Si cette valeur est définie sur none, aucun algorithme n'est désactivé. Utilisez ce paramètre avec prudence, car les algorithmes désactivés par défaut peuvent présenter des failles ou des problèmes de performances. Par exemple, SSLv3, RC4.
  • extraFilesToStage : chemins d'accès Cloud Storage ou secrets Secret Manager séparés par une virgule afin que les fichiers soient traités dans le nœud de calcul. Ces fichiers sont enregistrés dans le répertoire "/extra_files" de chaque nœud de calcul. Exemple :gs://<BUCKET_NAME>/file.txt,projects/<PROJECT_ID>/secrets/<SECRET_ID>/versions/<VERSION_ID>

Exécuter le modèle

Console

  1. Accédez à la page Dataflow Créer un job à partir d'un modèle.
    2. Accéder à la page Créer un job à partir d'un modèle
  2. Dans le champ Nom du job, saisissez un nom de job unique.
  3. Facultatif : pour Point de terminaison régional, sélectionnez une valeur dans le menu déroulant. La région par défaut est us-central1.

    Pour obtenir la liste des régions dans lesquelles vous pouvez exécuter un job Dataflow, consultez la page Emplacements Dataflow.

  4. Dans le menu déroulant Modèle Dataflow, sélectionnez le modèle Sourcedb to Spanner.
  5. Dans les champs fournis, saisissez vos valeurs de paramètres.
  6. Cliquez sur Run Job (Exécuter la tâche).

gcloud CLI

Dans le shell ou le terminal, exécutez le modèle :

gcloud dataflow flex-template run JOB_NAME \
    --template-file-gcs-location=gs://dataflow-templates/VERSION/flex/Sourcedb_to_Spanner_Flex \
    --project=PROJECT_ID \
    --region=REGION_NAME \
    --parameters \
       sourceConfigURL=SOURCE_CONFIG_URL,\
       instanceId=INSTANCE_ID,\
       databaseId=DATABASE_ID,\
       projectId=PROJECT_ID,\
       outputDirectory=OUTPUT_DIRECTORY,\

Remplacez les éléments suivants :

  • JOB_NAME : nom de job unique de votre choix
  • VERSION : version du modèle que vous souhaitez utiliser

    Vous pouvez utiliser les valeurs suivantes :

    • latest pour utiliser la dernière version du modèle, disponible dans le dossier parent non daté du bucket gs://dataflow-templates/latest/
    • Le nom de la version, par exemple : 2023-09-12-00_RC00, pour utiliser une version spécifique du modèle, qui peut être imbriquée dans le dossier parent daté du bucket :gs://dataflow-templates/
  • REGION_NAME : région dans laquelle vous souhaitez déployer votre job Dataflow, par exemple us-central1
  • SOURCE_CONFIG_URL : URL permettant de se connecter à l'hôte de la base de données source. La valeur peut être de 1. URL de connexion JDBC, qui doit contenir le nom de l'hôte, du port et de la base de données source, et peut éventuellement contenir des propriétés telles que autoReconnect, maxReconnects etc. Format: `jdbc:mysql://{host}:{port}/{dbName}?{parameters}`2. Chemin d'accès à la configuration de segmentation
  • INSTANCE_ID : ID de l'instance Cloud Spanner
  • DATABASE_ID : ID de la base de données Cloud Spanner
  • PROJECT_ID : ID du projet Cloud Spanner
  • OUTPUT_DIRECTORY : répertoire de sortie pour les événements défaillants/ignorés/filtrés

API

Pour exécuter le modèle à l'aide de l'API REST, envoyez une requête HTTP POST. Pour en savoir plus sur l'API, ses autorisations et leurs champs d'application, consultez la section projects.templates.launch.

POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/flexTemplates:launch
{
   "launchParameter": {
     "jobName": "JOB_NAME",
     "parameters": {
       "sourceConfigURL": "SOURCE_CONFIG_URL",
       "instanceId": "INSTANCE_ID",
       "databaseId": "DATABASE_ID",
       "projectId": "PROJECT_ID",
       "outputDirectory": "OUTPUT_DIRECTORY",
     },
     "containerSpecGcsPath": "gs://dataflow-templates/VERSION/flex/Sourcedb_to_Spanner_Flex",
     "environment": { "maxWorkers": "10" }
  }
}

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet Google Cloud dans lequel vous souhaitez exécuter le job Dataflow
  • JOB_NAME : nom de job unique de votre choix
  • VERSION : version du modèle que vous souhaitez utiliser

    Vous pouvez utiliser les valeurs suivantes :

    • latest pour utiliser la dernière version du modèle, disponible dans le dossier parent non daté du bucket gs://dataflow-templates/latest/
    • Le nom de la version, par exemple : 2023-09-12-00_RC00, pour utiliser une version spécifique du modèle, qui peut être imbriquée dans le dossier parent daté du bucket :gs://dataflow-templates/
  • LOCATION : région dans laquelle vous souhaitez déployer votre job Dataflow, par exemple us-central1
  • SOURCE_CONFIG_URL : URL permettant de se connecter à l'hôte de la base de données source. La valeur peut être de 1. URL de connexion JDBC, qui doit contenir le nom de l'hôte, du port et de la base de données source, et peut éventuellement contenir des propriétés telles que autoReconnect, maxReconnects etc. Format: `jdbc:mysql://{host}:{port}/{dbName}?{parameters}`2. Chemin d'accès à la configuration de segmentation
  • INSTANCE_ID : ID de l'instance Cloud Spanner
  • DATABASE_ID : ID de la base de données Cloud Spanner
  • PROJECT_ID : ID du projet Cloud Spanner
  • OUTPUT_DIRECTORY : répertoire de sortie pour les événements défaillants/ignorés/filtrés