CKTIS / JavaScript
IDBOpenDBRequest — een IndexedDB-database openen en bijwerken
IDBOpenDBRequest staat voor een asynchroon verzoek om een IndexedDB-database te openen of te verwijderen. Via gebeurtenissen kun je schema-upgrades, blokkering door andere verbindingen en het voltooien van de bewerking afhandelen. Het is geen databaseverbinding en ook geen Promise.
Versie: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Syntax
const request = indexedDB.open(name, version);
request.onupgradeneeded = (event) => { /* migrate schema */ };
request.addEventListener("blocked", handler);
request.addEventListener("success", handler);
request.addEventListener("error", handler);
// request.transaction: upgrade IDBTransaction or nullIDBOpenDBRequest wordt direct teruggegeven door indexedDB.open(name, version) en indexedDB.deleteDatabase(name). Het erft van IDBRequest en daarna van EventTarget; haal het resultaat op via gebeurtenissen, niet met await request. Dit is een browser-Web-API uit de IndexedDB-familie, geen ECMAScript-functie. Volgens MDN is de interface sinds juli 2015 breed beschikbaar. MDN vermeldt afzonderlijk dat de interface beschikbaar is in Web Workers. Die datum geeft niet aan sinds wanneer browsers de interface breed ondersteunen in Web Workers. Node 24 in een repository bewijst niet dat deze API wordt ondersteund.
IDBOpenDBRequest.upgradeneeded duidt de gebeurtenis upgradeneeded aan, geen methode. Deze wordt geactiveerd bij het aanmaken van een database of het openen ervan met een hogere versie. IDBOpenDBRequest.onupgradeneeded is de eigenschap waaraan je de handler toewijst; addEventListener("upgradeneeded", handler) is een alternatief. Hier maak of wijzig je object stores en indexen. De overgeërfde eigenschap IDBOpenDBRequest.transaction geeft de upgrade-transactie in de modus versionchange weer; zonder upgrade is de waarde null. Deze eigenschap staat niet voor een willekeurige latere datatransactie.
IDBOpenDBRequest.blocked duidt de gebeurtenis blocked aan: een andere open verbinding verhindert een upgrade of het verwijderen van de database. Dit is een wachttoestand, geen definitieve fout. Handel versionchange op elke verbinding af door deze met db.close() te sluiten, en informeer de gebruiker over de blokkering. Een blocked-handler sluit op zichzelf geen andere verbindingen.
IDBOpenDBRequest.success en IDBOpenDBRequest.error duiden gebeurtenissen aan die zijn overgeërfd van IDBRequest en ook via onsuccess en onerror worden afgehandeld. Na het succesvol openen bevat request.result een IDBDatabase; na verwijdering is de waarde undefined. Het openen slaagt pas nadat een vereiste upgrade is vastgelegd; upgradeneeded betekent nog niet dat het is gelukt. Controleer bij een fout request.error. Lees het resultaat niet meteen na open(); handel asynchrone fouten af via error, los van synchrone uitzonderingen die de aanroep zelf veroorzaakt.
Voorbeelden
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>IDBOpenDBRequest: opening and upgrading a database</title>
</head>
<body>
<h1>Opening and upgrading an IndexedDB database</h1>
<script>
(() => {
const name = 'cktis-open-' + crypto.getRandomValues(new Uint32Array(4)).join('-');
const report = error => console.log(error.name === 'SecurityError'
? 'IndexedDB unavailable: SecurityError' : `IndexedDB error: ${error.name}`);
let factory, opening;
try {
factory = window.indexedDB;
if (!factory) {
console.log('IndexedDB unavailable: API missing');
return;
}
opening = factory.open(name, 1);
} catch (error) {
report(error);
return;
}
let created = false;
opening.onerror = () => report(opening.error);
opening.onupgradeneeded = () => {
created = true;
opening.result.createObjectStore('notes', { keyPath: 'id' });
};
opening.onsuccess = () => {
const first = opening.result;
if (!created) {
first.close();
console.log('Fixture name already in use');
return;
}
// Hold the old connection open until the new request reports that it is blocked.
const upgrade = factory.open(name, 2);
upgrade.onblocked = event => {
console.log(`blocked: ${event.oldVersion} -> ${event.newVersion}`);
first.close();
};
upgrade.onupgradeneeded = () => {
upgrade.result.createObjectStore('labels');
console.log(`upgrade: ${upgrade.transaction.mode}`);
};
upgrade.onerror = () => {
first.close();
report(upgrade.error);
factory.deleteDatabase(name);
};
upgrade.onsuccess = () => {
const db = upgrade.result;
console.log(`open: ${db.version}, labels: ${db.objectStoreNames.contains('labels')}`);
db.close();
const deletion = factory.deleteDatabase(name);
deletion.onerror = () => report(deletion.error);
deletion.onsuccess = event => console.log(`deleted version: ${event.oldVersion}`);
};
};
})();
</script>
</body>
</html>Resultaat
Observed in the isolated run (IndexedDB access denied): IndexedDB unavailable: SecurityError Expected on a successful run with IndexedDB access: blocked: 1 -> 2 upgrade: versionchange open: 2, labels: true deleted version: 2
De getoonde code en het opgegeven resultaat zijn in een geïsoleerde omgeving geverifieerd met de methode die in het verificatiebewijs voor exact deze versie is vastgelegd.