IndexedDB Transactions and Storage Quotas
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.
IndexedDB Transaction Auto-Commit Lifecycle
See why awaiting a non-IDB Promise kills an active IndexedDB 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');- 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.
- Scope Locking: Multiple
readonlytransactions execute concurrently; areadwritetransaction blocks overlappingreadwritetransactions on the same object store. - Microtask Auto-Commit: After
IDBRequest.onsuccessfires, if no new request is queued before microtasks drain, the engine commits the transaction automatically. - Quota & Eviction: Browsers allocate a percentage of free disk per origin (
navigator.storage.estimate()) and evictbest-effortorigins under disk pressure unless grantednavigator.storage.persist().
// 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
- Awaiting non-IDB promises inside a transaction:
await fetch()orawait new Promise(setTimeout)closes the transaction and throwsTransactionInactiveErroron the next write. - Large
structuredClonepayloads on the main thread: Writing 50 MB blobs in onestore.put()stalls the UI thread; run heavy writes in a Dedicated Web Worker.
- 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
IndexedDB schema changes run exclusively inside the versionchange transaction triggered by indexedDB.open(name, version).
Single-leader coordination prevents concurrent tabs from interleaving read-modify-write IndexedDB transactions.
Persisting the outbox inside IndexedDB readwrite transactions survives tab closes and offline periods.
IDB transaction auto-commit is tied directly to microtask queue exhaustion.
OPFS shares the origin's storage quota pool and eviction rules with IndexedDB.
OPFS provides raw byte-level file handles without structured-clone or transaction overhead.
IndexedDB locks object stores per transaction, whereas Web Locks and BroadcastChannel coordinate multi-tab state explicitly.
IndexedDB persists single-device B-tree records, whereas CRDTs merge concurrent multi-device edits deterministically.
Seen in Architecture Autopsies
Mechanical Comparisons
IndexedDB locks object stores per transaction, whereas Web Locks and BroadcastChannel coordinate multi-tab state explicitly.
IndexedDB persists single-device B-tree records, whereas CRDTs merge concurrent multi-device edits deterministically.
OPFS provides raw byte-level file handles without structured-clone or transaction overhead.