CKTIS / JavaScript
IndexedDB: onupgradeneeded e la transazione di aggiornamento
Modifica lo schema IndexedDB in `onupgradeneeded`, accedi alla transazione con `request.transaction` e attendi `success` prima di usare il nuovo schema.
Versione: Current web platform; runtime support varies
Sintassi
// The upgrade lifecycle is defined by IndexedDB, not by an ECMAScript edition.
const request = indexedDB.open(name, version);
request.onupgradeneeded = (event) => {
const db = request.result;
const tx = request.transaction;
// Apply schema changes through db and tx while tx is active.
};indexedDB.open(name, version) restituisce subito un IDBOpenDBRequest; l’apertura avviene in modo asincrono. onupgradeneeded è la proprietà che riceve il gestore dell’evento upgradeneeded. L’evento si verifica quando si crea un database o lo si apre con una versione superiore. Con la stessa versione non si verifica; una versione inferiore causa VersionError. IndexedDB è un’API web, non una funzionalità di ECMAScript 2024.
Nel gestore, request.result contiene la connessione IDBDatabase. La proprietà di sola lettura request.transaction, ereditata da IDBRequest, contiene l’IDBTransaction che IndexedDB crea automaticamente in modalità "versionchange". Vale null subito dopo open() e di nuovo all’evento success. db.transaction() avvia una transazione separata in modalità "readonly" o "readwrite", non una transazione di aggiornamento.
Usa event.oldVersion e event.newVersion per scegliere i passaggi della migrazione. Per un nuovo database, oldVersion vale 0; controlli di versione distinti permettono di eseguire più passaggi anche se si saltano versioni intermedie. Crea un archivio di oggetti con db.createObjectStore() e aggiungi un indice a un archivio esistente con tx.objectStore(name).createIndex(). Puoi anche migrare i record nella stessa transazione.
Accoda operazioni mentre la transazione è attiva: direttamente nel gestore di upgradeneeded o nei gestori degli eventi delle sue richieste. Non dare per scontato che rimanga attiva dopo await fetch() o nella funzione di callback di un timer. tx.abort() annulla le modifiche a schema, dati e versione; la richiesta di apertura genera error anziché success. Se la transazione viene confermata, il suo evento complete precede il success della richiesta di apertura.
Una connessione esistente, per esempio in un’altra scheda, può ritardare l’aggiornamento. Gestisci blocked sulla richiesta di apertura e chiudi le connessioni esistenti con db.close() nei rispettivi gestori di versionchange.
Esempi
<!doctype html>
<meta charset="utf-8">
<title>IndexedDB upgrade transaction</title>
<script>
(() => {
const name = `cktis-indexeddb-${crypto.randomUUID()}`;
const reportError = (event) => console.error(event.target.error);
function openVersion(version) {
const request = indexedDB.open(name, version);
request.onerror = reportError;
request.onupgradeneeded = ({ oldVersion, newVersion }) => {
const db = request.result;
const tx = request.transaction;
if (oldVersion < 1) db.createObjectStore("books", { keyPath: "id" });
if (oldVersion < 2 && newVersion >= 2) {
console.log(`upgrade: ${oldVersion} -> ${newVersion} (${tx.mode})`);
tx.objectStore("books").createIndex("by_title", "title");
tx.oncomplete = () => console.log("complete");
}
};
return request;
}
const first = openVersion(1);
first.onsuccess = () => {
first.result.close();
const second = openVersion(2);
console.log(`before: ${second.transaction}`);
second.onsuccess = () => {
const db = second.result;
const store = db.transaction("books", "readonly").objectStore("books");
console.log(`success: ${second.transaction}; index: ${store.indexNames.contains("by_title")}`);
db.close();
indexedDB.deleteDatabase(name).onerror = reportError;
};
};
})();
</script>Risultato
before: null upgrade: 1 -> 2 (versionchange) complete success: null; index: true
Apri la pagina HTML nel browser in un contesto sicuro con accesso a IndexedDB e a `crypto.randomUUID()`. Controlla l’output nella console per sviluppatori. L’esempio crea un database con nome casuale alla versione 1, chiude la connessione, aggiunge `by_title` alla versione 2 e richiede l’eliminazione del database di prova dopo aver controllato l’indice.
Lezioni correlate
- JavaScript · Lezione 31 · Avanzato · Versione: 4
Fonti
- IDBOpenDBRequest: upgradeneeded event
- IDBRequest: transaction property
- IDBFactory: open() method
- IDBRequest: error property
- IDBTransaction
- IDBDatabase: transaction() method
- Using IndexedDB
- IDBOpenDBRequest: blocked event
- IDBDatabase: versionchange event
- IDBObjectStore: createIndex() method
- Crypto: randomUUID() method
- IDBFactory: deleteDatabase() method