Znalostní bázeCentrum zkoušek
CSČeština
Vybrat jazyk13

CKTIS / JavaScript

IndexedDB: onupgradeneeded a transakce změny verze

Změňte schéma IndexedDB v `onupgradeneeded`, získejte transakci z `request.transaction` a s použitím nového schématu počkejte na `success`.

Verze: Current web platform; runtime support varies

Syntaxe

// 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) ihned vrátí IDBOpenDBRequest; databáze se otevírá asynchronně. onupgradeneeded je vlastnost pro nastavení obsluhy události upgradeneeded. Událost nastane při vytvoření databáze nebo při jejím otevření s vyšší verzí. Při stejné verzi nenastane a požadavek s nižší verzí skončí chybou VersionError. IndexedDB je webové API, nikoli součást ECMAScriptu 2024.

V obsluze události obsahuje request.result připojení IDBDatabase. Vlastnost request.transaction, zděděná z IDBRequest a určená jen pro čtení, obsahuje IDBTransaction, kterou IndexedDB automaticky vytváří v režimu "versionchange". Ihned po open() a znovu při success má hodnotu null. db.transaction() zahajuje samostatnou transakci v režimu "readonly" nebo "readwrite", nikoli transakci změny verze.

Pomocí event.oldVersion a event.newVersion vyberte kroky migrace. U nové databáze je oldVersion rovno 0; samostatné podmínky pro jednotlivé verze umožňují provést více kroků při přeskočení mezilehlých verzí. Úložiště objektů vytvořte pomocí db.createObjectStore() a do existujícího úložiště přidejte index pomocí tx.objectStore(name).createIndex(). Ve stejné transakci můžete migrovat i záznamy.

Zadávejte operace, dokud je transakce aktivní: přímo v obsluze upgradeneeded nebo v obsluze událostí jejích požadavků. Nespoléhejte na to, že bude stále aktivní po await fetch() nebo ve zpětném volání časovače. tx.abort() vrátí změny schématu, dat i verze zpět; požadavek na otevření vyvolá error místo success. Pokud se transakce potvrdí, její complete předchází události success požadavku na otevření.

Již otevřené připojení, například na jiné kartě, může změnu verze pozdržet. Ošetřete blocked na požadavku na otevření a existující připojení zavírejte pomocí db.close() v jejich obsluze versionchange.

Příklady

<!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>

Výsledek

before: null
upgrade: 1 -> 2 (versionchange)
complete
success: null; index: true

Otevřete stránku HTML v prohlížeči v zabezpečeném kontextu s přístupem k IndexedDB a `crypto.randomUUID()`. Výstup najdete ve vývojářské konzoli. Příklad vytvoří databázi s náhodným názvem ve verzi 1, zavře připojení, ve verzi 2 přidá `by_title` a po kontrole indexu požádá o odstranění testovací databáze.

Související lekce

  • JavaScript · Lekce 31 · Pokročilá · Verze: 4

Zdroje