IndexDB API

Crearea, deschiderea și ștergerea bazei de date

Indexed Database API sau IndexedDB API oferă funcționalități pentru lucrul cu o bază de date care se află în browser. Această bază de date se numește IndexedDB. Particularitatea sa este că este o bază de date nereținută (ceea ce se numește NoSQL). Ideea principală a IndexedDB constă în stocarea obiectelor sub anumite chei.

Deschiderea/crearea bazei de date IndexDB

Pentru a accesa funcționalitatea IndexedDB se utilizează proprietatea indexedDB a obiectului window:

const dbFactory = window.indexedDB;
console.log(dbFactory);    // IDBFactory{}

Această proprietate reprezintă un obiect de tip IDBFactory, care oferă funcționalitatea pentru lucrul cu baza de date. În special, cu ajutorul metodei sale open() se poate deschide o bază de date.

open(name)
open(name, version)

Ca parametru în metoda open() se transmite numele bazei de date. Ca al doilea parametru opțional se poate transmite numărul versiunii bazei de date, care, de fapt, definește schema bazei de date utilizată pentru stocarea obiectelor.

const request = indexedDB.open("test"); // ne conectăm la bd test

În acest cod încercăm să ne conectăm la baza de date "test". Și nu contează că inițial această bază de date nu există - dacă lipsește, ea este automat creată.

Valoarea returnată de metoda open() este un obiect de tip IDBOpenDBRequest. Se poate spune că acesta este un obiect de cerere pentru deschiderea corespunzătoare a bazei de date.

Pentru a accesa baza de date propriu-zisă la obiectul IDBOpenDBRequest se poate procesa evenimentul success. Acesta apare la deschiderea cu succes a bazei de date. Pentru a seta un handler pentru acest eveniment se poate folosi proprietatea onsuccess:

const request = indexedDB.open("test"); // ne conectăm la bd test
// la deschiderea reușită se activează evenimentul success
// procesăm acest eveniment
request.onsuccess = (event) => {  
   const database = event.target.result;  // accesăm baza de date  
   console.log(database.name);            // "Test"  
};

În interiorul handlerului evenimentului, prin proprietatea event.target.result putem obține baza de date, care reprezintă un obiect IDBDatabase.

Procesarea erorilor la deschiderea bazei de date

Totuși, la încercarea de a deschide baza de date poate apărea și o eroare - evenimentul error, de exemplu, când utilizatorul nu are permisiuni în browser pentru acces la baza de date. În acest caz putem defini un handler pentru evenimentul error prin proprietatea onerror:

const request = indexedDB.open("test"); // ne conectăm la bd test
// procesăm eroarea
request.onerror = (event) => {
   const error = event.target.error;      // Obținem informații despre eroare  
   console.error(error.message);
};

Urmărirea creării bazei de date

La deschiderea bazei de date, dacă aceasta lipsește, ea este automat creată. Prin urmare, în acest sens nu contează dacă avem sau nu baza de date. Totuși, uneori este necesar să urmărim crearea bazei de date. În acest caz putem folosi evenimentul upgradeneeded, care este apelat de fiecare dată când baza de date solicitată încă nu există și prin urmare este creată, sau când baza de date solicitată încă nu există în această versiune specifică.

În ambele cazuri, handlerul evenimentului apelat primește ca parametru un obiect de tip IDBVersionChangeEvent. Acest obiect permite obținerea versiunii vechi și a celei noi a bd. Pentru a seta un handler pentru eveniment se poate folosi proprietatea onupgradeneeded:

request.onupgradeneeded = (event) => {
   console.log(event.oldVersion);         // versiunea veche a bazei de date
   console.log(event.newVersion);         // versiunea nouă a bazei de date
   const database = event.target.result;  // accesăm baza de date propriu-zisă
};

Deoarece acest handler este apelat la crearea bazei de date, el reprezintă un loc convenabil pentru efectuarea diferitelor setări și inițializări ale bd, în special, pentru crearea spațiilor de stocare ale acesteia.

Obținerea bazelor de date

Metoda databases() a obiectului IDBFactory permite obținerea unei liste a tuturor bazelor de date existente. Această metodă returnează un promise, din care se pot obține date sub forma unui array, unde fiecare element reprezintă un obiect cu două proprietăți - name (numele bazei de date) și version (versiunea bazei de date):

const promise = indexedDB.databases();
promise.then((databases) => console.log(databases));

De exemplu, outputul în cazul meu:

(2) [{...}, {...}]
0: {name: 'test', version: 1}
1: {name: 'test2', version: 1}
length: 2
Prototype: Array(0)

În acest caz se vede că am două baze de date - test și test2, fiecare având versiunea 1.

Ștergerea bazei de date

Pentru ștergerea bazei de date la obiectul IDBFactory se utilizează metoda deleteDatabase(), în care se transmite numele bazei de date care urmează să fie ștearsă:

indexedDB.deleteDatabase("test2");

Este de menționat că această metodă ca rezultat returnează un obiect IDBOpenDBRequest (menționat mai sus). Astfel putem procesa evenimentele success și error, pentru a determina dacă ștergerea a avut loc cu succes sau a apărut o eroare:

const DBDeleteRequest = indexedDB.deleteDatabase("test2");

DBDeleteRequest.onerror = (event) => {
 console.error("Error deleting database.");
};

DBDeleteRequest.onsuccess = (event) => {
 console.log("Database deleted successfully");

 console.log(event.result); // ar trebui să fie undefined
};

Dacă baza de date a fost ștearsă cu succes, atunci proprietatea result a argumentului în handlerul evenimentului success nu va fi setată.