IDBFactory.open()

La méthode open() de l'interface IDBFactory lance une requête pour ouvrir une connexion à une base de données.

La méthode renvoie immédiatement un objet IDBOpenDBRequest puis effectue l'opération d'ouverture de façon asynchrone. Si l'opération réussit, un évènement success sera éms sur l'objet IDBOpenDBRequest renvoyé par la méthode, et la propriété result de l'évènement aura la valeur de l'objet IDBDatabase associé à la connexion.

Si une erreur se produit lors de la connexion, un évènement error sera émis sur l'objet IDBOpenDBRequest renvoyé par la méthode.

Cette méthode peut également émettre les évènements upgradeneeded, blocked ou versionchange.

Note: Cette fonctionnalité est disponible via les Web Workers.

Syntaxe

La syntaxe standard est la suivante :

js
var IDBOpenDBRequest = indexedDB.open(nom);
var IDBOpenDBRequest = indexedDB.open(nom, version);

Paramètres

nom

Le nom de la base de données qu'on souhaite ouvrir.

version Facultatif

Paramètre optionnel qui représente la version de la base de données qu'on veut ouvrir. Si ce paramètre n'est pas fourni et que la base de données existe, une connexion sera ouverte sans changer la version de la base de données. Si ce paramètre n'est pas fourni est que la base de données n'existe pas, elle sera créée avec une version 1.

Objet options expérimental de Gecko

options (version et storage) Facultatif

Dans Gecko, à partir de la version 26, il est possible de passer en paramètre un objet options non standard, qui contienne le numéro de version de la base de données (équivalent donc au paramètre version définit ci-avant), et également une valeur storage qui décrit si on souhaite utiliser un stockage permanent (avec la valeur persistent) ou un stockage temporaire (avec la valeur temporary).

Attention : l'attribut storage est déprécié et sera prochainement retiré de Gecko. Vous devriez utiliser StorageManager.persist() à la place pour obtenir un stockage persistant.

Note : Vous pouvez consulter l'article les limites de stockage du navigateur et les critères d'éviction pour en savoir plus sur les différents types de stockage disponibles et la façon dont Firefox gère les données côté client.

Valeur de retour

Un objet IDBOpenDBRequest sur lequel sont déclenchés les différents évènements liés à cette requête.

Exceptions

Cette méthode peut lever une DOMException de type suivant :

Exception Description
TypeError La valeur de version est zéro ou un nombre négatif ou n'est pas un nombre.

Exemples

Voici un exemple d'ouverture de la base de données toDoList en utilisant la syntaxe standard et le paramètre version :

js
var request = window.indexedDB.open("toDoList", 4);

Dans le fragment de code qui suit, on effectue une requête pour ouvrir une base de données et on inclut des gestionnaires d'évènements pour gérer la réussite ou l'échec de l'ouverture. Pour consulter un exemple fonctionnel complet, vous pouvez étudier notre application To-do Notifications (cf. l'exemple live).

js
var note = document.querySelector("ul");

window.indexedDB =
  window.indexedDB ||
  window.mozIndexedDB ||
  window.webkitIndexedDB ||
  window.msIndexedDB;
// NE PAS utiliser "var indexedDB = ..." si on n’est pas dans une fonction.
// On pourrait avoir besoin de références vers quelques objets window.IDB* :
window.IDBTransaction =
  window.IDBTransaction ||
  window.webkitIDBTransaction ||
  window.msIDBTransaction;
window.IDBKeyRange =
  window.IDBKeyRange || window.webkitIDBKeyRange || window.msIDBKeyRange;
// Mozilla n’a jamais préfixé ces objets, donc on n’a pas besoin de window.mozIDB*

// On ouvre la version 4 de la base de données
var DBOpenRequest = window.indexedDB.open("toDoList", 4);

// On ajoute deux gestionnaires d'évènements
// Le premier utilisé en cas d'échec
DBOpenRequest.onerror = function (event) {
  note.innerHTML += "<li>Erreur lors du chargement de la base.</li>";
};

// Et le second en cas de réussite
DBOpenRequest.onsuccess = function (event) {
  note.innerHTML += "<li>Base de données initialisée.</li>";

  // On stocke le résultat de l'ouverture dans la
  // variable db qui sera utilisée par la suite
  // pour d'autres opérations
  db = DBOpenRequest.result;
};

Spécifications

Specification
Indexed Database API 3.0
# ref-for-dom-idbfactory-open②

Compatibilité des navigateurs

BCD tables only load in the browser

Voir aussi