CKTIS / JavaScript
IDBOpenDBRequest — abrir y actualizar una base de datos IndexedDB
IDBOpenDBRequest representa una solicitud asíncrona para abrir o eliminar una base de datos IndexedDB. Sus eventos permiten gestionar las actualizaciones del esquema, el bloqueo por otras conexiones y la finalización de la operación. No es una conexión a la base de datos ni una Promise.
Versión: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintaxis
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 se devuelve inmediatamente con indexedDB.open(name, version) y indexedDB.deleteDatabase(name). Hereda de IDBRequest y, después, de EventTarget; obtén el resultado mediante eventos, no con await request. Es una API web del navegador de la familia IndexedDB, no una característica de ECMAScript. MDN indica que la interfaz está ampliamente disponible desde julio de 2015. Por separado, MDN señala que la interfaz está disponible en Web Workers; esa fecha no indica desde cuándo los navegadores ofrecen compatibilidad generalizada con la interfaz en Web Workers. Que un repositorio use Node 24 no demuestra que esta API sea compatible.
IDBOpenDBRequest.upgradeneeded designa el evento upgradeneeded, no un método. Se activa al crear una base de datos o al abrirla con una versión superior. IDBOpenDBRequest.onupgradeneeded es la propiedad para asignar su controlador; otra opción es addEventListener("upgradeneeded", handler). Aquí puedes crear o modificar almacenes de objetos e índices. La propiedad heredada IDBOpenDBRequest.transaction expone la transacción de actualización en modo versionchange; si no hay actualización, vale null. No representa cualquier transacción de datos posterior.
IDBOpenDBRequest.blocked designa el evento blocked: otra conexión abierta impide actualizar o eliminar la base de datos. Es una situación de espera, no un fallo definitivo. Gestiona versionchange en cada conexión cerrándola con db.close(), e informa al usuario del bloqueo. Un controlador blocked por sí solo no cierra otras conexiones.
IDBOpenDBRequest.success y IDBOpenDBRequest.error designan eventos heredados de IDBRequest, que también se gestionan mediante onsuccess y onerror. Tras abrir correctamente, request.result contiene un IDBDatabase; tras eliminar la base, su valor es undefined. La apertura solo tiene éxito cuando se confirma cualquier actualización necesaria; upgradeneeded todavía no significa que haya terminado correctamente. Si se produce un error, consulta request.error. No leas el resultado justo después de open(); gestiona los fallos asíncronos mediante error, por separado de las excepciones síncronas que pueda producir la propia llamada.
Ejemplos
<!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>Resultado
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
El código mostrado y el resultado declarado se verificaron en un entorno aislado mediante el método registrado en la evidencia de verificación de esta versión exacta.