CKTIS / JavaScript
Apertura di IndexedDB: upgradeneeded, blocked, success ed error
Distingui quando una richiesta di apertura di IndexedDB deve aggiornare lo schema, attende la chiusura di una connessione, riesce o fallisce.
Versione: ECMAScript 2024 and the current web platform; runtime support varies
Sintassi
const request = indexedDB.open(name); // or indexedDB.open(name, version)
request.addEventListener("upgradeneeded", onUpgradeNeeded);
request.addEventListener("blocked", onBlocked);
request.addEventListener("success", onSuccess);
request.addEventListener("error", onError);
// Alternatively, assign one handler to each property:
request.onupgradeneeded = onUpgradeNeeded;
request.onblocked = onBlocked;
request.onsuccess = onSuccess;
request.onerror = onError;indexedDB.open(name, version) restituisce subito un IDBOpenDBRequest, non una Promise. L’apertura è asincrona. upgradeneeded e blocked appartengono a IDBOpenDBRequest; success ed error sono ereditati da IDBRequest. Se ometti version, viene aperta la versione esistente oppure viene creato un database alla versione 1. IndexedDB è un’API della piattaforma web, non di ECMAScript; l’accesso dipende dall’ambiente di esecuzione e dalle impostazioni di archiviazione.
upgradeneeded si verifica quando si crea il database (oldVersion === 0) o si richiede una versione superiore. Usa oldVersion e newVersion dell’evento per scegliere le migrazioni da eseguire. Modifica lo schema tramite request.result all’interno della transazione versionchange attiva, disponibile in request.transaction. Non dare per scontato che resti attiva mentre attendi un’operazione indipendente come fetch().
blocked indica che la richiesta di aggiornamento attende la chiusura di un’altra connessione allo stesso database. IndexedDB non invia versionchange a una connessione già in fase di chiusura, ma questa può comunque ritardare l’aggiornamento fino al termine delle sue transazioni. Nell’applicazione, gestisci versionchange sulla connessione IDBDatabase esistente e chiama close() su quella connessione. Usa blocked per spiegare all’utente il motivo dell’attesa. Non serve ripetere la richiesta.
success indica che request.result contiene la connessione IDBDatabase aperta. Se era necessario un aggiornamento, la relativa transazione è già stata confermata. Aprire la versione corrente non genera upgradeneeded. L’apertura riuscita non garantisce il successo delle transazioni successive.
error indica che la richiesta è fallita. Leggi la DOMException in request.error. Richiedere una versione inferiore a quella memorizzata produce VersionError; interrompere la transazione di aggiornamento annulla le sue modifiche e fa fallire l’apertura. Un errore sincrono, come TypeError per la versione 0, viene lanciato direttamente da open() senza generare un evento error.
Esempi
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>IndexedDB open request events</title>
</head>
<body>
<pre id="output"></pre>
<script>
(async () => {
const { indexedDB, crypto } = window;
const output = document.getElementById("output");
const name = `ck-tis-idb-${crypto.randomUUID()}`;
function log(line) {
output.textContent += (output.textContent ? "\n" : "") + line;
console.log(line);
}
function open(version, releaseBlocker) {
return new Promise((resolve, reject) => {
const request = indexedDB.open(name, version);
request.onupgradeneeded = ({ oldVersion, newVersion }) => {
log(`upgradeneeded: ${oldVersion} -> ${newVersion}`);
const db = request.result;
if (oldVersion < 1) db.createObjectStore("notes");
if (oldVersion < 2 && newVersion >= 2) db.createObjectStore("tags");
};
request.onblocked = () => {
log(`blocked: ${version}`);
releaseBlocker?.();
};
request.onsuccess = () => {
log(`success: ${request.result.version}`);
resolve(request.result);
};
request.onerror = () => reject(request.error);
});
}
let first;
let second;
try {
first = await open(1);
// Intentionally keep version 1 open until the next request is blocked.
second = await open(2, () => first.close());
try {
const unexpected = await open(1);
unexpected.close();
throw new Error("Expected VersionError");
} catch (error) {
if (error.name !== "VersionError") throw error;
log(`error: ${error.name}`);
}
} finally {
first?.close();
second?.close();
const cleanup = indexedDB.deleteDatabase(name);
cleanup.onerror = () => console.error(cleanup.error);
}
})().catch((error) => console.error(error));
</script>
</body>
</html>Risultato
upgradeneeded: 0 -> 1 success: 1 blocked: 2 upgradeneeded: 1 -> 2 success: 2 error: VersionError
Apri la pagina HTML tramite HTTPS o da localhost in un browser in cui sono disponibili IndexedDB e `crypto.randomUUID()`. La connessione alla versione `1` resta volutamente aperta fino a `blocked`. Chiudendola, la stessa richiesta apre la versione `2`. La richiesta successiva della versione `1` fallisce con `VersionError`.
Lezioni correlate
- JavaScript · Lezione 20 · Intermedio · Versione: 3
- JavaScript · Lezione 21 · Intermedio · Versione: 3
Fonti
- IDBOpenDBRequest
- IDBFactory: open() method
- IDBOpenDBRequest: upgradeneeded event
- IDBOpenDBRequest: blocked event
- IDBRequest: success event
- IDBRequest: error event
- IDBRequest: error property
- IDBRequest: transaction property
- IDBVersionChangeEvent
- IDBDatabase: versionchange event
- Using IndexedDB
- Crypto: randomUUID() method