Executando Consultas com o IndexedDB em 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);
};

Documentação oficial:

Indexed Database API - W3C