IDBUpgradeTransaction

IDBUpgradeTransaction is a specialized transaction type in the IndexedDB API that represents the version-change phase of a database upgrade. It is exposed during the onupgradeneeded event of an IDBOpenDBRequest when a database is opened with a higher version than its current one. The upgrade transaction is available as event.target.transaction and is used to apply schema changes as part of upgrading the database.

This transaction is a variant of the standard IDBTransaction and inherits its API, while being explicitly associated with the upgrade process. Its primary purpose is to enable schema migrations, including creating or deleting object stores and indexes, and performing data migrations within the existing stores as needed to conform to the new version. Although it shares the general transaction capabilities, the upgrade transaction is scoped to the version-change operation and the changes it enforces are committed atomically if no errors occur.

Lifecycle and constraints: the upgrade transaction exists only during the version-change flow initiated by the upgrade. If the upgrade completes successfully, the changes are committed and the new version of the database becomes active. If an error occurs, the transaction can be aborted, causing the upgrade to fail and the open request to reject. Developers should keep upgrade logic efficient and idempotent, as long-running operations can delay the completion of the upgrade.

In practice, IDBUpgradeTransaction is the mechanism through which a database’s schema is evolved in a controlled, atomic fashion during onupgradeneeded. It complements the IDBDatabase interface used to perform the actual schema changes, under the umbrella of a single, version-change transaction.