Web APIsBaseline · Widely

IndexedDB Transactions and Storage Quotas

Mental Model

IndexedDB stores structured-cloned JavaScript objects in indexed B-trees on disk. Every read or write runs inside a scoped transaction that auto-commits the moment the Event Loop drains with no pending IDBRequests, while capacity is governed by dynamic origin-wide storage quotas.

Interactive Simulator

IndexedDB Transaction Auto-Commit Lifecycle

See why awaiting a non-IDB Promise kills an active IndexedDB transaction.

Transaction (Active)
Microtask Queue
Step 1 / 3: 1. Open readwrite Transaction

db.transaction('docs', 'readwrite') acquires a write lock on the 'docs' object store and marks the transaction active.

const tx = db.transaction('docs', 'readwrite');
Internal State / Memory
txState
ACTIVE
pendingRequests
0
storeLock
EXCLUSIVE

Under the Hood

An IndexedDB transaction behaves like a bank vault's dead-man switch: the door locks shut the instant you stop feeding it requests, even if you only stepped away to check the network.

  1. Scope Locking: Multiple readonly transactions execute concurrently; a readwrite transaction blocks overlapping readwrite transactions on the same object store.
  2. Microtask Auto-Commit: After IDBRequest.onsuccess fires, if no new request is queued before microtasks drain, the engine commits the transaction automatically.
  3. Quota & Eviction: Browsers allocate a percentage of free disk per origin (navigator.storage.estimate()) and evict best-effort origins under disk pressure unless granted navigator.storage.persist().
JS
// Safe pattern: resolve async I/O BEFORE opening the transaction
const payload = await fetch('/api/doc/42').then((r) => r.json());
const tx = db.transaction('docs', 'readwrite');
const store = tx.objectStore('docs');
store.put(payload);
await new Promise((resolve, reject) => {
  tx.oncomplete = () => resolve();
  tx.onerror = () => reject(tx.error);
});

Problem Genealogy

  • 2010 (Web SQL Deprecated): SQLite-over-SQL was abandoned over dialect lock-in, leaving IndexedDB as the sole structured client database.
  • 2014 (Quota Management API): Unified IndexedDB, Cache API, and OPFS under one origin quota pool.
  • 2023+ (SQLite-on-Wasm + OPFS): Large analytical apps increasingly bypass IndexedDB's structured-clone tax by storing raw SQLite pages in OPFS.

Production Pitfalls

Production Pitfall
  • Awaiting non-IDB promises inside a transaction: await fetch() or await new Promise(setTimeout) closes the transaction and throws TransactionInactiveError on the next write.
  • Large structuredClone payloads on the main thread: Writing 50 MB blobs in one store.put() stalls the UI thread; run heavy writes in a Dedicated Web Worker.
When Not to Use
  • When not to use IndexedDB: For sequential binary file streaming, SQLite page files, or append-only logs, use OPFS instead of serializing chunks into B-tree records; for multi-tab mutexes or offline conflict resolution, pair it with BroadcastChannel & Web Locks and Local-First Sync & CRDTs.

Connections & Logical Next Steps

What This UnlocksBaseline · Widely
Client Storage Versioning & Zero-Downtime Migrations
State & Architecture

IndexedDB schema changes run exclusively inside the versionchange transaction triggered by indexedDB.open(name, version).

What This UnlocksBaseline · Widely
Multi-Tab State Synchronization & Leader Election
State & Architecture

Single-leader coordination prevents concurrent tabs from interleaving read-modify-write IndexedDB transactions.

What This UnlocksBaseline · Widely
Outbox Queues, Idempotency Keys & Causal Ordering
State & Architecture

Persisting the outbox inside IndexedDB readwrite transactions survives tab closes and offline periods.

Useful PrerequisitesBaseline · Widely
Event Loop, Macrotasks, and Microtask Queue
JS Runtime

IDB transaction auto-commit is tied directly to microtask queue exhaustion.

Under the HoodBaseline · Widely
Origin Private File System (OPFS)
Web APIs

OPFS shares the origin's storage quota pool and eviction rules with IndexedDB.

Often Confused WithBaseline · Widely
Origin Private File System (OPFS)
Web APIs

OPFS provides raw byte-level file handles without structured-clone or transaction overhead.

Often Confused WithBaseline · Widely
BroadcastChannel and Web Locks API
Web APIs

IndexedDB locks object stores per transaction, whereas Web Locks and BroadcastChannel coordinate multi-tab state explicitly.

Often Confused WithExperimental
Local-First Sync & CRDTs
State & Architecture

IndexedDB persists single-device B-tree records, whereas CRDTs merge concurrent multi-device edits deterministically.

Seen in Architecture Autopsies

Mechanical Comparisons