Introduction to IndexedDB

September 15, 2025

What is IndexedDB?

IndexedDB is a NoSQL database integrated into browsers, enabling the storage and management of large amounts of client-side data. It is a powerful JavaScript API designed to store structured data, such as JavaScript objects, rather than simple strings like localStorage or sessionStorage. IndexedDB supports CRUD operations (Create, Read, Update, Delete) and provides efficient searching capabilities through indexes.

Key Features of IndexedDB

Large data storage: IndexedDB can store hundreds of megabytes of data, depending on the browser and device.
Transaction support: Ensures data integrity through transactions, preventing errors during multiple simultaneous operations.
High performance: Uses indexes for fast querying.
Asynchronous operation: The IndexedDB API operates asynchronously, avoiding blocking the main application thread.
Versatile data support: Can store various data types, including JavaScript objects, binary files (Blobs), and more.

Role of IndexedDB

IndexedDB plays a crucial role in modern web applications, particularly in Progressive Web Apps (PWAs). Its key roles include:

Offline data storage: IndexedDB allows web applications to store data locally, enabling users to access data without an internet connection.
Improved performance: By storing data locally, IndexedDB reduces server requests, speeding up application load times.
Complex data management: With its ability to store and query structured data, IndexedDB is ideal for applications managing complex data, such as product lists, user information, or multimedia content.
PWA support: IndexedDB is a vital component in building web applications that function like native apps, with offline data storage capabilities.

Advantages of IndexedDB

Large storage capacity: IndexedDB can store significantly more data than localStorage (typically limited to 5-10MB), depending on the browser and device.
Structured data support: Enables storage of complex JavaScript objects, making data management and querying easier.
High performance: Uses indexes for fast queries and supports transactions to ensure data integrity.
Asynchronous operation: Does not interrupt the main application thread, improving user experience.
Offline support: Ideal for applications requiring offline functionality, such as PWAs.
Versatile data types: Supports storage of various data types, from text and numbers to binary files like images or videos.

Disadvantages of IndexedDB

High complexity: The IndexedDB API is more complex than localStorage or sessionStorage, requiring developers to understand transactions, indexes, and asynchronous handling.
Browser compatibility: While widely supported, some older browsers or specific versions may lack full support or have implementation differences.
Debugging challenges: Debugging errors in IndexedDB can be complex, especially when working with transactions or database structures.
No visual interface: Unlike databases like SQLite, IndexedDB lacks built-in tools for visually managing data, making manual data inspection or modification difficult.
Complex version management: Changing the database structure requires incrementing the version number and handling upgrade logic, which can lead to errors if not done carefully.

How to Use IndexedDB

Below is a basic guide to working with IndexedDB, covering the main steps for creating, reading, updating, and deleting data.

1. Opening a Database

To use IndexedDB, you first need to open a database. If the database doesn’t exist, it will be created.

const request = indexedDB.open("myDatabase", 1);

request.onupgradeneeded = function(event) {
  const db = event.target.result;
  // Create an object store (data table) with "id" as the primary key
  const objectStore = db.createObjectStore("users", { keyPath: "id" });
  // Create an index for searching by email
  objectStore.createIndex("email", "email", { unique: true });
};

request.onsuccess = function(event) {
  const db = event.target.result;
  console.log("Database opened successfully");
};

request.onerror = function(event) {
  console.error("Error opening database:", event.target.error);
};

indexedDB.open(name, version): Opens or creates a database with a specific name and version.
onupgradeneeded: Triggered when the database needs upgrading (e.g., creating a new database or modifying its structure).
onsuccess: Called when the database is opened successfully.
onerror: Handles errors if they occur.

2. Adding Data

To add data to an object store, you need to use a transaction.

function addUser(db, user) {
  const transaction = db.transaction(["users"], "readwrite");
  const objectStore = transaction.objectStore("users");
  const request = objectStore.add(user);

  request.onsuccess = function() {
    console.log("User added successfully");
  };

  request.onerror = function(event) {
    console.error("Error adding user:", event.target.error);
  };
}

// Example of adding a user
const newUser = { id: 1, name: "John Doe", email: "john@example.com" };
addUser(db, newUser);

3. Reading Data

To retrieve data, you can use methods like get, getAll, or query via an index.

function getUserById(db, id) {
  const transaction = db.transaction(["users"], "readonly");
  const objectStore = transaction.objectStore("users");
  const request = objectStore.get(id);

  request.onsuccess = function(event) {
    if (event.target.result) {
      console.log("User:", event.target.result);
    } else {
      console.log("User not found");
    }
  };

  request.onerror = function(event) {
    console.error("Error retrieving data:", event.target.error);
  };
}

// Retrieve user with id = 1
getUserById(db, 1);

4. Updating Data

To update data, use the put method.

function updateUser(db, user) {
  const transaction = db.transaction(["users"], "readwrite");
  const objectStore = transaction.objectStore("users");
  const request = objectStore.put(user);

  request.onsuccess = function() {
    console.log("User updated successfully");
  };

  request.onerror = function(event) {
    console.error("Error updating user:", event.target.error);
  };
}

// Update user information
const updatedUser = { id: 1, name: "Jane Doe", email: "jane@example.com" };
updateUser(db, updatedUser);

5. Deleting Data

To delete data, use the delete method.

function deleteUser(db, id) {
  const transaction = db.transaction(["users"], "readwrite");
  const objectStore = transaction.objectStore("users");
  const request = objectStore.delete(id);

  request.onsuccess = function() {
    console.log("User deleted successfully");
  };

  request.onerror = function(event) {
    console.error("Error deleting user:", event.target.error);
  };
}

// Delete user with id = 1
deleteUser(db, 1);

6. Using Indexes

Indexes enable faster querying of data based on non-primary key fields.

function getUserByEmail(db, email) {
  const transaction = db.transaction(["users"], "readonly");
  const objectStore = transaction.objectStore("users");
  const index = objectStore.index("email");
  const request = index.get(email);

  request.onsuccess = function(event) {
    if (event.target.result) {
      console.log("User:", event.target.result);
    } else {
      console.log("User with this email not found");
    }
  };
}

// Find user by email
getUserByEmail(db, "john@example.com");

Notes on Using IndexedDB

Browser compatibility: IndexedDB is supported by most modern browsers (Chrome, Firefox, Safari, Edge). However, compatibility should be checked for older browsers.
Version management: Whenever the database structure changes (e.g., adding/removing object stores or indexes), the version number in indexedDB.open must be incremented.
Error handling: Always check and handle errors in onerror events to ensure application stability.
Performance: Avoid performing too many transactions simultaneously to prevent performance degradation.

Conclusion

IndexedDB is a powerful tool for storing and managing client-side data in web applications. With its ability to handle large datasets, support transactions, and provide efficient querying, IndexedDB is ideal for modern web applications, particularly those requiring offline functionality or high performance. However, developers should be mindful of its complex API and challenges related to version management and debugging. By mastering the IndexedDB API, you can build robust and flexible web applications.

HT Blog