Migrer vers Cloud SQL à partir d'un fichier physique XtraBackup

Cette page explique comment migrer une base de données MySQL d'un serveur externe vers Cloud SQL à l'aide d'un fichier physique Percona XtraBackup pour MySQL.

Cloud SQL permet de migrer des bases de données MySQL sur des serveurs externes vers des instances Cloud SQL pour MySQL à l'aide de Percona XtraBackup. Vous générez des fichiers physiques avec l'utilitaire XtraBackup, puis les importez dans Cloud Storage. En utilisant des fichiers physiques, vous pouvez améliorer la vitesse globale de votre migration jusqu'à 10 fois par rapport à une migration standard basée sur un fichier de dump logique.

Cloud SQL est compatible avec la migration basée sur un fichier physique pour MySQL 5.7 et 8.0. MySQL 5.6 n'est pas compatible. Il n'est pas possible de migrer des bases de données Amazon RDS depuis Amazon Aurora ou MySQL. De plus, l'instance répliquée cible dans Cloud SQL pour MySQL doit être installée avec la même version majeure de MySQL que votre serveur externe. Cependant, l'instance répliquée cible peut utiliser une version mineure ultérieure. Par exemple, si votre base de données externe utilise MySQL 8.0.31, votre instance répliquée cible doit utiliser Cloud SQL pour MySQL version 8.0.31 ou ultérieure.

La procédure décrite dans ce document utilise l'API Admin Cloud SQL pour MySQL. Vous pouvez également utiliser Database Migration Service pour effectuer cette migration. Pour en savoir plus sur l'utilisation de Database Migration Service, consultez la page Migrer vos bases de données à l'aide d'un fichier physique Percona XtraBackup.

Avant de commencer

Cette section décrit la procédure à suivre avant de migrer votre base de données MySQL vers Google Cloud.

Configurer un projet Google Cloud

  1. Connectez-vous à votre compte Google Cloud. Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits gratuits pour exécuter, tester et déployer des charges de travail.

  2. Dans Google Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.

    Accéder au sélecteur de projet

  3. Vérifiez que la facturation est activée pour votre projet Google Cloud.

  4. Activez l'API Cloud SQL Admin

    Activer l'API

    5.

  5. Dans Google Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.

    Accéder au sélecteur de projet

  6. Vérifiez que la facturation est activée pour votre projet Google Cloud.

  7. Activez l'API Cloud SQL Admin

    Activer l'API

    8.

  8. Assurez-vous de disposer des rôles d'administrateur Cloud SQL, d'administrateur de l'espace de stockage et de lecteur de Compute sur votre compte utilisateur.

    Accéder à la page IAM

Configurer un bucket Cloud Storage

Si vous ne l'avez pas déjà fait, créez un bucket Cloud Storage.

Installer le SDK Google Cloud

Pour exécuter les commandes de la gcloud CLI sur votre serveur externe, installez le SDK Google Cloud.

Préparer le serveur externe pour la migration

  1. Installez l'une des versions suivantes de l'utilitaire XtraBackup sur votre serveur externe.

    Pour MySQL 8.0, vous devez installer une version de XtraBackup identique ou ultérieure à la version de votre serveur source. Pour en savoir plus, consultez la page Comparaison des versions de serveur et de sauvegarde dans la documentation de Percona XtraBackup.

  2. Assurez-vous que votre serveur externe répond à toutes les exigences nécessaires à la réplication. Pour en savoir plus, consultez la section Configurer le serveur externe pour la réplication.

    En plus des exigences liées au serveur externe pour la réplication, la migration à partir d'un fichier physique XtraBackup est soumise aux exigences suivantes :

    • Votre base de données MySQL doit être une base de données sur site ou une base de données MySQL autogérée sur une VM Compute Engine. Il n'est pas possible de migrer des bases de données Amazon RDS depuis Amazon Aurora ou MySQL.
    • Vous devez configurer le paramètre innodb_data_file_path avec un seul fichier de données portant le nom par défaut ibdata1. Si votre base de données est configurée avec deux fichiers de données ou si elle contient un fichier de données portant un nom différent, vous ne pouvez pas migrer la base de données à l'aide d'un fichier physique XtraBackup. Par exemple, il n'est pas possible de migrer une base de données configurée avec innodb_data_file_path=ibdata01:50M:autoextend.
    • Le paramètre innodb_page_size de votre base de données externe source doit être configuré avec la valeur par défaut 16384.

  3. Si ce n'est pas déjà fait, créez un compte utilisateur de réplication. Vous aurez besoin du nom d'utilisateur et du mot de passe de ce compte utilisateur.

Effectuer la migration

Effectuez toutes les étapes des sections suivantes pour migrer votre base de données MySQL externe vers Cloud SQL.

Créer et préparer le fichier physique XtraBackup

  1. Sur le serveur externe, utilisez XtraBackup pour effectuer une sauvegarde complète de la base de données source. Pour savoir comment effectuer une sauvegarde complète, consultez la page Créer une sauvegarde complète dans la documentation de Percona XtraBackup.

    Les autres types de sauvegardes, tels que les sauvegardes incrémentielles et partielles, ne sont pas acceptés.

    Exemple :

    sudo xtrabackup --backup \
--target-dir=XTRABACKUP_PATH \
--user=USERNAME \
--password=PASSWORD

    Remplacez les variables suivantes :

    • XTRABACKUP_PATH : emplacement du fichier de sauvegarde de sortie
    • USERNAME : utilisateur disposant de droits BACKUP_ADMIN sur la base de données source
    • PASSWORD : mot de passe de l'utilisateur

  2. Préparez le fichier de sauvegarde à l'aide de l'utilitaire XtraBackup. L'état du fichier doit être cohérent. Pour en savoir plus sur la préparation d'une sauvegarde complète, consultez la page Préparer une sauvegarde complète. Exemple :

    sudo xtrabackup --prepare --target-dir=XTRABACKUP_PATH

    Remplacez XTRABACKUP_PATH par l'emplacement du fichier de sauvegarde de sortie. L'exécution de cette commande peut prendre quelques minutes en fonction de la taille de votre base de données.

Importer le fichier physique XtraBackup dans Cloud Storage

Importez le fichier de sauvegarde dans Cloud Storage à l'aide de l'utilitaire gsutil.

  time gsutil -m rsync -r XTRABACKUP_PATH CLOUD_STORAGE_BUCKET

Remplacez XTRABACKUP_PATH par l'emplacement du fichier de sauvegarde de sortie et CLOUD_STORAGE_BUCKET par le chemin d'accès du bucket Cloud Storage.

La taille de vos fichiers XtraBackup n'est pas limitée. Cependant, la taille de chaque fichier que vous pouvez importer dans un bucket Cloud Storage est limitée à 5 To.

Définir l'instance de représentation source

  1. Créez un fichier source.json qui définit l'instance de représentation source de votre serveur externe. Une instance de représentation source fournit des métadonnées pour le serveur externe dans Cloud SQL.

    Dans votre fichier source.json, indiquez les informations de base suivantes concernant votre serveur externe.

    {
"name": "SOURCE_NAME",
 "region": "REGION",
 "databaseVersion": "DATABASE_VERSION",
 "onPremisesConfiguration": {
    "hostPort": "SOURCE_HOST:3306",
    "username": "REPLICATION_USER_NAME",
    "password": "REPLICATION_USER_PASSWORD",
    "dumpFilePath": "CLOUD_STORAGE_BUCKET"
    "caCertificate": "SOURCE_CERT",
    "clientCertificate": "CLIENT_CERT",
    "clientKey": "CLIENT_KEY"
  }
}
    Propriété Description
    SOURCE_NAME Nom de l'instance de représentation source à créer.
    REGION Région dans laquelle vous souhaitez que l'instance de représentation source réside. Spécifiez la région dans laquelle vous allez créer l'instance répliquée Cloud SQL cible.
    DATABASE_VERSION Version de base de donnée exécutée sur votre serveur externe. Les seules options acceptées sont MYSQL_5_7 et MYSQL_8_0.
    SOURCE_HOST Adresse IPv4 et port du serveur externe, ou adresse DNS du serveur externe. Si vous utilisez une adresse DNS, elle peut contenir jusqu'à 60 caractères.
    USERNAME Compte utilisateur de réplication sur le serveur externe.
    PASSWORD Mot de passe du compte utilisateur de réplication.
    CLOUD_STORAGE_BUCKET Nom du bucket Cloud Storage contenant le fichier physique XtraBackup.
    CLIENT_CA_CERT Certificat CA sur le serveur externe. À n'inclure que si SSL/TLS est utilisé sur le serveur externe.
    CLIENT_CERT Certificat client sur le serveur externe. Requis uniquement pour l'authentification serveur-client. À n'inclure que si SSL/TLS est utilisé sur le serveur externe.
    CLIENT_KEY Fichier de clé privée du certificat client sur le serveur externe. Requis uniquement pour l'authentification serveur-client. À n'inclure que si SSL/TLS est utilisé sur le serveur externe.

  2. Créez l'instance de représentation source en envoyant une requête à l'API Cloud SQL Admin à l'aide de la commande curl suivante. Dans les données de la requête, indiquez le fichier source.json que vous avez créé.

    gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
    --header 'Content-Type: application/json' \
    --data @./source.json \
    -X POST \
https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances
    Propriété Description
    PROJECT_ID ID de votre projet dans Google Cloud.

Identifier une instance répliquée cible

Créez un fichier qui identifie l'instance répliquée cible dans Cloud SQL pour la migration. Vous pouvez migrer des données vers une nouvelle instance en créant une instance répliquée, ou utiliser une instance Cloud SQL existante en rétrogradant une instance répliquée.

Option 1 : Créer une instance répliquée

  1. Pour créer une instance répliquée, utilisez l'exemple de fichier replica.json suivant :

    {
"name": "REPLICA_NAME",
"region": "REGION",
"databaseVersion": "DB_VERSION",
"settings": {
   "tier": "INSTANCE_TIER",
   "dataDiskSizeGb": "DISK_SIZE_GB",
   "edition": "EDITION_NAME"
},
"masterInstanceName": "SOURCE_NAME"
}
    Propriété Description
    REPLICA_NAME Nom de l'instance dupliquée Cloud SQL à créer.
    REGION Spécifiez la région que vous avez attribuée à l'instance de représentation source.
    DATABASE_VERSION Version de base de données à utiliser avec l'instance répliquée Cloud SQL. Les options pour cette version sont MYSQL_5_7 ou MYSQL_8_0. Cette version majeure de base de données doit correspondre à la version de base de données que vous avez spécifiée pour le serveur externe. Vous pouvez également spécifier une version mineure, mais celle-ci doit être identique ou ultérieure à la version installée sur le serveur externe. Pour obtenir la liste des chaînes disponibles pour MySQL, consultez la page SqlDatabaseVersion.
    INSTANCE_TIER Type de machine qui héberge votre instance répliquée. Vous devez spécifier un type de machine correspondant à l'édition de votre instance. Par exemple, si vous indiquez ENTERPRISE_PLUS dans le champ edition, vous devez spécifier un type de machine optimisé pour les performances des bases de données. Pour obtenir la liste des types de machines compatibles, consultez la section Type de machine.
    DISK_SIZE_GB Taille de l'espace de stockage pour l'instance dupliquée Cloud SQL, en Go.
    EDITION_NAME Édition Cloud SQL à utiliser pour l'instance répliquée. Les valeurs possibles sont ENTERPRISE_PLUS (MySQL 8.0 uniquement) ou ENTERPRISE.
    SOURCE_NAME Nom que vous avez attribué à l'instance de représentation source.

  2. Créez l'instance répliquée cible en envoyant une requête à l'API Cloud SQL Admin à l'aide de la commande curl suivante. Dans les données de la requête, indiquez le fichier JSON que vous avez créé.

    gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
    --header 'Content-Type: application/json' \
    --data @./replica.json \
    -X POST \
https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances
    Propriété Description
    PROJECT_ID ID de votre projet dans Google Cloud.

Option 2 : Utiliser une instance répliquée existante

  1. Assurez-vous que l'instance répliquée existante dispose au moins de la même quantité d'espace disque disponible que les fichiers physiques que vous avez importés dans le bucket Cloud Storage. L'instance doit disposer d'un espace disque suffisant pour pouvoir télécharger la même quantité de données depuis Cloud Storage.

  2. Pour utiliser une instance répliquée existante, utilisez l'exemple de fichier replica.json suivant :

    {
"demoteContext": {
    "sourceRepresentativeInstanceName": "SOURCE_NAME"
  }
}
    Propriété Description
    SOURCE_NAME Nom que vous avez attribué à l'instance de représentation source.

  3. Rétrogradez l'instance répliquée cible existante en envoyant une requête à l'API Cloud SQL Admin de rétrogradation à l'aide de la commande curl suivante. Dans les données de la requête, indiquez le fichier JSON que vous avez créé.

    gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
    --header 'Content-Type: application/json' \
    --data @./replica.json \
    -X POST \
https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/EXISTING_INSTANCE_ID/demote
    Propriété Description
    PROJECT_ID ID de votre projet dans Google Cloud.
    EXISTING_INSTANCE_ID ID de l'instance répliquée existante que vous souhaitez utiliser pour la migration.

Valider vos paramètres de migration

Vérifiez que vos instances sont correctement configurées pour la migration en exécutant la commande suivante.

gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header 'Content-Type: application/json' \
     --data '{
             "syncMode": "SYNC_MODE",
             "skipVerification": false,
             "migrationType": "PHYSICAL"
               }' \
     -X POST \
https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/REPLICA_NAME/verifyExternalSyncSettings
Propriété Description
SYNC_MODE Spécifiez offline pour configurer la migration en tant que processus ponctuel. Pour configurer la réplication continue à partir du serveur externe, spécifiez online.
PROJECT_ID ID de votre projet dans Google Cloud.
REPLICA_NAME Nom que vous avez attribué à l'instance répliquée cible.

Cette étape de validation renvoie un compte de service dans sa réponse initiale. Vous devez attribuer des autorisations Cloud Storage à ce compte de service pour poursuivre le processus de migration. Le message d'erreur "Autorisations insuffisantes" est attendu. Voici un exemple de réponse :

{
    "kind": "sql#externalSyncSettingError",
    "type": "INSUFFICIENT_GCS_PERMISSIONS",
    "detail": "Service account
              [email protected]
              is missing necessary permissions storage.objects.list and
              storage.objects.get to access Google Cloud Storage bucket"
}

Ajouter des autorisations Cloud Storage au compte de service renvoyé

Pour ajouter les autorisations requises, procédez comme suit :

  1. Dans la console Google Cloud, accédez à la page Buckets Cloud Storage.

    Accéder à la page "Buckets"

  2. Cliquez sur l'onglet Autorisations.

  3. Cliquez sur Accorder l'accès.

  4. Dans le champ Nouveaux comptes principaux, saisissez le nom du compte de service renvoyé dans la réponse de validation. Par exemple, dans l'exemple de résultat de l'étape précédente, le nom du compte de service renvoyé est [email protected].

  5. Dans la liste déroulante Sélectionner un rôle, sélectionnez le rôle Storage Object Viewer.

  6. Cliquez sur Enregistrer.

Relancer la validation

Après avoir ajouté les autorisations requises au compte de service, exécutez à nouveau l'étape de validation pour vous assurer que le compte de service a accès au bucket Cloud Storage.

L'étape de validation vérifie si les conditions suivantes sont remplies :

  • La connectivité est établie entre l'instance répliquée Cloud SQL et le serveur externe, mais seulement si la migration est continue.
  • Les droits de l'utilisateur de réplication sont suffisants.
  • Les versions sont compatibles.
  • L'instance répliquée Cloud SQL n'est pas déjà en cours de réplication.
  • Les binlogs sont activés sur le serveur externe

Si des problèmes sont détectés, Cloud SQL renvoie un message d'erreur.

Ajouter des utilisateurs à l'instance dupliquée Cloud SQL

Vous ne pouvez pas importer ni migrer de comptes utilisateur de base de données à partir du serveur externe. Si vous devez ajouter des comptes utilisateur de base de données à l'instance répliquée Cloud SQL, ajoutez-les avant de commencer la réplication. Pour en savoir plus, consultez la page Gérer les utilisateurs avec l'authentification intégrée.

Lancer la migration

Une fois la validation terminée et qu'aucune erreur n'est renvoyée, vous êtes prêt à commencer la migration. Pour migrer votre serveur externe, utilisez l'API startExternalSync.

Exécutez la commande suivante :

gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header 'Content-Type: application/json' \
     --data '{
               "syncMode": "SYNC_MODE",
               "skipVerification": false,
               "migrationType": "PHYSICAL"
              }' \
     -X POST \
https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/REPLICA_NAME/startExternalSync
Propriété Description
SYNC_MODE Spécifiez offline pour configurer la migration en tant que processus ponctuel. Pour configurer la réplication continue à partir du serveur externe, spécifiez online.
PROJECT_ID ID de votre projet dans Google Cloud.
REPLICA_NAME Nom que vous avez attribué à l'instance répliquée cible.

Surveiller la migration

Pour vérifier l'état de votre migration, procédez comme suit :

  1. Récupérez l'ID d'opération du job de migration à partir de la réponse de l'API startExternalSync. Exemple :

    {
"kind": "sql#operation",
 "targetLink": "https://sqladmin.googleapis.com/v1/projects/my-project/instances/replica-instance",
 "status": "PENDING",
 "user": "[email protected]",
 "insertTime": "******",
 "operationType": "START_EXTERNAL_SYNC",
 "name": "******",
 "targetId": "replica-instance",
 "selfLink": "https://sqladmin.googleapis.com/v1/projects/my-project/operations/OPERATION_ID",
 "targetProject": "my-project"
}

  2. Utilisez l'ID de l'opération dans la commande suivante.

    gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
    --header 'Content-Type: application/json' \
    -X GET \
https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/START_EXTERNAL_SYNC_OPERATION_ID
    Propriété Description
    PROJECT_ID ID de votre projet dans Google Cloud.
    START_EXTERNAL_SYNC_OPERATION_ID ID d'opération de votre job de migration.

Surveiller la duplication

Une fois que l'instance répliquée cible dans Cloud SQL a terminé le chargement initial des données, l'instance se connecte au serveur externe et applique toutes les mises à jour effectuées après l'exportation.

Pour surveiller l'état de la réplication, consultez la section Vérifier l'état de la réplication.

Une fois que l'instance répliquée Cloud SQL a reçu toutes les modifications du serveur externe et qu'elle ne présente pas de délai de réplication, connectez-vous à votre base de données. Exécutez les commandes de base de données appropriées pour vous assurer que le contenu est conforme aux attentes par rapport au serveur externe.

Après avoir promu l'instance répliquée cible en instance autonome, vous pouvez supprimer les fichiers physiques XtraBackup de votre bucket Cloud Storage. Conservez votre serveur externe jusqu'à la fin des validations nécessaires.

Limites

Cette section répertorie les limites du processus de migration XtraBackup :

  • Vous devez utiliser Percona XtraBackup pour sauvegarder vos données dans le bucket Cloud Storage. Aucun autre utilitaire de sauvegarde n'est accepté.
  • La migration n'est pas compatible avec les versions majeures ou mineures de bases de données antérieures. Par exemple, vous ne pouvez pas migrer de MySQL 8.0 vers la version 5.7, ou de MySQL 8.0.36 vers la version 8.0.16.
  • La migration de bases de données à partir d'un fichier physique XtraBackup n'est possible que pour les bases de données MySQL sur site ou les bases de données MySQL autogérées s'exécutant sur une VM Compute Engine. Il n'est pas possible de migrer des bases de données Amazon RDS depuis Amazon Aurora ou MySQL.
  • Vous ne pouvez effectuer la migration qu'à partir d'une sauvegarde complète. Les autres types de sauvegardes, tels que les sauvegardes incrémentielles ou partielles, ne sont pas compatibles.
  • La migration d'une base de données n'inclut pas les utilisateurs ni les droits associés à la base de données.
  • Vous devez définir le format du journal binaire sur ROW. Si vous configurez le journal binaire dans un autre format, tel que STATEMENT ou MIXED, la réplication peut échouer.
  • Cloud Storage limite la taille d'un fichier que vous pouvez importer dans un bucket à 5 To.
  • Vous ne pouvez migrer aucun plug-in depuis votre base de données externe.
  • Si vous avez configuré la haute disponibilité pour votre instance, le contrat de niveau de service ne s'applique qu'à la fin de la phase initiale de la migration. Cette phase est considérée comme terminée lorsque toutes les données des fichiers physiques XtraBackup ont été importées dans l'instance Cloud SQL.

Résoudre les problèmes

Cette section répertorie les scénarios de dépannage courants.

Échec de l'importation

Si vous rencontrez un message d'erreur semblable à Attempt 1/2: import failed lors de la migration, vous devez spécifier PHYSICAL pour migrationType lorsque vous démarrez la migration.

Si vous ne spécifiez pas de migrationType, le type par défaut est LOGICAL.

Annuler ou arrêter une migration

Si vous devez annuler ou arrêter une migration, vous pouvez exécuter la commande suivante :

gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header 'Content-Type: application/json' \
    -X POST \
https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/REPLICA_NAME/restart
Propriété Description
PROJECT_ID ID de votre projet dans Google Cloud.
REPLICA_NAME Nom que vous avez attribué à l'instance répliquée cible.

Étapes suivantes