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 não é compatível. 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.

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

Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

Acessar o seletor de projetos

Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

Ative a API Cloud SQL Admin.

Ative a API

No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

Acessar o seletor de projetos

Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

Ative a API Cloud SQL Admin.

Ative a API

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

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

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.

Exemplo:
```
sudo xtrabackup --backup \
--target-dir=XTRABACKUP_PATH \
--user=USERNAME \
--password=PASSWORD
```
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
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. Exemplo:
```
sudo xtrabackup --prepare --target-dir=XTRABACKUP_PATH
```
Substitua XTRABACKUP_PATH pelo local do arquivo de backup de saída. Esse comando pode levar alguns minutos para ser concluído, dependendo do tamanho do seu banco de dados.

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

Use o utilitário gsutil para fazer upload do arquivo de backup para o Cloud Storage.

  time gsutil -m rsync -r XTRABACKUP_PATH CLOUD_STORAGE_BUCKET

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

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.

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

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.

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

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

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

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.

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

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

Acessar buckets
Clique na guia Permissões.
Clique em Conceder acesso
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 é p703314288590-df3om0@my-project.iam.gserviceaccount.com.
No menu suspenso Selecionar um papel, escolha o papel Storage Object Viewer.
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

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.

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:

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

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

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.

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.

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.

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

Antes de começar

Configure um projeto do Google Cloud

Configure um bucket do Cloud Storage

Instalar o SDK Google Cloud

Preparar o servidor externo para a migração

Faça a migração

Crie e prepare o arquivo físico do XtraBackup

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

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

Identifique uma instância de réplica de destino

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

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

Verifique suas configurações de migração

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

Execute a verificação novamente

Adicionar usuários à réplica do Cloud SQL

Iniciar a migração

Monitorar a migração

Replicação do monitor

Limitações

Resolver problemas

Falha ao importar

Cancelar ou interromper uma migração

A seguir