CKTIS / JavaScript
IndexedDB: onupgradeneeded und die Upgrade-Transaktion
Ändere das IndexedDB-Schema in `onupgradeneeded`, greife über `request.transaction` auf die Upgrade-Transaktion zu und verwende das neue Schema erst nach `success`.
Version: Current web platform; runtime support varies
Syntax
// 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) gibt sofort ein IDBOpenDBRequest zurück; die Datenbank wird asynchron geöffnet. onupgradeneeded ist die Handler-Eigenschaft für das Ereignis upgradeneeded. Es wird beim Anlegen einer Datenbank oder beim Öffnen mit einer höheren Version ausgelöst. Bei gleicher Version bleibt es aus; eine niedrigere Version führt zu VersionError. IndexedDB ist eine Web-API und keine Funktion von ECMAScript 2024.
Im Handler enthält request.result die IDBDatabase-Verbindung. Die von IDBRequest geerbte, schreibgeschützte Eigenschaft request.transaction enthält die von IndexedDB automatisch erzeugte IDBTransaction im Modus "versionchange". Direkt nach open() und erneut bei success ist sie null. db.transaction() startet eine separate Transaktion im Modus "readonly" oder "readwrite", keine Upgrade-Transaktion.
Wähle anhand von event.oldVersion und event.newVersion die Migrationsschritte aus. Bei einer neuen Datenbank ist oldVersion gleich 0; getrennte Versionsprüfungen führen auch beim Überspringen von Zwischenversionen mehrere Schritte aus. Lege einen Objektspeicher mit db.createObjectStore() an und füge einem vorhandenen Speicher mit tx.objectStore(name).createIndex() einen Index hinzu. In derselben Transaktion lassen sich auch Datensätze migrieren.
Plane Operationen ein, solange die Transaktion aktiv ist: direkt im upgradeneeded-Handler oder in den Ereignishandlern ihrer Anfragen. Verlass dich nicht darauf, dass sie nach await fetch() oder in einem Timer-Callback noch aktiv ist. tx.abort() macht Schema-, Daten- und Versionsänderungen rückgängig; die Öffnungsanfrage löst dann error statt success aus. Wird die Transaktion erfolgreich abgeschlossen, kommt ihr complete vor dem success der Öffnungsanfrage.
Eine bestehende Verbindung, etwa in einem anderen Tab, kann das Upgrade aufhalten. Behandle blocked bei der Öffnungsanfrage und schließe bestehende Verbindungen in ihren versionchange-Handlern mit db.close().
Beispiele
<!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>Ergebnis
before: null upgrade: 1 -> 2 (versionchange) complete success: null; index: true
Öffne die HTML-Seite im Browser in einem sicheren Kontext, in dem IndexedDB und `crypto.randomUUID()` verfügbar sind. Die Ausgabe erscheint in der Entwicklerkonsole. Das Beispiel legt eine Datenbank mit zufälligem Namen in Version 1 an, schließt die Verbindung, fügt `by_title` in Version 2 hinzu und fordert nach der Indexprüfung das Löschen der Testdatenbank an.
Zugehörige Lektionen
- JavaScript · Lektion 31 · Fortgeschritten · Version: 4
Quellen
- 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