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.

In the following example, the API is used to access a “library” database that holds books stored by their “isbn” attribute. Additionally, an index is maintained on the “title” attribute of the objects stored in the object store. This index can be used to look up books by title, and enforces a uniqueness constraint. Another index is maintained on the “author” attribute of the objects, and can be used to look up books by author.

A connection to the database is opened. If the “library” database did not already exist, it is created and an event handler creates the object store and indexes. Finally, the opened connection is saved for use in subsequent examples.

The following example populates the database using a transaction.

var tx = db.transaction("books", "readwrite");
var store = tx.objectStore("books");
 
store.put({title: "Quarry Memories", author: "Fred", isbn: 123456});
store.put({title: "Water Buffaloes", author: "Fred", isbn: 234567});
store.put({title: "Bedrock Nights", author: "Barney", isbn: 345678});
 
tx.oncomplete = function() {
  // All requests have succeeded and the transaction has committed.
};

var tx = db.transaction("books", "readonly");
var store = tx.objectStore("books");
var index = store.index("by_title");
 
var request = index.get("Bedrock Nights");
request.onsuccess = function() {
  var matching = request.result;
  if (matching !== undefined) {
    // A match was found.
    report(matching.isbn, matching.title, matching.author);
  } else {
    // No match was found.
    report(null);
};

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

The following example shows how errors could be handled when a request fails.

var tx = db.transaction("books", "readwrite");
var store = tx.objectStore("books");
var request = store.put({title: "Water Buffaloes", author: "Slate", isbn: 987654});
request.onerror = function(event) {
  // The uniqueness constraint of the "by_title" index failed.
  report(request.error);
  // Could call event.preventDefault() to prevent the transaction from aborting.
};
tx.onabort = function() {
  // Otherwise the transaction will automatically abort due the failed request.
  report(tx.error);
};

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

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 of the database.

To avoid blocking a new client from upgrading, clients can listen for the version change 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 to the database.

One way of doing this is to reload the page:

db.onversionchange = function() {
  // First, save any unsaved data:
  saveUnsavedData().then(function() {
    // If the document isn’t being actively used, it could be appropriate to reload
    // the page without the user’s interaction.
    if (!document.hasFocus()) {
      location.reload();
      // Reloading will close the database, and also reload with the new JavaScript
      // and database definitions.
      // If the document has focus, it can be too disruptive to reload the page.
      // Maybe ask the user to do it manually:
      displayMessage("Please reload this page for the latest version.");
    }
  });
};
 
function saveUnsavedData() {
  // How you do this depends on your app.
}
 
function displayMessage() {
  // Show a non-modal message to the user.
}

Another way is to call the connection‘s method. However, you need to make sure your app is aware of this, as subsequent attempts to access the database will fail.

db.onversionchange = function() {
  saveUnsavedData().then(function() {
    db.close();
    stopUsingTheDatabase();
  });
};
 
function stopUsingTheDatabase() {
  // Put the app into a state where it no longer uses the database.

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 event fires if other clients still hold a connection to the database after their "versionchange" events have fired.