# IndexedDB

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

- Type: term
- Domain: Engineering & architecture
- Level: Intermediate
- Last reviewed: 2026-09-23
- Original: [Soroush’s Product Wiki](<https://wiki.soroush.uk/topic/indexeddb/>)

## What 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.

## Why 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.

## When 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.

## How 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.

## A practical 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.

## Where 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.

## Visualization

[View the visualization on the website](<https://wiki.soroush.uk/topic/indexeddb/#visualization-indexeddb>)

## Sources

1. [Indexed Database API 3.0](<https://www.w3.org/TR/IndexedDB-3/>) — W3C · Web standard
2. [IndexedDB API](<https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API>) — MDN Web Docs · Official technical documentation

## Related topics

- [Web Storage](<https://wiki.soroush.uk/topic/web-storage/>)
- [Database](<https://wiki.soroush.uk/topic/database/>)
- [Progressive Web App \(PWA\)](<https://wiki.soroush.uk/topic/progressive-web-app/>)
