База знанияИзпитен център
BGБългарски
Избери език13

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

Източници