Les concepts basiques d'IndexedDB

IndexedDB est un moyen pour stocker des données dans le navigateur d'un utilisateur, de manière persistante. Ses fonctions de recherche avancées permettent de créer des applications qui fonctionnent tant connecté que déconnecté. IndexedDB est utile pour créer des applications qui stockent une grosse quantité de données (par exemple: un catalogue de DVDs dans une bibliothèque) et des applications qui n'ont pas forcément besoin d'une connectivité Internet en continu (par exemple: des clients de messagerie électronique, des listes de tâches, des bloc-notes).

À propos de ce document

Ce document introduit les concepts et les termes essentiels d'IndexedDB. Vous aurez une vue d'ensemble et vous comprendrez les concepts-clés. Pour en savoir plus sur les termes d'IndexedDB, voyez la section Definitions.

Pour avoir un tutoriel sur l'utilisation de l'API, voyez Using IndexedDB (non traduit pour l'instant). Pour accéder à la documentation de référence sur l'API IndexedDB, voyez l'article IndexedDB et ses sous-parties (non traduit pour l'instant), qui documentent les types d'objets utilisés par IndexedDB, ainsi que les méthodes des API synchrone et asynchrone.

Vue d'ensemble d'IndexedDB

IndexedDB vous permet de stocker et récupérer des objets qui sont indexés avec une "clé". Tous les changements que vous faites dans la base de données sont forcément transactionnels. Comme la plupart des solutions de stockage du web, IndexedDB respecte la politique de sécurité utilisant l'origne (same-origin policy). Ainsi, vous pouvez accéder aux données stockées d'un domaine, alors que vous ne pouvez pas accéder aux données de domaines différents.

L'API comporte à la fois une API asynchrone et une API synchrone (non traduits). L'API asynchrone peut être utilisée dans la plupart des cas, alors que l'API sycnrhone est prévue pour être utilisée dans des Web Workers. Actuellement, aucun navigateur ne supporte l'API synchrone. Mais même si un jour cette API était supportée, dans la majorité des cas, vous utiliserez l'API asynchrone de toute manière.

IndexedDB est une alternative à l'API WebSQL Database, qui a été dépréciée par le W3C le 18 novembre 2010. Alors que ces APIs sont toutes deux des solutions de stockage, elles n'offrent pas les mêmes fonctionnalités. WebSQL Database est un système d'accès à une base de données relationnelle alors qu'IndexedDB est un système à table indexée.

Les grands concepts

Si vous avez l'habitude de travailler avec d'autres types de bases de données, vous pourrez être désorienté avec l'utlisation d'IndexedDB. Mais il suffit de garder les concepts importants suivants en tête :

Les bases d'IndexedDB stockent des paires clé-valeur. Les valeurs peuvent êtres des objets structurés, et les clés peuvent être des propriétés de ces objets. Vous pouvez créer des indexes à partir de n'importe quelle propriété des objets, pour faciliter la recherche et l'énumération ordonnée.

IndexedDB est construit autour d'un modèle de base de données transactionnelle. Tout ce que vous faites avec IndexedDB se passe dans le contexte d'une transaction. L'API IndexedDB fournit beaucoup d'objets qui représentent les indexes, les tables, les curseurs, etc, mais chacun de ces objets est forcément relié à une transaction donnée. Il n'est pas possible d'exécuter de commandes ou ouvrir des curseurs en dehors d'une transaction.

Les transactions ont une durée de vie bien définie, donc il est incorrect d'utiliser une transaction après qu'elle soit terminée, et des exceptions seront jetées dans ce cas. Par ailleurs, les transactions sont appliquées automatiquement ("auto-commit") et ne peuvent pas être appliquées à la demande.

Ce modèle basé sur des transactions est vraiment utile: rendez-vous compte qu'un utilisateur peut ouvrir deux instances de la même application web dans deux onglets différents en même temps. Si on n'utilisait pas d'opérations transactionnelles, une instance pourrait écraser les modifications de l'autre, et vice versa. Si vous n'êtes pas à l'aise avec la notion de transaction dans une base de données, vous pouvez consulter l'article Wikipedia sur les transactions. Vous pouvez aussi voir plus loin la partie transaction dans la section des définitions.

L'API IndexedDB est majoritairement asynchrone. L'API ne vous donne pas les données en retournant des valeurs. Au contraire, vous devez passer une fonction de rappel ("callback"). Vous ne stockez pas une valeur dans la base, ou vous ne récupérez pas une valeur de la base de manière synchrone, mais vous demandez à ce qu'une opération de base de données soit exécutée. Un événement DOM est envoyé lorsque l'opération est terminée, et le type d'événement vous permet de savoir si l'opération a réussi ou a échoué. Cela peut sembler un peu compliqué au premier abord, mais après tout, ce n'est pas si différent du fonctionnement de XMLHttpRequest.

IndexedDB est orienté objet. IndexedDB n'est pas une base de données relationnelle, avec des tables, des colonnes et des lignes. Cette différence importante et fondamentale change votre manière de concevoir et construire vos applications.

Dans un espace de stockage de données relationel habituel, on aurait un tableau qui permet de stocker un ensemble de lignes de donnée, et de colonnes de donnée avec un nom. Avec IndexedDB, au contraire, on crée un espace de stockage d'objets pour un type de données particulier, et on persiste tout simplement des objets JavaScript dans cet espace. Chaque magasin d'objet peut utiliser un ensemble d'indexes qui rendent efficace la recherche et l'itération. Si les systèmes de base de données orientée objet ne vous sont pas familiers, vous pouvez aller lire l'article Wikipedia sur les bases de données objet.

IndexedDB ne s'utilise pas avec le langage SQL. On utilise des recherches sur un index pour obtenir un curseur, que l'on utilise ensuite pour parcourir l'ensemble des résultats. Si vous ne connaissez pas bien les systèmes NoSQL, vous pouvez consulter l'article Wikipedia sur NoSQL.

IndexedDB utilise le concept de requête un peu partout. Les requêtes sont des objets qui reçoivent les événements DOM de succès ou d'échec dont nous avons parlé plus tôt. Elles ont des propriétés onsuccess et onerror, et on peut appeler addEventListener() et removeEventListener() sur ces objets. Elles ont aussi les propriétés readyState, result, et errorCode qui vous donnent l'état d'une requête. La propriété result est plutôt magique car elle peut correspondre à beaucoup de choses différentes en fonction de la manière dont la requête a été créée. Par exemple, une instance de IDBCursor, ou la clé de la valeur que vous venez d'insérer dans la base de données.)

IndexedDB uses DOM events to notify you when results are available. DOM events always have a type property (in IndexedDB, it is most commonly set to "success" or "error"). DOM events also have a target property that tells where the event is headed. In most cases, the target of an event is the IDBRequest object that was generated as a result of doing some database operation. Success events don't bubble up and they can't be canceled. Error events, on the other hand, do bubble, and can be cancelled. This is quite important, as error events abort whatever transactions they're running in, unless they are cancelled.
IndexedDB adheres to a same-origin policy. An origin is the domain, application layer protocol, and port of a URL of the document where the script is being executed. Each origin has its own associated set of databases. Every database has a name that identifies it within an origin.

The security boundary imposed on IndexedDB prevents applications from accessing data with a different origin. For example, while an app or a page in https://www.example.com/app/ can retrieve data from https://www.example.com/dir/, because they have the same origin, it cannot retrieve data from https://www.example.com:8080/dir/ (different port) or https://www.example.com/dir/ (different protocol), because they have different origins.

Definitions

This section defines and explains terms used in the IndexedDB API.

Database

database

A repository of information, typically comprising one or more object stores. Each database must have the following:

Name. It identifies the database within a specific origin and stays constant throughout its lifetime. The name can be any string value (including an empty string).
Current version. When a database is first created, its version is the integer 1. Each database can have only one version at any given time.

object store

The mechanism by which data is stored in the database. The object store persistently holds records, which are key-value pairs. Records within an object store are sorted according to the keys in an ascending order.

Every object store must have a name that is unique within its database. The object store can optionally have a key generator and a key path. If the object store has a key path, it is using in-line keys; otherwise, it is using out-of-line keys.

For the reference documentation on object store, see IDBObjectStore or IDBObjectStoreSync.

version

When a database is first created, its version is the integer 1. Each database has one version at a time; a database can't exist in multiple versions at once. The only way to change the version is by opening it with a greater version than the current one. This will start a VERSION_CHANGE transaction and fire an upgradeneeded event. The only place where the schema of the database can be updated is inside the handler of that event.

Note : This definition describes the most recent specifications, which is only implemented in some up-to-date browsers. Old browsers implemented the now deprecated and removed IDBDatabase.setVersion() method.

database connection

An operation created by opening a database. A given database can have multiple connections at the same time.

transaction

An atomic and durable set of data-access and data-modification operations on a particular database. It is how you interact with the data in a database. In fact, any reading or changing of data in the database must happen in a transaction.

A database connection can have several active transaction associated with it at a time, so long as the writing transactions do not have overlapping scopes. The scope of transactions, which is defined at creation, determines which object stores the transaction can interact with and remains constant for the lifetime of the transaction. So, for example, if a database connection already has a writing transaction with a scope that just covers the flyingMonkey object store, you can start a second transaction with a scope of the unicornCentaur and unicornPegasus object stores. As for reading transactions, you can have several of them—even overlapping ones.

Transactions are expected to be short-lived, so the browser can terminate a transaction that takes too long, in order to free up storage resources that the long-running transaction has locked. You can abort the transaction, which rolls back the changes made to the database in the transaction. And you don't even have to wait for the transaction to start or be active to abort it.

The three modes of transactions are: read/write, read only, and version change. The only way to create and delete object stores and indexes is by using a version-change transaction. To learn more about transaction types, see the reference article for IndexedDB.

Because everything happens within a transaction, it is a very important concept in IndexedDB. To learn more about transactions, especially on how it relates to versioning, see IDBTransaction, which also has reference documentation. For the documentation on the synchronous API, see IDBTransactionSync.

request

The operation by which reading and writing on a database is done. Every request represents one read or write operation.

index

A specialized object store for looking up records in another object store, called the referenced object store. The index is a persistent key-value storage where the value part of its records is the key part of a record in the referenced object store. The records in an index are automatically populated whenever records in the referenced object store are inserted, updated, or deleted. Each record in an index can point to only one record in its referenced object store, but several indexes can reference the same object store. When the object store changes, all indexes that refers to the object store are automatically updated.

Alternatively, you can also look up records in an object store using the key.

To learn more on using indexes, see Using IndexedDB. For the reference documentation on index, see IDBKeyRange.

Key and value

key

A data value by which stored values are organized and retrieved in the object store. The object store can derive the key from one of three sources: a key generator, a key path, and an explicitly specified value. The key must be of a data type that has a number that is greater than the one before it. Each record in an object store must have a key that is unique within the same store, so you cannot have multiple records with the same key in a given object store.

A key can be one of the following type: string, date, float, and array. For arrays, the key can range from an empty value to infinity. And you can include an array within an array. Note that Firefox prior to 11 only accepted keys of type string or integer.

Alternatively, you can also look up records in an object store using the index.

key generator

A mechanism for producing new keys in an ordered sequence. If an object store does not have a key generator, then the application must provide keys for records being stored. Generators are not shared between stores. This is more a browser implementation detail, because in web development, you don't really create or access key generators.

in-line key

A key that is stored as part of the stored value. It is found using a key path. An in-line key can be generated using a generator. After the key has been generated, it can then be stored in the value using the key path or it can also be used as a key.

out-of-line key

A key that is stored separately from the value being stored.

key path

Defines where the browser should extract the key from a value in the object store or index. A valid key path can include one of the following: an empty string, a JavaScript identifier, or multiple JavaScript identifiers separated by periods. It cannot include spaces.

value

Each record has a value, which could include anything that can be expressed in JavaScript, including: boolean, number, string, date, object, array, regexp, undefined, and null.

When an object or array is stored, the properties and values in that object or array can also be anything that is a valid value.

Note : The specification lets you store files and blobs, but this has only been implemented in Firefox 11+.

Range and scope

scope

The set of object stores and indexes to which a transaction applies. The scopes of read-only transactions can overlap and execute at the same time. On the other hand, the scopes of writing transactions cannot overlap. You can still start several transactions with the same scope at the same time, but they just queue up and execute one after another.

cursor

A mechanism for iterating over multiple records with a key range. The cursor has a source that indicates which index or object store it is iterating. It has a position within the range, and moves in a direction that is increasing or decreasing in the order of record keys. For the reference documentation on cursors, see IDBCursor or IDBCursorSync.

key range

A continuous interval over some data type used for keys. Records can be retrieved from object stores and indexes using keys or a range of keys. You can limit or filter the range using lower and upper bounds. For example, you can iterate over all values of a key between x and y.

For the reference documentation on key range, see IDBKeyRange.

Limitations

IndexedDB is designed to cover most cases that need client-side storage. However, it is not designed for a few cases like the following:

Internationalized sorting. Not all languages sort strings in the same way, so internationalized sorting is not supported. While the database can't store data in a specific internationalized order, you can sort the data that you've read out of the database yourself.
Synchronizing. The API is not designed to take care of synchronizing with a server-side database. You have to write code that synchronizes a client-side indexedDB database with a server-side database.
Full text searching. The API does not have an equivalent of the LIKE operator in SQL.

In addition, be aware that browsers can wipe out the database, such as in the following conditions:

The user requests a wipe out.
Many browsers have settings that let users wipe all data stored for a given website, including cookies, bookmarks, stored passwords, and IndexedDB data.
The browser is in private browsing mode.
Some browsers, have "private browsing" (Firefox) or "incognito" (Chrome) modes. At the end of the session, the browser wipes out the database.
The disk or quota limit has been reached.
The data is corrupt.
An incompatible change is made to the feature.

The exact circumstances and browser capabilities change over time, but the general philosophy of the browser vendors is to make the best effort to keep the data when possible.

Next step

OK, so, now with these big concepts under our belts, we can get to more concrete stuff. For a tutorial on how to use the API, see Using IndexedDB.