Atualizar a versão principal do banco de dados no local

Nesta página, descrevemos como fazer upgrade da versão principal do banco de dados fazendo upgrade da instância do Cloud SQL no local, em vez de migrar os dados.

Introdução

Os provedores de software de banco de dados lançam periodicamente novas versões principais que contêm novos recursos, melhorias de desempenho e melhorias de segurança. O Cloud SQL recebe novas versões após o lançamento delas. Depois que o Cloud SQL passar a oferecer suporte para uma nova versão principal, será possível fazer upgrade das instâncias para manter o banco de dados atualizado.

Para fazer upgrade da versão do banco de dados de uma instância no local, basta migrar os dados. Os upgrades no local são uma maneira mais simples de fazer upgrade da versão principal da instância. Não é necessário migrar os dados ou mudar as strings de conexão do aplicativo. Com os upgrades no local, é possível manter o nome, o endereço IP e outras configurações da instância atual após o upgrade. Os upgrades no local não exigem a movimentação de arquivos de dados e podem ser concluídos mais rapidamente. Em alguns casos, o tempo de inatividade é menor do que o exigido pela migração de dados.

Para o MySQL 8.0.15 e versões anteriores, a operação de upgrade no local do MySQL usa o utilitário mysql_upgrade. No MySQL 8.0.16 e versões mais recentes, a operação de upgrade no local do MySQL é processada pelo processo MySQL server. Para mais informações sobre a operação de upgrade no local, consulte O que o processo de upgrade do MySQL faz upgrade.

Planejar um upgrade da versão principal

  1. Escolha uma versão principal de destino.

    gcloud

    Para informações sobre como instalar e dar os primeiros passos com a CLI gcloud, consulte Instalar a CLI gcloud. Para mais informações sobre como iniciar o Cloud Shell, consulte Usar o Cloud Shell.

    Para verificar as versões do banco de dados que podem ser segmentadas para um upgrade no local da sua instância, faça o seguinte:

    1. Execute o comando a seguir.
      2. gcloud sql instances describe INSTANCE_NAME

      Substitua INSTANCE_NAME pelo nome da instância.

    2. Na saída do comando, localize a seção identificada como upgradableDatabaseVersions.
    3. Cada subseção retorna uma versão do banco de dados disponível para upgrade. Em cada subseção, revise os seguintes campos.
      • majorVersion: a versão principal que pode ser segmentada para o upgrade no local.
      • name: a string da versão do banco de dados que inclui a versão principal. No Cloud SQL para MySQL, esse campo também inclui a versão secundária do banco de dados.
      • displayName: o nome de exibição da versão do banco de dados.

    REST v1

    Para verificar quais versões do banco de dados de destino estão disponíveis para um upgrade no local de uma versão principal, use o método instances.get da API Cloud SQL Admin.

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • INSTANCE_NAME: o nome da instância.

    Método HTTP e URL: 

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

    Para enviar a solicitação, expanda uma destas opções:

    Você receberá uma resposta JSON semelhante a esta:

    
upgradableDatabaseVersions:

{
  major_version: "MYSQL_8_0"
  name: "MYSQL_8_0_36"
  display_name: "MySQL 8.0.36"
}

    REST v1beta4

    Para verificar quais versões do banco de dados de destino estão disponíveis para os principais upgrades de versão no local de uma instância, use o Método instances.get da API Cloud SQL Admin.

    Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

    • INSTANCE_NAME: o nome da instância.

    Método HTTP e URL: 

    GET https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME

    Para enviar a solicitação, expanda uma destas opções:

    Você receberá uma resposta JSON semelhante a esta:

    
upgradableDatabaseVersions:

{
  major_version: "MYSQL_8_0"
  name: "MYSQL_8_0_36"
  display_name: "MySQL 8.0.36"
}

    Para ver a lista completa das versões de bancos de dados com suporte do Cloud SQL, consulte Versões do banco de dados e políticas de versão.

  2. Considere os recursos oferecidos em cada versão principal do banco de dados e as incompatibilidades de endereço.

    As novas versões principais apresentam alterações incompatíveis que podem exigir que você modifique o código do aplicativo, o esquema ou as configurações do banco de dados. Antes de fazer upgrade da instância do banco de dados, analise as notas da versão principal de destino para determinar as incompatibilidades que você precisa resolver.

    Depois do upgrade para uma versão posterior, o valor padrão de algumas variáveis do sistema pode mudar. Por exemplo, o valor padrão de character_set_server no MySQL 5.6 e MySQL 5.7 é utf8. Quando você faz upgrade para o MySQL 8.0, o valor padrão de character_set_server muda para utf8mb4. Para reverter para utf8, é necessário alterar manualmente o valor da flag do banco de dados para o valor antigo. Consulte Configurar sinalizações do banco de dados para mais informações. A maioria das mudanças de valor padrão é feita pela comunidade do MySQL. Saiba mais em Padrões do servidor de upgrade.

  3. Se você estiver fazendo upgrade do MySQL 8.0 para o 8.4, primeiro faça upgrade das instâncias para o MySQL 8.0.37 ou mais recente antes de fazer upgrade para o MySQL 8.4. Para fazer o upgrade da versão secundária, consulte Fazer upgrade da versão secundária do banco de dados.

  4. Faça a pré-verificação para upgrades.

    • Se você estiver fazendo upgrade do MySQL 5.7 para o 8.0, realize uma pré-verificação para upgrades do MySQL 5.7 para o 8.0. Use o utilitário Checker do upgrade no shell do MySQL.

    • Se você estiver fazendo upgrade do MySQL 8.0 para o 8.4, realize uma pré-verificação para upgrades do MySQL 8.0 para o 8.4. Use o utilitário Checker do upgrade no shell do MySQL.

      Se algum problema for encontrado durante a pré-verificação, corrija-o antes de prosseguir para o upgrade. O Cloud SQL não é compatível com a pré-verificação durante um upgrade de versão principal. Uma tentativa de fazer upgrade de uma instância que falhou na pré-verificação também pode falhar.

  5. Verifique se há espaço em disco e tipos de máquinas de instância.

    Um upgrade de versão principal requer recursos adicionais, como espaço em disco, para armazenar tabelas atualizadas. Se o espaço em disco não for suficiente, o upgrade falhará e será revertido. Para fazer upgrade do MySQL 5.7 para o 8.0, é necessário ter mais memória para converter metadados antigos no novo dicionário de dados. Antes de executar um upgrade de versão principal, verifique se há mais de 100 mil de memória para cada tabela. É possível aumentar temporariamente a memória mudando o tipo de máquina.

  6. Para upgrades do MySQL 5.7 para o MySQL 8.0, verifique se houve mudanças na concessão de usuários no MySQL 8.0.

    O Cloud SQL para MySQL versão 8.0 usa uma flag chamada partial_revokes, que é definida como ON por padrão. Ao contrário do MySQL 5.7, essa flag remove o recurso de uso de caracteres curinga em comandos GRANT do banco de dados. Para garantir que os usuários do banco de dados tenham acesso aos esquemas de banco de dados corretos, modifique os privilégios de usuário do banco de dados antes de fazer upgrade para o MySQL 8.0. Atualize os privilégios do usuário para usar o nome completo dos esquemas de banco de dados necessários em vez de usar caracteres curinga.

    Para mais informações sobre como essa sinalização funciona no MySQL 8.0, consulte partial_revokes no MySQL 8.0.

  7. Teste o upgrade com uma simulação.

    Faça uma simulação do processo de upgrade de ponta a ponta em um ambiente de teste antes de fazer upgrade do banco de dados de produção. Você pode clonar sua instância para criar uma cópia idêntica dos dados em que o processo de upgrade será testado.

    Além de validar se o upgrade foi concluído com sucesso, execute testes para garantir que o aplicativo se comporta conforme o esperado no banco de dados atualizado.

  8. Escolha um horário para o upgrade.

    O upgrade exige que a instância fique indisponível por um período. Planeje o upgrade durante um período em que a atividade do banco de dados estiver baixa.

Preparar-se para um upgrade de versão principal

Antes de fazer upgrade, siga estas etapas:

  1. Para upgrades do MySQL 5.7 para 8.0 SOMENTE: verifique e corrija problemas incompatíveis encontrados durante o processo de pré-verificação. Veja alguns problemas comuns encontrados:

    1. Adição de novas palavras-chave reservadas, como RANKS, GROUPS, FUNCTION, em procedimentos armazenados, acionadores e outros objetos de banco de dados. Consulte Palavras-chave e palavras reservadas para mais informações.
    2. caracteres UTF inválidos em definições de tabela.
    3. Transições XA não confirmadas que precisam ser confirmadas (usando a instrução XA COMMIT) ou revertidas (usando a instrução XA ROLLBACK).
    4. restrição de chave externa em nomes com mais de 64 caracteres.
    5. tipo de dados espacial no índice misto de colunas. Para mais informações, consulte Tipo de dados espaciais.

    Para mais informações, consulte Como preparar a instalação para upgrade e Como fazer upgrade para o MySQL 8.0?.

    Para upgrades do MySQL 8.0 para o MySQL 8.4 SOMENTE: verifique e corrija problemas incompatíveis encontrados durante o processo de pré-verificação. Um problema comum pode ser:

    • Terminologia de replicação desatualizada. Os termos MASTER e SLAVE foram completamente removidos do MySQL 8.4. Se você ainda usar comandos ou configurações com esses termos, será necessário substituí-los ou removê-los. Para mais informações sobre a remoção e substituição desses termos, consulte O que há de novo no MySQL 8.4 desde o MySQL 8.0.
    • Atualize o plug-in de autenticação das suas contas de usuário atuais para usar o plug-in de autenticação caching_sha2_password em vez do plug-in mysql_native_password descontinuado.

      Para mudar as contas de usuário do banco de dados já existentes para que usem o plug-in de autenticação caching_sha2_password, use o seguinte comando: 
           ALTER USER 'username'@'%'
     IDENTIFIED WITH caching_sha2_password BY 'user_password';
      Substitua username e user_password pelos valores da conta de usuário que você atualizará.

  2. Verificar o espaço em disco e o tipo de máquina da instância

    Os upgrades de versão principais requerem espaço em disco e memória adicionais para armazenar as tabelas atualizadas e o novo dicionário de dados. A falta de espaço em disco necessário faz com que o upgrade falhe e reverta para a versão original. O Cloud SQL recomenda um mínimo de 100 mil memórias para cada tabela.

    Observação: você pode aumentar temporariamente a memória alterando o tipo de máquina antes de executar a atualização de versão principal. Para saber mais, consulte como alterar o tipo de máquina.

  3. Faça upgrade das réplicas de leitura.

    Se você usa réplicas de leitura, faça upgrade de todas as réplicas de leitura antes de fazer upgrade da instância principal. Se a réplica for atualizada, mas a instância principal não, a replicação poderá ser interrompida se a instância primária usar instruções ou funções que não são mais compatíveis com uma versão posterior do MySQL usada pela réplica. Para evitar esses problemas, o Cloud SQL recomenda que você:

    1. faça upgrade da principal imediatamente após o upgrade das réplicas.
    2. evite executar consultas incompatíveis com a nova versão na instância principal até que o upgrade seja concluído.
    3. Opcional: pause todas as instruções WRITE na instância principal até que o upgrade seja concluído.
    4. Opcional: remova todas as réplicas antes de fazer o upgrade da principal e recrie as réplicas assim que o upgrade for concluído.

    Se a replicação falhar, a réplica será revertida para a versão da instância principal. É possível fazer upgrade da réplica novamente, mas, se o problema persistir, consulte Perguntas frequentes.

Atualizar a versão principal do banco de dados no local

Quando você inicia uma operação de upgrade, o Cloud SQL verifica primeiro a configuração da sua instância para garantir que ela seja compatível com um upgrade. Depois de verificar a configuração, o Cloud SQL disponibiliza a instância, faz um backup pré-upgrade, executa o upgrade, disponibiliza a instância e depois faz um backup pós-upgrade.

Quando você faz upgrade para o MySQL 8.0, o Cloud SQL provisiona automaticamente sua instância na versão secundária padrão.

Console

  1. No console do Google Cloud, acesse a página Instâncias do Cloud SQL.

    Acesse Instâncias do Cloud SQL

  2. Para abrir a página Visão geral de uma instância, clique no nome dela.
  3. Clique em Editar.
  4. Na seção Informações da instância, clique no botão Fazer upgrade e confirme que você quer acessar a página de upgrade.
  5. Na página Escolha uma versão de banco de dados, clique no campo Versão do banco de dados para upgrade e selecione uma das versões principais disponíveis do banco de dados.
  6. Clique em Continuar.
  7. Na caixa ID da instância, insira o nome da instância e clique no botão Iniciar upgrade.
A consulta leva alguns minutos para ser concluída.

Verifique se a versão principal atualizada do banco de dados aparece abaixo do nome da instância na página Visão geral da instância.

gcloud

  1. Iniciar o upgrade.

    Use o comando gcloud sql instances patch com a sinalização --database-version.

    Antes de executar o comando, substitua o seguinte:

    • INSTANCE_NAME: o nome da instância
    • DATABASE_VERSION: o tipo enumerado da versão principal do banco de dados, que precisa ser superior à versão atual. Especificar uma versão do banco de dados para uma versão principal disponível como um upgrade para a instância. Esse tipo enumerado pode ser obtido como a primeira etapa para Planejar o upgrade. Se você precisar de uma lista completa de tipos enumerados de versão do banco de dados, consulte SqlDatabaseEnums.
    gcloud sql instances patch INSTANCE_NAME \
--database-version=DATABASE_VERSION

    Os upgrades das versões principais levam vários minutos para serem concluídos. Talvez você veja uma mensagem indicando que a operação está demorando mais que o esperado. Você pode ignorar essa mensagem ou executar o comando gcloud sql operations wait para dispensá-la.

  2. Recebe o nome da operação de upgrade.

    Use o comando gcloud sql operations list com a sinalização --instance.

    Antes de executar o comando, substitua a variável INSTANCE_NAME pelo nome da instância. 

    gcloud sql operations list --instance=INSTANCE_NAME

  3. Monitore o status do upgrade.

    Use o comando gcloud sql operations describe:

    Antes de executar o comando, substitua a variável OPERATION pelo nome da operação de upgrade recuperada na etapa anterior. 

    gcloud sql operations describe OPERATION

REST v1

  1. Inicie o upgrade no local.

    Use uma solicitação PATCH com o método instances:patch.

    Antes de usar qualquer um dos dados da solicitação, substitua estas variáveis:

    • PROJECT_ID: o ID do projeto
    • INSTANCE_NAME: o nome da instância

    Método HTTP e URL: 

    PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

    Corpo JSON da solicitação:

    {
  "databaseVersion": DATABASE_VERSION
}

    Substitua DATABASE_VERSION pelo tipo enumerado da versão principal do banco de dados, que precisa ser superior à versão atual. Especificar uma versão do banco de dados para uma versão principal disponível como um upgrade para a instância. Esse tipo enumerado pode ser obtido como a primeira etapa para Planejar o upgrade. Se você precisar de uma lista completa de tipos enumerados de versões do banco de dados, consulte SqlDatabaseVersion.

  2. Recebe o nome da operação de upgrade.

    Use uma solicitação GET com o método operations.list após substituir PROJECT_ID pelo ID do projeto.

    Método HTTP e URL: 

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations

  3. Monitore o status do upgrade.

    Use uma solicitação GET com o método operations.get após substituir as seguintes variáveis:

    • PROJECT_ID: o ID do projeto
    • OPERATION_NAME: o nome da operação de upgrade recuperada na etapa anterior.

    Método HTTP e URL: 

    GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operation/OPERATION_NAME

Terraform

Para atualizar a versão do banco de dados, use um recurso do Terraform e o provedor do Terraform para o Google Cloud, versão 4.34.0 ou posterior.

resource "google_sql_database_instance" "instance" {
  name             = "mysql-instance"
  region           = "us-central1"
  database_version = "MYSQL_8_0"
  settings {
    tier = "db-n1-standard-2"
  }
  # set `deletion_protection` to true, will ensure that one cannot accidentally delete this instance by
  # use of Terraform whereas `deletion_protection_enabled` flag protects this instance at the GCP level.
  deletion_protection = false
}

Aplique as alterações

Para aplicar a configuração do Terraform em um projeto do Google Cloud, conclua as etapas nas seções a seguir.

Preparar o Cloud Shell

  1. Inicie o Cloud Shell.

  2. Defina o projeto padrão do Google Cloud em que você quer aplicar as configurações do Terraform.

    Você só precisa executar esse comando uma vez por projeto, e ele pode ser executado em qualquer diretório.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    As variáveis de ambiente serão substituídas se você definir valores explícitos no arquivo de configuração do Terraform.

Preparar o diretório

Cada arquivo de configuração do Terraform precisa ter o próprio diretório, também chamado de módulo raiz.

  1. No Cloud Shell, crie um diretório e um novo arquivo dentro dele. O nome do arquivo precisa ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o arquivo é chamado de main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Se você estiver seguindo um tutorial, poderá copiar o exemplo de código em cada seção ou etapa.

    Copie o exemplo de código no main.tf recém-criado.

    Se preferir, copie o código do GitHub. Isso é recomendado quando o snippet do Terraform faz parte de uma solução de ponta a ponta.

  3. Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
  4. Salve as alterações.
  5. Inicialize o Terraform. Você só precisa fazer isso uma vez por diretório. 
    terraform init

    Opcionalmente, para usar a versão mais recente do provedor do Google, inclua a opção -upgrade: 

    terraform init -upgrade

Aplique as alterações

  1. Revise a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expectativas: 
    terraform plan

    Faça as correções necessárias na configuração.

  2. Para aplicar a configuração do Terraform, execute o comando a seguir e digite yes no prompt: 
    terraform apply

    Aguarde até que o Terraform exiba a mensagem "Apply complete!".

  3. Abra seu projeto do Google Cloud para ver os resultados. No console do Google Cloud, navegue até seus recursos na IU para verificar se foram criados ou atualizados pelo Terraform.

Excluir as alterações

Para excluir as mudanças, faça o seguinte:

  1. Para desativar a proteção contra exclusão, no arquivo de configuração do Terraform, defina o argumento deletion_protection como false. 
    deletion_protection =  "false"
  2. Para aplicar a configuração atualizada do Terraform, execute o comando a seguir e digite yes no prompt: 
    terraform apply

  1. Remova os recursos aplicados anteriormente com a configuração do Terraform executando o seguinte comando e inserindo yes no prompt:

    terraform destroy

Quando você faz uma solicitação de upgrade no local, o Cloud SQL realiza uma verificação de pré-upgrade. Se o Cloud SQL determinar que a instância não está pronta para upgrade, a solicitação de upgrade falhará com uma mensagem sugerindo como resolver o problema. Consulte também Resolver problemas com um upgrade de versão principal.

Backups automáticos de upgrade

Quando você realiza um upgrade de versão principal, o Cloud SQL faz automaticamente dois backups sob demanda, chamados de backups de upgrade:

  • O primeiro é o backup pré-upgrade, que é feito imediatamente antes do início do upgrade. É possível usar esse backup para restaurar a instância do banco de dados para o estado na versão anterior.
  • O segundo backup de upgrade é o backup de pós-upgrade, que é feito imediatamente após as novas gravações serem permitidas para a instância de banco de dados atualizada.

Quando você visualiza a lista de backups, os backups de upgrade são listados com o tipo On-demand. Os backups de upgrade são rotulados para ser possível identificá-los com rapidez. Por exemplo, se você estiver fazendo upgrade do MySQL 5.7 para o MySQL 8.0, o backup pré-upgrade será rotulado como Pre-upgrade backup, MYSQL_5_7 to MYSQL_8_0. e o pós-upgrade como Post-upgrade backup, MYSQL_8_0 from MYSQL_5_7. Se você estiver fazendo upgrade do MySQL 8.0 para o MySQL 8.4, o backup pré-upgrade será rotulado como Pre-upgrade backup, MYSQL_8_0 to MYSQL_8_4. e o pós-upgrade como Post-upgrade backup, MYSQL_8_4 from MYSQL_8_0.

Assim como acontece com outros backups sob demanda, os backups de upgrade permanecem até que você os exclua ou exclua a instância. Se a PITR estiver ativada, não será possível excluir os backups de upgrade enquanto eles estiverem na janela de retenção. Caso precise excluir seus backups de upgrade, desative a PITR ou aguarde até que os backups de upgrade não estejam mais na sua janela de retenção.

Concluir o upgrade da versão principal

Depois de terminar de fazer upgrade da instância principal, execute as seguintes etapas para concluir o upgrade:

  1. Faça testes de aceitação.

    Execute testes para confirmar se o sistema atualizado tem o desempenho esperado.

  2. Opcional: atualize os privilégios do usuário.

    Se você fez o upgrade para o MySQL 8.0, observe que ele alterou os sistemas de segurança e gerenciamento de contas. Para saber mais, consulte O que há de novo no MySQL 8.0.

    Isso pode fazer com que os usuários criados na versão 5.7 do MySQL da instância não tenham os mesmos privilégios dos usuários criados diretamente no MySQL 8.0. Por exemplo, um usuário atualizado do MySQL 5.7 pode não ter os privilégios CREATE ROLE e DROP ROLE porque esses privilégios não existiam no MySQL 5.7. O Cloud SQL recomenda que você redefina os privilégios do usuário após o upgrade das versões para corrigir problemas relacionados.

    Se você fez upgrade do MySQL 8.0 para o MySQL 8.4, há outras mudanças nos privilégios do usuário, incluindo a adição de privilégios introduzidos no MySQL 8.4 e a remoção de privilégios que existiam no MySQL 8.0. Para mais informações, consulte Privilégios de usuário do MySQL 8.4 (cloudsqlsuperuser).

    Para atualizar os privilégios de usuário no MySQL 8.0 ou no MySQL 8.4, faça o seguinte:

    1. Crie um usuário com o papel cloudsqlsuperuser concedido.

    2. Use o usuário criado para revogar todos os privilégios anteriores de um usuário que fez upgrade com:

      REVOKE ALL PRIVILEGES ON *.* FROM user@host

    3. Conceda os privilégios esperados ao usuário atualizado.

  3. Opcional: crie um backup.

    O Cloud SQL cria automaticamente um backup depois que você faz upgrade da instância principal, mas o Cloud SQL recomenda que você crie um por conta própria para recuperar o banco de dados, se necessário.

  4. Opcional: se você fez upgrade para o Cloud SQL para MySQL 8.4, atualize também todos os conectores, clientes e shells do MySQL para o MySQL 8.4.

Resolver problemas de upgrade da versão principal

O Cloud SQL retornará uma mensagem de erro se você tentar utilizar um comando de upgrade inválido, por exemplo, se a instância contiver flags de banco de dados inválidas para a nova versão.

Se a solicitação de upgrade falhar, confira a sintaxe dela. Se a solicitação tiver uma estrutura válida, tente analisar as sugestões a seguir.

Ver registros de upgrade

Se ocorrer algum problema com uma solicitação de upgrade válida, o Cloud SQL publicará registros de erro em projects/PROJECT_ID/logs/cloudsql.googleapis.com%2Fmysql.err. Cada entrada de registro contém um rótulo com o identificador da instância para ajudar você a identificá-la com o erro de upgrade. Procure esses erros de upgrade e resolva-os.

Para ver os registros de erro, siga estas etapas:

  1. No console do Google Cloud, acesse a página Instâncias do Cloud SQL.

    Acesse Instâncias do Cloud SQL

  2. Para abrir a página Visão geral de uma instância, clique no nome da instância.

  3. No painel Operações e registros da página Visão geral da instância, clique no link Verificar registros de erros do MySQL.

    A página Análise de registros é aberta.

  4. Para ver os registros, faça o seguinte:

    • Para listar todos os registros de erro em um projeto, selecione o nome do registro no filtro de registro Nome do registro.

    Para mais informações sobre filtros de consulta, confira Consultas avançadas.

    • Para filtrar os registros de erro de upgrade de uma única instância, digite a seguinte consulta na caixa Pesquisar todos os campos depois de substituir DATABASE_ID

    pelo ID do projeto, seguido do nome da instância neste formato: project_id:instance_name.

    resource.type="cloudsql_database"
resource.labels.database_id="DATABASE_ID"
logName : "projects/PROJECT_ID/logs/cloudsql.googleapis.com%2Fmysql.err"

    Por exemplo, para filtrar os registros de erro de upgrade por uma instância chamada shopping-db em execução no projeto buylots, use o seguinte filtro de consulta:

     resource.type="cloudsql_database"
 resource.labels.database_id="buylots:shopping-db"
 logName : "projects/buylots/logs/cloudsql.googleapis.com%2Fmysql.err"

Restaurar para a versão principal anterior

Se o sistema de banco de dados atualizado não tiver o desempenho esperado, talvez seja necessário restaurar sua instância para a versão anterior. Para fazer isso, restaure seu backup de pré-upgrade para uma instância de recuperação do Cloud SQL, que é uma nova instância que executa a versão de pré-upgrade.

Para restaurar a versão anterior, siga estas etapas:

  1. Identifique seu backup pré-upgrade.

    Consulte Backups automáticos de upgrade.

  2. Crie uma instância de recuperação.

    Crie uma nova instância do Cloud SQL usando a versão principal que o Cloud SQL estava executando quando foi feito o backup pré-upgrade. Defina as mesmas flags e configurações de instância usadas pela instância original.

  3. Restaure o backup pré-upgrade.

    Restaure o backup de pré-upgrade para a instância de recuperação. Esse comando pode levar alguns minutos para ser concluído.

  4. Adicione suas réplicas de leitura.

    Se você estava usando réplicas de leitura, adicione-as individualmente.

  5. Conecte o aplicativo.

    Depois de recuperar o sistema de banco de dados, atualize o aplicativo com detalhes sobre a instância de recuperação e as réplicas de leitura. É possível retomar a exibição de tráfego na versão de pré-upgrade do seu banco de dados.

Limitações

Esta seção lista as limitações para o upgrade da versão principal local.

  • Não é possível realizar um upgrade de versão principal no local em uma réplica externa.
  • O upgrade de instâncias do MySQL 5.7 para 8.0 com mais de 512.000 tabelas pode levar muito tempo e atingir o tempo limite.
  • O upgrade de instâncias do MySQL 8.0 para 8.4 com mais de 512.000 tabelas pode levar muito tempo e atingir o tempo limite.

  • Ao fazer upgrade do MySQL 8.0 para o 8.4, se você tiver atualizado uma réplica para o MySQL 8.4, mas não a instância principal, será possível criar uma nova conta de usuário em uma instância principal não atualizada com o plug-in de autenticação mysql_native_password descontinuado. Para evitar essa situação, faça upgrade da instância principal imediatamente após atualizar as réplicas ou crie apenas novas contas de usuário na instância principal usando o comando a seguir.

    CREATE USER USERNAME'@'% IDENTIFIED WITH caching_sha2_password BY 'PASSWORD';

    Substitua USERNAME e PASSWORD pelos valores apropriados.

Perguntas frequentes

As seguintes perguntas podem surgir durante o upgrade da versão principal do banco de dados.

Minha instância fica indisponível durante um upgrade?
Sim. Enquanto o Cloud SQL realiza o upgrade, a instância permanece indisponível por um período.
Quanto tempo leva um upgrade?

O upgrade de uma única instância normalmente leva menos de 10 minutos. Se a configuração da instância usar poucas vCPUs ou memória, o upgrade poderá levar mais tempo.

Se a instância hospedar muitos bancos de dados ou tabelas, ou se os bancos de dados forem muito grandes, o upgrade pode levar horas ou até mesmo expirar porque o tempo do upgrade corresponde ao número de objetos nos bancos de dados. Se você tiver várias instâncias que precisam ser atualizadas, o tempo total do upgrade aumentará proporcionalmente.

Posso monitorar cada etapa do meu processo de upgrade?
Embora o Cloud SQL permita monitorar se uma operação de upgrade ainda está em andamento, não é possível rastrear as etapas individuais de cada upgrade.
Posso cancelar meu upgrade após iniciá-lo?
Não é possível cancelar um upgrade após o início do processo. Se o upgrade falhar, o Cloud SQL recuperará automaticamente a instância na versão anterior.
O que acontece com minhas configurações durante um upgrade?

Quando você executa um upgrade de versão principal no local, o Cloud SQL mantém as configurações do banco de dados, incluindo o nome da instância, o endereço IP, os valores de flags configurados explicitamente e os dados do usuário. No entanto, o valor padrão das variáveis do sistema pode mudar. Por exemplo, o valor padrão da flag character_set_server no MySQL 5.7 é utf8. Quando você faz upgrade para o MySQL 8.0, o valor padrão da flag muda para utf8mb4. Para revertê-lo para utf8, defina o valor da flag de volta com o valor anterior.

Para saber mais, consulte Configurar flags do banco de dados. Se uma determinada flag ou um valor não for mais aceito na sua versão de destino, o Cloud SQL removerá automaticamente a flag durante o upgrade.

O que posso fazer se a replicação falhar após o upgrade da réplica?
Se a replicação falhar após o upgrade da réplica, ela será revertida para a versão do MySQL da instância principal. É possível fazer upgrade da réplica novamente, mas, se o problema persistir, a replicação poderá falhar novamente.

Se a réplica não for revertida, você terá duas opções:

  1. Exclua a réplica corrompida, crie uma nova réplica e faça upgrade da nova réplica.

    Se o upgrade falhar novamente, ele provavelmente foi causado por alterações incompatíveis adicionadas à principal quando ela foi atualizada. Resolva o problema para localizar o problema, corrija a instância principal e tente fazer upgrade da réplica. Consulte o artigo sobre solução de problemas para mais informações.

  2. Fazer upgrade da instância principal

    A operação de upgrade na instância principal recria as réplicas se a linha de execução de réplica não estiver funcionando.

Por que minha réplica atualizada foi revertida para a versão antiga?

Se um upgrade não for concluído, a réplica será revertida para a versão da instância principal. É possível fazer upgrade da réplica novamente, mas, se o problema persistir, verifique o registro mysql.err na réplica para encontrar a origem. Pesquise palavras-chave como [REPL]... failed executing transaction.... end_log_pos...; Failure Reason.

Se a mensagem de erro contiver Access denied for AuthId.... com alterações nos privilégios do usuário, provavelmente uma consulta está sendo executada usando privilégios de usuário do MySQL 5.7 em esquemas mysql e sys e pode falhar devido às alterações nos sistemas de segurança e gerenciamento de conta no MySQL 8.0. Para resolver esse problema, você precisa interromper as consultas na instância principal antes de atualizar a instância principal para a nova versão e, em seguida, tentar atualizar a réplica novamente. O Cloud SQL também recomenda que você interrompa temporariamente todas essas consultas na instância principal também antes de fazer upgrade para a nova versão, já que isso pode causar um problema semelhante.

Se o motivo da falha, como Access denied for AuthID.... nos registros do MySQL, não for exibido, é provável que o problema seja causado por novos dados incompatíveis que podem ter sido adicionados à instância principal depois do upgrade da réplica. Consulte Como se preparar para um upgrade de versão principal sobre como corrigir problemas de incompatibilidade antes de fazer o upgrade novamente.

A seguir