CKTIS / JavaScript
IDBOpenDBRequest — ouvrir et mettre à niveau une base de données IndexedDB
IDBOpenDBRequest représente une requête asynchrone visant à ouvrir ou supprimer une base de données IndexedDB. Des événements permettent de gérer les mises à niveau du schéma, le blocage par d’autres connexions et la fin de l’opération. Ce n’est ni une connexion à la base ni une Promise.
Version : ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Syntaxe
const request = indexedDB.open(name, version);
request.onupgradeneeded = (event) => { /* migrate schema */ };
request.addEventListener("blocked", handler);
request.addEventListener("success", handler);
request.addEventListener("error", handler);
// request.transaction: upgrade IDBTransaction or nullIDBOpenDBRequest est renvoyé immédiatement par indexedDB.open(name, version) et indexedDB.deleteDatabase(name). Il hérite de IDBRequest, puis de EventTarget ; récupère son résultat au moyen d’événements, et non avec await request. Il s’agit d’une API Web du navigateur appartenant à la famille IndexedDB, et non d’une fonctionnalité ECMAScript. Selon MDN, l’interface est largement disponible depuis juillet 2015. MDN précise séparément qu’elle est disponible dans les Web Workers ; cette date ne permet pas de savoir depuis quand la prise en charge dans les Web Workers est répandue parmi les navigateurs. La présence de Node 24 dans un dépôt ne prouve pas la prise en charge de cette API.
IDBOpenDBRequest.upgradeneeded désigne l’événement upgradeneeded, et non une méthode. Il est déclenché lors de la création d’une base ou de son ouverture avec une version supérieure. IDBOpenDBRequest.onupgradeneeded est la propriété permettant d’affecter son gestionnaire ; addEventListener("upgradeneeded", handler) est une autre possibilité. C’est ici que tu crées ou modifies les magasins d’objets et les index. La propriété héritée IDBOpenDBRequest.transaction expose la transaction de mise à niveau en mode versionchange ; sans mise à niveau, sa valeur est null. Elle ne représente pas une transaction de données ultérieure quelconque.
IDBOpenDBRequest.blocked désigne l’événement blocked : une autre connexion ouverte empêche la mise à niveau ou la suppression de la base. Il s’agit d’une attente, pas d’un échec définitif. Gère versionchange sur chaque connexion en la fermant avec db.close(), et informe l’utilisateur du blocage. Un gestionnaire blocked ne ferme pas à lui seul les autres connexions.
IDBOpenDBRequest.success et IDBOpenDBRequest.error désignent des événements hérités de IDBRequest, également gérés avec onsuccess et onerror. Après une ouverture réussie, request.result contient un IDBDatabase ; après une suppression, sa valeur est undefined. L’ouverture ne réussit qu’une fois toute mise à niveau nécessaire validée ; upgradeneeded ne signifie pas encore que l’opération a réussi. En cas d’échec, consulte request.error. Ne lis pas le résultat juste après open() ; traite les échecs asynchrones avec error, séparément des exceptions synchrones éventuellement levées par l’appel lui-même.
Exemples
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>IDBOpenDBRequest: opening and upgrading a database</title>
</head>
<body>
<h1>Opening and upgrading an IndexedDB database</h1>
<script>
(() => {
const name = 'cktis-open-' + crypto.getRandomValues(new Uint32Array(4)).join('-');
const report = error => console.log(error.name === 'SecurityError'
? 'IndexedDB unavailable: SecurityError' : `IndexedDB error: ${error.name}`);
let factory, opening;
try {
factory = window.indexedDB;
if (!factory) {
console.log('IndexedDB unavailable: API missing');
return;
}
opening = factory.open(name, 1);
} catch (error) {
report(error);
return;
}
let created = false;
opening.onerror = () => report(opening.error);
opening.onupgradeneeded = () => {
created = true;
opening.result.createObjectStore('notes', { keyPath: 'id' });
};
opening.onsuccess = () => {
const first = opening.result;
if (!created) {
first.close();
console.log('Fixture name already in use');
return;
}
// Hold the old connection open until the new request reports that it is blocked.
const upgrade = factory.open(name, 2);
upgrade.onblocked = event => {
console.log(`blocked: ${event.oldVersion} -> ${event.newVersion}`);
first.close();
};
upgrade.onupgradeneeded = () => {
upgrade.result.createObjectStore('labels');
console.log(`upgrade: ${upgrade.transaction.mode}`);
};
upgrade.onerror = () => {
first.close();
report(upgrade.error);
factory.deleteDatabase(name);
};
upgrade.onsuccess = () => {
const db = upgrade.result;
console.log(`open: ${db.version}, labels: ${db.objectStoreNames.contains('labels')}`);
db.close();
const deletion = factory.deleteDatabase(name);
deletion.onerror = () => report(deletion.error);
deletion.onsuccess = event => console.log(`deleted version: ${event.oldVersion}`);
};
};
})();
</script>
</body>
</html>Résultat
Observed in the isolated run (IndexedDB access denied): IndexedDB unavailable: SecurityError Expected on a successful run with IndexedDB access: blocked: 1 -> 2 upgrade: versionchange open: 2, labels: true deleted version: 2
Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.