CKTIS / JavaScript
IndexedDB: onupgradeneeded и транзакцията за промяна на версията
Промени схемата на IndexedDB в `onupgradeneeded`, вземи транзакцията чрез `request.transaction` и използвай новата схема след събитието `success`.
Версия: Current web platform; runtime support varies
Синтаксис
// 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) връща веднага IDBOpenDBRequest; базата се отваря асинхронно. onupgradeneeded е свойството, чрез което задаваш обработчик за събитието upgradeneeded. То се задейства при създаване на база или при отварянето ѝ с по-висока версия. При същата версия не се задейства, а заявка за по-ниска версия завършва с VersionError. IndexedDB е уеб API, а не част от ECMAScript 2024.
В обработчика request.result съдържа връзката IDBDatabase. Наследеното от IDBRequest свойство request.transaction е само за четене и съдържа транзакцията IDBTransaction, която IndexedDB създава автоматично в режим "versionchange". Непосредствено след open() и отново при success стойността е null. db.transaction() започва отделна транзакция в режим "readonly" или "readwrite", а не транзакция за промяна на версията.
Използвай event.oldVersion и event.newVersion, за да избереш стъпките за миграция. При нова база oldVersion е 0; отделните проверки на версиите позволяват да се изпълнят няколко стъпки при прескачане на междинни версии. Създай хранилище за обекти с db.createObjectStore() и добави индекс към съществуващо хранилище с tx.objectStore(name).createIndex(). В същата транзакция можеш да мигрираш и записи.
Добавяй операции, докато транзакцията е активна: направо в обработчика на upgradeneeded или в обработчиците на събитията от нейните заявки. Не разчитай, че ще остане активна след await fetch() или при изпълнение на функцията на таймер. tx.abort() отменя промените в схемата, данните и версията; заявката за отваряне задейства error вместо success. Ако транзакцията се потвърди, нейното събитие complete предхожда success на заявката за отваряне.
Съществуваща връзка, например в друг раздел, може да забави промяната на версията. Обработи blocked на заявката за отваряне и затваряй съществуващите връзки с db.close() в техните обработчици на versionchange.
Примери
<!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>Резултат
before: null upgrade: 1 -> 2 (versionchange) complete success: null; index: true
Отвори HTML страницата в браузър в защитен контекст с достъп до IndexedDB и `crypto.randomUUID()`. Виж резултата в конзолата за разработчици. Примерът създава база със случайно име във версия 1, затваря връзката, добавя `by_title` във версия 2 и заявява изтриване на тестовата база след проверката на индекса.
Свързани уроци
- JavaScript · Урок 31 · Напреднало · Версия: 4
Източници
- 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