termEngineering & architecture

IndexedDB

IndexedDB is an asynchronous, transactional browser database for storing and querying significant amounts of structured origin-scoped data.

Download Markdown (.md)

01What it means

IndexedDB is a low-level browser database API organized around databases, versioned schemas, object stores, keys, indexes, requests, and transactions. It stores values supported by the structured clone algorithm, including blobs, and performs normal operations asynchronously. It differs from Web Storage's small synchronous string stores and from server databases that provide authoritative shared state.[1][2]

Origin-scoped asynchronous browser database Open a version, migrate stores in upgrade, then transact against explicit scope
  1. Open databaseName and requested version
  2. UpgradeCreate or migrate stores and indexes
  3. Start transactionStore scope and read/write mode
  4. Issue requestsAsynchronous success, error, abort
  5. Close or version againPlan quota, eviction, conflicts, sync

Schema changes repeat the versioned upgrade lifecycle

IndexedDB stores structured-clone values and blobs; it is neither synchronous Web Storage nor authoritative shared server data.

02Why it matters

IndexedDB enables offline data, local caches, drafts, and data-rich browser applications without blocking the main thread for storage operations. Schema upgrades, quotas, eviction, concurrency, and synchronization still need deliberate product behavior.

03When to use it

Use it for substantial structured client data, searchable offline records, large drafts, or durable caches. Use Web Storage for a few small preference strings and keep authoritative or cross-device records on a backend.

04How it works

  1. Open a named, versioned database for the current origin.
  2. Create or migrate object stores and indexes during the upgrade transaction.
  3. Start a transaction with an explicit store scope and access mode.
  4. Issue asynchronous requests and handle completion, errors, and transaction aborts.
  5. Plan conflict, quota, eviction, deletion, and server synchronization behavior.

05A practical example

Example

A field app stores inspections, photos, and an outbound change queue in IndexedDB. Transactions keep each draft consistent, and synchronization records conflicts instead of silently overwriting newer server data.

06Where it breaks

The API is verbose, storage is origin-scoped and not guaranteed against eviction or user clearing, and version upgrades can be blocked by open tabs. IndexedDB does not supply cross-device synchronization or business conflict resolution.

Common mistakes

  • Treating local browser data as an authoritative backup.
  • Performing schema upgrades without handling other open connections.
  • Keeping transactions alive across unrelated asynchronous application work.
  • Ignoring quota, private browsing, corruption, and user-cleared storage paths.

07Sources

  1. Indexed Database API 3.0W3C · Web standardIndexed Database API 3.0
  2. IndexedDB APIMDN Web Docs · Official technical documentationIndexedDB API
View saved topics

Start typing to search titles, definitions, categories, and frameworks.