mozilla

IndexedDB

IndexedDB is a low-level API for client-side storage of significant amounts of structured data, which also enables high performance searches of this data using indexes. While DOM Storage is useful for storing smaller amounts of data, it is less useful for storing larger amounts of structured data. IndexedDB provides a solution. This is the main landing page for MDN's IndexedDB coverage — here we provide links to the full API reference and usage guides, browser support details, and some explanation of key concepts.

IndexedDB API is powerful, but may seem too complicated for simple cases. If you'd prefer a simple API, try libraries such as localForage and dexie.js that make IndexedDB more user-friendly.

Key concepts and usage

IndexedDB is a transactional database system, like a SQL-based RDBMS; however whereas the latter uses tables with fixed columns, IndexedDB is a JavaScript-based object-oriented database. IndexedDB lets you store and retrieve objects that are indexed with a key; any objects supported by the structured clone algorithm can be stored. You need to specify the database schema, open a connection to your database, and then retrieve and update data within a series of transactions.

Note: Like most web storage solutions, IndexedDB follows a same-origin policy. So while you can access stored data within a domain, you cannot access data across different domains.

Synchronous and asynchronous

Operations performed using IndexedDB are done asynchronously, so as not to block the rest of an application's running. IndexedDB originally included both an asynchronous API and a synchronous API; the synchronous API being intended for use only with Web Workers. The synchronous version was removed from the spec because its need was questionable, however it may be reintroduced in the future if there is enough demand from web developers.

Storage limits and eviction criteria

There are a number of web technologies that store data of one kind or another on the client-side (i.e. on your local disk), IndexedDB being the most commonly talked about one. The process by which the browser works out how much space to allocate to web data storage and what to delete when that limit is reached is not simple, and differs between browsers. Browser storage limits and eviction criteria attempts to explain how this works, at least in the case of Firefox.

Details on how other browsers deal with this will be added as soon as more information is obtained.

IndexedDB Interfaces

To get access to a database, call open() on the indexedDB attribute of a window object. This method returns an IDBRequest object; asynchronous operations communicate to the calling application by firing events on IDBRequest objects.

Connecting to a database

IDBEnvironment
Provides access to IndexedDB functionality. It is implemented by the window and worker objects.
IDBFactory
Provides access to a database. This is the interface implemented by the global object indexedDB and is therefore the entry point for the API.
IDBOpenDBRequest
Represents a request to open a database.
IDBDatabase
Represents a connection to a database. It's the only way to get a transaction on the database.
IDBRequest
Generic interface that handles database requests and provides access to results.

Retrieving and modifying data

IDBTransaction
Represents a transaction. You create a transaction on a database, specify the scope (such as which object stores you want to access), and determine the kind of access (read only or readwrite) that you want.
IDBObjectStore
Represents an object store that allows access to a set of data in an IndexedDB database, looked up via primary key.
IDBIndex
Also allows access to a subset of data in an IndexedDB database, but uses an index to retrieve the record(s) rather than the primary key. This is sometimes faster than using IDBObjectStore.
IDBCursor
Iterates over object stores and indexes.
IDBCursorWithValue
Iterates over object stores and indexes and returns the cursor's current value.
IDBKeyRange
Defines a range of keys that can be used to retrieve data from a database in a certain range.

Custom event interfaces

This specification fires events with the following custom interface:

IDBVersionChangeEvent
The IDBVersionChangeEvent interface indicates that the version of the database has changed, as the result of an IDBOpenDBRequest.onupgradeneeded event handler function.

Obsolete interfaces

An early version of the specification also defined these now removed interfaces. They are still documented in case you need to update previously written code:

IDBVersionChangeRequest
Represents a request to change the version of a database. The way to change the version of the database has since changed (by calling IDBFactory.open without also calling IDBDatabase.setVersion), and the interface IDBOpenDBRequest now has the functionality of the removed IDBVersionChangeRequest.
IDBDatabaseException 
Represents exception conditions that can be encountered while performing database operations.
IDBTransactionSync
Sync version of IDBTransaction.
IDBObjectStoreSync
Sync version of IDBObjectStore.
IDBIndexSync
Sync version of IDBIndex.
IDBFactorySync
Sync version of IDBFactory.
IDBEnvironmentSync
Sync version of IDBEnvironment.
IDBDatabaseSync
Sync version of IDBDatabase.
IDBCursorSync
Sync version of IDBCursor.

Examples

Browser compatibility

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support

23.0 webkit
24

10.0 (10.0) moz
16.0 (16.0)
10, partial 15 7.1
Feature Android Firefox Mobile (Gecko) Firefox OS IE Phone Opera Mobile Safari Mobile
Basic support 4.4 22.0 (22.0) 1.0.1 10 22 8

Note: Some older browsers don't support IndexedDB but do support WebSQL. One way around this problem is to use an IndexedDB Polyfill or Shim that falls back to WebSQL or even localStorage for non-supporting browsers. The best available polyfill at present is localForage.

Specifications

Specification Status Comment
Indexed Database API
The definition of 'IDBEnvironment' in that specification.
Candidate Recommendation  

See also

  • localForage: A Polyfill providing a simple name:value syntax for client-side data storage, which uses IndexedDB in the background, but falls back to WebSQL and then localStorage in browsers that don't support IndexedDB.
  • dexie.js: A wrapper for IndexedDB that allows much faster code development via nice, simple syntax.
Hide Sidebar