Migra a Cloud SQL desde un archivo físico de XtraBackup

MySQL   |  PostgreSQL   |  SQL Server

En esta página, se describe cómo migrar una base de datos de MySQL de un servidor externo a Cloud SQL mediante un archivo físico de Percona XtraBackup para MySQL.

Cloud SQL admite la migración de bases de datos de MySQL en servidores externos a instancias de Cloud SQL para MySQL mediante Percona XtraBackup. Puedes generar archivos físicos con la utilidad XtraBackup y, luego, subirlos a Cloud Storage. Mediante el uso de archivos físicos, puedes mejorar la velocidad general de la migración hasta 10 veces en comparación con una migración regular basada en archivos de volcado lógico.

Cloud SQL admite la migración basada en archivos físicos para MySQL 5.7 y 8.0. MySQL 5.6 y 8.4 no son compatibles. No se admite la migración desde Amazon Aurora o MySQL en las bases de datos de Amazon RDS. Además, la instancia de réplica de destino en Cloud SQL para MySQL debe instalarse con la misma versión principal de MySQL que el servidor externo. Sin embargo, la réplica de destino puede usar una versión secundaria posterior. Por ejemplo, si tu base de datos externa usa MySQL 8.0.31, la réplica de destino debe ser Cloud SQL para MySQL 8.0.31 o una versión posterior.

Nota:En el procedimiento de este documento, se usa la API de Administrador de Cloud SQL para MySQL. También puedes usar Database Migration Service para realizar esta migración. Para obtener más información sobre el uso de Database Migration Service, consulta Cómo migrar tus bases de datos con un archivo físico de Percona XtraBackup.

Antes de comenzar

En esta sección, se proporcionan los pasos que debes seguir antes de migrar tu base de datos de MySQL a Google Cloud.

Configura un proyecto de Google Cloud

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

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

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

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

4. Enable the Cloud SQL Admin API.

   Enable the API

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

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

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

7. Enable the Cloud SQL Admin API.

   Enable the API

8. Asegúrate de tener las funciones de administrador de Cloud SQL, administrador de almacenamiento y visualizador de Compute en tu cuenta de usuario.

   Ir a la página IAM

Configure un bucket de Cloud Storage

Si aún no lo hiciste, crea un bucket de Cloud Storage.

Instala el SDK de Google Cloud

Para usar los comandos de gcloud CLI en tu servidor externo, instala el SDK de Google Cloud.

Prepara el servidor externo para la migración

1. Instala una de las siguientes versiones de la utilidad XtraBackup en tu servidor externo.

   • Para MySQL 5.7, instala Percona XtraBackup 2.4.
   • Para MySQL 8.0, instala Percona XtraBackup 8.0.x.

   Para MySQL 8.0, debes instalar una versión de XtraBackup que sea igual o superior a la versión del servidor de origen. Para obtener más información, consulta la comparación de la versión del servidor y la versión de copia de seguridad en la documentación de Percona XtraBackup.

2. Asegúrate de que tu servidor externo cumpla con todos los requisitos necesarios para la replicación. Si deseas obtener más información, consulta Configura el servidor externo para la replicación.

   Además de los requisitos del servidor externo para la replicación, la migración desde un archivo físico de XtraBackup tiene los siguientes requisitos:

   • Tu base de datos MySQL debe ser una base de datos local o una base de datos MySQL autoadministrada en una VM de Compute Engine. No se admite la migración desde Amazon Aurora o MySQL en las bases de datos de Amazon RDS.
   • Debes configurar el parámetro innodb_data_file_path con un solo archivo de datos que use el nombre de archivo de datos predeterminado ibdata1. Si tu base de datos está configurada con dos archivos de datos o tiene un archivo de datos con un nombre diferente, no puedes migrar la base de datos mediante un archivo físico de XtraBackup. Por ejemplo, una base de datos configurada con innodb_data_file_path=ibdata01:50M:autoextend no es compatible con la migración.
   • El parámetro innodb_page_size en tu base de datos externa de origen debe configurarse con el valor predeterminado 16384.

3. Si aún no configuraste una, crea una cuenta de usuario de replicación. Necesitarás el nombre de usuario y la contraseña para esta cuenta de usuario.

Realice la migración

Completa todos los pasos de las siguientes secciones para migrar tu base de datos externa de MySQL a Cloud SQL.

Crea y prepara el archivo físico de XtraBackup

1. En el servidor externo, usa XtraBackup para realizar una copia de seguridad completa de la base de datos de origen. Para obtener más información sobre cómo realizar una copia de seguridad completa, consulta Crea una copia de seguridad completa en la documentación de Percona XtraBackup.

   No se admiten otros tipos de copia de seguridad, como la incremental y la parcial.

   Para mejorar el rendimiento del proceso de copia de seguridad, haz lo siguiente:

   • Copia varios archivos en paralelo durante el paso de copia de seguridad con --parallel=threads.
   • Aumenta la asignación de memoria durante el paso de preparación con --use-memory=size.

   Por ejemplo:

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

   Reemplaza las siguientes variables:

   • XTRABACKUP_PATH: la ubicación del archivo de copia de seguridad de salida
   • USERNAME: un usuario que tiene privilegios BACKUP_ADMIN en la base de datos de origen
   • PASSWORD: la contraseña del usuario
   • THREADS: Es la cantidad de subprocesos que se deben usar cuando se copian varios archivos de datos de forma simultánea mientras se crea una copia de seguridad.

2. Usa la utilidad XtraBackup para preparar el archivo de copia de seguridad. El archivo debe estar en un estado coherente. Para obtener más información sobre cómo preparar una copia de seguridad completa, consulta Prepara una copia de seguridad completa. Por ejemplo:

   sudo xtrabackup --prepare --target-dir=XTRABACKUP_PATH \
       --use-memory=MEMORY

   Reemplaza las siguientes variables:

   • XTRABACKUP_PATH: la ubicación del archivo de copia de seguridad de salida
   • MEMORY: Es la memoria asignada para la preparación. Especifica entre 1 GB y 2 GB. Para obtener más información sobre la opción -use-memory, consulta la documentación de Percona XtraBackup.

   El tiempo necesario para preparar el archivo de copia de seguridad puede variar según el tamaño de la base de datos.

Sube el archivo físico de XtraBackup a Cloud Storage

Usa la gcloud CLI para subir el archivo de copia de seguridad a Cloud Storage.

  gcloud storage rsync XTRABACKUP_PATH CLOUD_STORAGE_BUCKET --recursive
  

Reemplaza XTRABACKUP_PATH por la ubicación del archivo de copia de seguridad de salida y CLOUD_STORAGE_BUCKET por la ruta de acceso del bucket de Cloud Storage.

No hay límite para el tamaño de tus archivos de XtraBackup. Sin embargo, existe un límite de 5 TB para el tamaño de cada archivo que puedes subir a un bucket de Cloud Storage.

Define la instancia de representación de origen

1. Crea un archivo source.json que defina la instancia de representación de origen para tu servidor externo. Una instancia de representación de origen proporciona metadatos para el servidor externo en Cloud SQL.

   En tu archivo source.json, proporciona la siguiente información básica sobre tu servidor externo.

   {
   "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"
     }
   }

   Propiedad	Descripción
   SOURCE_NAME	Es el nombre de la instancia de representación de origen que se creará.
   REGION	Es la región en la que quieres que resida la instancia de representación de origen. Especifica la misma región en la que crearás la instancia de réplica de Cloud SQL de destino.
   DATABASE_VERSION	Es la versión de la base de datos que se ejecuta en el servidor externo. Las únicas opciones compatibles son MYSQL_5_7 o MYSQL_8_0.
   SOURCE_HOST	Es la dirección IPv4 y el puerto del servidor externo, o la dirección de DNS para el servidor externo. Si usas una dirección de DNS, puede contener hasta 60 caracteres.
   USERNAME	La cuenta de usuario de replicación en el servidor externo.
   PASSWORD	Es la contraseña de la cuenta de usuario de replicación.
   CLOUD_STORAGE_BUCKET	El nombre del bucket de Cloud Storage que contiene el archivo físico de XtraBackup.
   CLIENT_CA_CERT	Es el certificado de CA en el servidor externo. Solo debes incluirlo si usas SSL/TLS en el servidor externo.
   CLIENT_CERT	Es el certificado de cliente en el servidor externo. Solo es obligatorio para la autenticación del servidor y del cliente. Solo debes incluirlo si usas SSL/TLS en el servidor externo.
   CLIENT_KEY	El archivo de claves privadas para el certificado de cliente en el servidor externo. Solo es obligatorio para la autenticación del servidor y del cliente. Solo debes incluirlo si usas SSL/TLS en el servidor externo.

2. Crea la instancia de representación de origen mediante una solicitud a la API de Cloud SQL Admin con el siguiente comando de curl. En los datos de la solicitud, proporciona el archivo source.json que creaste.

   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

   Propiedad	Descripción
   PROJECT_ID	Es el ID de tu proyecto en Google Cloud.

Identifica una instancia de réplica de destino

Crea un archivo que identifique la réplica de destino en Cloud SQL para la migración. Puedes migrar datos a una instancia nueva si creas una réplica o puedes usar una instancia de Cloud SQL existente si desciende de nivel una réplica.

Opción 1: Crea una instancia de réplica

1. Para crear una instancia de réplica, usa el siguiente archivo replica.json de ejemplo:

   {
   "name": "REPLICA_NAME",
   "region": "REGION",
   "databaseVersion": "DB_VERSION",
   "settings": {
      "tier": "INSTANCE_TIER",
      "dataDiskSizeGb": "DISK_SIZE_GB",
      "edition": "EDITION_NAME"
   },
   "masterInstanceName": "SOURCE_NAME"
   }

   Propiedad	Descripción
   REPLICA_NAME	Es el nombre de la réplica de Cloud SQL que se creará.
   REGION	Especifica la misma región que asignaste a la instancia de representación de origen.
   DATABASE_VERSION	Es la versión de la base de datos que se usará con la réplica de Cloud SQL. Las opciones para esta versión son MYSQL_5_7 o MYSQL_8_0. Esta versión principal de la base de datos debe coincidir con la versión de la base de datos que especificaste para el servidor externo. También puedes especificar una versión secundaria, pero esta debe ser igual o posterior a la instalada en el servidor externo. Si quieres obtener una lista de las cadenas disponibles para MySQL, consulta SqlDatabaseVersion.
   INSTANCE_TIER	Es el tipo de máquina para alojar tu instancia de réplica. Debes especificar un tipo de máquina que coincida con la edición de tu instancia. Por ejemplo, si especificas ENTERPRISE_PLUS para el campo edition, debes especificar un tipo de máquina db-perf-optimized. Para obtener una lista de los tipos de máquinas compatibles, consulta Tipos de máquinas.
   DISK_SIZE_GB	Es el tamaño de almacenamiento de la réplica de Cloud SQL, en GB. Importante: Debes especificar un tamaño de almacenamiento mayor que el tamaño del archivo físico que subiste a Cloud Storage.
   EDITION_NAME	Es la edición de Cloud SQL que se usará para la réplica. Los valores posibles son ENTERPRISE_PLUS (solo MySQL 8.0) o ENTERPRISE.
   SOURCE_NAME	Es el nombre que asignaste a la instancia de representación de origen.

2. Crea la instancia de réplica de destino mediante una solicitud a la API de Cloud SQL Admin con el siguiente comando de curl. En los datos de la solicitud, proporciona el archivo JSON que creaste.

   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

   Propiedad	Descripción
   PROJECT_ID	Es el ID de tu proyecto en Google Cloud.

Opción 2: Usa una instancia de réplica existente

1. Asegúrate de que la instancia de réplica existente tenga al menos la misma cantidad libre de espacio en el disco que los archivos físicos que subiste al bucket de Cloud Storage. La instancia debe tener suficiente disco para descargar la misma cantidad de datos de Cloud Storage.

2. Para usar una instancia de réplica existente, usa el siguiente archivo replica.json de ejemplo:

   {
   "demoteContext": {
       "sourceRepresentativeInstanceName": "SOURCE_NAME"
     }
   }

   Propiedad	Descripción
   SOURCE_NAME	Es el nombre que asignaste a la instancia de representación de origen.

3. Para descender de nivel la instancia de réplica de destino existente, realiza una solicitud a la API de Administrador de Cloud SQL de nivel de baja con el siguiente comando de curl. En los datos de la solicitud, proporciona el archivo JSON que creaste.

   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

   Propiedad	Descripción
   PROJECT_ID	Es el ID de tu proyecto en Google Cloud.
   EXISTING_INSTANCE_ID	El ID de la instancia de réplica existente que deseas usar para la migración.

Verifica la configuración de la migración

Ejecuta el siguiente comando a fin de verificar que tus instancias estén configuradas de forma correcta para la migración.

Importante: En el campo migrationType, debes especificar el valor PHYSICAL. Si no especificas este valor, la verificación fallará.

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

Propiedad	Descripción
SYNC_MODE	Especifica offline para configurar la migración como un proceso único. Para configurar la replicación continua desde el servidor externo, especifica online.
PROJECT_ID	Es el ID de tu proyecto en Google Cloud.
REPLICA_NAME	El nombre que asignaste a la instancia de réplica de destino.

Como respuesta inicial, este paso de verificación muestra una cuenta de servicio. Debes proporcionar a esta cuenta de servicio permisos de Cloud Storage para continuar con el proceso de migración. Se espera que aparezca el mensaje de error de permisos insuficientes. A continuación, se muestra una respuesta de ejemplo:

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

Agrega permisos de Cloud Storage a la cuenta de servicio que se muestra

Para agregar los permisos necesarios, haz lo siguiente:

1. En la consola de Google Cloud, ve a la página Buckets de Cloud Storage.

   Ir a Buckets

2. Haz clic en la pestaña Permisos.

3. Haz clic en Otorgar acceso.

4. En el campo Principales nuevas, escribe el nombre de la cuenta de servicio que se muestra en la respuesta de verificación. Por ejemplo, en el resultado de muestra del paso anterior, el nombre de la cuenta de servicio que se muestra es [e-mail].

5. En el menú desplegable Seleccionar un rol, selecciona el rol Storage Object Viewer.

6. Haz clic en Guardar.

Vuelve a ejecutar la verificación

Después de agregar los permisos necesarios a la cuenta de servicio, vuelve a ejecutar el paso de verificación para asegurarte de que la cuenta de servicio tenga acceso al bucket de Cloud Storage.

El paso de verificación comprobará lo siguiente:

• La conectividad entre la réplica de Cloud SQL y el servidor externo está presente, pero solo si la migración es continua
• Los privilegios de usuario de replicación son suficientes
• Las versiones son compatibles
• La réplica de Cloud SQL aún no se replica
• Los binlogs están habilitados en el servidor externo

Si se detectan problemas, Cloud SQL muestra un mensaje de error.

Agrega usuarios a la réplica de Cloud SQL

Nota: Si no necesitas agregar ninguna cuenta de usuario de base de datos a la réplica de Cloud SQL, puedes omitir este paso.

No puedes importar ni migrar cuentas de usuario de base de datos desde el servidor externo. Si necesitas agregar cuentas de usuario de base de datos a la réplica de Cloud SQL, agrégalas antes de comenzar la replicación. Para obtener más información, consulta Administra usuarios con autenticación integrada.

Inicia la migración

Después de completar la verificación y que no se muestren errores, estarás listo para comenzar la migración. Para migrar tu servidor externo, usa la API startExternalSync.

Importante: En el campo migrationType, debes especificar el valor PHYSICAL. Si no especificas este valor, la migración fallará.

Usa el siguiente comando:

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

Propiedad	Descripción
SYNC_MODE	Especifica offline para configurar la migración como un proceso único. Para configurar la replicación continua desde el servidor externo, especifica online.
PROJECT_ID	Es el ID de tu proyecto en Google Cloud.
REPLICA_NAME	El nombre que asignaste a la instancia de réplica de destino.

Supervisa la migración

Para verificar el estado de tu migración, puedes hacer lo siguiente:

1. Recupera el ID de operación del trabajo de migración de la respuesta de la API de startExternalSync. Por ejemplo:

   {
   "kind": "sql#operation",
    "targetLink": "https://sqladmin.googleapis.com/v1/projects/my-project/instances/replica-instance",
    "status": "PENDING",
    "user": "[e-mail]",
    "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. Usa el ID de operación en el siguiente comando.

   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

   Propiedad	Descripción
   PROJECT_ID	Es el ID de tu proyecto en Google Cloud.
   START_EXTERNAL_SYNC_OPERATION_ID	El ID de operación de tu trabajo de migración.

Supervisar replicación

Cuando la instancia de réplica de destino en Cloud SQL finaliza la carga de datos inicial, la instancia se conecta al servidor externo y aplica todas las actualizaciones que se realizaron después de la operación de exportación.

Para supervisar el estado de la replicación, consulta Confirma el estado de replicación.

Una vez que la réplica de Cloud SQL reciba todos los cambios del servidor externo y no exista demora de replicación en la réplica de Cloud SQL, conéctate a la base de datos. Ejecuta los comandos de base de datos adecuados para asegurarte de que el contenido sea el esperado en comparación con el servidor externo.

Después de ascender la réplica de destino a una instancia independiente, puedes borrar los archivos físicos de XtraBackup en el bucket de Cloud Storage. Conserva tu servidor externo hasta que se realicen las validaciones necesarias.

Limitaciones

En esta sección, se enumeran las limitaciones del proceso de migración de XtraBackup:

• Debes usar Percona XtraBackup para hacer una copia de seguridad de los datos en el bucket de Cloud Storage. No se admiten otras utilidades de copias de seguridad.
• La migración no es compatible con versiones principales o secundarias de bases de datos anteriores. Por ejemplo, no puedes migrar de MySQL 8.0 a 5.7 ni de MySQL 8.0.36 a 8.0.16.
• La migración de bases de datos desde un archivo físico de XtraBackup solo es compatible con las bases de datos locales de MySQL o una base de datos MySQL autoadministrada que se ejecuta en una VM de Compute Engine. No se admite la migración desde Amazon Aurora o MySQL en las bases de datos de Amazon RDS.
• Solo puedes migrar desde una copia de seguridad completa. No se admiten otros tipos de copia de seguridad, como las copias de seguridad incrementales o parciales.
• La migración de la base de datos no incluye usuarios ni privilegios de la base de datos.
• Debes configurar el formato de registro binario como ROW. Si configuras el registro binario en cualquier otro formato, como STATEMENT o MIXED, la replicación podría fallar.
• Cloud Storage limita el tamaño de un archivo que puedes subir a un bucket a 5 TB.
• No puedes migrar complementos desde tu base de datos externa.
• Si configuraste la alta disponibilidad para tu instancia, el ANS no se aplicará hasta que se complete la fase inicial de la migración. Esta fase se considera completa cuando todos los datos de los archivos físicos de XtraBackup se importaron a la instancia de Cloud SQL.
• No puedes migrar a una base de datos de MySQL 8.4 ni desde ella.

Solucionar problemas

En esta sección, se enumeran las situaciones comunes de solución de problemas.

No se pudo importar

Si encuentras un mensaje de error similar a Attempt 1/2: import failed cuando migras, debes especificar PHYSICAL para el migrationType cuando inicias la migración.

Si no especificas un migrationType, el tipo predeterminado es LOGICAL.

Cancela o detén una migración

Si necesitas cancelar o detener una migración, puedes ejecutar el siguiente comando:

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

Propiedad	Descripción
PROJECT_ID	Es el ID de tu proyecto en Google Cloud.
REPLICA_NAME	El nombre que asignaste a la instancia de réplica de destino.

¿Qué sigue?

• Asciende la réplica a una instancia principal
• Agrega réplicas de lectura a tu instancia
• Configura tu instancia para que tenga alta disponibilidad (HA).