IndexedDB Versioning: The 'upgradeneeded' Gatekeeper

Why it exists

Web apps evolve, and so must their client-side databases. IndexedDB needs a safe, structured way to update its schema (the object stores and indexes) without forcing users to lose their stored data. The versioning system provides this controlled migration path.

The mental model

Think of the version number you pass to indexedDB.open() as a "target schema version." If the browser's stored database is at an older version, IndexedDB triggers the upgradeneeded event, giving you a single, exclusive transaction to run your migration code and bring the schema up to date.

How it works

When you call window.indexedDB.open("myDB", 2), the browser checks the current database version. If it's 1 (or doesn't exist), it blocks all other connections, fires the upgradeneeded event, and waits. Inside this event handler, you receive a database connection (event.target.result) and can run structural changes like db.createObjectStore() and objectStore.createIndex(). The event object also contains oldVersion and newVersion for handling sequential migrations. Once your handler finishes without error, the new schema is committed and the database version is officially set to 2.

When to use it

Use this mechanism whenever you deploy a new version of your web app that requires a change to the client-side database structure. This includes adding an object store for a new feature, adding an index to improve query performance, or removing an obsolete store.

When not to use it

Do not increment the version for routine data operations like adding, reading, or deleting records. The upgradeneeded event is strictly for schema migrations. Trying to perform structural changes outside of this event handler is the most common error; the API will throw an InvalidStateError.

One canonical example

To add a 'users' table, you'd increment your database version. First, const request = indexedDB.open("appDB", 2);. Then, you'd define the schema change in the event handler: request.onupgradeneeded = event => { const db = event.target.result; if (event.oldVersion < 2) { const store = db.createObjectStore("users", { keyPath: "id" }); store.createIndex("email", "email", { unique: true }); } }; This ensures the 'users' store is created only when upgrading from a version less than 2.