Client Storage Versioning & Zero-Downtime Migrations
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.
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.
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- 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.
- Cooperative close: Every tab attaches
db.onversionchange = () => db.close()immediately afteropen()succeeds, unblocking newer tabs opened after a deploy. - Sequential step table: Inside
onupgradeneeded(e), iteratefor (let v = e.oldVersion; v < e.newVersion; v++)so users jumping from v1 to v4 execute every intermediate store/index transform. - 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.
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()indeleteDatabase()on version errors, silently erasing offline user drafts whenever a schema bumped. - 2018+ (Versioned Step Runners &
onversionchange): Standardized multi-tabclose()handshakes and additive schema migrations modeled after backend SQL runners.
Production Pitfalls
- New tab hangs forever on splash screen after deploy: Omitting
db.onversionchange = () => db.close()leaves background tabs holding the v1 handle, firingonblockedindefinitely in the v2 tab. ConstraintErrororTransactionInactiveErrorduringupgradeneeded: Callingawait fetch()insideonupgradeneededcommits and closes theversionchangetransaction before the network resolves.
- 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
versionchangelock.
Connections & Logical Next Steps
IndexedDB schema changes run exclusively inside the versionchange transaction triggered by indexedDB.open(name, version).
Coordinating Service Worker activation with open tab storage versions prevents old JS bundles from reading new schemas.