Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / JavaScript

IndexedDB : onupgradeneeded et la transaction de mise à niveau

Modifiez le schéma IndexedDB dans `onupgradeneeded`, récupérez la transaction avec `request.transaction` et attendez `success` avant d’utiliser le nouveau schéma.

Version : 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) renvoie immédiatement une requête IDBOpenDBRequest ; l’ouverture se fait de manière asynchrone. onupgradeneeded est la propriété qui reçoit le gestionnaire de l’événement upgradeneeded. Celui-ci se déclenche lors de la création d’une base ou de son ouverture avec une version supérieure. À version égale, il ne se déclenche pas ; une version inférieure provoque VersionError. IndexedDB est une API web, pas une fonctionnalité d’ECMAScript 2024.

Dans le gestionnaire, request.result contient la connexion IDBDatabase. La propriété en lecture seule request.transaction, héritée de IDBRequest, contient la transaction IDBTransaction qu’IndexedDB crée automatiquement en mode "versionchange". Elle vaut null juste après open(), puis de nouveau lors de success. db.transaction() ouvre une transaction distincte en mode "readonly" ou "readwrite", et non une transaction de mise à niveau.

Utilisez event.oldVersion et event.newVersion pour choisir les étapes de migration. Pour une nouvelle base, oldVersion vaut 0 ; des tests de version distincts permettent d’exécuter plusieurs étapes si des versions intermédiaires ont été sautées. Créez un magasin d’objets avec db.createObjectStore() et ajoutez un index à un magasin existant avec tx.objectStore(name).createIndex(). Vous pouvez aussi migrer les enregistrements dans la même transaction.

Planifiez les opérations tant que la transaction est active : directement dans le gestionnaire de upgradeneeded ou dans les gestionnaires d’événements de ses requêtes. Ne supposez pas qu’elle reste active après await fetch() ou dans le rappel d’un minuteur. tx.abort() annule les changements de schéma, de données et de version ; la requête d’ouverture déclenche alors error plutôt que success. Si la transaction est validée, son événement complete précède le success de la requête d’ouverture.

Une connexion existante, par exemple dans un autre onglet, peut retarder la mise à niveau. Gérez blocked sur la requête d’ouverture et fermez les connexions existantes avec db.close() dans leurs gestionnaires de versionchange.

Exemples

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

Résultat

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

Ouvrez la page HTML dans un navigateur en contexte sécurisé, avec accès à IndexedDB et à `crypto.randomUUID()`. Consultez le résultat dans la console de développement. L’exemple crée une base de nom aléatoire en version 1, ferme la connexion, ajoute `by_title` en version 2 et demande la suppression de la base de test après avoir vérifié l’index.

Leçons associées

  • JavaScript · Leçon 31 · Avancé · Version : 4

Sources