What Is IndexedDB?

What is IndexedDB?

IndexedDB is a low-level API built into every modern browser that lets you store large amounts of structured data client-side — including files and blobs. Unlike localStorage and sessionStorage, IndexedDB is:

Asynchronous — all operations are non-blocking and event- or Promise-based
Transactional — reads and writes happen inside transactions, so your data stays consistent even if something goes wrong mid-operation
Object-oriented — you store JavaScript objects directly, not just strings
Indexed — you can define indexes on object properties and query by them efficiently
Large quota — browsers typically allow hundreds of megabytes to gigabytes (storage is negotiated with the browser, not capped at 5–10 MB)

IndexedDB vs Web Storage

Feature	localStorage / sessionStorage	IndexedDB
API style	Synchronous	Asynchronous (events / Promises)
Value types	Strings only	Structured objects, blobs, files
Storage quota	~5–10 MB	Hundreds of MB to GB
Querying	Key lookup only	Key + indexes on any property
Transactions	None	Full ACID transactions
Use from workers	sessionStorage: no; localStorage: limited	Yes — fully usable in Web Workers

The rule of thumb: use Web Storage for small, simple config/preferences. Reach for IndexedDB when you need to store structured records, large data, support offline, or query beyond a single key.

Structure of an IndexedDB database

Every IndexedDB database has a name and a version number. Inside a database you create one or more object stores — roughly analogous to tables. Each object store holds records, and each record is a JavaScript object identified by a key.

flowchart LR
  DB["Database
(name + version)"]
  OS1["Object Store
'users'"]
  OS2["Object Store
'posts'"]
  R1["Record
{id:1, name:'Ada'}"]
  R2["Record
{id:2, name:'Alan'}"]
  R3["Record
{id:1, title:'Hello'}"]
  DB --> OS1
  DB --> OS2
  OS1 --> R1
  OS1 --> R2
  OS2 --> R3

IndexedDB structure: database → object stores → records

When to use IndexedDB

Use IndexedDB when any of the following apply:

You need to store more than a few kilobytes of data per origin
Your data is structured (objects with multiple fields) and you want to query or sort it
You are building an offline-first or PWA experience and need to cache network responses or sync queues
You need to store binary data (images, audio, PDF blobs)
You want to share storage access from a Web Worker or Service Worker

Stick with localStorage for simple flags, theme preferences, or small serialised objects where synchronous access is convenient and the data fits comfortably in a few KB.

Module overview

This module walks through IndexedDB from scratch in five lessons:

Order	Lesson	What you will learn
1	What Is IndexedDB? (this lesson)	Concepts, structure, and when to use it
2	Opening a Database	`indexedDB.open`, versioning, `onupgradeneeded`
3	Object Stores and Keys	Creating stores, key paths, auto-increment
4	Transactions	Read-only vs read-write, error handling, aborting
5	CRUD Operations	`add`, `put`, `get`, `getAll`, `delete`, cursors

Runnable: verifying IndexedDB is available

The snippet below opens a database, confirms the name, then deletes it to leave no trace.

Browser Storage

const result = await new Promise((resolve, reject) => {
  const req = indexedDB.open('demo-check', 1);
  req.onsuccess = () => {
    resolve(req.result.name);
    req.result.close();
  };
  req.onerror = () => reject(req.error);
});
console.log('Opened DB:', result);
indexedDB.deleteDatabase('demo-check');
console.log('Cleanup done');