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

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 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 para ver as 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 para ver as 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 do Amazon DocumentDB 5.0 para 8.0 para ver as mudanças de recursos.

Para ver as versões secundárias disponíveis em 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 secundária 5.0 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 alcançar o 8.0 de 3.6 ou 4.0, execute dois MVUs: primeiro para uma versão secundária 5.0 de sua escolha e depois para uma versão secundária 8.0 de sua escolha. Não há caminho direto de MVU 3,6→8,0 ou 4,0→8,0.

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.

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 oudb.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 binDatabool,date, doubledecimal, 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 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 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.
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.

Instância Índices máximos para MVU

db.t4g.medium

3 mil

db.t3.medium

10 mil
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 oudefault.docdb8.0).
Instantâneo manual — Crie um instantâneo manual antes da atualização. O processo de upgrade cria um instantâneo automático chamadopreupgrade-<name>-<version>-<timestamp>, mas sempre cria 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 o MVU no clone e teste totalmente as diferenças funcionais.
Verifique se uma atualização já está agendada executando describe-db-clusters e procurandoPendingModifiedValues.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"
},
```
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 paraavailable.

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

Foi iniciada a atualização da versão principal do mecanismo de cluster de banco de dados. 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-events para monitorar o progresso da atualização. Para receber notificações automaticamente, use aws docdb create-event-subscription 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.


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.

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.
Clusters de tags atualizados da versão 3.6. Adicione uma tag para diferenciar os clusters atualizados da versão 3.6. (vejaPost-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 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.
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 Usando agrupamento no Amazon DocumentDB 8.0 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 o Planner versão 3 selecionado 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 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.
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.

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 do índice e a coleta de lixo, especialmente para índices de baixa cardinalidade. Depois de atualizar da versão 3.6 ou 4.0, reconstrua seus índices para garantir o desempenho ideal da consulta (opcional, envolve recursos adicionais). I/O Consulte Manutenção do índice 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 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, 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 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.

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