CKTIS / JavaScript
IndexedDB: onupgradeneeded i transakcja zmiany wersji
Zmień schemat IndexedDB w `onupgradeneeded`, odczytaj transakcję z `request.transaction` i zacznij korzystać z nowego schematu po `success`.
Wersja: Current web platform; runtime support varies
Składnia
// 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) natychmiast zwraca IDBOpenDBRequest; samo otwarcie odbywa się asynchronicznie. onupgradeneeded to właściwość obsługi zdarzenia upgradeneeded. Zdarzenie jest wywoływane przy tworzeniu bazy albo otwieraniu jej z wyższą wersją. Przy tej samej wersji go nie ma, a żądanie niższej wersji kończy się błędem VersionError. IndexedDB jest API platformy webowej, a nie funkcją ECMAScript 2024.
W funkcji obsługi request.result to połączenie IDBDatabase, a request.transaction to odziedziczona z IDBRequest właściwość tylko do odczytu. Zawiera transakcję IDBTransaction w trybie "versionchange", tworzoną automatycznie przez IndexedDB. Bezpośrednio po open() i ponownie w success właściwość ta ma wartość null. db.transaction() tworzy osobną transakcję w trybie "readonly" lub "readwrite", a nie transakcję zmiany wersji.
Użyj event.oldVersion i event.newVersion, by wybrać odpowiednie kroki migracji. Dla nowej bazy oldVersion wynosi 0; kolejne, niezależne warunki pozwalają wykonać kilka kroków przy pominięciu wersji pośrednich. Utwórz magazyn przez db.createObjectStore(), a do istniejącego magazynu dodaj indeks przez tx.objectStore(name).createIndex(). W tej samej transakcji możesz też migrować dane.
Zlecaj operacje, gdy transakcja jest aktywna: bezpośrednio w funkcji obsługi upgradeneeded lub w funkcjach obsługi zdarzeń jej żądań. Nie zakładaj, że transakcja będzie nadal aktywna po await fetch() lub po upływie czasu odmierzanego przez timer. tx.abort() wycofuje zmiany schematu, danych i wersji, a żądanie otwarcia kończy się zdarzeniem error zamiast success. Jeśli transakcja zatwierdzi zmiany, najpierw wystąpi jej complete, a potem success żądania otwarcia.
Otwarte połączenie, na przykład w innej karcie, może wstrzymać zmianę wersji. Obsłuż blocked na żądaniu otwarcia, a w funkcji obsługi versionchange istniejącego połączenia zamknij je przez db.close().
Przykłady
<!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>Wynik
before: null upgrade: 1 -> 2 (versionchange) complete success: null; index: true
Otwórz stronę HTML w przeglądarce w bezpiecznym kontekście, z dostępem do IndexedDB i `crypto.randomUUID()`. Wynik zobaczysz w konsoli deweloperskiej. Przykład tworzy bazę o losowej nazwie w wersji 1, zamyka połączenie, dodaje `by_title` w wersji 2 i po sprawdzeniu indeksu zleca usunięcie bazy testowej.
Powiązane lekcje
- JavaScript · Lekcja 31 · Zaawansowany · Wersja: 4
Źródła
- 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