Migrar para o Cloud SQL a partir de um arquivo físico do XtraBackup

MySQL   |  PostgreSQL   |  SQL Server

Nesta página, descrevemos como migrar um banco de dados MySQL de um servidor externo para o Cloud SQL usando um arquivo físico do Percona XtraBackup for MySQL.

O Cloud SQL aceita a migração de bancos de dados MySQL em servidores externos para instâncias do Cloud SQL para MySQL usando o Percona XtraBackup. Você gera arquivos físicos com o utilitário XtraBackup e faz upload deles no Cloud Storage. Ao usar arquivos físicos, é possível melhorar a velocidade geral da migração em até 10 vezes em comparação com uma migração normal baseada em arquivos de despejo lógico.

O Cloud SQL é compatível com a migração física baseada em arquivos para o MySQL 5.7 e 8.0. O MySQL 5.6 e 8.4 não são compatíveis. A migração do Amazon Aurora ou do MySQL em bancos de dados do Amazon RDS não é compatível. Além disso, a instância de réplica de destino no Cloud SQL para MySQL precisa ser instalada com a mesma versão principal do MySQL que o servidor externo. No entanto, a réplica de destino pode usar uma versão secundária posterior. Por exemplo, se o banco de dados externo estiver usando o MySQL 8.0.31, a réplica de destino precisará ser do Cloud SQL para MySQL versão 8.0.31 ou posterior.

Observação: o procedimento neste documento usa a API Cloud SQL para MySQL Admin. Também é possível usar o Database Migration Service para realizar essa migração. Para mais informações sobre como usar o Database Migration Service, consulte Migrar seus bancos de dados usando um arquivo físico do Percona XtraBackup.

Antes de começar

Nesta seção, apresentamos as etapas que você precisa seguir antes de migrar seu banco de dados MySQL para o Google Cloud.

Configure um projeto do 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. Verifique se você tem os papéis "Administrador" do Cloud SQL, "Administrador do Storage" e "Leitor do Compute" na conta de usuário.

   Acessar a página IAM

Configure um bucket do Cloud Storage

Se ainda não tiver feito isso, crie um bucket do Cloud Storage.

Instalar o SDK Google Cloud

Para usar os comandos da gcloud CLI no servidor externo, instale o SDK do Google Cloud.

Preparar o servidor externo para a migração

1. Instale uma das seguintes versões do utilitário XtraBackup no seu servidor externo.

   • Para MySQL 5.7, instale o Percona XtraBackup 2.4.
   • Para MySQL 8.0, instale o Percona XtraBackup 8.0.x.

   Para o MySQL 8.0, instale uma versão do XtraBackup igual ou superior à versão do servidor de origem. Para mais informações, consulte Comparação entre versões de servidor e de backup na documentação do Percona XtraBackup.

2. Verifique se o servidor externo atende a todos os requisitos necessários para replicação. Para mais informações, acesse Configurar o servidor externo para replicação.

   Além dos requisitos do servidor externo para replicação, a migração de um arquivo físico do XtraBackup tem os seguintes requisitos:

   • O banco de dados MySQL precisa ser local ou autogerenciado em uma VM do Compute Engine. A migração do Amazon Aurora ou do MySQL em bancos de dados do Amazon RDS não é compatível.
   • Você precisa configurar o parâmetro innodb_data_file_path com apenas um arquivo de dados que use o nome de arquivo de dados padrão ibdata1. Se o banco de dados estiver configurado com dois arquivos de dados ou tiver um arquivo de dados com um nome diferente, não será possível migrar o banco de dados usando um arquivo físico do XtraBackup. Por exemplo, um banco de dados configurado com innodb_data_file_path=ibdata01:50M:autoextend não é compatível com a migração.
   • O parâmetro innodb_page_size no banco de dados externo de origem precisa ser configurado com o valor padrão 16384.

3. Se você ainda não tiver configurado uma, crie uma conta de usuário de replicação. Você precisará do nome de usuário e da senha dessa conta de usuário.

Faça a migração

Conclua todas as etapas nas seções a seguir para migrar seu banco de dados MySQL externo para o Cloud SQL.

Crie e prepare o arquivo físico do XtraBackup

1. No servidor externo, use o XtraBackup para fazer um backup completo do banco de dados de origem. Para mais informações sobre como fazer um backup completo, consulte Criar um backup completo na documentação do Percona XtraBackup.

   Outros tipos de backup, como os incrementais e parciais, não são compatíveis.

   Para melhorar o desempenho do processo de backup, faça o seguinte:

   • Copie vários arquivos em paralelo durante a etapa de backup usando --parallel=threads
   • Aumente a alocação de memória durante a etapa de preparação usando --use-memory=size.

   Por exemplo:

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

   Substitua as seguintes variáveis:

   • XTRABACKUP_PATH: o local do arquivo de backup de saída.
   • USERNAME: um usuário que tem privilégios BACKUP_ADMIN no banco de dados de origem.
   • PASSWORD: a senha do usuário
   • THREADS: o número de linhas de execução que serão usadas ao copiar vários arquivos de dados simultaneamente durante a criação de um backup.

2. Use o utilitário XtraBackup para preparar o arquivo de backup. O arquivo precisa estar em um estado consistente. Para mais informações sobre como preparar um backup completo, consulte Preparar um backup completo. Por exemplo:

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

   Substitua as seguintes variáveis:

   • XTRABACKUP_PATH: o local do arquivo de backup de saída.
   • MEMORY: a memória alocada para preparação. Especifique de 1 GB a 2 GB. Para mais informações sobre a opção -use-memory, consulte a documentação do Percona XtraBackup (link em inglês).

   O tempo necessário para preparar o arquivo de backup pode variar dependendo do tamanho do banco de dados.

Faça upload do arquivo físico XtraBackup para o Cloud Storage

Use a gcloud CLI para fazer upload do arquivo de backup para o Cloud Storage.

  gcloud storage rsync XTRABACKUP_PATH CLOUD_STORAGE_BUCKET --recursive
  

Substitua XTRABACKUP_PATH pelo local do arquivo de backup de saída e CLOUD_STORAGE_BUCKET pelo caminho do bucket do Cloud Storage.

Não há limite para o tamanho dos seus arquivos do XtraBackup. No entanto, há um limite de 5 TB para o tamanho de cada arquivo que pode ser enviado para um bucket do Cloud Storage.

Definir a instância de representação de origem

1. Crie um arquivo source.json que defina a instância de representação de origem do servidor externo. Uma instância de representação de origem fornece metadados para o servidor externo no Cloud SQL.

   No arquivo source.json, forneça as seguintes informações básicas sobre o 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"
     }
   }

   Propriedade	Descrição
   SOURCE_NAME	O nome da instância de representação de origem a ser criada.
   REGION	A região onde você quer que a instância de representação de origem resida. Especifique a mesma região em que você criará a instância de réplica do Cloud SQL de destino.
   DATABASE_VERSION	A versão do banco de dados em execução no seu servidor externo. As únicas opções aceitas são MYSQL_5_7 ou MYSQL_8_0.
   SOURCE_HOST	O endereço IPv4 e a porta do servidor externo ou do endereço DNS do servidor externo. Se você usar um endereço DNS, ele poderá conter até 60 caracteres.
   USERNAME	A conta do usuário de replicação no servidor externo.
   PASSWORD	A senha da conta de usuário da replicação.
   CLOUD_STORAGE_BUCKET	O nome do bucket do Cloud Storage que contém o arquivo físico do XtraBackup.
   CLIENT_CA_CERT	O certificado de CA no servidor externo. Inclua somente se SSL/TLS for usado no servidor externo.
   CLIENT_CERT	O certificado do cliente no servidor externo. Necessário apenas para autenticação servidor-cliente. Inclua somente se SSL/TLS for usado no servidor externo.
   CLIENT_KEY	O arquivo de chave privada do certificado do cliente no servidor externo. Necessário apenas para autenticação servidor-cliente. Inclua somente se SSL/TLS for usado no servidor externo.

2. Crie a instância de representação de origem fazendo uma solicitação à API Cloud SQL Admin com o comando curl a seguir. Nos dados da solicitação, forneça o arquivo source.json que você criou.

   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

   Propriedade	Descrição
   PROJECT_ID	O ID do seu projeto no Google Cloud.

Identifique uma instância de réplica de destino

Crie um arquivo que identifique a réplica de destino no Cloud SQL para a migração. É possível migrar dados para uma nova instância criando uma réplica ou usar uma instância existente do Cloud SQL rebaixando uma réplica.

Opção 1: criar uma instância de réplica

1. Para criar uma instância de réplica, use o arquivo de exemplo replica.json a seguir:

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

   Propriedade	Descrição
   REPLICA_NAME	O nome da réplica do Cloud SQL a ser criada.
   REGION	Especifique a mesma região atribuída à instância de representação de origem.
   DATABASE_VERSION	A versão do banco de dados a ser usada com a réplica do Cloud SQL. As opções para essa versão são MYSQL_5_7 ou MYSQL_8_0. Essa versão principal do banco de dados precisa corresponder à versão do banco de dados especificada para o servidor externo. Também é possível especificar uma versão secundária, que precisa ser igual ou posterior à instalada no servidor externo. Para ver uma lista de strings disponíveis para MySQL, consulte SqlDatabaseVersion.
   INSTANCE_TIER	O tipo de máquina para hospedar a instância da réplica. Especifique um tipo de máquina que corresponda à edição da sua instância. Por exemplo, se você especificar ENTERPRISE_PLUS no campo edition, será necessário especificar um tipo de máquina db-perf-optimized. Para uma lista de tipos de máquina compatíveis, consulte Tipos de máquina.
   DISK_SIZE_GB	O tamanho de armazenamento da réplica do Cloud SQL, em GB. Importante: especifique um tamanho de armazenamento maior que o tamanho do arquivo físico que você fez upload para o Cloud Storage.
   EDITION_NAME	A edição do Cloud SQL a ser usada para a réplica. Os valores possíveis são ENTERPRISE_PLUS (somente MySQL 8.0) ou ENTERPRISE.
   SOURCE_NAME	O nome atribuído à instância de representação de origem.

2. Crie a instância de réplica de destino fazendo uma solicitação à API Cloud SQL Admin com o comando curl a seguir. Nos dados da solicitação, forneça o arquivo JSON criado.

   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

   Propriedade	Descrição
   PROJECT_ID	O ID do seu projeto no Google Cloud.

Opção 2: usar uma instância de réplica atual

1. Verifique se a instância de réplica atual tem pelo menos a mesma quantidade de espaço livre em disco que os arquivos físicos enviados ao bucket do Cloud Storage. A instância precisa ter disco suficiente para fazer o download da mesma quantidade de dados do Cloud Storage.

2. Para usar uma instância de réplica atual, use o arquivo de exemplo replica.json a seguir:

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

   Propriedade	Descrição
   SOURCE_NAME	O nome atribuído à instância de representação de origem.

3. Rebaixe a instância de réplica de destino atual fazendo uma solicitação à API Cloud SQL Admin com o comando curl a seguir. Nos dados da solicitação, forneça o arquivo JSON que você criou.

   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

   Propriedade	Descrição
   PROJECT_ID	O ID do seu projeto no Google Cloud.
   EXISTING_INSTANCE_ID	O ID da instância de réplica atual que você quer usar para a migração.

Verifique suas configurações de migração

Verifique se as instâncias estão configuradas corretamente para a migração executando o comando a seguir.

Importante :no campo migrationType, especifique o valor PHYSICAL. Se você não especificar esse valor, a verificação vai falhar.

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

Propriedade	Descrição
SYNC_MODE	Especifique offline para configurar a migração como um processo único. Para configurar a replicação contínua do servidor externo, especifique online.
PROJECT_ID	O ID do seu projeto no Google Cloud.
REPLICA_NAME	O nome atribuído à instância da réplica de destino.

Como resposta inicial, esta etapa de verificação retorna uma conta de serviço. Forneça a essa conta de serviço as permissões do Cloud Storage para continuar o processo de migração. A mensagem de erro de permissões insuficientes é esperada. Veja a seguir um exemplo de resposta:

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

Adicionar permissões do Cloud Storage à conta de serviço retornada

Para adicionar as permissões necessárias, faça o seguinte:

1. No console do Google Cloud, acesse a página Buckets do Cloud Storage.

   Acessar buckets

2. Clique na guia Permissões.

3. Clique em Conceder acesso

4. No campo Novos principais, digite o nome da conta de serviço retornada na resposta da verificação. Por exemplo, na amostra de saída da etapa anterior, o nome da conta de serviço retornada é [e-mail].

5. No menu suspenso Selecionar um papel, escolha o papel Storage Object Viewer.

6. Clique em Salvar.

Execute a verificação novamente

Depois de adicionar as permissões necessárias à conta de serviço, execute novamente a etapa de verificação para garantir que a conta de serviço tenha acesso ao bucket do Cloud Storage.

A etapa de verificação confere o seguinte:

• A conectividade entre a réplica do Cloud SQL e o servidor externo está presente, mas somente se a migração for contínua
• Os privilégios de usuário de replicação são suficientes
• As versões são compatíveis
• A réplica do Cloud SQL ainda não está replicando
• Os registros binários estão ativados no servidor externo

Se algum problema for detectado, o Cloud SQL retornará uma mensagem de erro.

Adicionar usuários à réplica do Cloud SQL

Observação: se você não precisar adicionar nenhuma conta de usuário do banco de dados à réplica do Cloud SQL, pule esta etapa.

.

Não é possível importar ou migrar contas de usuário do banco de dados do servidor externo. Se for necessário adicionar contas de usuário do banco de dados à réplica do Cloud SQL, adicione as contas antes de iniciar a replicação. Para mais informações, consulte Gerenciar usuários com a autenticação integrada.

Iniciar a migração

Depois de concluir a verificação e nenhum erro for retornado, estará pronto para iniciar a migração. Para migrar o servidor externo, use a API startExternalSync.

Importante :no campo migrationType, especifique o valor PHYSICAL. Se você não especificar esse valor, a migração vai falhar.

Use o comando a seguir:

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

Propriedade	Descrição
SYNC_MODE	Especifique offline para configurar a migração como um processo único. Para configurar a replicação contínua do servidor externo, especifique online.
PROJECT_ID	O ID do seu projeto no Google Cloud.
REPLICA_NAME	O nome atribuído à instância da réplica de destino.

Monitorar a migração

Para verificar o status da migração, faça o seguinte:

1. Recupere o ID da operação do job de migração na resposta da API startExternalSync. Por exemplo:

   {
   "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. Use o ID da operação no comando a seguir.

   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

   Propriedade	Descrição
   PROJECT_ID	O ID do seu projeto no Google Cloud.
   START_EXTERNAL_SYNC_OPERATION_ID	O ID da operação do job de migração.

Replicação do monitor

Quando a instância de réplica de destino no Cloud SQL concluir o carregamento de dados inicial, a instância se conectará ao servidor externo e aplicará todas as atualizações feitas após a operação de exportação.

Para monitorar o status da replicação, consulte Confirmar o status da replicação.

Depois que a réplica do Cloud SQL receber todas as alterações do servidor externo e não houver atraso de replicação na réplica do Cloud SQL, conecte-se ao seu banco de dados. Execute os comandos adequados do banco de dados para garantir que o conteúdo seja o esperado em comparação com o servidor externo.

Depois de promover a réplica de destino a uma instância independente, exclua os arquivos físicos do XtraBackup no bucket do Cloud Storage. Retenha seu servidor externo até que as validações necessárias sejam concluídas.

Limitações

Esta seção lista as limitações do processo de migração do XtraBackup:

• Use o Percona XtraBackup para fazer backup dos dados para o bucket do Cloud Storage. Outros utilitários de backup não são compatíveis.
• A migração não é suportada para versões principais ou secundárias anteriores do banco de dados. Por exemplo, não é possível migrar do MySQL 8.0 para o 5.7 ou do MySQL 8.0.36 para o 8.0.16.
• A migração de um arquivo físico XtraBackup só é compatível com bancos de dados MySQL locais ou um banco de dados MySQL autogerenciado em execução em uma VM do Compute Engine. A migração do Amazon Aurora ou do MySQL em bancos de dados do Amazon RDS não é compatível.
• Só é possível migrar de um backup completo. Outros tipos de backup, como backups incrementais ou parciais, não são compatíveis.
• A migração de banco de dados não inclui usuários ou privilégios dele.
• Defina o formato do registro binário como ROW. Se você configurar o registro binário para qualquer outro formato, como STATEMENT ou MIXED, a replicação pode falhar.
• O Cloud Storage limita a 5 TB o tamanho de um arquivo que pode ser enviado para um bucket.
• Não é possível migrar plug-ins do seu banco de dados externo.
• Se você configurou a alta disponibilidade para a instância, o SLA não será aplicado até que a fase inicial da migração seja concluída. Essa fase é considerada concluída quando todos os dados dos arquivos físicos do XtraBackup foram importados para a instância do Cloud SQL.
• Não é possível migrar de ou para um banco de dados MySQL 8.4.

Resolver problemas

Esta seção lista cenários de solução de problemas comuns.

Falha ao importar

Se você encontrar uma mensagem de erro semelhante a Attempt 1/2: import failed ao migrar, será necessário especificar PHYSICAL para o migrationType ao iniciar a migração.

Se você não especificar um migrationType, o tipo será definido como LOGICAL por padrão.

Cancelar ou interromper uma migração

Se você precisar cancelar ou interromper uma migração, execute o seguinte 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

Propriedade	Descrição
PROJECT_ID	O ID do seu projeto no Google Cloud.
REPLICA_NAME	O nome atribuído à instância da réplica de destino.

A seguir

• Promova a réplica a uma instância principal
• Adicione réplicas de leitura à instância.
• Configure sua instância para alta disponibilidade (HA, na sigla em inglês).