CKTIS / JavaScript
IndexedDB: onupgradeneeded y la transacción de actualización
Cambia el esquema de IndexedDB en `onupgradeneeded`, accede a la transacción mediante `request.transaction` y espera a `success` para usar el nuevo esquema.
Versión: Current web platform; runtime support varies
Sintaxis
// The upgrade lifecycle is defined by IndexedDB, not by an ECMAScript edition.
const request = indexedDB.open(name, version);
request.onupgradeneeded = (event) => {
const db = request.result;
const tx = request.transaction;
// Apply schema changes through db and tx while tx is active.
};indexedDB.open(name, version) devuelve de inmediato un IDBOpenDBRequest; la apertura es asíncrona. onupgradeneeded es la propiedad que recibe el manejador del evento upgradeneeded. El evento se dispara al crear una base de datos o al abrirla con una versión superior. Con la misma versión no se dispara; una versión inferior provoca VersionError. IndexedDB es una API web, no una función de ECMAScript 2024.
Dentro del manejador, request.result contiene la conexión IDBDatabase. La propiedad de solo lectura request.transaction, heredada de IDBRequest, contiene la IDBTransaction que IndexedDB crea automáticamente en modo "versionchange". Vale null justo después de open() y otra vez en success. db.transaction() inicia una transacción separada en modo "readonly" o "readwrite", no una transacción de actualización.
Usa event.oldVersion y event.newVersion para elegir los pasos de migración. En una base nueva, oldVersion vale 0; las comprobaciones de versión independientes permiten ejecutar varios pasos si se omiten versiones intermedias. Crea un almacén con db.createObjectStore() y añade un índice a un almacén existente con tx.objectStore(name).createIndex(). También puedes migrar registros en la misma transacción.
Encola operaciones mientras la transacción esté activa: directamente en el manejador de upgradeneeded o en los manejadores de eventos de sus solicitudes. No des por hecho que sigue activa después de await fetch() o al ejecutarse la función de un temporizador. tx.abort() revierte los cambios de esquema, datos y versión; la solicitud de apertura emite error en lugar de success. Si la transacción se confirma, su evento complete precede al success de la solicitud de apertura.
Una conexión existente, por ejemplo en otra pestaña, puede retrasar la actualización. Gestiona blocked en la solicitud de apertura y cierra las conexiones existentes con db.close() en sus manejadores de versionchange.
Ejemplos
<!doctype html>
<meta charset="utf-8">
<title>IndexedDB upgrade transaction</title>
<script>
(() => {
const name = `cktis-indexeddb-${crypto.randomUUID()}`;
const reportError = (event) => console.error(event.target.error);
function openVersion(version) {
const request = indexedDB.open(name, version);
request.onerror = reportError;
request.onupgradeneeded = ({ oldVersion, newVersion }) => {
const db = request.result;
const tx = request.transaction;
if (oldVersion < 1) db.createObjectStore("books", { keyPath: "id" });
if (oldVersion < 2 && newVersion >= 2) {
console.log(`upgrade: ${oldVersion} -> ${newVersion} (${tx.mode})`);
tx.objectStore("books").createIndex("by_title", "title");
tx.oncomplete = () => console.log("complete");
}
};
return request;
}
const first = openVersion(1);
first.onsuccess = () => {
first.result.close();
const second = openVersion(2);
console.log(`before: ${second.transaction}`);
second.onsuccess = () => {
const db = second.result;
const store = db.transaction("books", "readonly").objectStore("books");
console.log(`success: ${second.transaction}; index: ${store.indexNames.contains("by_title")}`);
db.close();
indexedDB.deleteDatabase(name).onerror = reportError;
};
};
})();
</script>Resultado
before: null upgrade: 1 -> 2 (versionchange) complete success: null; index: true
Abre la página HTML en un navegador, en un contexto seguro con acceso a IndexedDB y a `crypto.randomUUID()`. Consulta el resultado en la consola de desarrollo. El ejemplo crea una base de nombre aleatorio en la versión 1, cierra la conexión, añade `by_title` en la versión 2 y solicita eliminar la base de prueba tras comprobar el índice.
Lecciones relacionadas
- JavaScript · Lección 31 · Avanzado · Versión: 4
Fuentes
- IDBOpenDBRequest: upgradeneeded event
- IDBRequest: transaction property
- IDBFactory: open() method
- IDBRequest: error property
- IDBTransaction
- IDBDatabase: transaction() method
- Using IndexedDB
- IDBOpenDBRequest: blocked event
- IDBDatabase: versionchange event
- IDBObjectStore: createIndex() method
- Crypto: randomUUID() method
- IDBFactory: deleteDatabase() method