IndexedDB: A NoSQL Database in Your Browser

Why it exists

Web Storage (localStorage/sessionStorage) is great for small, simple key-value pairs. But modern web apps often need to store large amounts of structured data on the client for offline functionality or caching complex objects. IndexedDB was created to provide a robust, high-performance database directly in the browser to solve this problem.

The mental model

IndexedDB is a transactional, object-oriented database that lives on the user's machine. Instead of thinking in SQL tables and rows, think of it as a JavaScript-based NoSQL database. You store entire JavaScript objects in "object stores" (like collections or tables) and can retrieve them efficiently using "indexes" on object properties.

How it works

All operations are asynchronous to prevent blocking the user interface. The process involves three main steps. First, you request to open a database with a specific version number; if the database is new or the version is higher, you define the schema by creating object stores and indexes. Second, once connected, you start a transaction on one or more object stores. Third, within that transaction, you can add, read, update, or delete objects. All communication happens via events fired on request objects, not promises or callbacks directly.

When to use it

Use IndexedDB for building offline-first applications where users can view and edit data without a network connection. It's also ideal for caching large, structured data from APIs to reduce network requests and improve performance, or for temporarily storing user-generated content (like a complex form or document) before it's sent to a server.

When not to use it

Avoid IndexedDB for small, simple data like user settings or authentication tokens; localStorage is simpler and sufficient for that. Because the API is low-level and event-based, it can be complex to use directly for simple needs. Never use it as a sole source of truth for critical data, as browsers can and will delete data under storage pressure.

One canonical example

A web-based email client could use IndexedDB to store a user's recent emails. It would create an "emails" object store and an index on the 'date' property. When the user goes offline, they can still read and search their inbox. The app queries IndexedDB to display the cached emails. When the connection is restored, it syncs any changes with the server.