L'interface IDBTransaction
de l'API IndexedDB fournit une transaction statique asynchrone vers une base de données grâce à des attributs de gestion d'évènementns. Toutes les opérations de lecture et d'écriture de données sont effectuées au sein de transaction. Il est possible d'utiliser IDBDatabase
afin d'initier des transactions puis IDBTransaction
afin de paramétrer le mode de la transaction (c'est-à-dire s'il est en lecture seule ou en lecture/écriture) et d'accéder à un objet IDBObjectStore
pour réaliser une requête. On peut également utiliser IDBTransaction
pour interrompre une requête.
S'il vous garantir une certaine longévité (par exemple si on utilise des données critiques qui ne peuvent pas être recalculées par la suite), il est possible d'écrire le contenu de la transaction sur le disque avant la diffusion de l'évènement complete
grâce au mode expérimental non-standard readwriteflush
(cf. IDBDatabase.transaction
).
On notera qu'une transaction commence dès sa création et pas lorsque la première requête est lancée. Par exemple :
var trans1 = db.transaction("toto", "readwrite");
var trans2 = db.transaction("toto", "readwrite");
trans2.put("2", "clé");
trans1.put("1", "clé");
Une fois que le code est exécuté, le magasin d'objet contiendra la valeur "2" car la transaction est lancée après la transaction trans1
.
Méthodes
Cette interface hérite de EventTarget
.
IDBTransaction.abort
- Cette méthode annule les modifications apportées aux objets associés à cette transaction. Si la transaction a déjà été interrompue ou est terminée, cette méthode déclenchera un évènement d'erreur.
IDBTransaction.objectStore
- Cette méthode renvoie un objet
IDBObjectStore
qui représente le magasin d'objet associé à cette transaction.
Propriétés
IDBTransaction.db
Lecture seule- La connexion à la base de données associée à cette transaction.
IDBTransaction.mode
Lecture seule- Le mode de la transaction qui définit la façon dont on accède/modifie les données. Les différentes valeurs sont définies ci-après dans la section Constante. Par défaut, la valeur est
readonly
. IDBTransaction.objectStoreNames
Lecture seule- Cette propriété est une liste (
DOMStringList
) des noms des objetsIDBObjectStore
. IDBTransaction.error
Lecture seule- Cette propriété renvoie le type de l'erreur qui se produit lorsque la transaction infructueuse. Cette propriété vaut
null
si la transaction n'est pas finie, est finie et validée correctement ou a été cloturée avec la fonctionIDBTransaction.abort
.
Gestionnaires d'évènements
IDBTransaction.onabort
Lecture seule- Ce gestionnaire permet de gérer l'évènement
abort
qui est déclenché lorsque la transaction a été interrompue. IDBTransaction.oncomplete
Lecture seule- Ce gestionnaire permet de gérer l'évènement
complete
qui est déclenché lorsque la transaction se finit correctement. IDBTransaction.onerror
Lecture seule- Ce gestionnaire permet de gérer l'évènement
error
qui est déclenché lorsqu'une erreur empêche la transaction de se finir correctement.
Les différents modes
Une transaction peut s'effectuer dans l'un de ces modes :
Valeur | Description |
---|---|
"readonly" (0 dans Chrome) |
Ce mode permet de lire les données mais pas de les modifier. |
"readwrite" (1 dans Chrome) |
Ce mode permet de lire, d'écrire et de modifier les données du magasin d'objets. |
"versionchange" (2 dans Chrome) |
Ce mode permet d'effectuer toutes les opérations, y compris l'ajout ou la suppression de magasins d'objets et d'index. Ce mode doit être utilisé pour mettre à jour le numéro de version utilisé par les transactions démarées avec la méthode setVersion() de IDBDatabase . Les transactions lancées dans ce mode ne peuvent pas être lancées en même temps que d'autres transactions. Ces transactions sont parfois qualifiées comme « transactions de mise à jour ». |
Exemples
Dans l'exemple qui suit, on ouvre une transaction en lecture/écriture sur la base de données et on ajoute des données dans le magasin d'objet. On notera également l'utilisation des gestionnaires d'évènements attachés à la transaction qui permettent d'indiquer la réussite ou l'échec de l'ouverture de la transaction. Pour un exemple complet, voir l'application de notifications To-do (voir également la démonstration live)
// On commence par ouvrir la base de données
var DBOpenRequest = window.indexedDB.open("toDoList", 4);
DBOpenRequest.onsuccess = function(event) {
note.innerHTML += '<li>Initialisation de la base.</li>';
// On enregistre le résultat de l'ouverture
// dans la variable db afin de l'utiliser
// ensuite
var db = DBOpenRequest.result;
// On utilise la fonction addData() afin d'ajouter
// des données à la base de données
addData();
};
function addData() {
// On crée un nouvel objet prêt à être inséré
// dans la base de données
var newItem = [ { taskTitle: "Promener le chien", hours: 19, minutes: 30, day: 24, month: "Décembre", year: 2013, notified: "no" } ];
// On ouvre une transaction en lecture/écriture
// vers la base de données afin d'ajouter des
// données
var transaction = db.transaction(["toDoList"], "readwrite");
// On indique le succès de la transaction
transaction.oncomplete = function(event) {
note.innerHTML += '<li>Transaction terminée : modification finie.</li>';
};
transaction.onerror = function(event) {
note.innerHTML += '<li>Transaction non-ouverte à cause d'une erreur. Les doublons ne sont pas autorisés.</li>';
};
// On crée un magasin d'objet pour la transaction
var objectStore = transaction.objectStore("toDoList");
// On ajoute l'objet newItem au magasin d'objets
var objectStoreRequest = objectStore.add(newItem[0]);
objectStoreRequest.onsuccess = function(event) {
// On indique le succès de l'ajout de l'objet
// dans la base de données
note.innerHTML += '<li>Un nouvel élément a été ajouté dans la base de données.</li>';
};
};
Spécifications
Spécification | État | Commentaires |
---|---|---|
Indexed Database API La définition de 'IDBTransaction' dans cette spécification. |
Recommendation | Définition initiale |
Compatibilité des navigateurs
Fonctionnalité | Chrome | Edge | Firefox (Gecko) | Internet Explorer | Opera | Safari (WebKit) |
---|---|---|---|---|---|---|
Support simple | 23webkit 24 38 (dépréciation des préfixes) 57 (retrait des préfixes) |
(Oui) | 10 moz 16.0 (16.0) |
10, partial | 15 | 7.1 |
Disponible dans les web workers | (Oui) 38 (dépréciation des préfixes) 57 (retrait des préfixes) |
? | 37.0 (37.0) | ? | 35 | ? |
objectStoreNames |
48.0 | ? | 50.0 (50.0) | Pas de support | 35 | Pas de support |
Fonctionnalité | Webview Android | Chrome pour Android | Edge | Firefox Mobile (Gecko) | Firefox OS | IE Phone | Opera Mobile | Safari Mobile | Chrome pour Android |
---|---|---|---|---|---|---|---|---|---|
Support simple | (Oui) 38 (dépréciation des préfixes) 57 (retrait des préfixes) |
(Oui) 38 (dépréciation des préfixes) 57 (retrait des préfixes) |
(Oui) | 22.0 (22.0) | 1.0.1 | 10 | 22 | 8 | (Oui) |
Disponible dans les web workers | (Oui) 38 (dépréciation des préfixes) 57 (retrait des préfixes) |
(Oui) 38 (dépréciation des préfixes) 57 (retrait des préfixes) |
? | 37.0 (37.0) | (Oui) | ? | 35 | ? | (Oui) |
objectStoreNames |
48.0 | 48.0 | ? | Pas de support | Pas de support | Pas de support | 35 | Pas de support | 48.0 |
[1] Older versions of Chrome serialize all transactions. So even if you have only read-only transactions and no read-write transaction, your transactions are executed one at a time. Any subsequent transactions are not executed until all read-only transactions are completed. For the status, see bug 64076.
Note that as of Firefox 40, IndexedDB transactions have relaxed durability guarantees to increase performance (see bug 1112702.) Previously in a readwrite
transaction IDBTransaction.oncomplete
was fired only when all data was guaranteed to have been flushed to disk. In Firefox 40+ the complete
event is fired after the OS has been told to write the data but potentially before that data has actually been flushed to disk. The complete
event may thus be delivered quicker than before, however, there exists a small chance that the entire transaction will be lost if the OS crashes or there is a loss of system power before the data is flushed to disk. Since such catastrophic events are rare most consumers should not need to concern themselves further.
Voir aussi
- Utiliser IndexedDB
- Initier une connexion :
IDBDatabase
- Utiliser les transactions :
IDBTransaction
- Définir un intervalle de clés :
IDBKeyRange
- Récupérer et modifier les données :
IDBObjectStore
- Utiliser les curseurs
IDBCursor
- Exemple de référence : To-do Notifications (exemple live).