Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# Aggiornamento immediato della versione principale di Amazon DocumentDB
Puoi eseguire un aggiornamento della versione principale (Major Version Upgrade) 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 tutte le regioni in cui è disponibile Amazon DocumentDB.
**Importante**
Il cluster non sarà disponibile durante l'aggiornamento e verrà sottoposto a più riavvii. Non connettetevi, non leggete o scrivete sul cluster dopo l'avvio dell'aggiornamento. I tempi di inattività variano a seconda del numero di raccolte, indici, database e istanze. Si consiglia di eseguire l'aggiornamento durante la finestra di manutenzione o durante gli orari di scarsa utilizzazione.
Una volta effettuato l'aggiornamento, non è possibile effettuare il downgrade a una versione precedente. Se necessario, è possibile ripristinare l'istantanea precedente all'aggiornamento su un nuovo cluster.
**Topics**
+ [Percorsi di aggiornamento supportati](#mvu-upgrade-paths)
+ [Prerequisiti](#mvu-prerequisites)
+ [Best practice](#mvu-best-practices)
+ [Cosa cambia dopo l'aggiornamento da Amazon DocumentDB 5.0 a 8.0](#mvu-50-to-80-differences)
+ [Post-upgrade considerazioni per i cluster aggiornati dalla versione 3.6 o 4.0](#mvu-36-to-50-differences)
+ [Esecuzione dell'aggiornamento](#perform-an-mvu)
+ [Risoluzione dei problemi](#mvu-troubleshooting)
## Percorsi di aggiornamento supportati
| Versione di origine | Versione di destinazione |
| --- | --- |
| Amazon DocumentDB 3.6 | Amazon DocumentDB 5.0 |
| Amazon DocumentDB 4.0 | Amazon DocumentDB 5.0 |
| Amazon DocumentDB 5.0 | Amazon DocumentDB 8.0 |
**Nota**
In-place MVU non è supportato per cluster globali o 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. Saranno I/O addebitati dei costi mentre il sistema primario aggiornato replica i dati sui nuovi sistemi secondari. Per informazioni dettagliate sulle fasi, consulta [Rimozione di un cluster da un cluster globale Amazon DocumentDB](global-clusters.manage.md#global-clusters.remove).
## Prerequisiti
+ **Tipo di istanza**: Amazon DocumentDB 4.0\+ non supporta istanze db.r4. Modifica qualsiasi `db.r4.*` istanza in istanze o versioni successive prima dell'aggiornamento. `db.r5.*` Consulta [Modifica di un'istanza Amazon DocumentDB](db-instance-modify.md) e [Classi di istanza supportate per regione](db-instance-classes.md#db-instance-classes-by-region).
+ **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](db-instance-maintain.md#os-system-updates).
**Nota**
Le patch in sospeso del motore a livello di cluster possono nascondere le patch del sistema operativo delle istanze. Se necessario, applica prima le patch al motore. Per informazioni, consulta [Esecuzione di un aggiornamento della patch alla versione del motore di un cluster](db-cluster-version-upgrade.md).
+ **Limiti di indice sulle istanze espandibili (istanze della famiglia t): se disponi di più di 3.000 indici sulle istanze espandibili, aumenta il primario almeno a db.r5.large** prima dell'aggiornamento. È possibile ridimensionare la scala al termine dell'aggiornamento.
[See the AWS documentation website for more details](http://docs.aws.amazon.com/it_it/documentdb/latest/developerguide/docdb-mvu.html)
+ **Gruppo di parametri**: si consiglia di disporre di 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` o`default.docdb8.0`).
+ **Istantanea manuale**: crea un'istantanea manuale prima dell'aggiornamento. Il processo di aggiornamento crea un'istantanea automatica denominata`preupgrade---`, ma consigliamo vivamente di avere un backup personale. Per informazioni, consulta [Creazione di un'istantanea manuale del cluster](backup_restore-create_manual_cluster_snapshot.md).
**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 addebito purché rientri nel periodo di conservazione. È possibile scegliere di eliminare questa istantanea dopo aver verificato l'avvenuto aggiornamento del cluster.
## Best practice
### Prima dell'aggiornamento: test con un clone
1. [Clonazione di un volume per un cluster Amazon DocumentDB](db-cluster-cloning.md)Usalo per creare un clone del tuo cluster. Non dovrai sostenere costi di archiviazione a meno che non modifichi i dati sul clone.
1. Abbina il numero di istanze del clone al cluster di destinazione per una stima realistica del tempo.
1. Eseguite l'MVU sul clone e verificate completamente le differenze funzionali.
1. Verifica se un aggiornamento è già pianificato eseguendo [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/describe-db-clusters.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/describe-db-clusters.html)e cercando. `PendingModifiedValues.EngineVersion` Se hai modificato il cluster e hai scelto di applicarlo nella finestra di manutenzione successiva, la pianificazione non sarà visibile nella console ma potrai visualizzarla su AWS CLI:
```
aws docdb describe-db-clusters \
--region {{us-east-1}} \
--db-cluster-identifier {{mydocdbcluster}}
```
```
"PendingModifiedValues": {
"EngineVersion": "5.0.0"
},
```
1. 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 loco 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 a`upgrading`. `available`
Durante l'aggiornamento vengono generati i seguenti eventi:
1. È iniziato l'aggiornamento della versione principale del motore del cluster di database. Il cluster rimane online.
1. Preparazione dell’aggiornamento in corso: avvio dei controlli preliminari di aggiornamento online.
1. Preparazione dell’aggiornamento in corso: completamento dei controlli preliminari di aggiornamento online.
1. Disattivazione del cluster di database mentre l'istanza principale completa il patch/upgrade processo.
1. Preparazione dell'aggiornamento in corso: avvio dei controlli preliminari di aggiornamento offline.
1. Preparazione dell'aggiornamento in corso: precontrolli preliminari di aggiornamento offline completati.
1. Aggiornamento in corso: creazione di un'istantanea di pre-aggiornamento [preupgrade- - -to- -].
1. Aggiornamento in corso: clonazione del volume.
1. Aggiornamento in corso: aggiornamento di writer.
1. Aggiornamento in corso: aggiornamento dei lettori.
1. La versione principale del motore del cluster database è stata aggiornata.
Gli eventi sono visibili nella console nella pagina **Eventi**:
Da AWS CLI, puoi eseguire [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/describe-events.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/describe-events.html)per monitorare l'avanzamento dell'aggiornamento. Per ricevere notifiche automaticamente, usale [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/create-event-subscription.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/create-event-subscription.html)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](event-subscriptions.subscribe.md).
```
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, il cluster Amazon DocumentDB ripopola i metadati dell'indice utilizzati dal motore di 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 nel cluster.
Non riavviate, eseguite il failover o non up/down ridimensionate l'istanza di Writer durante questo periodo, poiché ciò potrebbe interrompere il ricalcolo dei metadati dell'indice. Si consiglia di attendere 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.
1. **Scatta un'istantanea manuale** del cluster aggiornato nel caso in cui sia necessario ripristinare lo stato successivo all'aggiornamento. Il processo di creazione automatica delle istantanee riprenderà non appena sarà completato l'aggiornamento della versione principale in atto.
1. **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](#mvu-36-to-50-differences)
1. **Aggiorna il driver.** Per utilizzare nuove funzionalità (ad esempio, collation, views o compressione Zstd in 8.0), esegui l'upgrade alla versione dell'API MongoDB corrispondente. Per ulteriori informazioni, consulta [Novità in Amazon DocumentDB](https://docs.aws.amazon.com/documentdb/latest/developerguide/compatibility.html#compatibility-whatsnew-8) 8.0.
1. **Esegui test approfonditi.** 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à sono abilitate o modificate:
+ **Collazione.** [Amazon DocumentDB 8.0 supporta la collazione.](https://docs.aws.amazon.com/documentdb/latest/developerguide/collation.html) Dopo l'aggiornamento, per le nuove raccolte e i relativi indici e per i nuovi indici sulle raccolte esistenti, le regole di confronto sono abilitate per impostazione predefinita.
+ **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 vengono modificati.
+ **Versione del pianificatore di query.** Se non disponevi di un gruppo di parametri personalizzato, viene creato un nuovo gruppo di parametri predefinito per Amazon DocumentDB 8.0 con Planner versione 3 selezionato automaticamente. Con la versione 3 di Query Planner, sono disponibili anche le [visualizzazioni](https://docs.aws.amazon.com/documentdb/latest/developerguide/views.html).
+ **Compressione.** Amazon DocumentDB 8.0 supporta la compressione di 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, consultate la sezione Dictionary-based compressione.](https://docs.aws.amazon.com/documentdb/latest/developerguide/dict-compression.html)
+ **Ricostruzione dell'indice.** Se si esegue l'aggiornamento da Amazon DocumentDB 5.0 ad Amazon DocumentDB 8.0, non è necessaria la ricostruzione dell'indice.
**Nota**
Per un elenco completo delle differenze funzionali, consulta. [Compatibilità di Amazon DocumentDB con MongoDB](compatibility.md)
## 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 raccolta dei rifiuti, in particolare per gli indici a bassa cardinalità. Dopo l'aggiornamento dalla versione 3.6 o 4.0, consigliamo di ricostruire gli indici per garantire prestazioni ottimali delle query (facoltativo, comporta ulteriori operazioni). I/O Per informazioni, consulta [Manutenzione dell'indice utilizzando `reIndex`](managing-indexes.md#reIndex).
+ **Confronto numerico tra sottodocumenti (solo 3.6).** I cluster aggiornati dalla versione 3.6 ereditano il comportamento 3.6 in base al quale i tipi numerici nei documenti secondari non vengono confrontati tra i tipi. Ad esempio, `{a: {b: NumberLong(1)}}` non è uguale `{a: {b: 1}}` nella versione 3.6, ma è uguale nella versione 4.0 e versioni successive. Questo comportamento influisce su tutti i cluster aggiornati dalla versione 3.6.
## Esecuzione dell'aggiornamento
------
#### [ Using the Console di gestione AWS ]
1. Accedi [Console di gestione AWS](https://console.aws.amazon.com/docdb/home?region=us-east-1)e apri la console Amazon DocumentDB.
1. **Nella tabella **Cluster**, seleziona il cluster di origine, fai clic su **Azioni**, quindi su Modifica.**
1. **Nelle **specifiche del cluster**, scegli la versione di destinazione (ad esempio, **5.0.0 o **8.0.0****) dal menu a discesa della versione del motore.**
1. Nelle **opzioni del cluster**, selezionate il gruppo di parametri del cluster per la versione del motore di destinazione. È possibile utilizzare il gruppo di parametri predefinito (ad esempio, **default.docdb5.0 o **default.docdb8.0****) o un gruppo di parametri personalizzato creato dall'utente.
1. Scegli **Continua**, seleziona la tua preferenza di pianificazione (applica immediatamente o nella finestra di manutenzione successiva), quindi scegli **Modifica cluster**.
1. **Monitora lo stato del cluster nella tabella dei cluster man mano che passa all'aggiornamento:**
------
#### [ Using the AWS CLI ]
Usa [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/modify-db-cluster.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/docdb/modify-db-cluster.html)con la bandiera: `--allow-major-version-upgrade`
```
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}}
```
Sostituisci ciascuno {{placeholder}} con le informazioni del tuo cluster.
------
## Risoluzione dei problemi
+ **Errore di aggiornamento e rollback.** Se l'aggiornamento fallisce, tenta automaticamente di eseguire il rollback. Un rollback riuscito genera l'evento: «Il cluster di database si trova in uno stato che non può essere aggiornato». Il cluster torna allo stato precedente all'aggiornamento ed è possibile continuare a utilizzarlo. Contatta l' AWS assistenza per risolvere i problemi prima di riprovare.
+ **Post-upgrade prestazioni.** Durante l'aggiornamento dei metadati dell'indice possono verificarsi un temporaneo peggioramento delle prestazioni e un elevato utilizzo della CPU. Se il degrado persiste oltre le 3 ore, contatta l'assistenza. AWS
Per ulteriore assistenza, contatta l'[AWS assistenza](https://aws.amazon.com/support).