Master IndexedDB: A Complete Guide to Browser Storage, Transactions, and Indexes

Introduction to IndexedDB

IndexedDB is a browser API for storing large amounts of data, supporting queries and offline usage.

Key Features

Replaces WebSQL.

Follows same‑origin policy.

Provides both asynchronous and (theoretically) synchronous APIs; synchronous API requires WebWorkers and is not widely supported.

Transactional key‑value database.

Does not use SQL; queries are performed via indexes and cursors.

Basic Usage Pattern

Open a database and start a transaction.

Create an object store.

Create a request to perform operations such as add or retrieve data.

Listen for appropriate DOM events to know when the operation completes.

Creating and Opening a Database

IndexedDB is available on the global window object. The primary method is indexedDB.open(dbName, version), where dbName is a string and version is an integer.

If the database does not exist, it is created and the upgradeneeded and success events fire. If it already exists, only success (or error) fires.

Object Stores and Indexes

A database can contain multiple object stores, each with its own primary key and optional indexes, similar to tables in a relational database.

Object stores are usually created inside the upgradeneeded callback using db.createObjectStore(name, {keyPath: 'id'}). Indexes are created with

objectStore.createIndex(indexName, keyPath, {unique: true|false})

.

Adding and Deleting Data

All data modifications must occur within a transaction. Transaction modes are readonly, readwrite, and versionchange.

To add data, use objectStore.add(record). If a record with the same primary key exists, add fails; put will overwrite or insert.

Delete data with objectStore.delete(key).

Retrieving Data

Use objectStore.get(key) to fetch a single record. For multiple records, use a cursor.

Using Cursors

Cursors iterate over records. Create them with objectStore.openCursor([keyRange], [direction]) or index.openCursor(). The result is an IDBCursorWithValue object; call continue() to move to the next record.

Key ranges ( IDBKeyRange) limit the cursor’s traversal, and the direction can be next, prev, nextunique, or prevunique.

Closing and Deleting a Database

Close a connection with db.close(). The db object remains but cannot start new transactions.

Delete a database with indexedDB.deleteDatabase(dbName).

Limitations

Not suitable for multilingual mixed storage without custom handling.

Synchronization with server‑side databases must be implemented manually.

No built‑in full‑text search.

Data may be cleared when the user clears site data, uses private browsing, exceeds storage quota, or the database becomes corrupted.

Summary

Open a database with indexedDB.open.

Delete a database with indexedDB.deleteDatabase.

Create object stores via db.createObjectStore.

Create indexes with objectStore.createIndex.

Perform all operations inside a transaction.

Use add, get, delete, put on object stores.

Query via indexes and cursors.