KennisbankExamencentrum
NL · NLNederlands (Nederland)
Taal kiezen13

CKTIS / JavaScript

IndexedDB: onupgradeneeded en de upgradetransactie

Wijzig een IndexedDB-schema in `onupgradeneeded`, haal de transactie op via `request.transaction` en wacht op `success` voordat je het nieuwe schema gebruikt.

Versie: 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) geeft direct een IDBOpenDBRequest terug; het openen gebeurt asynchroon. onupgradeneeded is de eigenschap waarmee je de handler voor de gebeurtenis upgradeneeded instelt. Die gebeurtenis treedt op bij het aanmaken van een database of bij het openen met een hogere versie. Bij dezelfde versie treedt ze niet op; een lagere versie leidt tot VersionError. IndexedDB is een web-API, geen onderdeel van ECMAScript 2024.

In de handler bevat request.result de IDBDatabase-verbinding. De alleen-lezen eigenschap request.transaction, geërfd van IDBRequest, bevat de IDBTransaction die IndexedDB automatisch in de modus "versionchange" aanmaakt. Meteen na open() en opnieuw bij success is de waarde null. db.transaction() start een aparte transactie in de modus "readonly" of "readwrite", geen upgradetransactie.

Gebruik event.oldVersion en event.newVersion om de migratiestappen te kiezen. Bij een nieuwe database is oldVersion gelijk aan 0; dankzij aparte versiecontroles kun je meerdere stappen uitvoeren als tussenversies zijn overgeslagen. Maak een objectopslag aan met db.createObjectStore() en voeg met tx.objectStore(name).createIndex() een index toe aan een bestaande opslag. Je kunt ook records migreren in dezelfde transactie.

Plan bewerkingen in zolang de transactie actief is: direct in de handler voor upgradeneeded of in de handlers voor gebeurtenissen van de bijbehorende verzoeken. Ga er niet van uit dat de transactie na await fetch() of in de callback van een timer nog actief is. tx.abort() draait schema-, gegevens- en versiewijzigingen terug; het openingsverzoek geeft dan error in plaats van success. Wordt de transactie vastgelegd, dan komt haar gebeurtenis complete vóór success van het openingsverzoek.

Een bestaande verbinding, bijvoorbeeld in een ander tabblad, kan de upgrade ophouden. Handel blocked af op het openingsverzoek en sluit bestaande verbindingen met db.close() in hun versionchange-handlers.

Voorbeelden

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

Resultaat

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

Open de HTML-pagina in een browser in een beveiligde context met toegang tot IndexedDB en `crypto.randomUUID()`. Bekijk de uitvoer in de ontwikkelaarsconsole. Het voorbeeld maakt een database met een willekeurige naam aan in versie 1, sluit de verbinding, voegt `by_title` toe in versie 2 en vraagt na controle van de index om verwijdering van de testdatabase.

Gerelateerde lessen

  • JavaScript · Les 31 · Gevorderd · Versie: 4

Bronnen