IndexedDB

A real database in the browser

IndexedDB is the browser’s built-in database for structured data. It is not a string-only shelf like localStorage. It stores JavaScript values with the structured clone algorithm, runs asynchronously with events, and can hold enough data for serious offline features in most browsers.

You use IndexedDB when an app needs to keep many records between visits: drafts, messages waiting to sync, product catalogs, map tiles, user-generated files, or an offline reading list. It also works in workers, so heavier storage work does not have to block the main page.

IndexedDB’s vocabulary sounds large, so this lesson builds one piece at a time: first the cabinet, then a teller-like transaction, then indexes and cursors, then version upgrades, and finally tiny promise helpers.

You start with indexedDB.open(name, version). It returns an IDBOpenDBRequest immediately. The browser later fires onupgradeneeded if the database needs schema work, then onsuccess when a connection is ready, or onerror/onblocked when it cannot proceed.

Object stores are where records live. You choose how keys are made: a keyPath reads a property from the stored object, an out-of-line key is passed separately to add(value, key), and autoIncrement can generate numeric keys. Keys can be numbers, strings, Dates, arrays, or binary values.

1const request = indexedDB.open("cf-demo-indexeddb", 1);Run2 3request.onupgradeneeded = (event) => {4  const db = request.result;5  db.createObjectStore("books", { keyPath: "id", autoIncrement: true });6};7 8request.onsuccess = () => {9  const db = request.result;10  const tx = db.transaction("books", "readwrite");11  const store = tx.objectStore("books");12  store.put({ title: "Eloquent JavaScript", author: "Marijn" });13  tx.oncomplete = () => db.close();14};

1const request = indexedDB.open("cf-demo-indexeddb", 2);2request.onupgradeneeded = () => {3  const store = db.createObjectStore("books", {4    keyPath: "id",5    autoIncrement: true,6  });7  store.createIndex("author", "author", { unique: false });8  store.createIndex("isbn", "isbn", { unique: true });9};10 11store.add(book);    // fail if key exists12store.put(book);    // insert or replace13store.get(1);14store.delete(1);15store.getAll();

Notice the difference between add and put. add means “create a new folder only.” If the key already exists, the request fails with ConstraintError. put means “insert or replace.” That makes put useful for saves and add useful when duplicates must be rejected.

A transaction is the unit of work. You open one with selected store names and a mode: readonly for reading, readwrite for changing data, and the special versionchange mode during upgrades. Every request belongs to a transaction.

1const tx = db.transaction("accounts", "readwrite");2const store = tx.objectStore("accounts");3const ada = await promisifyRequest(store.get("ada"));4 5await new Promise((resolve) => setTimeout(resolve, 0));6 7store.put({ ...ada, balance: ada.balance - 10 });8// TransactionInactiveError: the transaction had no pending IndexedDB requests.

The sneaky rule is lifetime. Transactions auto-commit when their request queue is empty and the browser gets control back. Awaiting an unrelated timer, network request, or any non-IndexedDB promise in the middle can let the transaction finish. The next store.put then throws TransactionInactiveError in browsers that enforce the rule.

The primary key finds a record by its label. Indexes add other lookup paths. In the playground, author is non-unique because one author can write many books, while isbn is unique because two books should not share the same ISBN.

IDBKeyRange.only(value) means exactly this key. IDBKeyRange.bound(low, high) means between two keys. IDBKeyRange.lowerBound(value) means this key and everything after it. For a batch, getAll(range, count) is compact. For one-at-a-time work, openCursor(range, direction) returns a cursor; call cursor.continue() to move.

1const tx = db.transaction("books", "readonly");2const byAuthor = tx.objectStore("books").index("author");3const range = IDBKeyRange.only("Ada Lovelace");4const matches = await promisifyRequest(byAuthor.getAll(range, 3));5 6const cursorRequest = byAuthor.openCursor(null, "prev");7cursorRequest.onsuccess = () => {8  const cursor = cursorRequest.result;9  if (!cursor) return;10  console.log(cursor.key, cursor.value.title);11  cursor.continue();12};

The second argument to indexedDB.open is a database version number. You can only create or delete object stores and indexes during the onupgradeneeded event, inside its versionchange transaction. That is where you remodel the cabinet.

1const first = indexedDB.open("cf-demo-indexeddb-versioning", 1);2first.onsuccess = () => {3  const db1 = first.result;4  db1.onversionchange = () => db1.close();5 6  const second = indexedDB.open("cf-demo-indexeddb-versioning", 2);7  second.onblocked = () => console.log("waiting for db1");8  second.onupgradeneeded = (event) => {9    console.log(event.oldVersion, second.result.version);10    second.transaction.objectStore("notes").createIndex("tag", "tag");11  };12};

Real apps usually listen for db.onversionchange and close the old connection, then ask the user to reload. They also handle openRequest.onblocked so the upgrade is not silently stuck.

IndexedDB is event-based. A request has onsuccess and onerror; a transaction has oncomplete, onabort, and onerror. Small wrappers let you use the Promisification and async & await lessons without hiding the transaction rules.

1function promisifyRequest(request) {2  return new Promise((resolve, reject) => {3    request.onsuccess = () => resolve(request.result);4    request.onerror = () => reject(request.error);5  });6}7 8function txDone(tx) {9  return new Promise((resolve, reject) => {10    tx.oncomplete = () => resolve();11    tx.onabort = () => reject(tx.error);12    tx.onerror = () => reject(tx.error);13  });14}15 16async function saveBook(db, book) {17  const tx = db.transaction("books", "readwrite");18  const id = await promisifyRequest(tx.objectStore("books").add(book));19  await txDone(tx);20  return id;21}

1function promisifyRequest(request) {2  return new Promise((resolve, reject) => {3    request.onsuccess = () => resolve(request.result);4    request.onerror = () => reject(request.error);5  });6}7 8function txDone(tx) {9  return new Promise((resolve, reject) => {10    tx.oncomplete = () => resolve();11    tx.onabort = () => reject(tx.error);12    tx.onerror = () => reject(tx.error);13  });14}15 16async function saveBook(db, book) {17  const tx = db.transaction("books", "readwrite");18  const id = await promisifyRequest(tx.objectStore("books").add(book));19  await txDone(tx);20  return id;21}

Libraries such as idb provide polished promise wrappers and convenience helpers. They are excellent in production. Learning the tiny version first helps you understand why awaiting IndexedDB requests is fine, while awaiting an unrelated timer inside a transaction is a trap.

Where you’ll use this

IndexedDB shines when the browser needs a local source of truth. An offline notes app might store drafts in a notes store, attach a updatedAt index for sync, and keep attachments as Blobs. A shop might cache a product catalog and queue checkout attempts while the network is unreliable.

1async function queueDraft(db, draft) {2  const tx = db.transaction(["drafts", "syncQueue"], "readwrite");3  const drafts = tx.objectStore("drafts");4  const queue = tx.objectStore("syncQueue");5 6  const key = await promisifyRequest(drafts.put(draft));7  await promisifyRequest(queue.add({ type: "draft", key, createdAt: new Date() }));8  await txDone(tx);9}

The important design choice is the transaction boundary: saving the draft and queueing the sync job belong together. If one fails, the app should not pretend the other happened.

Common misconceptions

• “IndexedDB is just localStorage with objects.” No. It is asynchronous, transactional, indexed, and structured-clone based.
• “Opening returns the database.” No. Opening returns a request; the connection appears later on request.result.
• “I can create stores whenever I want.” No. Schema changes belong in onupgradeneeded.
• “A transaction waits while I await anything.” No. Awaiting non-IDB work can let the transaction finish.
• “Indexes store duplicate data I must keep in sync.” No. The browser maintains indexes for a store.
• “Structured clone stores functions.” No. Functions and DOM nodes throw DataCloneError.

Key takeaways

• Open returns a request; schema setup happens in onupgradeneeded; success gives you a connection.
• Object stores hold records, keys identify records, and indexes provide additional lookup paths.
• Transactions are all-or-nothing and auto-commit when their request queue empties.
• Key ranges, cursors, and getAll let you query without loading everything blindly.
• Promise wrappers make code pleasant, but they do not change IndexedDB’s event-loop lifetime rules.

Final definition: IndexedDB is the browser’s transactional, indexed, structured-data database for apps that need more than string storage.

Up next: Cache API & file storage.