IndexedDB Cursors: Iterate Large Datasets Efficiently

Why it exists

Loading a large dataset from IndexedDB with getAll() can be slow and consume significant memory, potentially freezing the browser's main thread. This makes it impractical for collections with thousands or millions of records. Cursors were created to provide a memory-efficient, non-blocking way to process records individually.

The mental model

An IndexedDB cursor is like a database pointer that you can move through the records of an object store or index. It doesn't load the whole collection at once. Instead, you open a cursor, get a reference to the first record, process it, and then explicitly tell the cursor to advance to the next one. This one-by-one processing is the key to its efficiency and performance.

How it works

You call openCursor() on an IDBObjectStore or IDBIndex, which returns an IDBRequest object. You then attach an onsuccess event handler to this request. When a record is found, the handler fires, and its event.target.result contains the cursor object. If the cursor is not null, you can access the data via cursor.value. To proceed to the next record, you must call cursor.continue(). When no more records are available, the event.target.result will be null, signaling the end of the iteration.

When to use it

Use cursors when dealing with datasets too large to fit comfortably in memory. This is ideal for tasks like searching for a specific record in a massive store, performing a bulk update on a subset of records, or displaying paginated data without fetching everything upfront. It's the standard, performant way to handle non-trivial amounts of data in IndexedDB.

When not to use it

If you know you're only dealing with a small, predictable number of records, using get() for a single record or getAll() for a small collection can be simpler and require less boilerplate code. Cursors add asynchronous complexity that is unnecessary for small-scale operations where memory usage is not a concern.

One canonical example

To iterate all records in a 'notes' object store, you first open a read-only transaction. Then, get the object store and call openCursor(). In the onsuccess handler for the resulting request, you check if event.target.result (the cursor) exists. If it does, you can process its data with cursor.value. Crucially, you must then call cursor.continue() to trigger the onsuccess handler for the next record. If the cursor is null, you know you have processed all records.