State & ArchitectureBaseline · Widely

Client Storage Versioning & Zero-Downtime Migrations

Mental Model

Bumping an IndexedDB schema version while an older tab holds an open connection triggers onblocked and hangs the new tab indefinitely. Handling onversionchange to call db.close() in old tabs and running idempotent versionchange steps lets migrations complete without data loss.

Interactive Simulator

IndexedDB Multi-Tab Versionchange Handshake

Trace how Tab 1 releases its v1 handle via onversionchange so Tab 2 can run the v2 migration without blocking.

Tab 1 (v1 Open)
IDB Engine (Pending v2)
Tab 2 (Waiting)
Step 1 / 3: 1. Tab 2 Requests Schema v2

Newly deployed Tab 2 calls indexedDB.open('app-db', 2) while Tab 1 still holds a v1 connection.

const req = indexedDB.open('app-db', 2);
// blocked until Tab 1 closes
Internal State / Memory
tab1Version
1
tab2Status
waiting-versionchange

Under the Hood

The IndexedDB specification enforces a single-writer lock across the entire origin during schema upgrades. Opening version N + 1 cannot start onupgradeneeded until every tab holding version N closes its IDBDatabase handle.

  1. Cooperative close: Every tab attaches db.onversionchange = () => db.close() immediately after open() succeeds, unblocking newer tabs opened after a deploy.
  2. Sequential step table: Inside onupgradeneeded(e), iterate for (let v = e.oldVersion; v < e.newVersion; v++) so users jumping from v1 to v4 execute every intermediate store/index transform.
  3. Expand-and-contract: During rolling Service Worker updates, add new stores or nullable fields before dropping legacy ones so older cached tabs do not crash.
TS
const req = indexedDB.open('app-db', 2);
req.onupgradeneeded = (e) => {
  const db = req.result;
  if (e.oldVersion < 1) db.createObjectStore('drafts', { keyPath: 'id' });
  if (e.oldVersion < 2) {
    const store = req.transaction!.objectStore('drafts');
    store.createIndex('byUpdated', 'updatedAt', { unique: false });
  }
};
req.onsuccess = () => {
  req.result.onversionchange = () => req.result.close();
};

Problem Genealogy

  • 2013–2017 (Delete-on-Mismatch Shortcuts): Apps wrapped indexedDB.open() in deleteDatabase() on version errors, silently erasing offline user drafts whenever a schema bumped.
  • 2018+ (Versioned Step Runners & onversionchange): Standardized multi-tab close() handshakes and additive schema migrations modeled after backend SQL runners.

Production Pitfalls

Production Pitfall
  • New tab hangs forever on splash screen after deploy: Omitting db.onversionchange = () => db.close() leaves background tabs holding the v1 handle, firing onblocked indefinitely in the v2 tab.
  • ConstraintError or TransactionInactiveError during upgradeneeded: Calling await fetch() inside onupgradeneeded commits and closes the versionchange transaction before the network resolves.
When Not to Use
  • When not to use an IndexedDB version bump: For adding an optional JSON property inside an existing object store value, deserialize lazily at read time with a runtime schema default instead of triggering a cross-tab versionchange lock.

Connections & Logical Next Steps

State & ArchitectureClient Storage Versioning & Zero-Downtime Migrations
What This Unlocks
Leaf concept

Seen in Architecture Autopsies