CKTIS / JavaScript
IDBOpenDBRequest — abrir e atualizar uma base de dados IndexedDB
IDBOpenDBRequest representa um pedido assíncrono para abrir ou eliminar uma base de dados IndexedDB. Os eventos permitem gerir atualizações do esquema, bloqueios causados por outras ligações e a conclusão da operação. Não é uma ligação à base de dados nem uma Promise.
Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintaxe
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 é devolvido imediatamente por indexedDB.open(name, version) e indexedDB.deleteDatabase(name). Herda de IDBRequest e, depois, de EventTarget; obtém o resultado através de eventos, não com await request. É uma API Web do navegador da família IndexedDB, não uma funcionalidade ECMAScript. Segundo a MDN, a interface está amplamente disponível desde julho de 2015. A MDN indica separadamente que a interface está disponível em Web Workers; essa data não indica desde quando o suporte em Web Workers é generalizado entre os navegadores. A presença de Node 24 num repositório não comprova o suporte desta API.
IDBOpenDBRequest.upgradeneeded designa o evento upgradeneeded, não um método. É acionado ao criar uma base de dados ou ao abri-la com uma versão superior. IDBOpenDBRequest.onupgradeneeded é a propriedade à qual atribuis o respetivo controlador; em alternativa, podes usar addEventListener("upgradeneeded", handler). É aqui que crias ou alteras object stores e índices. A propriedade herdada IDBOpenDBRequest.transaction expõe a transação de atualização no modo versionchange; sem atualização, o valor é null. Não representa uma transação de dados posterior qualquer.
IDBOpenDBRequest.blocked designa o evento blocked: outra ligação aberta impede a atualização ou eliminação da base de dados. Trata-se de uma situação de espera, não de uma falha definitiva. Trata versionchange em cada ligação, fechando-a com db.close(), e informa o utilizador sobre o bloqueio. Um controlador blocked, por si só, não fecha outras ligações.
IDBOpenDBRequest.success e IDBOpenDBRequest.error designam eventos herdados de IDBRequest, também tratados através de onsuccess e onerror. Após a abertura bem-sucedida, request.result contém um IDBDatabase; após a eliminação, o valor é undefined. A abertura só é bem-sucedida depois de confirmada qualquer atualização necessária; upgradeneeded ainda não significa sucesso. Em caso de erro, consulta request.error. Não leias o resultado imediatamente após open(); trata as falhas assíncronas através de error, separadamente das exceções síncronas lançadas pela própria chamada.
Exemplos
<!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
O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.