IndexedDB

A real database in the browser

IndexedDB is a database that is built into the browser. A database is a place where a program keeps a lot of data in order, so it can find that data again later. IndexedDB keeps its data on the user's device. The data is still there after the page closes.

You may know localStorage. It can only store strings. IndexedDB can store real JavaScript values, such as objects, arrays, and dates.

IndexedDB is asynchronous. That means you ask for something, your code keeps running, and the answer arrives later as an event. So a big read or write does not freeze the page.

Apps use IndexedDB to keep many records between visits. For example:

• drafts the user hasn't sent yet,
• messages waiting to be sent when the network comes back,
• a product list to show while offline,
• files the user made, such as photos.

IndexedDB also works in web workers. A web worker is a script that runs in the background, away from the page, so heavy storage work doesn't slow the page down.

This lesson builds IndexedDB one part at a time:

1. open a database and make an object store,
2. group reads and writes in a transaction,
3. find records with an index,
4. change the database's layout with a new version,
5. write two small helpers so you can use await.

You start with indexedDB.open(name, version). The name picks the database. The version is a whole number that says which layout of the database you want.

open does not give you the database. It gives you a request right away: an object of type IDBOpenDBRequest that tells you later what happened. To hear about it, you put a function in the request's matching property, such as request.onsuccess. The browser then fires these events on the request:

• upgradeneeded runs first, if the database is new or older than the version you asked for. This is where you create object stores.
• success runs when the database is ready. Now request.result is the open database.
• error runs if opening fails. blocked runs if another open tab is in the way.

An object store holds records. Every record has a key: a value that names it, like a number on a locker. You choose how keys are made when you create the store:

• keyPath: "id" means "read the key from each record's id property".
• With no keyPath, you pass the key yourself, as a second argument: add(value, key). This is called an out-of-line key.
• autoIncrement: true makes the store count up for you: 1, 2, 3, and so on.

A key can be a number, a string, a Date, an array, or binary data (raw bytes).

Step through the code below. Choose a first visit or a return visit, then press Step and watch which handlers run.

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};

const request = indexedDB.open("notes-app", 1);
request.onupgradeneeded = () => {
  const db = request.result;
  const notes = db.createObjectStore("notes", { keyPath: "id", autoIncrement: true });
  notes.createIndex("updatedAt", "updatedAt");
};
request.onsuccess = () => console.log("notes store is ready");
request.onerror = () => console.error(request.error.name);

This is a second small database, for a notes app. Line 1 opens version 1 of a database called notes-app. Lines 2 to 6 are the upgrade handler. It is the only place where you can create object stores and indexes.

Line 4 creates the notes store. Its keyPath reads each note's id, and autoIncrement makes an id when a new note has none. Line 5 adds an index on updatedAt, so the app can also find and sort notes by the time they changed. Line 7 prints a message when the database is ready. Line 8 prints the error's name if opening failed.

In the playground below, press Add book first. Then press Duplicate add, and then Put id 1.

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();

The last two buttons show two ways to save a record:

• add saves a new record only. If a record with that key already exists, the request fails with a ConstraintError.
• put saves the record either way. If the key is new, it adds the record. If the key exists, it replaces the old record.

So use put to save changes. Use add when a second record with the same key would be a mistake.

const note = {
  title: "Tea",
  savedAt: new Date(),
  labels: new Map([["kind", "draft"]]),
};
store.put(note);
store.put({ title: "Not data", save: () => "later" });
// The second request fails with DataCloneError.

Lines 1 to 5 make a note with a string, a Date, and a Map. Line 6 saves it, because all three can be copied. Line 7 tries to save an object that holds a function. A function is code, not data, so that request fails with DataCloneError.

const request = store.add({ id: 1, title: "Draft" });
request.onsuccess = () => console.log("saved");
request.onerror = (event) => {
  event.preventDefault();
  console.log(request.error.name);
};

Each request reports its own error. Line 1 tries to add a record with id: 1. If that key is already taken, the error event fires instead of success.

By default, a failed request cancels its whole transaction: the group of work it belongs to. (The next section explains transactions.) Line 4 calls event.preventDefault() to stop that, so the rest of the work can still be saved. Line 5 prints the error's name, such as ConstraintError. Handling the error means the user isn't left with a save that failed without a word.

A transaction is a group of reads and writes that succeed or fail together. Every request belongs to one. To start a transaction, you name the object stores it may use and pick a mode:

• readonly can only read.
• readwrite can read and change data.
• versionchange is a special mode the browser uses during an upgrade. You don't start it yourself.

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.

A transaction finishes by itself, and saves its work for good, as soon as both of these are true:

• it has no requests still waiting, and
• your code has handed control back to the browser, for example at an await.

So if you await something that is not an IndexedDB request, such as a timer or a fetch, the transaction can finish while you wait. In the lab's code, line 5 waits for a timer. By line 7 the transaction has already finished, so store.put throws a TransactionInactiveError. Press Try inactive trap to see it.

The table lists what a transaction can tell you. Read each row as: when this happens, what it means, and what to do.

The key is the main way to find a record. An index gives you another way: it sorts the same records by one of their properties. The browser keeps each index up to date when records change. In the playground below, the books store has two indexes:

• author is not unique, because one author can write many books.
• isbn is unique, because no two books share an ISBN. Saving a second book with the same ISBN fails.

To ask for only some keys, you pass a key range: an IDBKeyRange object that says which keys you want.

• IDBKeyRange.only(value) means exactly this key.
• IDBKeyRange.bound(low, high) means every key from low to high.
• IDBKeyRange.lowerBound(value) means this key and every key after it.

Then you choose how to read the matching records:

• getAll(range, count) gives them all at once, as an array, but no more than count of them.
• openCursor(range, direction) gives a cursor, which points at one record at a time. Call cursor.continue() to move to the next record.

const tx = db.transaction("notes", "readonly");
const notes = tx.objectStore("notes");
const recent = notes.index("updatedAt");
const range = IDBKeyRange.lowerBound(new Date("2026-01-01"));
const request = recent.getAll(range, 10);
request.onsuccess = () => console.log(request.result.length);

Line 1 starts a readonly transaction. Line 3 picks the updatedAt index, which sorts the notes by the time they changed. Line 4 makes a range: every date from 1 January 2026 on. Line 5 asks for no more than 10 matching notes, so the result can't grow too big. Line 6 prints how many came back.

Use a cursor instead when you want to handle one note at a time, stop early, or work through a very long list.

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 the version number. To change the layout of a database, such as adding an object store or an index, you open it with a higher version. The browser then fires upgradeneeded.

Only inside that handler can you create or delete object stores and indexes. The handler runs inside a special transaction with the mode versionchange. Each open copy of the database, usually one per tab, is called a connection.

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};

In the playground's code, line 6 opens version 2 while the first connection is still open. Line 7 logs a message if that upgrade is blocked. Line 4 is how the first connection steps aside: when it gets versionchange, it closes. Then lines 8 to 10 run the upgrade and add the tag index.

Real apps handle both sides:

• The old tab listens for versionchange on its database, with db.onversionchange. It closes its connection and asks the user to reload the page.
• The new tab listens for blocked on its open request, with openRequest.onblocked. Then it can tell the user to close other tabs, instead of waiting without a word.

IndexedDB tells you about results with events, not promises. A request fires success or error. A transaction fires complete, abort, or error.

Two small helper functions can turn these events into promises. Then you can use await, as in the Promisification and async & await lessons. The transaction rules stay the same.

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}

• Lines 1 to 6: promisifyRequest returns a promise. It resolves with request.result when the request succeeds, and rejects with request.error when it fails.
• Lines 8 to 14: txDone returns a promise that resolves when the transaction completes. It rejects when the transaction aborts or fails.
• Lines 16 to 21: saveBook uses both. It waits for the add request to get the new key. Then it waits for the transaction to finish, so it reports success only after the book is really saved.

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 give you ready-made helpers like these, with more features. They are a good choice for real apps. Writing the small version yourself shows why you may await an IndexedDB request inside a transaction, but not a timer. The request keeps the transaction busy. The timer doesn't.

Where you’ll use this

IndexedDB is useful when the browser has to keep the app's data itself, for example while offline. Two examples:

• An offline notes app keeps drafts in a notes store. An updatedAt index finds what changed since the last sync, and attached files are saved as Blobs.
• A shop saves its product list, and keeps a list of orders to send when the network works again.

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}

Line 2 starts one readwrite transaction over two stores, drafts and syncQueue. Line 6 saves the draft and gets its key. Line 7 adds a job to the queue that says "send this draft to the server later". Line 8 waits until both are saved.

Both writes are in the same transaction on purpose. If one fails, neither is saved. So the app never has a queue job for a missing draft, or a draft that will never be sent.

const estimate = await navigator.storage.estimate();
console.log(estimate.usage, estimate.quota);
const alreadyPersistent = await navigator.storage.persisted();
const granted = alreadyPersistent || await navigator.storage.persist();
console.log(granted ? "less likely to be evicted" : "still best effort");

When a device runs low on space, the browser may delete a site's data by itself. This is called eviction. The code above checks for that risk:

• Lines 1 and 2 print how much space the site uses and how much it may use, its quota. Both numbers are rough guesses, not a promise of free space.
• Lines 3 and 4 check whether the site's data is already protected from eviction. If not, persist() asks for it. The browser may say no.
• Line 5 prints the answer. "Still best effort" means the browser keeps the data only while it has room.

Even then, data can disappear. Users can clear site data, and a private window may delete everything when it closes. So an offline app must be able to download its data from the server again.

Common misconceptions

• “IndexedDB is just localStorage with objects.” No. IndexedDB is asynchronous, groups work into transactions, finds records with indexes, and copies values with structured clone. localStorage does none of these.
• “Opening returns the database.” No. open returns a request. The database arrives later, in request.result.
• “I can create stores whenever I want.” No. You can create and delete stores and indexes only in onupgradeneeded.
• “A transaction waits while I await anything.” No. If you await something that is not an IndexedDB request, the transaction can finish while you wait.
• “Indexes store duplicate data I must keep in sync.” No. The browser updates every index of a store for you when its records change.
• “Structured clone stores functions.” No. Functions and DOM nodes throw DataCloneError.

The table compares IndexedDB with localStorage and sessionStorage. Each row answers one question about both.

Key takeaways

• open returns a request. You create stores in onupgradeneeded, and success gives you the database.
• Object stores hold records. A key names each record, and an index is a second way to find them.
• A transaction saves all of its changes or none. It finishes by itself when no requests are waiting.
• Key ranges, cursors, and getAll let you read only the records you need.
• Promise helpers make the code easier to read, but they don't change when a transaction finishes.

Final definition: IndexedDB is a database in the browser that saves copies of JavaScript values, finds them by key or index, and groups changes into transactions.

Up next: Cache API & file storage.