Migrer vos données MySQL

Ce document explique comment effectuer une migration de données en direct d'une instance MySQL source vers Spanner avec un temps d'arrêt minimal en utilisant Terraform pour déployer Dataflow et Datastream.

Une fois que vous avez effectué la migration des données en direct et que vous êtes certain que toutes vos données ont été transférées, que vous avez migré votre code et vos dépendances, et que vous avez terminé les tests, vous pouvez basculer votre application pour utiliser Spanner au lieu de votre base de données MySQL source.

Vous pouvez effectuer une migration de données en direct après avoir créé votre base de données Spanner cible. Vous devez créer un schéma compatible sur votre base de données cible avant de migrer les données.

Fonctionnement

La migration de données en direct se compose des deux phases suivantes :

  • Migration par remplissage :

    • Lors de la migration de backfill, Dataflow lit les données existantes de votre base de données MySQL source et les migre vers la base de données Spanner cible. Vous devez utiliser un modèle Dataflow de migration groupée pour déplacer les données de votre instance MySQL source vers Spanner.
    • Lorsque la migration de backfill ne parvient pas à écrire une ligne dans Spanner, elle l'écrit dans un répertoire de file d'attente de lettres mortes (DLQ) d'un bucket Cloud Storage. Vous pouvez demander à ce que la migration de remplissage tente à nouveau d'écrire ces lignes dans Spanner.

  • Migration de la capture des données modifiées (CDC) :

    • Cette phase s'exécute simultanément avec la migration de backfill, en capturant en temps réel les modifications apportées à l'instance MySQL source. Ces modifications sont ensuite appliquées à Spanner une fois la migration de remplissage terminée.
    • Vous devez utiliser Datastream pour capturer en temps réel les modifications apportées à votre instance MySQL source et les écrire dans un bucket Cloud Storage.
    • Une fois la migration de backfill terminée, vous devez utiliser Dataflow pour déplacer la CDC du bucket Cloud Storage vers Spanner. Si Dataflow ne parvient pas à écrire une ligne dans Spanner pour une raison quelconque, il l'écrit dans un répertoire DLQ d'un autre bucket Cloud Storage. La migration CDC tente automatiquement d'écrire les lignes du répertoire DLQ dans Spanner.

Planifier la migration de données à chaud

Vous devez configurer l'infrastructure réseau requise pour que les données circulent entre votre instance MySQL source, Datastream, Dataflow, les buckets Cloud Storage et la base de données Spanner cible. Nous vous recommandons de configurer une connectivité réseau privée pour une migration sécurisée. En fonction des exigences de conformité de votre organisation, vous devrez peut-être configurer une connectivité réseau publique ou privée. Pour en savoir plus sur la connectivité Datastream, consultez Options de connectivité réseau.

Pour planifier la migration des données en direct, vous devrez peut-être demander à l'administrateur réseau de votre organisation d'effectuer les tâches suivantes :

  • Utilisez le VPC par défaut ou créez un VPC dans votre projet en respectant les exigences suivantes :
    • L'instance MySQL source doit être disponible sur ce VPC. Vous devrez peut-être créer une règle de pare-feu de sortie sur ce VPC et une règle de pare-feu d'entrée sur le VPC où se trouve l'instance MySQL source.
    • Datastream, les buckets Dataflow et Cloud Storage, ainsi que la base de données Spanner cible doivent être disponibles sur ce VPC.
    • Vous devez créer une liste d'autorisation sur votre instance MySQL source pour autoriser les connexions depuis le VPC.
  • Déterminez et allouez une plage d'adresses IP dans le VPC que Datastream peut utiliser.
  • Créez un sous-réseau dans le VPC pour que Dataflow puisse effectuer la migration de remplissage.
  • Créez un sous-réseau dans le VPC que Dataflow utilisera pour effectuer la migration CDC ultérieurement.

Pour effectuer une migration de données en direct, procédez comme suit :

  1. Configurer la migration CDC.
  2. Effectuez la migration par remplissage.
  3. Effectuez la migration CDC une fois la migration de remplissage terminée.
  4. Surveillez et corrigez les erreurs liées à la CDC.
  5. Terminez la migration CDC.

La migration de données en direct nécessite le déploiement et la gestion d'un nombre important de ressources. Spanner fournit deux exemples de modèles Terraform pour chaque phase de la migration de données en direct.

Le modèle de migration à chaud effectue la migration CDC en deux phases :

  • Configurez la migration CDC vers un bucket Cloud Storage à l'aide de Datastream. Vous pouvez utiliser une variable Terraform pour empêcher le modèle de créer les jobs Dataflow.
  • Migrez le CDC vers Spanner à partir du bucket Cloud Storage à l'aide de Dataflow. Vous ne devez effectuer cette phase qu'une fois que le modèle Terraform de migration du remplissage est terminé.

Le modèle Terraform de migration de remplissage effectue la migration de remplissage de votre instance MySQL source vers Spanner.

Avant de commencer

  • Assurez-vous que Terraform est installé sur votre shell local.
  • Créez un compte de service pour exécuter la migration des données en direct. Pour en savoir plus sur la création d'un compte de service, consultez Créer des comptes de service.

  • Pour vous assurer que le compte de service dispose des autorisations nécessaires pour effectuer une migration à chaud, demandez à votre administrateur d'accorder les rôles IAM suivants au compte de service de votre projet :

    Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

    Ces rôles prédéfinis contiennent les autorisations requises pour effectuer une migration à chaud. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

    Autorisations requises

    Les autorisations suivantes sont requises pour effectuer une migration à chaud :

    • compute.globalAddresses.create
    • compute.globalAddresses.createInternal
    • compute.globalAddresses.createInternal
    • compute.globalAddresses.delete
    • compute.globalAddresses.deleteInternal
    • compute.globalAddresses.get
    • compute.globalOperations.get
    • compute.networks.addPeering
    • compute.networks.get
    • compute.networks.listPeeringRoutes
    • compute.networks.removePeering
    • compute.networks.use
    • compute.routes.get
    • compute.routes.list
    • compute.subnetworks.get
    • compute.subnetworks.list
    • dataflow.jobs.cancel
    • dataflow.jobs.create
    • dataflow.jobs.updateContents
    • datastream.connectionProfiles.create
    • datastream.connectionProfiles.delete
    • datastream.privateConnections.create
    • datastream.privateConnections.delete
    • datastream.streams.create
    • datastream.streams.delete
    • datastream.streams.update
    • iam.roles.get
    • iam.serviceAccounts.actAs
    • pubsub.subscriptions.create
    • pubsub.subscriptions.delete
    • pubsub.topics.attachSubscription
    • pubsub.topics.create
    • pubsub.topics.delete
    • pubsub.topics.getIamPolicy
    • pubsub.topics.setIamPolicy
    • resourcemanager.projects.setIamPolicy
    • storage.buckets.create
    • storage.buckets.delete
    • storage.buckets.update
    • storage.objects.delete

    Votre administrateur peut également attribuer au compte de service ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Configurer la migration CDC

Spanner propose un modèle Terraform pour configurer la CDC, puis effectuer la migration CDC. Vous pouvez utiliser une variable Terraform pour empêcher le modèle de créer les jobs Dataflow. Le modèle Terraform déploie et gère les ressources suivantes pour configurer la migration CDC :

  • Connexion privée Datastream : une connexion privée Datastream est déployée sur votre VPC configuré.

  • Profil de connexion Datastream source : profil de connexion qui permet à Datastream de se connecter à votre instance MySQL source.

  • Bucket Cloud Storage : bucket Cloud Storage dans lequel Datastream écrit les données.

  • Profil de connexion Datastream cible : ce profil de connexion permet à Datastream de se connecter au bucket Cloud Storage et d'y écrire des données.

  • Flux Datastream : flux Datastream qui lit les données de votre instance MySQL source et les écrit dans le bucket Cloud Storage tel que défini dans les profils de connexion.

  • Sujet et abonnement Pub/Sub : le bucket Cloud Storage envoie des notifications d'objets au sujet Pub/Sub, et Dataflow utilise l'abonnement Pub/Sub pour écrire des données dans Spanner.

  • Notifications de bucket Cloud Storage : notification de bucket Cloud Storage qui publie dans le sujet Pub/Sub.

Préparer la configuration Terraform pour le CDC

Vous pouvez préparer le modèle Terraform pour inclure les configurations de variables Dataflow, mais désactiver la création de jobs Dataflow :

common_params = {
  project = "PROJECT_ID"
  region  = "GCP_REGION"
}
datastream_params = {
  mysql_host = "MYSQL_HOST_IP_ADDRESS"
  mysql_username = "MYSQL_USERNAME"
  mysql_password = "MYSQL_PASSWORD"
  mysql_port     = 3306
  mysql_database = {
    database = "DATABASE_NAME"
  }
  private_connectivity = {
    vpc_name = "VPC_NAME"
    range = "RESERVED_RANGE"
  }
}
dataflow_params = {
  skip_dataflow = false
  enable_backfill = false
  template_params = {
    spanner_database_id = "SPANNER_DATABASE_ID"
    spanner_instance_id = "SPANNER_INSTANCE_ID"
  }
  runner_params = {
    max_workers = 10
    num_workers = 4
    on_delete   = "cancel"
    network     = "VPC_NETWORK"
    subnetwork  = "SUBNETWORK_NAME"
  }
}

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet Google Cloud .
  • GCP_REGION : région Google Cloud dans laquelle vous souhaitez exécuter le job Dataflow.
  • MYSQL_HOST_IP_ADDRESS : adresse IP de votre instance MySQL source.
  • MYSQL_USERNAME : nom d'utilisateur de votre instance MySQL source.
  • MYSQL_PASSWORD : mot de passe de votre instance MySQL source.
  • DATABASE_NAME : nom de votre base de données MySQL source dans l'instance.
  • VPC_NAME : nom d'un VPC existant utilisé par Datastream.
  • RESERVED_RANGE : plage d'adresses IP sur le VPC que vous avez réservée pour Datastream.
  • SPANNER_DATABASE_ID : ID de la base de données Spanner cible.
  • SPANNER_INSTANCE_ID : ID de l'instance Spanner cible.
  • VPC_NETWORK : nom d'un VPC existant utilisé par Dataflow.
  • SUBNETWORK_NAME : nom du sous-réseau désigné dans le VPC où Dataflow crée des nœuds de calcul.

Exécuter le modèle Terraform CDC

Pour effectuer la migration CDC, vous devez exécuter le modèle Terraform :

  1. Initialisez Terraform à l'aide de la commande suivante : 

      terraform init

  2. Validez les fichiers Terraform à l'aide de la commande suivante : 

      terraform plan --var-file=terraform_simple.tfvars

  3. Exécutez la configuration Terraform à l'aide de la commande suivante : 

      terraform apply --var-file=terraform_simple.tfvars

    La configuration Terraform produit un résultat semblable à celui-ci : 

    Outputs:
resource_ids = {
  "datastream_source_connection_profile" = "source-mysql-thorough-wombat"
  "datastream_stream" = "mysql-stream-thorough-wombat"
  "datastream_target_connection_profile" = "target-gcs-thorough-wombat"
  "gcs_bucket" = "live-migration-thorough-wombat"
  "pubsub_subscription" = "live-migration-thorough-wombat-sub"
  "pubsub_topic" = "live-migration-thorough-wombat"
}
resource_urls = {
  "datastream_source_connection_profile" = "https://console.cloud.google.com/datastream/connection-profiles/locations/us-central1/instances/source-mysql-thorough-wombat?project=your-project-here"
  "datastream_stream" = "https://console.cloud.google.com/datastream/streams/locations/us-central1/instances/mysql-stream-thorough-wombat?project=your-project-here"
  "datastream_target_connection_profile" = "https://console.cloud.google.com/datastream/connection-profiles/locations/us-central1/instances/target-gcs-thorough-wombat?project=your-project-here"
  "gcs_bucket" = "https://console.cloud.google.com/storage/browser/live-migration-thorough-wombat?project=your-project-here"
  "pubsub_subscription" = "https://console.cloud.google.com/cloudpubsub/subscription/detail/live-migration-thorough-wombat-sub?project=your-project-here"
  "pubsub_topic" = "https://console.cloud.google.com/cloudpubsub/topic/detail/live-migration-thorough-wombat?project=your-project-here"
}

Datastream diffuse désormais le CDC dans un bucket Cloud Storage. Vous devez effectuer la migration par remplissage et terminer la migration CDC ultérieurement.

Effectuer la migration par remplissage

Spanner propose un modèle Terraform pour effectuer la migration de remplissage. Le modèle Terraform déploie et gère la ressource suivante :

  • Job Dataflow : job Dataflow qui lit les données de l'instance MySQL source et les écrit dans la base de données Spanner cible.

Préparer la configuration Terraform de la migration de backfill

job_name = "JOB_NAME"
project = "PROJECT_ID"
region = "GCP_REGION"
working_directory_bucket = "WORKING_DIRECTORY_BUCKET"
working_directory_prefix = "WORKING_DIRECTORY_PREFIX"
source_config_url = "SOURCE_CONFIG_URL"
username = "USERNAME"
password = "PASSWORD"
instance_id = "SPANNER_INSTANCE_ID"
database_id  = "SPANNER_DATABASE_ID"
spanner_project_id = "SPANNER_PROJECT_ID"

Remplacez les éléments suivants :

  • JOB_NAME : nom du job Dataflow.
  • PROJECT_ID : ID du projet Google Cloud dans lequel le job Dataflow est exécuté.
  • GCP_REGION : région Google Cloud dans laquelle vous souhaitez exécuter le job Dataflow.
  • WORKING_DIRECTORY_BUCKET : bucket Cloud Storage pour importer le fichier de session et créer le répertoire de sortie.
  • WORKING_DIRECTORY_PREFIX : préfixe du bucket Cloud Storage pour le répertoire de travail Dataflow.
  • SOURCE_CONFIG_URL : adresse IP de votre instance MySQL source.
  • USERNAME : nom d'utilisateur de votre instance MySQL source.
  • PASSWORD : mot de passe de votre instance MySQL source.
  • SPANNER_INSTANCE_ID : ID de l'instance Spanner cible.
  • SPANNER_DATABASE_ID : ID de la base de données Spanner cible.
  • SPANNER_PROJECT_ID : ID du projet dans lequel réside votre instance Spanner. Cet ID de projet peut être différent de celui dans lequel vous exécutez Dataflow.

Exécuter le modèle Terraform de migration de remplissage

Pour effectuer la migration du remplissage, procédez comme suit :

  1. Initialisez Terraform à l'aide de la commande suivante : 

      terraform init

  2. Validez les fichiers Terraform à l'aide de la commande suivante : 

      terraform plan --var-file=terraform_simple.tfvars

  3. Exécutez la configuration Terraform à l'aide de la commande suivante : 

      terraform apply --var-file=terraform_simple.tfvars

    La configuration Terraform produit un résultat semblable à celui-ci : 

    Apply complete! Resources: 1 added, 0 changed, 0 destroyed.
Outputs:
dataflow_job_id = [
  "2024-06-05_00_41_11-4759981257849547781",
]
dataflow_job_url = [
  "https://console.cloud.google.com/dataflow/jobs/gcp-region/2024-06-05_00_41_11-4759981257849547781",
]

Lorsque la migration de remplissage ne peut pas écrire une ligne dans Spanner, elle l'écrit dans un répertoire de file d'attente de lettres mortes d'un bucket Cloud Storage.

Vous pouvez réessayer d'écrire ces lignes du répertoire de la file d'attente de lettres mortes dans Spanner avant de terminer la migration CDC.

Pour réessayer d'écrire ces lignes à partir du répertoire de la file d'attente des messages non distribués dans Spanner avant de terminer la migration CDC, exécutez la commande suivante :

gcloud dataflow flex-template run JOB_NAME \
    --project=PROJECT_ID \
    --region=GCP_REGION \
    --template-file-gcs-location=gs://dataflow-templates/latest/flex/Cloud_Datastream_to_Spanner \
    --additional-experiments=use_runner_v2 \
    --parameters inputFilePattern=INPUT_FILE_PATTERN,\
      streamName="ignore",\
      datastreamSourceType=SOURCE_TYPE,\
      instanceId=INSTANCE_ID,databaseId=DATABASE_ID,sessionFilePath=SESSION_FILE_PATH,\
      deadLetterQueueDirectory=DLQ_DIRECTORY,\
      runMode="retryDLQ"

Remplacez les éléments suivants :

  • JOB_NAME : nom du job Dataflow.
  • PROJECT_ID : ID du projet Google Cloud dans lequel le job Dataflow est exécuté.
  • GCP_REGION : région Google Cloud dans laquelle vous souhaitez exécuter le job Dataflow.
  • INPUT_FILE_PATTERN : emplacement du bucket Cloud Storage du modèle de fichier d'entrée.
  • SOURCE_TYPE : type de la base de données source (par exemple, mysql).
  • INSTANCE_ID : ID de l'instance Spanner cible.
  • DATABASE_ID : ID de la base de données Spanner cible.
  • SESSION_FILE_PATH : chemin d'accès Cloud Storage au fichier de session généré par l'outil de migration Spanner.
  • DLQ_DIRECTORY : chemin d'accès Cloud Storage au répertoire racine de la file d'attente de lettres mortes contenant les fichiers d'erreur à réessayer (par exemple, gs://MIGRATION_BUCKET/ENV/SERVICE/cdc/DB_SCHEMA/).

Effectuer la migration CDC

Une fois la migration de backfill terminée, vous pouvez utiliser Dataflow pour migrer la CDC vers Spanner. Le job Dataflow récupère les événements de modification du bucket Cloud Storage et les écrit dans Spanner.

Pour effectuer la migration CDC, remplacez la valeur du paramètre Terraform skip_dataflow par false et réexécutez le modèle Terraform de migration à chaud.

Exécutez la configuration Terraform à l'aide de la commande suivante : 

      terraform apply --var-file=terraform_simple.tfvars

Surveiller et résoudre les erreurs de CDC

Lors de la réplication de capture de données modifiées (CDC) en direct de MySQL vers Spanner, si votre job Dataflow en flux continu ne peut pas écrire un événement de modification dans Spanner, il classe l'échec dans l'une des deux catégories d'erreur et écrit l'enregistrement dans un répertoire DLQ du bucket Cloud Storage deadLetterQueueDirectory :

  • Erreurs pouvant être relancées : défaillances temporaires, qui incluent, sans s'y limiter, les éléments suivants :

    • Erreurs de dépassement de délai Spanner
    • Non-respect des contraintes de clé étrangère et de table entrelacée. Cela peut se produire lorsqu'une ligne enfant arrive avant sa ligne parente en raison d'erreurs réseau ou d'un traitement parallèle.

    Dataflow écrit ces événements dans un répertoire DLQ retry/ et les relance dans le même pipeline jusqu'à ce qu'ils réussissent ou dépassent la limite maximale de nouvelles tentatives.

  • Erreurs graves : échecs permanents qui ne peuvent pas être résolus par des nouvelles tentatives automatisées. Voici quelques exemples :

    • Erreurs de conversion des types de données
    • Cas de non-conformité liés à l'index unique
    • Exceptions dans les fichiers JAR de transformation personnalisée

    Dataflow écrit ces événements dans un répertoire DLQ severe/ et incrémente le compteur d'utilisateurs personnalisé Total permanent errors.

Comme les erreurs graves ne peuvent pas être résolues par des nouvelles tentatives automatisées, Dataflow supprime ces événements ayant échoué du flux de réplication actif et les enregistre dans le répertoire severe/. Si vous ne les traitez pas, ces enregistrements seront manquants dans votre base de données Spanner de destination. Surveillez régulièrement le compteur Total permanent errors et le répertoire severe/ pendant la migration à chaud afin de pouvoir résoudre et rejouer les événements de modification ayant échoué avant de lancer le basculement de l'application.

Notez que le compteur personnalisé Dataflow Total permanent errors est une métrique cumulative qui enregistre le nombre total d'erreurs graves rencontrées depuis le début du job de streaming. Lorsque vous rejouez et résolvez les enregistrements ayant échoué à l'aide d'un job de réessai de DLQ, ce compteur de votre pipeline de streaming d'origine ne diminue pas. Par conséquent, votre répertoire DLQ de gravité élevée Cloud Storage (gs://.../severe/) est la source d'informations fiable pour déterminer si des erreurs non traitées existent.

Relire les enregistrements ayant échoué

Lorsque des enregistrements ayant échoué s'affichent dans votre répertoire DLQ de gravité élevée, inspectez les fichiers d'erreur JSON dans Cloud Storage, identifiez la cause première et résolvez le problème sous-jacent dans Spanner (par exemple, en insérant manuellement les enregistrements parents manquants ou en mettant à jour les mappages de remplacement du schéma).

Pour relire les enregistrements de la file d'attente de lettres mortes corrigés dans Spanner, lancez un nouveau job Dataflow en utilisant l'un des modes d'exécution de nouvelle tentative de la file d'attente de lettres mortes suivants :

  • Mode retryDLQ : exécutez ce mode en tant que job par lot en parallèle de votre pipeline de streaming actif pour traiter les fichiers d'erreur dans le répertoire severe/ sans interrompre la réplication CDC en direct.
  • Mode retryAllDLQ : si votre pipeline de traitement en flux continu habituel est arrêté, utilisez ce mode pour traiter les répertoires retry/ et severe/. N'exécutez pas retryAllDLQ en même temps qu'un pipeline actif, car cela entraînerait des conflits de fichiers et de traitement.

Pour lancer un job de nouvelle tentative DLQ à l'aide de la gcloud CLI, exécutez la commande suivante :

gcloud dataflow flex-template run RETRY_JOB_NAME \
    --project=PROJECT_ID \
    --region=GCP_REGION \
    --template-file-gcs-location=gs://dataflow-templates/latest/flex/Cloud_Datastream_to_Spanner \
    --additional-experiments=use_runner_v2 \
    --parameters streamName="ignore",\
datastreamSourceType=SOURCE_TYPE,\
instanceId=INSTANCE_ID,databaseId=DATABASE_ID,sessionFilePath=SESSION_FILE_PATH,\
deadLetterQueueDirectory=DLQ_DIRECTORY,\
runMode="retryDLQ"

Remplacez les éléments suivants :

  • RETRY_JOB_NAME : nom du job de nouvelle tentative de DLQ Dataflow.
  • PROJECT_ID : ID du projet Google Cloud dans lequel le job Dataflow s'exécute.
  • GCP_REGION : Google Cloud région dans laquelle vous souhaitez exécuter le job Dataflow.
  • SOURCE_TYPE : type de la base de données source (par exemple, mysql).
  • INSTANCE_ID : ID de l'instance Spanner cible.
  • DATABASE_ID : ID de la base de données Spanner cible.
  • SESSION_FILE_PATH : chemin d'accès Cloud Storage au fichier de session généré par l'outil de migration Spanner.
  • DLQ_DIRECTORY : chemin d'accès Cloud Storage au répertoire racine de la file d'attente de lettres mortes contenant les fichiers d'erreur à réessayer (par exemple, gs://MIGRATION_BUCKET/ENV/SERVICE/cdc/DB_SCHEMA/).

Terminer la migration CDC

Une fois que la quasi-totalité des données du bucket Cloud Storage a été écrite dans Spanner, arrêtez les opérations d'écriture sur l'instance MySQL source pour permettre d'écrire les modifications restantes dans Spanner.

Cela entraîne un court temps d'arrêt pendant que Spanner rattrape l'instance MySQL source. Une fois toutes les modifications écrites dans Spanner, votre application peut commencer à utiliser Spanner comme base de données.

Pour obtenir des instructions détaillées sur la suspension des écritures d'application, la vidange des données en cours de transfert et le basculement d'application, consultez Effectuer le basculement depuis MySQL.

Étapes suivantes