IndexedDB : introduction et concepts

IndexedDB est une base de données transactionnelle intégrée au navigateur : elle stocke de grandes quantités de données structurées (objets, fichiers, binaires), les interroge par index et fonctionne hors ligne. Cette rubrique appartient au front : le code s’exécute dans le navigateur. Les exemples utilisent des noms génériques (base boutique, magasin clients).

Quand l’utiliser

Besoin	Outil
Quelques réglages (thème, langue)	localStorage
Beaucoup de données, recherche par champ, tri	IndexedDB
Fichiers, images, données binaires	IndexedDB (objets `Blob`)
Application utilisable hors ligne	IndexedDB + service worker
Traitement dans un Web Worker	IndexedDB (localStorage y est indisponible)
Données partagées entre appareils	Le serveur (IndexedDB est local à un navigateur)

Comparaison avec localStorage

	`localStorage`	IndexedDB
Données	Chaînes	Objets JavaScript, `Blob`, tableaux typés, dates
Taille	~5 Mo	Très grande (une partie de l’espace disque libre, de l’ordre de centaines de Mo à plusieurs Go)
Accès	Synchrone (bloque l’interface)	Asynchrone
Requêtes	Aucune	Index, plages de clés, curseurs
Transactions	Non	Oui (atomiques)
Web Workers	Non	Oui
Complexité	Très simple	Plus complexe (API à événements)

Vocabulaire

Terme	Sens
Base de données (`IDBDatabase`)	Conteneur nommé et versionné, propre à une origine
Magasin d’objets (`IDBObjectStore`)	Équivalent d’une table ou d’une collection
Clé	Identifiant d’un enregistrement dans un magasin
Index (`IDBIndex`)	Permet de chercher par un autre champ que la clé
Transaction (`IDBTransaction`)	Groupe d’opérations atomiques sur un ou plusieurs magasins
Requête (`IDBRequest`)	Résultat asynchrone d’une opération
Curseur (`IDBCursor`)	Parcours d’enregistrements un par un
Version	Entier qui commande les changements de schéma

origine https://exemple.com
└── base « boutique » (version 2)
    ├── magasin « clients »   (clé : id)    index : email (unique), nom
    └── magasin « commandes » (clé : numero) index : clientId, date

Un fonctionnement asynchrone

Toutes les opérations renvoient un objet requête qui signale le résultat par des événements (success, error), pas par des promesses natives :

const requete = indexedDB.open('boutique', 1);
requete.onsuccess = () => console.log('ouverte', requete.result);
requete.onerror = () => console.error('échec', requete.error);
requete.onupgradeneeded = () =>
  console.log('création ou mise à jour du schéma');

Cette API ancienne est lourde à utiliser telle quelle ; on l’enveloppe dans des promesses ou on utilise une bibliothèque (voir Avec idb et Dexie).

Données stockables

IndexedDB stocke tout ce que l’algorithme de clonage structuré sait copier :

Stockable	Non stockable
Objets simples, tableaux, chaînes, nombres, booléens	Fonctions
`Date`, `RegExp`, `Map`, `Set`	Éléments du DOM
`Blob`, `File`, `ArrayBuffer`, tableaux typés	Objets avec méthodes personnalisées (les méthodes sont perdues)
Objets imbriqués	Références circulaires gérées, mais classes perdues

Les instances de classes sont stockées comme objets simples : les méthodes ne reviennent pas.

Portée et sécurité

Une base est liée à l’origine (schéma + domaine + port) : https://exemple.com et https://app.exemple.com ont des bases séparées.
Comme pour localStorage, tout script de la page peut lire la base : ne pas y stocker de secrets (voir Sécurité et confidentialité).
L’utilisateur peut effacer les données du site, et le navigateur peut les évincer en cas de manque d’espace (voir Hors ligne et synchronisation).
La navigation privée supprime la base à la fermeture de la fenêtre ; certains navigateurs limitent ou désactivent IndexedDB dans ce mode.

Un premier exemple complet

function ouvrir() {
  return new Promise((resolve, reject) => {
    const requete = indexedDB.open('boutique', 1);
    requete.onupgradeneeded = () => {
      requete.result.createObjectStore('clients', {
        keyPath: 'id',
        autoIncrement: true,
      });
    };
    requete.onsuccess = () => resolve(requete.result);
    requete.onerror = () => reject(requete.error);
  });
}

const db = await ouvrir();

await new Promise((resolve, reject) => {
  const tx = db.transaction('clients', 'readwrite');
  tx.objectStore('clients').add({ nom: 'Alice', email: 'alice@exemple.com' });
  tx.oncomplete = resolve;
  tx.onerror = () => reject(tx.error);
});

const clients = await new Promise((resolve, reject) => {
  const requete = db.transaction('clients').objectStore('clients').getAll();
  requete.onsuccess = () => resolve(requete.result);
  requete.onerror = () => reject(requete.error);
});
console.log(clients);

Les pages suivantes détaillent chaque étape.

Vérifier la disponibilité

if (!('indexedDB' in window)) {
  console.warn('IndexedDB indisponible : prévoir un repli');
}

Dans un contexte non sécurisé (HTTP hors localhost), certaines API de stockage et de service worker sont limitées : servir le site en HTTPS.

Inspecter

Outils de développement (F12) : onglet Stockage (Firefox) ou Application (Chrome, Chromium, Edge) > IndexedDB : bases, magasins, enregistrements (lecture, modification, suppression, suppression de la base).

Dépannage

Symptôme	Piste
`indexedDB is not defined`	Code exécuté hors du navigateur (rendu serveur, Node.js)
La base est vide après un rechargement	Navigation privée, effacement par le navigateur, autre origine
Aucune donnée dans les outils de développement	Mauvaise origine ou mauvais nom de base
Les méthodes d’une classe disparaissent	Clonage structuré : stocker des données simples

Ubuntu 24.04 et 26.04 : différences à connaître

Aucune : fonction du navigateur. Sous Ubuntu, Firefox (paquet snap par défaut) et Chromium offrent les mêmes outils de développement.

Pour aller plus loin

Documentation : MDN, API IndexedDB
Suite : Ouvrir une base et définir le schéma