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

MySQL | PostgreSQL | SQL Server

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 et 8.4 ne sont pas compatibles. 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.

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

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Cloud SQL Admin API.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Cloud SQL Admin API.

Enable the API

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 Google Cloud SDK

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

Préparer le serveur externe pour la migration

Installez l'une des versions suivantes de l'utilitaire XtraBackup sur votre serveur externe.
- Pour MySQL 5.7, installez Percona XtraBackup 2.4.
- Pour MySQL 8.0, installez Percona XtraBackup 8.0.x.
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.
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.
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

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.

Pour améliorer les performances du processus de sauvegarde, procédez comme suit :
- Copiez plusieurs fichiers en parallèle lors de l'étape de sauvegarde à l'aide de --parallel=threads.
- Augmentez l'allocation de mémoire pendant l'étape de préparation à l'aide de --use-memory=size.
Exemple :
```
sudo xtrabackup --backup \
--target-dir=XTRABACKUP_PATH \
--user=USERNAME \
--password=PASSWORD \
--parallel=THREADS
```
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
- THREADS : nombre de threads à utiliser lors de la copie simultanée de plusieurs fichiers de données pendant la création d'une sauvegarde
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 \
    --use-memory=MEMORY
```
Remplacez les variables suivantes :
- XTRABACKUP_PATH : emplacement du fichier de sauvegarde de sortie
- MEMORY : mémoire allouée pour la préparation. Spécifiez de 1 Go à 2 Go. Pour en savoir plus sur l'option -use-memory, consultez la documentation de Percona XtraBackup.
Le temps nécessaire à la préparation du fichier de sauvegarde peut varier en fonction de la taille de la base de données.

Importer le fichier physique XtraBackup dans Cloud Storage

Importez le fichier de sauvegarde dans Cloud Storage à l'aide de gcloud CLI.

  gcloud storage rsync XTRABACKUP_PATH CLOUD_STORAGE_BUCKET --recursive

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

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.

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

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. Important : Vous devez spécifier une taille d'espace de stockage supérieure à celle du fichier physique que vous avez importé dans Cloud Storage.
`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.

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

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.
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.

Propriété	Description
`SOURCE_NAME`	Nom que vous avez attribué à l'instance de représentation source.

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
              p703314288590-df3om0@my-project.iam.gserviceaccount.com
              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 :

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

Accéder à la page "Buckets"
Cliquez sur l'onglet Autorisations.
Cliquez sur Accorder l'accès.
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 p703314288590-df3om0@my-project.iam.gserviceaccount.com.
Dans la liste déroulante Sélectionner un rôle, sélectionnez le rôle Storage Object Viewer.
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 :

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": "user@example.com",
 "insertTime": "******",
 "operationType": "START_EXTERNAL_SYNC",
 "name": "******",
 "targetId": "replica-instance",
 "selfLink": "https://sqladmin.googleapis.com/v1/projects/my-project/operations/OPERATION_ID",
 "targetProject": "my-project"
}

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.
Vous ne pouvez pas migrer vers ou depuis une base de données MySQL 8.4.

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.