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

CKTIS / JavaScript

Ouverture d’IndexedDB : upgradeneeded, blocked, success et error

Distinguez les événements qui signalent une mise à niveau du schéma, l’attente de la fermeture d’une connexion, une ouverture réussie ou un échec.

Version : ECMAScript 2024 and the current web platform; runtime support varies

Syntaxe

const request = indexedDB.open(name); // or indexedDB.open(name, version)
request.addEventListener("upgradeneeded", onUpgradeNeeded);
request.addEventListener("blocked", onBlocked);
request.addEventListener("success", onSuccess);
request.addEventListener("error", onError);

// Alternatively, assign one handler to each property:
request.onupgradeneeded = onUpgradeNeeded;
request.onblocked = onBlocked;
request.onsuccess = onSuccess;
request.onerror = onError;

indexedDB.open(name, version) renvoie immédiatement un IDBOpenDBRequest, pas une Promise. L’ouverture est asynchrone. upgradeneeded et blocked sont propres à IDBOpenDBRequest ; success et error sont hérités de IDBRequest. Sans version, la requête ouvre la version existante ou crée une base en version 1. IndexedDB est une API du Web, hors d’ECMAScript ; son accès dépend de l’environnement d’exécution et des réglages de stockage.

upgradeneeded se déclenche à la création de la base (oldVersion === 0) ou lorsqu’une version supérieure est demandée. Utilisez oldVersion et newVersion de l’événement pour choisir les migrations à effectuer. Modifiez le schéma via request.result dans la transaction versionchange active, accessible via request.transaction. Ne supposez pas qu’elle restera active pendant l’attente d’une opération indépendante telle que fetch().

blocked signifie que la requête de mise à niveau attend la fermeture d’une autre connexion à la même base. IndexedDB n’envoie pas versionchange à une connexion déjà en cours de fermeture, mais celle-ci peut tout de même retarder la mise à niveau jusqu’à la fin de ses transactions. Dans une application, gérez versionchange sur la connexion IDBDatabase existante et appelez-y close(). Utilisez blocked pour expliquer l’attente à l’utilisateur. Il n’est pas nécessaire de relancer la requête.

success signifie que request.result contient la connexion IDBDatabase ouverte. Si une mise à niveau était nécessaire, sa transaction a déjà été validée. Ouvrir la version actuelle ne déclenche pas upgradeneeded. Une ouverture réussie ne garantit pas le succès des transactions ultérieures.

error signifie que la requête a échoué. Lisez la DOMException dans request.error. Demander une version inférieure à celle stockée provoque VersionError ; interrompre la transaction de mise à niveau annule ses modifications et fait échouer l’ouverture. Une erreur synchrone, comme TypeError pour la version 0, est levée directement par open(), sans événement error.

Exemples

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>IndexedDB open request events</title>
</head>
<body>
  <pre id="output"></pre>
  <script>
    (async () => {
      const { indexedDB, crypto } = window;
      const output = document.getElementById("output");
      const name = `ck-tis-idb-${crypto.randomUUID()}`;

      function log(line) {
        output.textContent += (output.textContent ? "\n" : "") + line;
        console.log(line);
      }

      function open(version, releaseBlocker) {
        return new Promise((resolve, reject) => {
          const request = indexedDB.open(name, version);
          request.onupgradeneeded = ({ oldVersion, newVersion }) => {
            log(`upgradeneeded: ${oldVersion} -> ${newVersion}`);
            const db = request.result;
            if (oldVersion < 1) db.createObjectStore("notes");
            if (oldVersion < 2 && newVersion >= 2) db.createObjectStore("tags");
          };
          request.onblocked = () => {
            log(`blocked: ${version}`);
            releaseBlocker?.();
          };
          request.onsuccess = () => {
            log(`success: ${request.result.version}`);
            resolve(request.result);
          };
          request.onerror = () => reject(request.error);
        });
      }

      let first;
      let second;
      try {
        first = await open(1);
        // Intentionally keep version 1 open until the next request is blocked.
        second = await open(2, () => first.close());
        try {
          const unexpected = await open(1);
          unexpected.close();
          throw new Error("Expected VersionError");
        } catch (error) {
          if (error.name !== "VersionError") throw error;
          log(`error: ${error.name}`);
        }
      } finally {
        first?.close();
        second?.close();
        const cleanup = indexedDB.deleteDatabase(name);
        cleanup.onerror = () => console.error(cleanup.error);
      }
    })().catch((error) => console.error(error));
  </script>
</body>
</html>

Résultat

upgradeneeded: 0 -> 1
success: 1
blocked: 2
upgradeneeded: 1 -> 2
success: 2
error: VersionError

Ouvrez la page HTML via HTTPS ou depuis localhost dans un navigateur où IndexedDB et `crypto.randomUUID()` sont disponibles. La connexion à la version `1` reste volontairement ouverte jusqu’à `blocked`. Sa fermeture permet à la même requête d’ouvrir la version `2`. La requête suivante pour la version `1` échoue avec `VersionError`.

Leçons associées

  • JavaScript · Leçon 20 · Intermédiaire · Version : 3
  • JavaScript · Leçon 21 · Intermédiaire · Version : 3

Sources