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

En esta página se describe cómo migrar una base de datos 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 MySQL en servidores externos a instancias de Cloud SQL para MySQL mediante Percona XtraBackup. Genera archivos físicos con la utilidad XtraBackup y, a continuación, los sube a Cloud Storage. Si usas archivos físicos, puedes mejorar la velocidad general de la migración hasta 10 veces en comparación con una migración normal basada en archivos de volcado lógico.

Cloud SQL admite la migración física basada en archivos para MySQL 5.7 y 8.0. No se admiten MySQL 5.6 ni 8.4. No se admite la migración desde bases de datos de Amazon Aurora o MySQL en Amazon RDS. Además, la instancia de réplica de destino de Cloud SQL para MySQL debe tener instalada la misma versión principal de MySQL que tu 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, tu réplica de destino debe ser Cloud SQL para MySQL 8.0.31 o una versión posterior.

Antes de empezar

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

Configurar un Google Cloud proyecto

  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.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Cloud SQL Admin API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Cloud SQL Admin API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  8. Asegúrate de tener los roles Administrador de Cloud SQL, Administrador de Storage y Lector de Compute en tu cuenta de usuario.

    Ir a la página de gestión de identidades y accesos

  9. Configurar un segmento de Cloud Storage

    Si aún no lo has hecho, crea un segmento de Cloud Storage.

    Instala el Google Cloud SDK

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

    Preparar el servidor externo para la migración

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

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

    2. Asegúrate de que tu servidor externo cumpla todos los requisitos necesarios para la replicación. Para obtener más información, consulta Configurar 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 on-premise o una base de datos MySQL autogestionada en una VM de Compute Engine. No se admite la migración desde bases de datos de Amazon Aurora o MySQL en Amazon RDS.
      • Debe configurar el parámetro innodb_data_file_path con un solo archivo de datos que utilice 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 podrás migrar la base de datos con un archivo físico de XtraBackup. Por ejemplo, no se admite una base de datos configurada con innodb_data_file_path=ibdata01:50M:autoextend para la migración.
      • El parámetro innodb_page_size de tu base de datos externa de origen debe configurarse con el valor predeterminado 16384.
    3. Si aún no lo has hecho, crea una cuenta de usuario de replicación. Necesitarás el nombre de usuario y la contraseña de esta cuenta de usuario.

    Realizar la migración

    Sigue todos los pasos que se indican en las siguientes secciones para migrar tu base de datos MySQL externa a Cloud SQL.

    Crear y preparar el archivo físico de XtraBackup

    1. En el servidor externo, usa XtraBackup para hacer una copia de seguridad completa de la base de datos de origen. Para obtener más información sobre cómo crear una copia de seguridad completa, consulta el artículo Crear una copia de seguridad completa de la documentación de Percona XtraBackup.

      No se admiten otros tipos de copias de seguridad, como las incrementales y las parciales.

      Para mejorar el rendimiento del proceso de copia de seguridad, haga 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

      Sustituye las siguientes variables:

      • XTRABACKUP_PATH: la ubicación del archivo de copia de seguridad de salida
      • USERNAME: un usuario que tiene privilegios de BACKUP_ADMIN en la base de datos de origen
      • PASSWORD: la contraseña del usuario
      • THREADS: número de hilos que se usarán al copiar varios archivos de datos simultáneamente al crear 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 Preparar una copia de seguridad completa. Por ejemplo:

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

      Sustituye las siguientes variables:

      • XTRABACKUP_PATH: la ubicación del archivo de copia de seguridad de salida
      • MEMORY: la memoria asignada para la preparación. Especifica entre 1 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 en función del tamaño de la base de datos.

    Subir el archivo físico de XtraBackup a Cloud Storage

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

      gcloud storage rsync XTRABACKUP_PATH CLOUD_STORAGE_BUCKET --recursive
      

    Sustituye XTRABACKUP_PATH por la ubicación del archivo de copia de seguridad de salida y CLOUD_STORAGE_BUCKET por la ruta del segmento de Cloud Storage.

    No hay límite de tamaño para los archivos de XtraBackup. Sin embargo, el tamaño de cada archivo que puedes subir a un segmento de Cloud Storage está limitado a 5 TB.

    Define la instancia de representación de origen

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

      En el 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 Nombre de la instancia de representación de origen que se va a crear.
      REGION 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 La versión de la base de datos que se ejecuta en tu servidor externo. Las únicas opciones admitidas son MYSQL_5_7 y MYSQL_8_0.
      SOURCE_HOST La dirección IPv4 y el puerto del servidor externo o la dirección DNS del servidor externo. Si usas una dirección DNS, puede contener hasta 60 caracteres.
      USERNAME La cuenta de usuario de replicación del servidor externo.
      PASSWORD La contraseña de la cuenta de usuario de replicación.
      CLOUD_STORAGE_BUCKET Nombre del segmento de Cloud Storage que contiene el archivo físico de XtraBackup.
      CLIENT_CA_CERT El certificado de la AC en el servidor externo. Inclúyalo solo si se usa SSL/TLS en el servidor externo.
      CLIENT_CERT El certificado de cliente del servidor externo. Solo es necesario para la autenticación de cliente-servidor. Inclúyalo solo si se usa SSL/TLS en el servidor externo.
      CLIENT_KEY El archivo de clave privada del certificado de cliente en el servidor externo. Solo es necesario para la autenticación de cliente-servidor. Inclúyalo solo si se usa SSL/TLS en el servidor externo.
    2. Crea la instancia de representación de origen haciendo una solicitud a la API Admin de Cloud SQL con el siguiente comando curl. En los datos de la solicitud, proporciona el archivo source.json que has creado.

      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 El ID de tu proyecto en Google Cloud.

    Identificar 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 creando una réplica o usar una instancia de Cloud SQL que ya tengas degradando una réplica.

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

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

      {
      "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 Nombre de la réplica de Cloud SQL que se va a crear.
      REGION Especifica la misma región que asignaste a la instancia de representación de origen.
      DATABASE_VERSION Versión de la base de datos que se va a usar con la réplica de Cloud SQL. Las opciones de esta versión son MYSQL_5_7 o MYSQL_8_0. La versión principal de la base de datos debe coincidir con la versión de la base de datos que haya especificado para el servidor externo. También puedes especificar una versión secundaria, pero debe ser igual o posterior a la versión instalada en el servidor externo. Para ver una lista de las cadenas disponibles para MySQL, consulta SqlDatabaseVersion.
      INSTANCE_TIER El tipo de máquina que alojará tu instancia de réplica. Debes especificar un tipo de máquina que coincida con la edición de tu instancia y el tipo de arquitectura de tu servidor externo. Por ejemplo, si seleccionas ENTERPRISE_PLUS para el campo edition, debes especificar un tipo de máquina optimizado para el rendimiento de la base de datos. Para ver una lista de los tipos de máquinas admitidos, consulta Tipos de máquinas.
      DISK_SIZE_GB Tamaño de almacenamiento de la réplica de Cloud SQL, en GB.
      EDITION_NAME La edición de Cloud SQL que se va a usar en la réplica. Los valores posibles son ENTERPRISE_PLUS (solo en MySQL 8.0) o ENTERPRISE.
      SOURCE_NAME El nombre que ha asignado a la instancia de representación de la fuente.
    2. Crea la instancia réplica de destino enviando una solicitud a la API Admin de Cloud SQL con el siguiente comando curl. En los datos de la solicitud, proporcione el archivo JSON que ha creado.

      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 El ID de tu proyecto en Google Cloud.

    Opción 2: Usar una instancia de réplica

    1. Asegúrate de que la instancia de réplica tenga los siguientes atributos:

      • El mismo tipo de arquitectura (x86 o ARM) que el servidor externo.
      • Al menos la misma cantidad de espacio libre en disco que los archivos físicos que has subido al segmento de Cloud Storage. La instancia debe tener suficiente espacio en el disco para descargar la misma cantidad de datos de Cloud Storage.
    2. Para usar una instancia de réplica que ya tengas, usa el siguiente archivo replica.json de ejemplo:

      {
      "demoteContext": {
          "sourceRepresentativeInstanceName": "SOURCE_NAME"
        }
      }
      Propiedad Descripción
      SOURCE_NAME El nombre que ha asignado a la instancia de representación de la fuente.
    3. Para degradar la instancia réplica de destino, haz una solicitud a la API Admin de Cloud SQL con el siguiente comando curl. En los datos de la solicitud, proporciona el archivo JSON que has creado.

      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 El ID de tu proyecto en Google Cloud.
      EXISTING_INSTANCE_ID El ID de la instancia de réplica que quieres usar para la migración.

    Verificar la configuración de la migración

    Comprueba que tus instancias estén configuradas correctamente para la migración ejecutando 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/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 El ID de tu proyecto en Google Cloud.
    REPLICA_NAME El nombre que ha asignado a la instancia de réplica de destino.

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

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

    Añadir permisos de Cloud Storage a la cuenta de servicio devuelta

    Para añadir los permisos necesarios, sigue estos pasos:

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

      Ir a Contenedores

    2. Haz clic en la pestaña Permisos.

    3. Haz clic en Conceder acceso.

    4. En el campo Principales nuevas, escribe el nombre de la cuenta de servicio que se ha devuelto en la respuesta de verificación. Por ejemplo, en la salida de ejemplo del paso anterior, el nombre de la cuenta de servicio devuelta es p703314288590-df3om0@my-project.iam.gserviceaccount.com.

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

    6. Haz clic en Guardar.

    Volver a realizar la verificación

    Una vez que hayas añadido los permisos necesarios a la cuenta de servicio, vuelve a ejecutar el paso de verificación para asegurarte de que la cuenta de servicio tiene acceso al segmento de Cloud Storage.

    En el paso de verificación se comprueba 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 del usuario de replicación son suficientes
    • Las versiones son compatibles
    • La réplica de Cloud SQL aún no está replicando
    • Los registros binarios están habilitados en el servidor externo

    Si se detecta algún problema, Cloud SQL devuelve un mensaje de error.

    Añadir usuarios a la réplica de Cloud SQL

    No puedes importar ni migrar cuentas de usuario de bases de datos desde el servidor externo. Si necesitas añadir cuentas de usuario de base de datos a la réplica de Cloud SQL, añádelas antes de iniciar la replicación. Para obtener más información, consulta Gestionar usuarios con la autenticación integrada.

    Iniciar la migración

    Una vez que hayas completado la verificación y no se haya devuelto ningún error, podrás iniciar la migración. Para migrar tu servidor externo, usa la API startExternalSync.

    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 El ID de tu proyecto en Google Cloud.
    REPLICA_NAME El nombre que ha asignado a la instancia de réplica de destino.

    Controlar la migración

    Para comprobar el estado de la migración, puedes hacer lo siguiente:

    1. Obtén el ID de operación de la tarea de migración de la respuesta de la API startExternalSync. Por ejemplo:

      {
      "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"
      }
      
    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 El ID de tu proyecto en Google Cloud.
      START_EXTERNAL_SYNC_OPERATION_ID El ID de operación de tu tarea de migración.

    Supervisar replicación

    Cuando la instancia de réplica de destino de Cloud SQL termina de cargar los datos iniciales, se conecta al servidor externo y aplica todas las actualizaciones que se hayan realizado después de la operación de exportación.

    Para monitorizar el estado de la replicación, consulta Confirmar el estado de la replicación.

    Una vez que la réplica de Cloud SQL haya recibido todos los cambios del servidor externo y no haya ningún retraso en la réplica de Cloud SQL, conéctate a tu base de datos. Ejecuta los comandos de base de datos adecuados para asegurarte de que el contenido es el esperado en comparación con el servidor externo.

    Una vez que haya promovido la réplica de destino a una instancia independiente, puede eliminar los archivos físicos de XtraBackup del segmento de Cloud Storage. Conserva tu servidor externo hasta que se hayan completado las validaciones necesarias.

    Limitaciones

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

    • Debes usar Percona XtraBackup para crear una copia de seguridad de tus datos en el segmento de Cloud Storage. No se admiten otras utilidades de copia de seguridad.
    • No se admite la migración a versiones principales o secundarias anteriores de la base de datos. 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 a partir de un archivo físico de XtraBackup solo se admite en bases de datos MySQL on-premise o en bases de datos MySQL autogestionadas que se ejecuten en una VM de Compute Engine. No se admite la migración desde bases de datos de Amazon Aurora o MySQL en Amazon RDS.
    • Solo puedes migrar desde una copia de seguridad completa. No se admiten otros tipos de copias de seguridad, como las incrementales o las parciales.
    • La migración de bases de datos no incluye usuarios ni privilegios de bases de datos.
    • Debes definir el formato del registro binario como ROW. Si configuras el registro binario en cualquier otro formato, como STATEMENT o MIXED, es posible que la replicación falle.
    • Cloud Storage limita el tamaño de los archivos que puedes subir a un segmento a 5 TB.
    • No puedes migrar ningún complemento de tu base de datos externa.
    • Si ha configurado la alta disponibilidad para su instancia, el SLA no se aplicará hasta que se complete la fase inicial de la migración. Esta fase se considera completada cuando se han importado todos los datos de los archivos físicos de XtraBackup a la instancia de Cloud SQL.
    • No puedes migrar a una base de datos MySQL 8.4 ni desde ella.
    • No se admite la migración de bases de datos entre máquinas con diferentes tipos de arquitectura. Por ejemplo, no puedes migrar una base de datos MySQL alojada en una máquina con arquitectura ARM a una máquina con arquitectura x86.

    Solucionar problemas

    En esta sección se enumeran algunos casos habituales de solución de problemas.

    No se ha podido importar

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

    Si no especificas un migrationType, el tipo será LOGICAL de forma predeterminada.

    Cancelar o detener 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 El ID de tu proyecto en Google Cloud.
    REPLICA_NAME El nombre que ha asignado a la instancia de réplica de destino.

    Siguientes pasos