Executando Consultas com IndexedDB API - JavaScript

No IndexedDB, todas as operações de banco de dados são encapsuladas em transações, representadas pelo tipo IDBTransaction. Essas transações permitem manipular os dados de forma organizada e segura. Para criar uma transação, utiliza-se o método transaction() do objeto IDBDatabase.

O método transaction() possui a seguinte assinatura:

transaction(storeNames)
transaction(storeNames, mode)

O método transaction() pode receber seguintes parâmetros:

• storeNames: Um array contendo os nomes dos armazenamentos (object stores) que serão acessados na transação.

• mode(opcional): Define o tipo de acesso permitido na transação. Pode ter os seguintes valores:

  • readonly: Permite apenas leitura dos dados. É o padrão, caso o parâmetro não seja especificado.

  • readwrite: Permite leitura e escrita nos dados.

  • versionchange: Permite operações avançadas, como criação e exclusão de armazenamentos e índices.

Abaixo, um exemplo básico de criação de uma transação:

const request = indexedDB.open("test", 3); // Conecta ao banco de dados 'test'

request.onsuccess = (event) => {
    const db = event.target.result; // Obtém a instância do banco de dados
    const transaction = db.transaction("users"); // Cria uma transação para o armazenamento "users"
    console.log(transaction);
};

Para acessar múltiplos armazenamentos em uma única transação, basta listá-los como um array:

const transaction = db.transaction(["users", "companies"]); // Acessa "users" e "companies"

Caso seja necessário incluir todos os armazenamentos do banco, pode-se utilizar a propriedade objectStoreNames:

const transaction = db.transaction(db.objectStoreNames);

Propriedades do Objeto IDBTransaction

A interface IDBTransaction oferece propriedades úteis para obter informações sobre a transação:

• db: Instância do banco de dados (IDBDatabase).

• error: Detalhes sobre erros ocorridos na transação, representados como um objeto DOMException.

• mode: O modo de acesso da transação (por padrão, readonly).

• objectStoreNames: Lista de armazenamentos incluídos na transação, representada como um objeto DOMStringList.

Exemplo de uso das propriedades:

const request = indexedDB.open("test", 3);

request.onsuccess = (event) => {
    const db = event.target.result;
    const transaction = db.transaction(["users"], "readwrite"); 

    console.log(transaction.db.name); // Nome do banco: 'test'
    console.log(transaction.mode); // Modo: 'readwrite'
    console.log(transaction.objectStoreNames); // Armazenamentos: ["users"]
};

Acessando um Armazenamento (objectStore)

Dentro de uma transação, o acesso aos dados é realizado através de um objeto de armazenamento, representado pelo objeto IDBObjectStore. Para obtê-lo, utiliza-se o método objectStore() da transação:

const userStore = transaction.objectStore("users"); // Acessa o armazenamento "users"

É importante ressaltar que o armazenamento deve ter sido previamente criado utilizando o método createObjectStore() do objeto IDBDatabase.

Os armazenamentos geralmente são gerenciando durante o evento onupgradeneeded, que é disparado ao criar ou alterar a versão de um banco de dados. O exemplo abaixo ilustra a criação de um armazenamento chamado "users":

const request = indexedDB.open("test", 5); // Conecta ao banco de dados 'test'

// Evento para criação ou atualização da estrutura do banco
request.onupgradeneeded = (event) => {
    const db = event.target.result;

    // Remove o armazenamento "users", se já existir
    if (db.objectStoreNames.contains("users")) {
        db.deleteObjectStore("users");
    }

    // Cria um novo armazenamento com chave primária "id" e auto-incremento
    const userStore = db.createObjectStore("users", { keyPath: "id", autoIncrement: true });
    console.log(userStore);
};

// Evento para manipulação de dados após abertura do banco
request.onsuccess = (event) => {
    const db = event.target.result;
    const transaction = db.transaction(["users"], "readwrite");
    const userStore = transaction.objectStore("users");
    console.log(userStore);
};

Métodos Disponíveis no IDBObjectStore

O objeto IDBObjectStore oferece diversos métodos para gerenciar os dados no armazenamento:

• add(): Adiciona novos registros ao armazenamento.

• clear(): Remove todos os registros do armazenamento.

• count(): Retorna o número total de registros no armazenamento.

• createIndex(): Cria um novo índice para consulta.

• delete(): Remove um registro com base em sua chave.

• deleteIndex(): Remove um índice do armazenamento.

• get(): Retorna um registro baseado em uma chave específica.

• getKey(): Retorna apenas a chave de um registro.

• getAll(): Retorna todos os registros do armazenamento.

• getAllKeys(): Retorna todas as chaves dos registros.

• index(): Acessa um índice para realizar consultas específicas.

• openCursor(): Permite iterar pelos registros com o uso de um cursor.

• openKeyCursor(): Itera apenas pelas chaves dos registros.

• put(): Atualiza registros existentes ou adiciona novos.

A seguir, um exemplo de adição de um novo registro ao armazenamento "users":

const transaction = db.transaction(["users"], "readwrite");
const userStore = transaction.objectStore("users");

const newUser = { name: "John Doe", age: 30 };
const request = userStore.add(newUser);

request.onsuccess = () => {
    console.log("Registro adicionado com sucesso!");
};

Para recuperar todos os registros do armazenamento, utiliza-se o método getAll():

const transaction = db.transaction(["users"], "readonly");
const userStore = transaction.objectStore("users");

const request = userStore.getAll();

request.onsuccess = (event) => {
    console.log("Dados:", event.target.result);
};