CKTIS / JavaScript
IDBOpenDBRequest — opening and upgrading an IndexedDB database
IDBOpenDBRequest represents an asynchronous request to open or delete an IndexedDB database. It exposes schema upgrades, blocking by other connections, and operation completion through events. It is neither a database connection nor a Promise.
Version: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Syntax
const request = indexedDB.open(name, version);
request.onupgradeneeded = (event) => { /* migrate schema */ };
request.addEventListener("blocked", handler);
request.addEventListener("success", handler);
request.addEventListener("error", handler);
// request.transaction: upgrade IDBTransaction or nullIDBOpenDBRequest is returned immediately by indexedDB.open(name, version) and indexedDB.deleteDatabase(name). It inherits from IDBRequest, then EventTarget; obtain its result through events, not await request. This is a browser Web API in the IndexedDB family, not an ECMAScript feature. MDN lists the interface as widely available since July 2015. MDN separately notes that the interface is available in Web Workers; the July 2015 date does not establish when support in Web Workers became widespread across browsers. Node 24 in a repository does not establish support for this API.
IDBOpenDBRequest.upgradeneeded denotes the upgradeneeded event, not a method. It fires when creating a database or opening it with a higher version. IDBOpenDBRequest.onupgradeneeded is the property for assigning its handler; addEventListener("upgradeneeded", handler) is an alternative. Create or modify object stores and indexes here. The inherited IDBOpenDBRequest.transaction property exposes the upgrade transaction in versionchange mode; without an upgrade it is null. It does not represent an arbitrary later data transaction.
IDBOpenDBRequest.blocked denotes the blocked event: another open connection prevents an upgrade or database deletion. This is a waiting condition, not a terminal failure. Handle versionchange on each connection by closing it with db.close(), and inform the user about blocking. A blocked handler alone does not close other connections.
IDBOpenDBRequest.success and IDBOpenDBRequest.error denote events inherited from IDBRequest, also handled through onsuccess and onerror. After successful opening, request.result contains an IDBDatabase; after deletion it is undefined. Opening succeeds only after any required upgrade commits; upgradeneeded is not yet success. On failure, inspect request.error. Do not read the result immediately after open(); handle asynchronous failures through error, separately from synchronous exceptions thrown by the call itself.
Examples
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>IDBOpenDBRequest: opening and upgrading a database</title>
</head>
<body>
<h1>Opening and upgrading an IndexedDB database</h1>
<script>
(() => {
const name = 'cktis-open-' + crypto.getRandomValues(new Uint32Array(4)).join('-');
const report = error => console.log(error.name === 'SecurityError'
? 'IndexedDB unavailable: SecurityError' : `IndexedDB error: ${error.name}`);
let factory, opening;
try {
factory = window.indexedDB;
if (!factory) {
console.log('IndexedDB unavailable: API missing');
return;
}
opening = factory.open(name, 1);
} catch (error) {
report(error);
return;
}
let created = false;
opening.onerror = () => report(opening.error);
opening.onupgradeneeded = () => {
created = true;
opening.result.createObjectStore('notes', { keyPath: 'id' });
};
opening.onsuccess = () => {
const first = opening.result;
if (!created) {
first.close();
console.log('Fixture name already in use');
return;
}
// Hold the old connection open until the new request reports that it is blocked.
const upgrade = factory.open(name, 2);
upgrade.onblocked = event => {
console.log(`blocked: ${event.oldVersion} -> ${event.newVersion}`);
first.close();
};
upgrade.onupgradeneeded = () => {
upgrade.result.createObjectStore('labels');
console.log(`upgrade: ${upgrade.transaction.mode}`);
};
upgrade.onerror = () => {
first.close();
report(upgrade.error);
factory.deleteDatabase(name);
};
upgrade.onsuccess = () => {
const db = upgrade.result;
console.log(`open: ${db.version}, labels: ${db.objectStoreNames.contains('labels')}`);
db.close();
const deletion = factory.deleteDatabase(name);
deletion.onerror = () => report(deletion.error);
deletion.onsuccess = event => console.log(`deleted version: ${event.oldVersion}`);
};
};
})();
</script>
</body>
</html>Result
Observed in the isolated run (IndexedDB access denied): IndexedDB unavailable: SecurityError Expected on a successful run with IndexedDB access: blocked: 1 -> 2 upgrade: versionchange open: 2, labels: true deleted version: 2
The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.