1. Introduction

User agents need to store large numbers of objects locally in order to satisfy off-line data requirements of Web applications. [WEBSTORAGE] is useful for storing pairs of keys and their corresponding values. However, it does not provide in-order retrieval of keys, efficient searching over values, or storage of duplicate values for a key.

This specification provides a concrete API to perform advanced key-value data management that is at the heart of most sophisticated query processors. It does so by using transactional databases to store keys and their corresponding values (one or more per key), and providing a means of traversing keys in a deterministic order. This is often implemented through the use of persistent B-tree data structures that are considered efficient for insertion and deletion as well as in-order traversal of very large numbers of data records.

The following example uses the API to access a "library" database. It has a "books" object store that holds books records stored by their "isbn" property as the primary key.

Book records have a "title" property. This example artificially requires that book titles are unique. The code enforces this by creating an index named "by_title" with the [unique](#dom-idbindexparameters-unique) option set. This index is used to look up books by title, and will prevent adding books with non-unique titles.

Book records also have an "author" property, which is not required to be unique. The code creates another index named "by_author" to allow look-ups by this property.

The code first opens a connection to the database. The upgradeneeded event handler code creates the object store and indexes, if needed. The success event handler code saves the opened connection for use in later examples.

  1. const request = indexedDB.open("library");
  2. let db;
  3.  
  4. request.onupgradeneeded = function() {
  5.   // The database did not previously exist, so create object stores and indexes.
  6.   const db = request.result;
  7.   const store = db.createObjectStore("books", {keyPath: "isbn"});
  8.   const titleIndex = store.createIndex("by_title", "title", {unique: true});
  9.   const authorIndex = store.createIndex("by_author", "author");
  10.  
  11.   // Populate with initial data.
  12.   store.put({title: "Quarry Memories", author: "Fred", isbn: 123456});
  13.   store.put({title: "Water Buffaloes", author: "Fred", isbn: 234567});
  14.   store.put({title: "Bedrock Nights", author: "Barney", isbn: 345678});
  15. };
  16.  
  17. request.onsuccess = function() {
  18.   db = request.result;
  19. };

The following example populates the database using a transaction.

  1. const tx = db.transaction("books", "readwrite");
  2. const store = tx.objectStore("books");
  3.  
  4. store.put({title: "Quarry Memories", author: "Fred", isbn: 123456});
  5. store.put({title: "Water Buffaloes", author: "Fred", isbn: 234567});
  6. store.put({title: "Bedrock Nights", author: "Barney", isbn: 345678});
  7.  
  8. tx.oncomplete = function() {
  9.   // All requests have succeeded and the transaction has committed.
  10. };

The following example looks up a single book in the database by title using an index.

  1. const tx = db.transaction("books", "readonly");
  2. const store = tx.objectStore("books");
  3. const index = store.index("by_title");
  4.  
  5. const request = index.get("Bedrock Nights");
  6. request.onsuccess = function() {
  7.   const matching = request.result;
  8.   if (matching !== undefined) {
  9.     // A match was found.
  10.     report(matching.isbn, matching.title, matching.author);
  11.   } else {
  12.     // No match was found.
  13.     report(null);
  14.   }
  15. };

The following example looks up all books in the database by author using an index and a cursor.

  1. const tx = db.transaction("books", "readonly");
  2. const store = tx.objectStore("books");
  3. const index = store.index("by_author");
  4.  
  5. const request = index.openCursor(IDBKeyRange.only("Fred"));
  6. request.onsuccess = function() {
  7.   const cursor = request.result;
  8.   if (cursor) {
  9.     // Called for each matching record.
  10.     report(cursor.value.isbn, cursor.value.title, cursor.value.author);
  11.     cursor.continue();
  12.   } else {
  13.     // No more matching records.
  14.     report(null);
  15.   }
  16. };

The following example shows one way to handle errors when a request fails.

  1. const tx = db.transaction("books", "readwrite");
  2. const store = tx.objectStore("books");
  3. const request = store.put({title: "Water Buffaloes", author: "Slate", isbn: 987654});
  4. request.onerror = function(event) {
  5.   // The uniqueness constraint of the "by_title" index failed.
  6.   report(request.error);
  7.   // Could call event.preventDefault() to prevent the transaction from aborting.
  8. };
  9. tx.onabort = function() {
  10.   // Otherwise the transaction will automatically abort due the failed request.
  11.   report(tx.error);
  12. };

The database connection can be closed when it is no longer needed.

  1. db.close();

In the future, the database might have grown to contain other object stores and indexes. The following example shows one way to handle migrating from an older version.

  1. const request = indexedDB.open("library", 3); // Request version 3.
  2. let db;
  3.  
  4. request.onupgradeneeded = function(event) {
  5.   const db = request.result;
  6.   if (event.oldVersion < 1) {
  7.     // Version 1 is the first version of the database.
  8.     const store = db.createObjectStore("books", {keyPath: "isbn"});
  9.     const titleIndex = store.createIndex("by_title", "title", {unique: true});
  10.     const authorIndex = store.createIndex("by_author", "author");
  11.   }
  12.   if (event.oldVersion < 2) {
  13.     // Version 2 introduces a new index of books by year.
  14.     const bookStore = request.transaction.objectStore("books");
  15.     const yearIndex = bookStore.createIndex("by_year", "year");
  16.   }
  17.   if (event.oldVersion < 3) {
  18.     // Version 3 introduces a new object store for magazines with two indexes.
  19.     const magazines = db.createObjectStore("magazines");
  20.     const publisherIndex = magazines.createIndex("by_publisher", "publisher");
  21.     const frequencyIndex = magazines.createIndex("by_frequency", "frequency");
  22.   }
  23. };
  24.  
  25. request.onsuccess = function() {
  26.   db = request.result; // db.version will be 3.
  27. };

A single database can be used by multiple clients (pages and workers) simultaneously — transactions ensure they don’t clash while reading and writing. If a new client wants to upgrade the database (via the upgradeneeded event), it cannot do so until all other clients close their connection to the current version of the database.

To avoid blocking a new client from upgrading, clients can listen for the versionchange event. This fires when another client is wanting to upgrade the database. To allow this to continue, react to the versionchange event by doing something that ultimately closes this client’s connection to the database.

One way of doing this is to reload the page:

  1. db.onversionchange = function() {
  2.   // First, save any unsaved data:
  3.   saveUnsavedData().then(function() {
  4.     // If the document isn’t being actively used, it could be appropriate to reload
  5.     // the page without the user’s interaction.
  6.     if (!document.hasFocus()) {
  7.       location.reload();
  8.       // Reloading will close the database, and also reload with the new JavaScript
  9.       // and database definitions.
  10.     } else {
  11.       // If the document has focus, it can be too disruptive to reload the page.
  12.       // Maybe ask the user to do it manually:
  13.       displayMessage("Please reload this page for the latest version.");
  14.     }
  15.   });
  16. };
  17.  
  18. function saveUnsavedData() {
  19.   // How you do this depends on your app.
  20. }
  21.  
  22. function displayMessage() {
  23.   // Show a non-modal message to the user.
  24. }

Another way is to call the connection‘s [close()](#dom-idbdatabase-close) method. However, you need to make sure your app is aware of this, as subsequent attempts to access the database will fail.

  1. db.onversionchange = function() {
  2.   saveUnsavedData().then(function() {
  3.     db.close();
  4.     stopUsingTheDatabase();
  5.   });
  6. };
  7.  
  8. function stopUsingTheDatabase() {
  9.   // Put the app into a state where it no longer uses the database.
  10. }

The new client (the one attempting the upgrade) can use the blocked event to detect if other clients are preventing the upgrade from happening. The blocked event fires if other clients still hold a connection to the database after their versionchange events have fired.

  1. const request = indexedDB.open("library", 4); // Request version 4.
  2. let blockedTimeout;
  3.  
  4. request.onblocked = function() {
  5.   // Give the other clients time to save data asynchronously.
  6.   blockedTimeout = setTimeout(function() {
  7.     displayMessage("Upgrade blocked - Please close other tabs displaying this site.");
  8.   }, 1000);
  9. };
  10.  
  11. request.onupgradeneeded = function(event) {
  12.   clearTimeout(blockedTimeout);
  13.   hideMessage();
  14.   // ...
  15. };
  16.  
  17. function hideMessage() {
  18.   // Hide a previously displayed message.
  19. }

The user will only see the above message if another client fails to disconnect from the database. Ideally the user will never see this.