Caminhos de atualização com suporte Pré-requisitos Práticas recomendadas O que muda após a atualização do Amazon DocumentDB 5.0 para 8.0 Post-upgrade considerações para clusters atualizados da versão 3.6 ou 4.0 Executar a atualização Solução de problemas

Atualização da versão principal implementada do Amazon DocumentDB no local

Você pode realizar um upgrade 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 todos os Regiões da AWS lugares onde o Amazon DocumentDB está disponível.

Importante

Seu cluster ficará indisponível durante o upgrade e passará por várias reinicializações. Não se conecte, leia ou grave no cluster depois de iniciar o upgrade. O tempo de inatividade varia de acordo com o número de coleções, índices, bancos de dados e instâncias. Recomendamos realizar a atualização durante sua janela de manutenção ou horas de baixa utilização.

Depois de atualizado, 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.

Tópicos

Caminhos de atualização com suporte
Pré-requisitos
Práticas recomendadas
O que muda após a atualização do Amazon DocumentDB 5.0 para 8.0
Post-upgrade considerações para clusters atualizados da versão 3.6 ou 4.0
Executar a atualização
Solução de problemas

Caminhos de atualização com suporte

A tabela a seguir lista todos os caminhos de atualização da versão principal no local com suporte. Você pode selecionar qualquer versão secundária publicada no principal de destino como a versão do mecanismo de destino.

Fonte: versão principal	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 para ver as considerações após a 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 para ver as considerações após a 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 do Amazon DocumentDB 5.0 para 8.0 as alterações de recursos.

Para ver as versões secundárias disponíveis na sua AWS região, use o AWS CLI comandoaws docdb describe-db-engine-versions. Para obter uma lista das versões secundárias lançadas, consulteNotas da versão.

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 última versão 5.0 secundária publicada; não há necessidade de primeiro atualizar para a 5.0.0 e depois aplicar uma atualização de versão secundária.

Para chegar à 8.0 a partir da 3.6 ou 4.0, execute duas MVUs: primeiro para uma versão 5.0 secundária de sua escolha e, em seguida, para uma versão secundária 8.0 de sua escolha. Não há caminho direto de 3,6 → 8,0 ou 4,0 → 8,0 MVU.

nota

In-place O MVU não é compatível com clusters globais ou clusters elásticos. Para atualizar um cluster global, remova os clusters secundários, converta o primário em um cluster regional, execute a MVU e, em seguida, 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.

Pré-requisitos

Importante

Aumente a escala de instâncias com capacidade de intermitência antes da atualização. Se seu cluster usa tipos de instância com capacidade de intermitência (por exemplo, db.t3.medium oudb.t4g.medium), é altamente recomendável escalar 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 atualização, o que pode resultar em falhas de atualização e indisponibilidade prolongada do cluster. Você pode reduzir a escala após a conclusão da atualização.

Tipo de instância — O Amazon DocumentDB 4.0+ não oferece suporte a instâncias db.r4. Modifique todas db.r4.* as db.r5.* instâncias para instâncias ou mais recentes antes da atualização. Consulte Modificar uma instância do Amazon DocumentDB e Classes de instância compatíveis por região.
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.

nota
Os patches pendentes do mecanismo em nível de 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.
Limites de índice em instâncias com capacidade de intermitência (instâncias da família t) — Se você tiver mais de 3.000 índices em instâncias com capacidade de intermitência, aumente a escala primária para pelo menos db.r5.large antes da atualização. Você pode reduzir a escala após a conclusão da atualização.

Instância Índices máximos para MVU

db.t4g.medium

3 mil

db.t3.medium

10 mil
Grupo de parâmetros — Recomendamos ter 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 oudefault.docdb8.0).
Instantâneo manual — Crie um instantâneo manual antes da atualização. O processo de atualização cria um instantâneo automático chamadopreupgrade-<name>-<version>-<timestamp>, mas é altamente recomendável ter seu próprio backup. Consulte Criação de um snapshot manual de cluster.

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.

Instância	Índices máximos para MVU
db.t4g.medium	3 mil
db.t3.medium	10 mil

Práticas recomendadas

Antes da atualização — testando com um clone

Use Clonar um volume para um cluster Amazon DocumentDB para criar um clone do seu cluster. Você não incorrerá em custos de armazenamento, a menos que modifique os dados no clone.
Combine a contagem de instâncias do clone com o cluster de destino para obter uma estimativa de tempo realista.
Execute a MVU no clone e teste totalmente as diferenças funcionais.
Verifique se uma atualização já está agendada executando describe-db-clusterse procurandoPendingModifiedValues.EngineVersion. Se você modificou o cluster e optou por aplicá-lo na próxima janela de manutenção, a agenda não estará visível no console, mas você poderá visualizá-la no AWS CLI:
```
aws docdb describe-db-clusters \
  --region us-east-1 \
  --db-cluster-identifier mydocdbcluster
```
```
"PendingModifiedValues": {
    "EngineVersion": "5.0.0"
},
```
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”. Esse 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 paraavailable.

Os seguintes eventos são gerados durante a atualização:

A atualização da versão principal do mecanismo de cluster de banco de dados foi iniciada. O cluster permanece online.
Preparação da atualização em andamento: iniciando pré-verificações de atualização on-line.
Preparação da atualização em andamento: pré-verificações de atualização on-line concluídas.
Colocar o cluster de banco de dados off-line enquanto a instância primária conclui o patch/upgrade processo.
Preparação da atualização em andamento: iniciando as pré-verificações de atualização off-line.
Preparação da atualização em andamento: pré-verificações de atualização off-line concluídas.
<version-to><timestamp>Atualização em andamento: Criação de um instantâneo de pré-atualização [preupgrade- <cluster-name>- <version-from>-to- -].
Atualização em andamento: volume de clonagem.
Atualização em andamento: atualizando gravador.
Atualização em andamento: atualizando leitores.
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.

A partir do AWS CLI, você pode executar aws docdb describe-eventspara monitorar o progresso da atualização. Para receber notificações automaticamente, use aws docdb create-event-subscriptionpara se inscrever em eventos e encaminhá-los para o Amazon SNS para e-mail, mensagens push ou outros métodos de entrega. Para obter mais informações, consulte Tornar-se assinante de eventos do Amazon DocumentDB.


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 preenche novamente os metadados do í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 reinicie, 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. Recomendamos esperar até que você observe 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: o processo de atualização dos metadados do índice foi 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.

Faça um snapshot 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 da versão principal no local for concluída.
Clusters de tags atualizados da versão 3.6. Adicione uma tag para diferenciar os clusters atualizados da versão 3.6. (verPost-upgrade considerações para clusters atualizados da versão 3.6 ou 4.0).
Atualize seu driver. Para usar novos recursos (por exemplo, agrupamento, visualizações ou compressão Zstd na versão 8.0), atualize para a versão correspondente da API do MongoDB. Para obter mais informações, consulte O que há de novo no Amazon DocumentDB 8.0.
Teste minuciosamente. Valide seu aplicativo em relação ao cluster atualizado.

O que muda após a atualização do Amazon DocumentDB 5.0 para 8.0

Depois de realizar uma atualização de versão principal do Amazon DocumentDB 5.0 para 8.0, os seguintes recursos são habilitados ou alterados:

Cotejo. O Amazon DocumentDB 8.0 oferece suporte ao agrupamento. Após a atualização, novas coleções e seus índices, e novos índices em coleções existentes, têm o agrupamento habilitado 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 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 compressã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 as vantagens da 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.
Reconstrução do índice. Se você estiver atualizando do Amazon DocumentDB 5.0 para o Amazon DocumentDB 8.0, nenhuma reconstrução do índice será necessária.

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, consulteCompatibilidade do Amazon DocumentDB com MongoDB.

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 melhorou a manutenção de índices e a coleta de lixo, especialmente para índices de baixa cardinalidade. Depois da atualização da versão 3.6 ou 4.0, recomendamos reconstruir seus índices para garantir o desempenho ideal da consulta (opcional, envolve mais). I/O Consulte Manutenção de índices usando 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

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 para o tipo de instância. Faça upgrade para um tipo de instância maior antes de tentar o upgrade novamente. Para ver os limites de índice por tipo de instância, consultePré-requisitos.
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 a usá-lo. 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 durante a atualização dos metadados do índice. 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.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Datas de suporte da versão do mecanismo

Atualizando uma versão secundária do motor