As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Atualização da versão principal implementada do Amazon DocumentDB no local Você pode realizar uma atualização de versão principal (MVU) no local do seu cluster Amazon DocumentDB, mantendo os mesmos endpoints, armazenamento e tags. Seus aplicativos continuam funcionando sem modificações. Esse recurso está disponível sem custo adicional em todas as áreas em Regiões da AWS que o Amazon DocumentDB está disponível. **Importante** Seu cluster não está disponível durante a atualização e é reinicializado várias vezes. Não se conecte, leia ou grave no cluster depois de iniciar a atualização. O tempo de inatividade varia de acordo com o número de coleções, índices, bancos de dados e instâncias. Execute a atualização durante sua janela de manutenção ou horas de baixa utilização. Depois de fazer o upgrade, você não pode fazer o downgrade para uma versão anterior. Você pode restaurar seu snapshot de pré-upgrade em um novo cluster, se necessário. **Topics** + [Caminhos de atualização com suporte](#mvu-upgrade-paths) + [Pré-requisitos](#mvu-prerequisites) + [Práticas recomendadas](#mvu-best-practices) + [O que muda após a atualização para o Amazon DocumentDB 8.0](#mvu-50-to-80-differences) + [Post-upgrade considerações para clusters atualizados da versão 3.6 ou 4.0](#mvu-36-to-50-differences) + [Executar a atualização](#perform-an-mvu) + [Solução de problemas](#mvu-troubleshooting) ## Caminhos de atualização com suporte A tabela a seguir lista todos os caminhos de atualização de versões principais locais compatíveis. Você pode selecionar qualquer versão secundária publicada na versão principal de destino como a versão do mecanismo de destino. | Versão principal da fonte | Versão principal do Target | Observações | | --- | --- | --- | | Amazon DocumentDB 3.6 | Amazon DocumentDB 5.0 (qualquer versão secundária publicada) | Consulte [Post-upgrade considerações para clusters atualizados da versão 3.6 ou 4.0](#mvu-36-to-50-differences) para obter considerações pós-atualização. | | Amazon DocumentDB 3.6 | Amazon DocumentDB 8.0 (qualquer versão secundária publicada) | Consulte [Post-upgrade considerações para clusters atualizados da versão 3.6 ou 4.0](#mvu-36-to-50-differences) e [O que muda após a atualização para o Amazon DocumentDB 8.0](#mvu-50-to-80-differences) para considerações pós-atualização. | | Amazon DocumentDB 4.0 | Amazon DocumentDB 5.0 (qualquer versão secundária publicada) | Consulte [Post-upgrade considerações para clusters atualizados da versão 3.6 ou 4.0](#mvu-36-to-50-differences) para obter considerações pós-atualização. | | Amazon DocumentDB 4.0 | Amazon DocumentDB 8.0 (qualquer versão secundária publicada) | Consulte [Post-upgrade considerações para clusters atualizados da versão 3.6 ou 4.0](#mvu-36-to-50-differences) e [O que muda após a atualização para o Amazon DocumentDB 8.0](#mvu-50-to-80-differences) para considerações pós-atualização. | | Amazon DocumentDB 5.0 (qualquer versão secundária publicada) | Amazon DocumentDB 8.0 (qualquer versão secundária publicada) | Consulte [O que muda após a atualização para o Amazon DocumentDB 8.0](#mvu-50-to-80-differences) as mudanças de recursos. | Para ver as versões secundárias disponíveis em sua AWS região, use o AWS CLI comando`aws docdb describe-db-engine-versions`. Para obter uma lista das versões secundárias lançadas, consulte[Notas da versão](release-notes.md). **nota** Cada MVU pode ter como alvo qualquer versão secundária publicada na principal de destino. Por exemplo, a atualização do Amazon DocumentDB 3.6 ou 4.0 pode ir diretamente para a versão secundária 5.0 ou 8.0 mais recente publicada; não há necessidade de primeiro atualizar para a versão `.0` secundária e depois aplicar uma atualização de versão secundária. Você pode fazer o upgrade do Amazon DocumentDB 3.6 ou 4.0 diretamente para o 8.0 em uma única MVU. A atualização em etapas até a 5.0 (primeiro para uma versão secundária 5.0 e depois para uma versão secundária 8.0) também é suportada. **nota** In-place O MVU não é compatível com clusters globais ou elásticos. Para atualizar um cluster global, remova os clusters secundários, converta o cluster primário em regional, execute a MVU e recrie o cluster global adicionando clusters secundários usando os mesmos nomes para reter seus endpoints. Você incorrerá em I/O cobranças enquanto o primário atualizado replica os dados para os novos secundários. Para obter detalhes das etapas, consulte, [Remover um cluster de um cluster global do Amazon DocumentDB](global-clusters.manage.md#global-clusters.remove). ## Pré-requisitos **Importante** **Amplie as instâncias com capacidade de intermitência antes de fazer o upgrade. ** Se seu cluster usa tipos de instância com capacidade de intermitência (por exemplo, `db.t3.medium` ou`db.t4g.medium`), expanda a instância primária para pelo menos `db.r5.large` ou `db.r6g.large` antes de iniciar a atualização. As instâncias com capacidade de intermitência podem não ter CPU e memória suficientes para concluir o processo de upgrade, o que pode resultar em falhas de upgrade e indisponibilidade prolongada do cluster. Você pode reduzir a escala após a conclusão da atualização. **Amplie a instância do gravador sem servidor antes da atualização. ** Se seu cluster tiver uma instância de gravador sem servidor, o DCU máximo no `ServerlessV2ScalingConfiguration` deve ser definido como 3 ou superior antes de iniciar a atualização. Clusters com um máximo de DCU abaixo de 3 não podem ser atualizados porque não têm CPU ou memória suficientes para concluir o upgrade. **Verifique seus índices parciais antes da atualização (atualize do Amazon DocumentDB 5.0 para 8.0). ** Antes de iniciar a atualização, revise seus índices parciais para encontrar um `partialFilterExpression` que usa o `$type` operador para corresponder a determinados tipos de BSON: especificamente os aliases `binData``bool`,`date`, `double``decimal`, e de `array` tipo, ou um código de tipo numérico, como. `{ "$type" : 1 }` Esses índices parciais fazem com que a atualização falhe, mesmo que o índice funcione normalmente para leituras e gravações. Use `db.collection.getIndexes()` para revisar seus índices parciais. `partialFilterExpression` Elimine o índice parcial afetado antes de iniciar a atualização e recrie-o após a conclusão da atualização. Se você não tiver certeza se um índice foi afetado, entre em contato com o AWS suporte antes de fazer o upgrade. + **Tipo de instância ** — O Amazon DocumentDB 4.0\+ não oferece suporte a instâncias db.r4. Modifique todas `db.r4.*` as instâncias para `db.r5.*` instâncias ou mais recentes antes de fazer o upgrade. Consulte [Modificar uma instância do Amazon DocumentDB](db-instance-modify.md) e [Classes de instância compatíveis por região](db-instance-classes.md#db-instance-classes-by-region). + **Patches do sistema operacional ** — aplique todas as ações pendentes de manutenção do sistema operacional em todas as instâncias antes da atualização. Consulte [Atualizações do sistema operacional do Amazon DocumentDB](db-instance-maintain.md#os-system-updates). **nota** Os patches pendentes do mecanismo no nível do cluster podem ocultar os patches do sistema operacional da instância. Aplique os patches do motor primeiro, se necessário. Consulte [Executar uma atualização de patch para a versão do mecanismo de um cluster](db-cluster-version-upgrade.md). + **Limites de índice em instâncias intermitentes (instâncias da família t) ** — Se você tiver mais de 3.000 índices em instâncias intermitentes, amplie o primário para pelo menos db.r5.large antes de fazer o upgrade. Você pode reduzir a escala após a conclusão da atualização. [See the AWS documentation website for more details](http://docs.aws.amazon.com/pt_br/documentdb/latest/devguide/docdb-mvu.html) + **Grupo de parâmetros ** — Tenha um grupo de parâmetros de cluster personalizado para a versão de destino pronto antes da atualização. Se um não for especificado, o grupo de parâmetros padrão para a versão de destino será usado (por exemplo, `default.docdb5.0` ou`default.docdb8.0`). + **Instantâneo manual ** — Crie um instantâneo manual antes da atualização. O processo de upgrade cria um instantâneo automático chamado`preupgrade---`, mas sempre cria seu próprio backup. Consulte [Criação de um snapshot manual de cluster](backup_restore-create_manual_cluster_snapshot.md). **nota** O snapshot automático criado pelo processo de atualização não será excluído automaticamente após a conclusão da atualização da versão principal implementada. Esse snapshot não incorrerá em nenhuma cobrança, desde que esteja dentro do período de retenção. É possível optar por excluir esse snapshot depois de verificar uma atualização com êxito do seu cluster. ![Imagem: a caixa de navegação Snapshots mostrando uma tabela de snapshots criados anteriormente.](https://docs.aws.amazon.com/pt_br/documentdb/latest/devguide/images/mvu-snapshot-2.png) ## Práticas recomendadas ### Antes da atualização — testando com um clone 1. Use [Clonar um volume para um cluster Amazon DocumentDB](db-cluster-cloning.md) para criar um clone do seu cluster. Você não incorrerá em custos de armazenamento, a menos que modifique os dados no clone. 1. Combine a contagem de instâncias do clone com o cluster de destino para obter uma estimativa de tempo realista. 1. Execute o MVU no clone e teste totalmente as diferenças funcionais. 1. Verifique se uma atualização já está agendada executando [`describe-db-clusters`](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/describe-db-clusters.html) e procurando`PendingModifiedValues.EngineVersion`. Se você modificou o cluster e optou por aplicá-lo na próxima janela de manutenção, a programação não estará visível no console, mas você poderá visualizá-la em AWS CLI: ``` aws docdb describe-db-clusters \ --region {{us-east-1}} \ --db-cluster-identifier {{mydocdbcluster}} ``` ``` "PendingModifiedValues": { "EngineVersion": "5.0.0" }, ``` 1. Se o teste for bem-sucedido, continue com a atualização em seu cluster de produção. ### Durante a atualização É possível monitorar o andamento da atualização da versão principal implementada assinando os eventos de manutenção do cluster. Quando a atualização for concluída, você receberá o evento “A versão principal do cluster de banco de dados foi atualizada”. Esses e outros eventos que ocorrem durante a atualização aparecem na ** seção ** Eventos e tags da página de detalhes do cluster no console do Amazon DocumentDB. Em seguida, o status do cluster muda de `upgrading` para`available`. Os seguintes eventos são gerados durante a atualização: 1. Foi iniciada a atualização da versão principal do mecanismo de cluster de banco de dados. O cluster permanece online. 1. Preparação da atualização em andamento: iniciando pré-verificações de atualização on-line. 1. Preparação da atualização em andamento: pré-verificações de atualização on-line concluídas. 1. Colocar o cluster de banco de dados off-line enquanto a instância primária conclui o patch/upgrade processo. 1. Preparação da atualização em andamento: iniciando as pré-verificações de atualização off-line. 1. Preparação da atualização em andamento: pré-verificações de atualização off-line concluídas. 1. Atualização em andamento: Criação de um instantâneo de pré-atualização [preupgrade- - -to- -]. 1. Atualização em andamento: volume de clonagem. 1. Atualização em andamento: atualizando gravador. 1. Atualização em andamento: atualizando leitores. 1. A versão principal do mecanismo do cluster de banco de dados foi atualizada. Os eventos são visíveis no console na ** página ** Eventos: ![Imagem: a caixa de navegação Eventos mostrando uma tabela de eventos de atualização.](https://docs.aws.amazon.com/pt_br/documentdb/latest/devguide/images/mvu-events-2.png) A partir do AWS CLI, você pode executar [`aws docdb describe-events`](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/describe-events.html) para monitorar o progresso da atualização. Para receber notificações automaticamente, use [`aws docdb create-event-subscription`](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/create-event-subscription.html) para assinar eventos e encaminhá-los ao Amazon SNS para receber e-mails, mensagens push ou outros métodos de entrega. Para obter mais informações, consulte [Tornar-se assinante de eventos do Amazon DocumentDB](event-subscriptions.subscribe.md). ``` aws docdb describe-events --source-identifier {{mydocdbcluster}} --source-type db-cluster ``` Esse comando retorna uma saída semelhante à seguinte: ``` { "Events": [ { "SourceIdentifier": "mydocdbcluster", "SourceType": "db-cluster", "Message": "Database cluster engine version upgrade started.", "EventCategories": [ "maintenance" ], "Date": "2023-07-11T23:20:32.444000+00:00", "SourceArn": "arn:aws:rds:us-east-1:xxxx:cluster:mycluster" } ] } ``` ### Após a atualização **Atenção** Imediatamente após a atualização local da versão principal, seu cluster Amazon DocumentDB repreenche os metadados de índice que o mecanismo de banco de dados usa para otimizar os planos de execução de consultas. O desempenho da consulta retorna aos níveis esperados quando esse processo é concluído. Normalmente, ele termina em alguns minutos, mas pode levar até duas horas, dependendo do número de índices em seu cluster. Não reinicialize, faça failover ou escale up/down sua instância de gravador durante esse período, pois isso pode interromper o recálculo dos metadados do índice. Espere até observar o desempenho esperado da consulta antes de fazer essas alterações. Acompanhe o progresso por meio dos seguintes eventos de cluster: Post-upgrade status do cluster: processo de atualização de metadados do índice iniciado Post-upgrade status do cluster: processo de atualização de metadados do índice concluído em X segundos Entre em contato com o AWS suporte se o processo de atualização dos metadados do índice não for concluído em três horas ou se você continuar enfrentando problemas de desempenho após a conclusão do processo. 1. **Faça um instantâneo manual ** do cluster atualizado caso precise restaurar para o estado pós-upgrade. O processo automático de captura instantânea será retomado assim que a atualização local da versão principal for concluída. 1. **Clusters de tags atualizados da versão 3.6. ** Adicione uma tag para diferenciar os clusters atualizados da versão 3.6. (veja[Post-upgrade considerações para clusters atualizados da versão 3.6 ou 4.0](#mvu-36-to-50-differences)). 1. **Atualize seu driver. ** Para usar novos recursos (por exemplo, agrupamento, visualizações ou compactação Zstd na versão 8.0), atualize para a versão correspondente da API MongoDB. Para obter mais informações, consulte [O que há de novo no Amazon DocumentDB 8.0](compatibility.md#compatibility-whatsnew-8). 1. **Teste minuciosamente. ** Valide seu aplicativo em relação ao cluster atualizado. ## O que muda após a atualização para o Amazon DocumentDB 8.0 Depois de realizar uma atualização de versão principal para o Amazon DocumentDB 8.0 (do Amazon DocumentDB 5.0 ou diretamente da 3.6 ou 4.0), os seguintes recursos são habilitados ou alterados: + **Cotejamento. ** O Amazon DocumentDB 8.0 oferece suporte ao [Usando agrupamento no Amazon DocumentDB 8.0](collation.md) agrupamento. Após a atualização, novas coleções e seus índices, e novos índices em coleções existentes, têm o agrupamento ativado por padrão. + **Índice de texto. ** Novos índices de texto são criados usando o Text Index V2, que usa um analisador de pesquisa de texto atualizado para melhorar a compatibilidade com o MongoDB. Os índices de texto existentes não são afetados. + **Versão do planejador de consultas. ** Se você não tiver um grupo de parâmetros personalizado, um novo grupo de parâmetros padrão será criado para o Amazon DocumentDB 8.0 com a versão 3 do Planner selecionada automaticamente. Com a versão 3 do planejador de consultas, [ as ](views.md) visualizações também estão disponíveis. + **Compressão. ** O Amazon DocumentDB 8.0 oferece suporte à compactação de documentos baseada em dicionário usando o algoritmo Zstd. Após a atualização, novas coleções são criadas com a compactação Zstd ativada por padrão. As coleções existentes da versão 5.0 mantêm suas configurações de compactação. Para aproveitar a compactação Zstd em coleções existentes, você pode modificar suas configurações de compactação. Para obter mais informações, consulte [Gerenciando a compactação baseada em dicionário no Amazon DocumentDB 8.0](dict-compression.md). + **Reconstrução do índice. ** Se você estiver fazendo o upgrade do Amazon DocumentDB 5.0 para o Amazon DocumentDB 8.0, nenhuma reconstrução do índice será necessária. Se você estiver atualizando diretamente do Amazon DocumentDB 3.6 ou 4.0 para 8.0, reconstrua seus índices conforme descrito em. [Post-upgrade considerações para clusters atualizados da versão 3.6 ou 4.0](#mvu-36-to-50-differences) **Importante** O Amazon DocumentDB 8.0 exige TLS 1.2 ou superior. O TLS 1.0 e o TLS 1.1 não são mais suportados. **nota** Para obter uma lista completa das diferenças funcionais, consulte[Compatibilidade do Amazon DocumentDB com MongoDB](compatibility.md). ## Post-upgrade considerações para clusters atualizados da versão 3.6 ou 4.0 + **Reconstrução do índice. ** Uma MVU retém os índices originais. O Amazon DocumentDB 5.0 e versões posteriores aprimoraram a manutenção do índice e a coleta de lixo, especialmente para índices de baixa cardinalidade. Depois de atualizar da versão 3.6 ou 4.0 (para 5.0 ou 8.0), reconstrua seus índices para garantir o desempenho ideal da consulta (opcional, envolve mais). I/O Consulte [Manutenção do índice usando `reIndex`](managing-indexes.md#reIndex). + **Comparação numérica de subdocumentos (somente 3.6). ** Os clusters atualizados da versão 3.6 herdam o comportamento da versão 3.6, em que os tipos numéricos nos subdocumentos não são comparados entre os tipos. Por exemplo, `{a: {b: NumberLong(1)}}` não é igual `{a: {b: 1}}` em 3.6, mas eles são iguais em 4.0 e posteriores. Esse comportamento afeta todos os clusters atualizados da versão 3.6. ## Executar a atualização ------ #### [ Using the Console de gerenciamento da AWS ] 1. Faça login no [Console de gerenciamento da AWS](https://console.aws.amazon.com/docdb/home?region=us-east-1) e abra o console do Amazon DocumentDB. 1. Na ** tabela ** Clusters, selecione o cluster de origem, escolha ** Ações e**, em seguida, ** Modificar**. ![Imagem: a caixa de navegação Clusters mostrando uma lista dos links de cluster existentes e seus links de instância correspondentes.](https://docs.aws.amazon.com/pt_br/documentdb/latest/devguide/images/mvu-cluster-table-2.png) 1. Em Especificações ** do cluster**, escolha a versão de destino (por exemplo, ** 5.0.0 ** ou ** 8.0.0**) no menu suspenso Versão do ** mecanismo. ** ![Imagem: a seção Especificações do cluster da caixa de diálogo Modificar cluster mostrando os campos Identificador do cluster e Versão do mecanismo.](https://docs.aws.amazon.com/pt_br/documentdb/latest/devguide/images/mvu-modify-cluster-2.png) 1. Em Opções de ** cluster**, selecione seu grupo de parâmetros de cluster para a versão do mecanismo de destino. Você pode usar o padrão (por exemplo, ** default.docdb5.0 ** ou ** ** default.docdb8.0) ou um grupo de parâmetros personalizado que você criou. ![Imagem: a seção Opções de cluster da caixa de diálogo Modificar cluster mostrando o campo Grupo de parâmetros de cluster.](https://docs.aws.amazon.com/pt_br/documentdb/latest/devguide/images/mvu-param-group-2.png) 1. Escolha ** Continuar**, selecione sua preferência de agendamento (aplicar imediatamente ou na próxima janela de manutenção) e escolha ** Modificar cluster**. ![Imagem: a caixa de diálogo Modificar cluster mostrando o resumo e o agendamento da modificação para o cluster selecionado.](https://docs.aws.amazon.com/pt_br/documentdb/latest/devguide/images/mvu-mod-schedule-2.png) 1. Monitore o status do cluster na tabela de clusters à medida que ele muda para a ** atualização**: ![Imagem: a caixa de navegação Clusters destacando a coluna Status do cluster que está sendo atualizado.](https://docs.aws.amazon.com/pt_br/documentdb/latest/devguide/images/mvu-cluster-upgrading-2.png) ------ #### [ Using the AWS CLI ] Use [`modify-db-cluster`](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/modify-db-cluster.html) com a `--allow-major-version-upgrade` bandeira: ``` aws docdb modify-db-cluster \ ‐‐db-cluster-identifier {{mydocdbcluster}} \ ‐‐allow-major-version-upgrade \ ‐‐engine-version {{8.0.0}} \ ‐‐apply-immediately \ ‐‐cluster-parameter-group {{mydocdbparametergroup}} \ ‐‐region {{us-east-1}} ``` Substitua cada um {{placeholder}} pelas informações do seu cluster. ------ ## Solução de problemas + **Pre-upgrade falha na verificação. ** Antes do início da atualização, o Amazon DocumentDB executa verificações de validação pré-atualização. A seguir estão as causas comuns de falhas na pré-verificação: + **A atualização não pôde continuar porque as coleções têm nomes com 58 ou mais caracteres ** — Renomeie as coleções afetadas para nomes mais curtos antes de tentar a atualização novamente. + **A atualização não pôde continuar porque a contagem do índice excede o limite do tipo de instância ** — Atualize para um tipo de instância maior antes de tentar a atualização novamente. Para limites de índice por tipo de instância, consulte[Pré-requisitos](#mvu-prerequisites). + **Falha na atualização e reversão. ** Se a atualização falhar, ela tentará automaticamente uma reversão. Uma reversão bem-sucedida gera o evento: “O cluster de banco de dados está em um estado que não pode ser atualizado”. Seu cluster retorna ao estado de pré-atualização e você pode continuar usando-o. Entre em contato com o AWS suporte para solucionar o problema antes de tentar novamente. + **Post-upgrade desempenho. ** A degradação temporária do desempenho e a alta utilização da CPU podem ocorrer enquanto a atualização dos metadados do índice é executada. Se a degradação persistir por mais de 3 horas, entre em contato com AWS o suporte. Para obter assistência adicional, entre em contato com [AWS Support](https://aws.amazon.com/support).