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.