Tutorial de atualização no local de Aurora MySQL - Amazon Aurora
Descobrir os motivos das falhas de atualizaçãoSolução de problemas para atualização no local de Aurora MySQLLimpeza pós-upgrade do Aurora MySQL versão 3

Tutorial de atualização no local de Aurora MySQL

Os exemplos do Linux a seguir mostram como você pode executar as etapas gerais do procedimento de atualização no local usando AWS CLI.

Este primeiro exemplo cria um cluster de banco de dados do Aurora que está executando uma versão 2.x do Aurora MySQL. O cluster inclui uma instância de banco de dados de gravador e uma instância de banco de dados de leitor. O comando wait db-instance-available pausa até que a instância de banco de dados do gravador esteja disponível. Esse é o ponto em que o cluster está pronto para ser atualizado.

aws rds create-db-cluster --db-cluster-identifier mynewdbcluster --engine aurora-mysql \
  --db-cluster-version 5.7.mysql_aurora.2.10.2
...
aws rds create-db-instance --db-instance-identifier mynewdbcluster-instance1 \
  --db-cluster-identifier mynewdbcluster --db-instance-class db.t4g.medium --engine aurora-mysql
...
aws rds wait db-instance-available --db-instance-identifier mynewdbcluster-instance1

As versões 3.x do Aurora MySQL para as quais é possível fazer upgrade do cluster dependem da versão 2.x em que o cluster está sendo executado no momento e da Região da AWS em que o cluster está localizado. O primeiro comando com --output text apenas mostra a versão de destino disponível. O segundo comando mostra a saída JSON completa da resposta. Nessa resposta, você pode ver detalhes, como o valor aurora-mysql que você usa para o parâmetro engine. Você também pode ver o fato de que fazer upgrade para a versão 3.02.0 representa um upgrade de versão principal.

aws rds describe-db-clusters --db-cluster-identifier mynewdbcluster \
  --query '*[].{EngineVersion:EngineVersion}' --output text
5.7.mysql_aurora.2.10.2

aws rds describe-db-engine-versions --engine aurora-mysql --engine-version 5.7.mysql_aurora.2.10.2 \
  --query '*[].[ValidUpgradeTarget]'
...
{
    "Engine": "aurora-mysql",
    "EngineVersion": "8.0.mysql_aurora.3.02.0",
    "Description": "Aurora MySQL 3.02.0 (compatible with MySQL 8.0.23)",
    "AutoUpgrade": false,
    "IsMajorVersionUpgrade": true,
    "SupportedEngineModes": [
        "provisioned"
    ],
    "SupportsParallelQuery": true,
    "SupportsGlobalDatabases": true,
    "SupportsBabelfish": false
},
...

Este exemplo mostra que, se você inserir um número de versão de destino que não seja um destino de atualização válido para o cluster, o Aurora não realizará a atualização. O Aurora também não realiza uma atualização de versão principal, a menos que você inclua o parâmetro --allow-major-version-upgrade. Dessa forma, você não pode executar acidentalmente uma atualização que precise exigir testes e alterações amplas no código do aplicativo.

aws rds modify-db-cluster --db-cluster-identifier mynewdbcluster \
  --engine-version 5.7.mysql_aurora.2.09.2 --apply-immediately
An error occurred (InvalidParameterCombination) when calling the ModifyDBCluster operation: Cannot find upgrade target from 5.7.mysql_aurora.2.10.2 with requested version 5.7.mysql_aurora.2.09.2.

aws rds modify-db-cluster --db-cluster-identifier mynewdbcluster \
  --engine-version 8.0.mysql_aurora.3.02.0 --region us-east-1 --apply-immediately
An error occurred (InvalidParameterCombination) when calling the ModifyDBCluster operation: The AllowMajorVersionUpgrade flag must be present when upgrading to a new major version.

aws rds modify-db-cluster --db-cluster-identifier mynewdbcluster \
  --engine-version 8.0.mysql_aurora.3.02.0 --apply-immediately --allow-major-version-upgrade
{
  "DBClusterIdentifier": "mynewdbcluster",
  "Status": "available",
  "Engine": "aurora-mysql",
  "EngineVersion": "5.7.mysql_aurora.2.10.2"
}

Demora alguns momentos para que o status do cluster e das instâncias de banco de dados associadas mudem para upgrading. Os números de versão para as instâncias de cluster e banco de dados só mudam quando a atualização for concluída. Novamente, você pode usar o comando wait db-instance-available para que a instância de banco de dados do gravador aguarde até que a atualização seja concluída antes de prosseguir. 

aws rds describe-db-clusters --db-cluster-identifier mynewdbcluster \
  --query '*[].[Status,EngineVersion]' --output text
upgrading 5.7.mysql_aurora.2.10.2

aws rds describe-db-instances --db-instance-identifier mynewdbcluster-instance1 \
  --query '*[].{DBInstanceIdentifier:DBInstanceIdentifier,DBInstanceStatus:DBInstanceStatus} | [0]'
{
    "DBInstanceIdentifier": "mynewdbcluster-instance1",
    "DBInstanceStatus": "upgrading"
}

aws rds wait db-instance-available --db-instance-identifier mynewdbcluster-instance1

Neste ponto, o número da versão para o cluster corresponde ao que foi especificado para a atualização. 

aws rds describe-db-clusters --db-cluster-identifier mynewdbcluster \
  --query '*[].[EngineVersion]' --output text

8.0.mysql_aurora.3.02.0

O exemplo anterior fez uma atualização imediata especificando o parâmetro --apply-immediately. Para que a atualização aconteça em um momento conveniente quando o cluster não estiver ocupado, você pode especificar o parâmetro --no-apply-immediately. Isso faz com que a atualização inicie durante a próxima janela de manutenção para o cluster. A janela de manutenção define o período durante o qual as operações de manutenção podem ser iniciadas. Uma operação de longa duração pode não ser concluída durante a janela de manutenção. Assim, você não precisa definir uma janela de manutenção maior mesmo se esperar que a atualização possa levar muito tempo.

O exemplo a seguir faz upgrade de um cluster que está executando inicialmente o Aurora MySQL versão 2.10.2. Na saída describe-db-engine-versions, os valores False e True representam a propriedade IsMajorVersionUpgrade. A partir da versão 2.10.2, é possível fazer upgrade para algumas outras versões 2.*. Essas atualizações não são consideradas atualizações de versão principais e, portanto, não exigem uma atualização no local. O upgrade no local só está disponível para upgrades para as versões 3.* que são mostradas na lista.

aws rds describe-db-clusters --db-cluster-identifier mynewdbcluster \
  --query '*[].{EngineVersion:EngineVersion}' --output text
5.7.mysql_aurora.2.10.2

aws rds describe-db-engine-versions --engine aurora-mysql --engine-version 5.7.mysql_aurora.2.10.2 \
  --query '*[].[ValidUpgradeTarget]|[0][0]|[*].[EngineVersion,IsMajorVersionUpgrade]' --output text

5.7.mysql_aurora.2.10.3 False
5.7.mysql_aurora.2.11.0 False
5.7.mysql_aurora.2.11.1 False
8.0.mysql_aurora.3.01.1 True
8.0.mysql_aurora.3.02.0 True
8.0.mysql_aurora.3.02.2 True


aws rds modify-db-cluster --db-cluster-identifier mynewdbcluster \
  --engine-version 8.0.mysql_aurora.3.02.0 --no-apply-immediately --allow-major-version-upgrade
...

Quando um cluster é criado sem uma janela de manutenção especificada, Aurora seleciona um dia aleatório da semana. Nesse caso, o comando modify-db-cluster é enviado em uma segunda-feira. Assim, mudamos a janela de manutenção para terça-feira de manhã. Todos os horários são representados no fuso horário UTC. A janela tue:10:00-tue:10:30 corresponde ao intervalo das 2h às 2h30 no horário do Pacífico. A alteração na janela de manutenção entra em vigor imediatamente.

aws rds describe-db-clusters --db-cluster-identifier mynewdbcluster --query '*[].[PreferredMaintenanceWindow]'
[
    [
        "sat:08:20-sat:08:50"
    ]
]

aws rds modify-db-cluster --db-cluster-identifier mynewdbcluster --preferred-maintenance-window tue:10:00-tue:10:30"
aws rds describe-db-clusters --db-cluster-identifier mynewdbcluster --query '*[].[PreferredMaintenanceWindow]'
[
    [
        "tue:10:00-tue:10:30"
    ]
]

O exemplo a seguir mostra como obter um relatório dos eventos gerados pela atualização. O argumento --duration representa o número de minutos para recuperar as informações do evento. Ele é necessário porque, por padrão, describe-events só exibe eventos da última hora.

aws rds describe-events --source-type db-cluster --source-identifier mynewdbcluster --duration 20160
{
    "Events": [
        {
            "SourceIdentifier": "mynewdbcluster",
            "SourceType": "db-cluster",
            "Message": "DB cluster created",
            "EventCategories": [
                "creation"
            ],
            "Date": "2022-11-17T01:24:11.093000+00:00",
            "SourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:mynewdbcluster"
        },
        {
            "SourceIdentifier": "mynewdbcluster",
            "SourceType": "db-cluster",
            "Message": "Upgrade in progress: Performing online pre-upgrade checks.",
            "EventCategories": [
                "maintenance"
            ],
            "Date": "2022-11-18T22:57:08.450000+00:00",
            "SourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:mynewdbcluster"
        },
        {
            "SourceIdentifier": "mynewdbcluster",
            "SourceType": "db-cluster",
            "Message": "Upgrade in progress: Performing offline pre-upgrade checks.",
            "EventCategories": [
                "maintenance"
            ],
            "Date": "2022-11-18T22:57:59.519000+00:00",
            "SourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:mynewdbcluster"
        },
        {
            "SourceIdentifier": "mynewdbcluster",
            "SourceType": "db-cluster",
            "Message": "Upgrade in progress: Creating pre-upgrade snapshot [preupgrade-mynewdbcluster-5-7-mysql-aurora-2-10-2-to-8-0-mysql-aurora-3-02-0-2022-11-18-22-55].",
            "EventCategories": [
                "maintenance"
            ],
            "Date": "2022-11-18T23:00:22.318000+00:00",
            "SourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:mynewdbcluster"
        },
        {
            "SourceIdentifier": "mynewdbcluster",
            "SourceType": "db-cluster",
            "Message": "Upgrade in progress: Cloning volume.",
            "EventCategories": [
                "maintenance"
            ],
            "Date": "2022-11-18T23:01:45.428000+00:00",
            "SourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:mynewdbcluster"
        },
        {
            "SourceIdentifier": "mynewdbcluster",
            "SourceType": "db-cluster",
            "Message": "Upgrade in progress: Purging undo records for old row versions. Records remaining: 164",
            "EventCategories": [
                "maintenance"
            ],
            "Date": "2022-11-18T23:02:25.141000+00:00",
            "SourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:mynewdbcluster"
        },
        {
            "SourceIdentifier": "mynewdbcluster",
            "SourceType": "db-cluster",
            "Message": "Upgrade in progress: Purging undo records for old row versions. Records remaining: 164",
            "EventCategories": [
                "maintenance"
            ],
            "Date": "2022-11-18T23:06:23.036000+00:00",
            "SourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:mynewdbcluster"
        },
        {
            "SourceIdentifier": "mynewdbcluster",
            "SourceType": "db-cluster",
            "Message": "Upgrade in progress: Upgrading database objects.",
            "EventCategories": [
                "maintenance"
            ],
            "Date": "2022-11-18T23:06:48.208000+00:00",
            "SourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:mynewdbcluster"
        },
        {
            "SourceIdentifier": "mynewdbcluster",
            "SourceType": "db-cluster",
            "Message": "Database cluster major version has been upgraded",
            "EventCategories": [
                "maintenance"
            ],
            "Date": "2022-11-18T23:10:28.999000+00:00",
            "SourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:mynewdbcluster"
        }
    ]
}

Descobrir os motivos das falhas de atualização

No tutorial anterior, a atualização do Aurora MySQL versão 2 para a versão 3 foi bem-sucedida. Mas, se a atualização tivesse falhado, seria útil saber o motivo.

É possível começar usando o comando describe-events da AWS CLI para examinar os eventos do cluster de banco de dados. Este exemplo mostra os eventos de mydbcluster nas últimas dez horas.

aws rds describe-events \
    --source-type db-cluster \
    --source-identifier mydbcluster \
    --duration 600

Nesse caso, tivemos uma falha na pré-verificação da atualização.

{
    "Events": [
        {
            "SourceIdentifier": "mydbcluster",
            "SourceType": "db-cluster",
            "Message": "Database cluster engine version upgrade started.",
            "EventCategories": [
                "maintenance"
            ],
            "Date": "2024-04-11T13:23:22.846000+00:00",
            "SourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster"
        },
        {
            "SourceIdentifier": "mydbcluster",
            "SourceType": "db-cluster",
            "Message": "Database cluster is in a state that cannot be upgraded: Upgrade prechecks failed. For more details, see the  
             upgrade-prechecks.log file. For more information on troubleshooting the cause of the upgrade failure, see 
             https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.Updates.MajorVersionUpgrade.html#AuroraMySQL.Upgrading.Troubleshooting.",
            "EventCategories": [
                "maintenance"
            ],
            "Date": "2024-04-11T13:23:24.373000+00:00",
            "SourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster"
        }
    ]
}

Para diagnosticar a causa exata do problema, examine os logs do banco de dados para a instância de banco de dados de gravador. Quando uma atualização para o Aurora MySQL versão 3 falha, a instância de gravador contém um arquivo de log com o nome do arquivo upgrade-prechecks.log. Este exemplo mostra como detectar a presença desse log e, em seguida, baixá-lo para um arquivo local para exame.

aws rds describe-db-log-files --db-instance-identifier mydbcluster-instance \
    --query '*[].[LogFileName]' --output text

error/mysql-error-running.log
error/mysql-error-running.log.2024-04-11.20
error/mysql-error-running.log.2024-04-11.21
error/mysql-error.log
external/mysql-external.log
upgrade-prechecks.log

aws rds download-db-log-file-portion --db-instance-identifier mydbcluster-instance \
    --log-file-name upgrade-prechecks.log \
    --starting-token 0 \
    --output text >upgrade_prechecks.log

O arquivo upgrade-prechecks.log está no formato JSON. Nós o baixamos usando a opção --output text para evitar codificar a saída JSON em outro wrapper JSON. Para atualizações do Aurora MySQL versão 3, esse log sempre inclui determinadas mensagens informativas e de aviso. Ele só inclui mensagens de erro se a atualização falhar. Se a atualização for bem-sucedida, o arquivo de log não será produzido.

Para resumir todos esses erros e exibir os campos de objeto e descrição associados, é possível executar o comando grep -A 2 '"level": "Error"' no conteúdo do arquivo upgrade-prechecks.log. Isso exibe cada linha de erro e as duas linhas depois dela. Elas contêm o nome do objeto de banco de dados correspondente e orientações sobre como corrigir o problema.

$ cat upgrade-prechecks.log | grep -A 2 '"level": "Error"'

"level": "Error",
"dbObject": "problematic_upgrade.dangling_fulltext_index",
"description": "Table `problematic_upgrade.dangling_fulltext_index` contains dangling FULLTEXT index. Kindly recreate the table before upgrade."

Neste exemplo, é possível executar o comando SQL a seguir na tabela com problemas para tentar corrigi-los ou recriar a tabela sem o índice pendente.

OPTIMIZE TABLE problematic_upgrade.dangling_fulltext_index;

Tente realizar a atualização novamente.

Solução de problemas para atualização no local de Aurora MySQL

Use as dicas a seguir para ajudar a solucionar problemas com as atualizações no local do Aurora MySQL. Estas dicas não se aplicam a clusters de banco de dados do Aurora Serverless.

Motivo para a atualização no local ser cancelada ou lenta Efeito Solução para permitir que a atualização no local seja concluída dentro da janela de manutenção
A réplica associada entre regiões do Aurora ainda não foi corrigida Aurora cancela a atualização. Atualize a réplica entre regiões do Aurora e tente novamente.
Cluster tem transações XA no estado preparado Aurora cancela a atualização. Confirmar ou reverter todas as transações XA preparadas.
O cluster está processando qualquer instrução DDL (Data Definition Language) Aurora cancela a atualização. Considere esperar e executar a atualização depois que todas as instruções DDL estiverem concluídas.
Cluster tem alterações não confirmadas para muitas linhas A atualização pode levar muito tempo.

O processo de atualização reverte as alterações não confirmadas. O indicador para esta condição é o valor de TRX_ROWS_MODIFIED na tabela INFORMATION_SCHEMA.INNODB_TRX.

Considere executar a atualização somente depois que todas as grandes transações forem confirmadas ou revertidas.
Cluster tem um número elevado de registros para desfazer A atualização pode levar muito tempo.

Mesmo que as transações não confirmadas não afetem um grande número de linhas, podem envolver um grande volume de dados. Por exemplo, você pode inserir BLOBs grandes. O Aurora não detecta nem gera automaticamente um evento para esse tipo de atividade de transação. O indicador para essa condição é o tamanho da lista de histórico (HLL). O processo de atualização reverte as alterações não confirmadas.

É possível conferir o HLL na saída do comando SHOW ENGINE INNODB STATUS SQL ou diretamente usando a seguinte consulta SQL:

SELECT count FROM information_schema.innodb_metrics WHERE name = 'trx_rseg_history_len';

Também é possível monitorar a métrica RollbackSegmentHistoryListLength no Amazon CloudWatch.

Pense em realizar a atualização somente quando o HLL for menor.
O cluster está no processo de confirmação de uma grande transação de log binário A atualização pode levar muito tempo.

O processo de atualização aguarda até que as alterações de log binário sejam aplicadas. Mais transações ou instruções DDL podem começar durante esse período, retardando ainda mais o processo de atualização.

Agende o processo de atualização quando o cluster não estiver ocupado gerando alterações de replicação de log binário. O Aurora não detecta nem gera automaticamente um evento para esta condição.
Inconsistências em esquemas resultantes da remoção ou corrupção de arquivos Aurora cancela a atualização.

Altere o mecanismo de armazenamento padrão para tabelas temporárias do MyISAM para o InnoDB. Siga estas etapas:

  1. Modifique o parâmetro de banco de dados default_tmp_storage_engine para InnoDB.

  2. Reinicialize o cluster de banco de dados.

  3. Após a reinicialização, confirme se o parâmetro de banco de dados default_tmp_storage_engine está definido como InnoDB. Use o seguinte comando:

    show global variables like 'default_tmp_storage_engine';

  4. Certifique-se de não criar nenhuma tabela temporária que use o mecanismo de armazenamento MyISAM. Recomendamos que você pause todas as workloads de banco de dados e não crie nenhuma conexão de banco de dados, porque você fará upgrade em breve.

  5. Tente realizar o upgrade local novamente.
O usuário mestre foi excluído. Aurora cancela a atualização.
Importante

Não exclua o usuário mestre.

No entanto, se por algum motivo você excluir o usuário mestre, restaure-o usando os seguintes comandos SQL:

CREATE USER 'master_username'@'%' IDENTIFIED BY 'master_user_password' REQUIRE NONE PASSWORD EXPIRE DEFAULT ACCOUNT UNLOCK;

GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, RELOAD, PROCESS, REFERENCES, INDEX, ALTER, SHOW DATABASES, CREATE TEMPORARY TABLES, 
LOCK TABLES, EXECUTE, REPLICATION SLAVE, REPLICATION CLIENT, CREATE VIEW, SHOW VIEW, CREATE ROUTINE, ALTER ROUTINE, CREATE USER, EVENT, 
TRIGGER, LOAD FROM S3, SELECT INTO S3, INVOKE LAMBDA, INVOKE SAGEMAKER, INVOKE COMPREHEND ON *.* TO 'master_username'@'%' WITH GRANT OPTION;

Para ver mais detalhes sobre a solução de problemas que fazem com que as verificações prévias de atualização falhem, consulte os seguintes blogs:

Você pode usar as etapas a seguir para executar suas próprias verificações para algumas das condições na tabela anterior. Dessa forma, você pode agendar a atualização em um momento em que você sabe que o banco de dados está em um estado onde a atualização pode ser concluída com sucesso e rapidamente.

  • Você pode verificar se há transações XA abertas executando a instrução XA RECOVER. Você pode então confirmar ou reverter as transações XA antes de iniciar a atualização.

  • Você pode verificar se há instruções DDL executando uma instrução SHOW PROCESSLIST e procurando CREATE, DROP, ALTER, RENAME e TRUNCATE na saída. Permita que todas as instruções DDL terminem antes de iniciar a atualização.

  • Você pode verificar o número total de linhas não confirmadas consultando a tabela INFORMATION_SCHEMA.INNODB_TRX. A tabela contém uma linha para cada transação. A coluna TRX_ROWS_MODIFIED contém o número de linhas modificadas ou inseridas pela transação.

  • Você pode verificar o comprimento da lista de histórico do InnoDB executando a instrução SHOW ENGINE INNODB STATUS SQL e procurando o History list length na saída. Você também pode verificar o valor diretamente executando a seguinte consulta: 

    SELECT count FROM information_schema.innodb_metrics WHERE name = 'trx_rseg_history_len';

    O comprimento da lista de histórico corresponde à quantidade de informações desfeitas armazenadas pelo banco de dados para implementar o controle de simultaneidade de várias versões (MVCC).

Limpeza pós-upgrade do Aurora MySQL versão 3

Depois de concluir o upgrade de qualquer cluster do Aurora MySQL versão 2 para o Aurora MySQL versão 3, você poderá executar essas outras ações de limpeza:

  • Crie novas versões compatíveis com o MySQL 8.0 de qualquer grupo de parâmetros personalizado. Aplique todos os valores de parâmetros personalizados necessários aos novos grupos de parâmetros.

  • Atualize todos os alarmes do CloudWatch, scripts de configuração e assim por diante para utilizar os novos nomes de qualquer métrica cujos nomes tenham sido afetados por alterações inclusivas de idioma. Para obter uma lista dessas métricas, consulte Alterações de linguagem inclusiva do Aurora MySQL versão 3.

  • Atualize qualquer template do AWS CloudFormation para utilizar os novos nomes para quaisquer parâmetros de configuração cujos nomes tenham sido afetados por alterações inclusivas de linguagem. Para obter uma lista completa desses parâmetros, consulte Alterações de linguagem inclusiva do Aurora MySQL versão 3.

Índices espaciais

Depois de atualizar para o Aurora MySQL versão 3, verifique se você precisa descartar ou recriar objetos e índices relacionados a índices espaciais. Antes do MySQL 8.0, o Aurora podia otimizar consultas espaciais utilizando índices que não continham um identificador de recursos espaciais (SRID). O Aurora MySQL versão 3 utiliza apenas índices espaciais contendo SRIDs. Durante um upgrade, o Aurora descarta automaticamente todos os índices espaciais sem SRIDs e imprime mensagens de aviso no log do banco de dados. Se você observar essas mensagens de aviso, crie novos índices espaciais com SRIDs após o upgrade. Para obter mais informações sobre alterações em funções espaciais e tipos de dados no MySQL 8.0, consulte o tópico sobre Alterações feitas no MySQL 8.0, no Guia de referência do MySQL.