Percorsi di aggiornamento supportati Prerequisiti Best practice Cosa cambia dopo l'aggiornamento da Amazon DocumentDB 5.0 a 8.0 Post-upgrade considerazioni per i cluster aggiornati dalla versione 3.6 o 4.0 Esecuzione dell'aggiornamento Risoluzione dei problemi

Aggiornamento della versione principale in-place di Amazon DocumentDB

Puoi eseguire un aggiornamento della versione principale (MVU) sul posto del tuo cluster Amazon DocumentDB mantenendo gli stessi endpoint, storage e tag. Le tue applicazioni continuano a funzionare senza modifiche. Questa funzionalità è disponibile senza costi aggiuntivi in tutti i paesi in Regioni AWS cui è disponibile Amazon DocumentDB.

Importante

Il cluster non è disponibile durante l'aggiornamento e si riavvia più volte. Non connettere, leggere o scrivere sul cluster dopo aver avviato l'aggiornamento. Il tempo di inattività varia in base al numero di raccolte, indici, database e istanze. Eseguite l'aggiornamento durante la finestra di manutenzione o durante le ore di scarso utilizzo.

Una volta eseguito l'aggiornamento, non è possibile effettuare il downgrade a una versione precedente. Se necessario, puoi ripristinare lo snapshot precedente all'aggiornamento su un nuovo cluster.

Argomenti

Percorsi di aggiornamento supportati
Prerequisiti
Best practice
Cosa cambia dopo l'aggiornamento da Amazon DocumentDB 5.0 a 8.0
Post-upgrade considerazioni per i cluster aggiornati dalla versione 3.6 o 4.0
Esecuzione dell'aggiornamento
Risoluzione dei problemi

Percorsi di aggiornamento supportati

La tabella seguente elenca tutti i percorsi di aggiornamento della versione principale in loco supportati. È possibile selezionare qualsiasi versione secondaria pubblicata sulla versione principale di destinazione come versione del motore di destinazione.

Versione principale di origine	Versione principale di Target	Note
Amazon DocumentDB 3.6	Amazon DocumentDB 5.0 (qualsiasi versione secondaria pubblicata)	Consulta la sezione Post-upgrade considerazioni per i cluster aggiornati dalla versione 3.6 o 4.0 per le considerazioni successive all'aggiornamento.
Amazon DocumentDB 4.0	Amazon DocumentDB 5.0 (qualsiasi versione secondaria pubblicata)	Consulta la sezione Post-upgrade considerazioni per i cluster aggiornati dalla versione 3.6 o 4.0 per le considerazioni successive all'aggiornamento.
Amazon DocumentDB 5.0 (qualsiasi versione secondaria pubblicata)	Amazon DocumentDB 8.0 (qualsiasi versione secondaria pubblicata)	Consulta le Cosa cambia dopo l'aggiornamento da Amazon DocumentDB 5.0 a 8.0 modifiche alle funzionalità.

Per visualizzare le versioni secondarie disponibili nella tua AWS regione, usa il AWS CLI comandoaws docdb describe-db-engine-versions. Per un elenco delle versioni secondarie rilasciate, consultaNote di rilascio.

Nota

Ogni MVU può indirizzare qualsiasi versione secondaria pubblicata sulla principale di destinazione. Ad esempio, l'aggiornamento da Amazon DocumentDB 3.6 o 4.0 può passare direttamente all'ultima versione secondaria 5.0 pubblicata; non è necessario eseguire prima l'aggiornamento alla 5.0.0 e quindi applicare un aggiornamento della versione secondaria.

Per passare alla versione 8.0 da 3.6 o 4.0, esegui due MVU: prima a una versione secondaria 5.0 a tua scelta, poi a una versione secondaria 8.0 a tua scelta. Non esiste un percorso MVU diretto 3.6→8.0 o 4.0→8.0.

Nota

In-place MVU non è supportato per i cluster globali o i cluster elastici. Per aggiornare un cluster globale, rimuovi i cluster secondari, converti il cluster primario in un cluster regionale, esegui l'MVU, quindi ricrea il cluster globale aggiungendo cluster secondari con gli stessi nomi per conservare gli endpoint. Ti verranno addebitati dei I/O costi mentre il sistema primario aggiornato replica i dati sui nuovi secondari. Per informazioni dettagliate sulle fasi, consulta Rimuovere un cluster da un cluster globale Amazon DocumentDB.

Prerequisiti

Importante

Aumenta la scalabilità delle istanze burstable prima dell'aggiornamento. Se il tuo cluster utilizza tipi di istanza burstable (ad esempio, db.t3.medium ordb.t4g.medium), aumenta l'istanza primaria almeno db.r5.large o db.r6g.large prima di iniziare l'aggiornamento. Le istanze burstable potrebbero non disporre di CPU e memoria sufficienti per completare il processo di aggiornamento, con conseguenti errori di aggiornamento e prolungata indisponibilità del cluster. È possibile ridimensionare il sistema una volta completato l'aggiornamento.

Aumenta la scalabilità dell'istanza serverless writer prima dell'aggiornamento. Se il cluster ha un'istanza di writer serverless, la DCU massima in ServerlessV2ScalingConfiguration deve essere impostata su 3 o superiore prima di iniziare l'aggiornamento. I cluster con una DCU massima inferiore a 3 non possono essere aggiornati perché non dispongono di CPU o memoria sufficienti per completare l'aggiornamento.

Controlla gli indici parziali prima dell'aggiornamento (aggiornamento da Amazon DocumentDB 5.0 a 8.0). Prima di iniziare l'aggiornamento, controlla i tuoi indici parziali per verificare partialFilterExpression che l'$typeoperatore corrisponda a determinati tipi di BSON: in particolare gli alias binDatabool,date, doubledecimal, e array di tipo o un codice di tipo numerico come. { "$type" : 1 } Tali indici parziali causano il fallimento dell'aggiornamento, anche se l'indice funziona normalmente per le letture e le scritture. db.collection.getIndexes()Usalo per rivedere i tuoi partialFilterExpression indici parziali. Elimina l'indice parziale interessato prima di iniziare l'aggiornamento e ricrealo al termine dell'aggiornamento. Se non sei sicuro che un indice sia interessato, contatta l' AWS assistenza prima dell'aggiornamento.

Tipo di istanza: Amazon DocumentDB 4.0+ non supporta le istanze db.r4. Modifica qualsiasi db.r4.* istanza in istanze o più recenti prima dell'aggiornamento. db.r5.* Consulta Modifica di un'istanza Amazon DocumentDB e Classi di istanze supportate per regione.
Patch del sistema operativo: applica eventuali azioni di manutenzione del sistema operativo in sospeso su tutte le istanze prima dell'aggiornamento. Per informazioni, consulta Aggiornamenti del sistema operativo Amazon DocumentDB.

Nota
Le patch del motore a livello di cluster in sospeso possono nascondere le patch del sistema operativo dell'istanza. Se necessario, applica prima le patch del motore. Per informazioni, consulta Esecuzione di un aggiornamento della patch alla versione del motore di un cluster.
Limiti dell'indice sulle istanze burstable (istanze della famiglia t): se hai più di 3.000 indici sulle istanze burstable, aumenta il primario ad almeno db.r5.large prima dell'aggiornamento. Puoi ridimensionare la scala al termine dell'aggiornamento.

Istanza Indici massimi per MVU

db.t4g.medium

3K

db.t3.medium

10.000
Gruppo di parametri: prepara un gruppo di parametri del cluster personalizzato per la versione di destinazione prima dell'aggiornamento. Se non ne viene specificato uno, verrà utilizzato il gruppo di parametri predefinito per la versione di destinazione (ad esempio, default.docdb5.0 odefault.docdb8.0).
Istantanea manuale: crea un'istantanea manuale prima dell'aggiornamento. Il processo di aggiornamento crea un'istantanea automatica denominatapreupgrade-<name>-<version>-<timestamp>, ma crea sempre il tuo backup. Per informazioni, consulta Creazione manuale di un'istantanea del cluster.

Nota
L'istantanea automatica creata dal processo di aggiornamento non verrà eliminata automaticamente dopo il completamento dell'aggiornamento della versione principale sul posto. Questa istantanea non comporterà alcun costo fintanto che rientra nel periodo di conservazione. Puoi scegliere di eliminare questa istantanea dopo aver verificato l'avvenuto aggiornamento del cluster.

Istanza	Indici massimi per MVU
db.t4g.medium	3K
db.t3.medium	10.000

Best practice

Prima dell'aggiornamento: test con un clone

Utilizzalo Clonazione di un volume per un cluster Amazon DocumentDB per creare un clone del tuo cluster. Non dovrai sostenere costi di archiviazione a meno che non modifichi i dati sul clone.
Abbina il numero di istanze del clone al cluster di destinazione per una stima realistica dei tempi.
Esegui l'MVU sul clone e verifica completamente le differenze funzionali.
Controlla se è già programmato un aggiornamento eseguendo describe-db-clusters e cercando. PendingModifiedValues.EngineVersion Se hai modificato il cluster e hai scelto di applicarlo nella successiva finestra di manutenzione, la pianificazione non sarà visibile nella console ma potrai visualizzarla in AWS CLI:
```
aws docdb describe-db-clusters \
  --region us-east-1 \
  --db-cluster-identifier mydocdbcluster
```
```
"PendingModifiedValues": {
    "EngineVersion": "5.0.0"
},
```
Se il test ha esito positivo, procedi con l'aggiornamento del cluster di produzione.

Durante l'aggiornamento

È possibile monitorare lo stato di avanzamento dell'aggiornamento della versione principale in corso sottoscrivendo gli eventi di manutenzione del cluster. Al termine dell'aggiornamento, riceverai l'evento «La versione principale del cluster di database è stata aggiornata». Questo e altri eventi che si verificano durante l'aggiornamento vengono visualizzati nella sezione Eventi e tag della pagina dei dettagli del cluster nella console Amazon DocumentDB. Lo stato del cluster cambia quindi da aupgrading. available

Durante l'aggiornamento vengono generati i seguenti eventi:

È iniziato l'aggiornamento della versione principale del motore del cluster di database. Il cluster rimane online.
Preparazione dell’aggiornamento in corso: avvio dei controlli preliminari di aggiornamento online.
Preparazione dell’aggiornamento in corso: completamento dei controlli preliminari di aggiornamento online.
Mettere offline il cluster di database mentre l'istanza principale completa il patch/upgrade processo.
Preparazione dell'aggiornamento in corso: avvio dei controlli preliminari dell'aggiornamento offline.
Preparazione dell'aggiornamento in corso: controlli preliminari per l'aggiornamento offline completati.
<version-to><timestamp>Aggiornamento in corso: creazione di un'istantanea precedente all'aggiornamento [preupgrade- <cluster-name>- <version-from>-to- -].
Aggiornamento in corso: clonazione del volume.
Aggiornamento in corso: aggiornamento di writer.
Aggiornamento in corso: aggiornamento dei lettori.
La versione principale del motore del cluster database è stata aggiornata.

Gli eventi sono visibili nella console nella pagina Eventi:

Immagine: la casella di navigazione Eventi che mostra una tabella degli eventi di aggiornamento.

Da AWS CLI, è possibile eseguire aws docdb describe-events per monitorare l'avanzamento dell'aggiornamento. Per ricevere notifiche automaticamente, utilizza l'aws docdb create-event-subscriptionopzione per iscriverti agli eventi e indirizzarli ad Amazon SNS per e-mail, messaggi push o altri metodi di consegna. Per ulteriori informazioni, consulta Iscrizione agli eventi di Amazon DocumentDB.


aws docdb describe-events 
  --source-identifier mydocdbcluster 
  --source-type db-cluster

Il comando restituisce un output simile al seguente:


{
    "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"
        }
    ]
}

Dopo l'aggiornamento

avvertimento

Subito dopo l'aggiornamento della versione principale sul posto, il cluster Amazon DocumentDB ripopola i metadati degli indici utilizzati dal motore del database per ottimizzare i piani di esecuzione delle query. Le prestazioni delle query tornano ai livelli previsti una volta completato questo processo. In genere termina in pochi minuti, ma può richiedere fino a due ore a seconda del numero di indici sul cluster.

Non riavviate, eseguite il failover o scalate l'istanza di writer durante questo periodo, poiché ciò potrebbe interrompere up/down il ricalcolo dei metadati dell'indice. Attendi di osservare le prestazioni previste delle query prima di apportare tali modifiche.

Tieni traccia dei progressi tramite i seguenti eventi del cluster:

Post-upgrade stato del cluster: è iniziato il processo di aggiornamento dei metadati dell'indice
Post-upgrade stato del cluster: processo di aggiornamento dei metadati dell'indice completato in X secondi

Contatta l' AWS assistenza se il processo di aggiornamento dei metadati dell'indice non viene completato entro tre ore o se continui a riscontrare problemi di prestazioni dopo il completamento del processo.

Scatta un'istantanea manuale del cluster aggiornato nel caso in cui sia necessario ripristinare lo stato successivo all'aggiornamento. Il processo di istantanea automatica riprenderà non appena sarà completato l'aggiornamento della versione principale sul posto.
Cluster di tag aggiornati dalla versione 3.6. Aggiungi un tag per differenziare i cluster aggiornati dalla versione 3.6. (vedi). Post-upgrade considerazioni per i cluster aggiornati dalla versione 3.6 o 4.0
Aggiorna il driver. Per utilizzare nuove funzionalità (ad esempio, confronto, visualizzazioni o compressione Zstd in 8.0), esegui l'aggiornamento alla versione corrispondente dell'API MongoDB. Per ulteriori informazioni, consulta Cosa c'è di nuovo in Amazon DocumentDB 8.0.
Esegui un test approfondito. Convalida la tua applicazione rispetto al cluster aggiornato.

Cosa cambia dopo l'aggiornamento da Amazon DocumentDB 5.0 a 8.0

Dopo aver eseguito un aggiornamento della versione principale da Amazon DocumentDB 5.0 a 8.0, le seguenti funzionalità vengono abilitate o modificate:

Fascicolazione. Amazon DocumentDB 8.0 supporta la raccolta. Dopo l'aggiornamento, le regole di confronto sono abilitate per impostazione predefinita per le nuove raccolte e i relativi indici e per i nuovi indici sulle raccolte esistenti.
Indice di testo. I nuovi indici di testo vengono creati utilizzando Text Index V2, che utilizza un parser di ricerca di testo aggiornato per una migliore compatibilità con MongoDB. Gli indici di testo esistenti non sono interessati.
Versione Query Planner. Se non disponi di un gruppo di parametri personalizzato, viene creato un nuovo gruppo di parametri predefinito per Amazon DocumentDB 8.0 con Planner versione 3 selezionata automaticamente. Con la versione 3 di Query Planner, sono disponibili anche le visualizzazioni.
Compressione. Amazon DocumentDB 8.0 supporta la compressione dei documenti basata su dizionari utilizzando l'algoritmo Zstd. Dopo l'aggiornamento, vengono create nuove raccolte con la compressione Zstd abilitata per impostazione predefinita. Le raccolte esistenti a partire dalla versione 5.0 mantengono le impostazioni di compressione. Per sfruttare la compressione Zstd sulle raccolte esistenti, puoi modificarne le impostazioni di compressione. Per ulteriori informazioni, consulta Gestione della compressione basata su dizionari in Amazon DocumentDB 8.0.
Ricostruzione dell'indice. Se si esegue l'aggiornamento da Amazon DocumentDB 5.0 ad Amazon DocumentDB 8.0, non è necessaria la ricostruzione dell'indice.

Importante

Amazon DocumentDB 8.0 richiede TLS 1.2 o versioni successive. TLS 1.0 e TLS 1.1 non sono più supportati.

Nota

Per un elenco completo delle differenze funzionali, consulta. Compatibilità di Amazon DocumentDB con MongoDB

Post-upgrade considerazioni per i cluster aggiornati dalla versione 3.6 o 4.0

Ricostruzione dell'indice. Un MVU mantiene gli indici originali. Amazon DocumentDB 5.0 ha migliorato la manutenzione degli indici e la garbage collection, in particolare per gli indici a bassa cardinalità. Dopo l'aggiornamento dalla versione 3.6 o 4.0, ricostruisci gli indici per garantire prestazioni ottimali delle query (opzionale, comporta l'aggiunta di ulteriori). I/O Per informazioni, consulta Manutenzione dell'indice utilizzando ReIndex .
Confronto numerico tra documenti secondari (solo 3.6). I cluster aggiornati dalla versione 3.6 ereditano il comportamento 3.6 in cui i tipi numerici nei documenti secondari non vengono confrontati tra i tipi. Ad esempio, {a: {b: NumberLong(1)}} non è uguale {a: {b: 1}} in 3.6, ma è uguale in 4.0 e versioni successive. Questo comportamento influisce su tutti i cluster aggiornati dalla versione 3.6.

Esecuzione dell'aggiornamento

Risoluzione dei problemi

Pre-upgrade errore di controllo. Prima dell'inizio dell'aggiornamento, Amazon DocumentDB esegue controlli di convalida pre-aggiornamento. Le seguenti sono le cause più comuni di errori di pre-controllo:
- L'aggiornamento non può procedere perché le raccolte hanno nomi con 58 o più caratteri. Rinomina le raccolte interessate con nomi più brevi prima di riprovare l'aggiornamento.
- L'aggiornamento non può procedere perché il numero di indici supera il limite per il tipo di istanza. Esegui l'upgrade a un tipo di istanza più grande prima di riprovare l'aggiornamento. Per i limiti dell'indice per tipo di istanza, consulta. Prerequisiti
Errore di aggiornamento e rollback. Se l'aggiornamento non riesce, tenta automaticamente un rollback. Un rollback riuscito genera l'evento: «Il cluster di database è in uno stato che non può essere aggiornato». Il cluster torna allo stato precedente all'aggiornamento e puoi continuare a utilizzarlo. Contatta l' AWS assistenza per risolvere il problema prima di riprovare.
Post-upgrade prestazioni. Durante l'esecuzione dell'aggiornamento dei metadati dell'indice possono verificarsi un temporaneo peggioramento delle prestazioni e un elevato utilizzo della CPU. Se il deterioramento persiste per oltre 3 ore, contatta l'assistenza. AWS

Per ulteriore assistenza, contatta. Supporto AWS

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Date di supporto delle versioni del motore

Aggiornamento di una versione secondaria del motore