Chapter 49: IndexedDB Client-Side Database

CRUD Operations

Mastering data mutations: inserting with `add()`, querying with `get()` & `getAll()`, upserting with `put()`, removing with `delete()`, and managing `IDBRequest` events.

LEARNING OBJECTIVES ⌵

Differentiate between add() (strict insert) and put() (upsert/replace).
Query records accurately using get(), getAll(), count(), and getKey().
Remove records safely using delete() and purge collections with clear().
Understand the IDBRequest lifecycle, event bubbling hierarchy, and error propagation.

🎬 INTERACTIVE VISUAL PIPELINE Core Architecture Simulation

🌐

1. Input

Directives & Tags

⚙️

2. Parse

Tokenizer & AST

🌳

3. Layout

Box Model & Flow

🎨

4. Render

GPU Paint & Composite

PHASE 1: INPUT & DIRECTIVES

Browser receives declarative markup stream, parsing tag tokens and initializing component state.

📖 The Mental Model & Story (Intuitive Foundation)

Imagine a physical post office box system with numbered lockboxes.

add(record) (Strict New Lease): You attempt to place a package into Box #42. If Box #42 already contains a package, the clerk firmly stops you: "Halt! Box #42 is occupied!" (A ConstraintError is raised).
put(record) (Upsert / Overwrite): You tell the clerk: "Deliver this package to Box #42. If it's empty, put it in. If there's already something in there, replace it completely."
get(key) (Fetch): You ask the clerk to look inside Box #42. If it contains an item, you receive it. If it is empty, you are handed undefined (not an error—just an empty box).
delete(key) (Remove): You instruct the clerk to empty Box #42. If Box #42 was already empty, the operation still succeeds silently without error.
The IDBRequest Ticket: Every time you make a request at the counter, the clerk hands you a claim ticket (IDBRequest). You cannot peek at the contents immediately. When the clerk returns from the back room, your claim ticket lights up with onsuccess and you can read request.result.

Technical Deep Dive & Specifications

CRUD Methods on `IDBObjectStore`

+----------------------------------------------------------------------------------------------------+
|                                    IDBOBJECTSTORE CRUD API MATRIX                                  |
+-------------+-----------------------------+------------------------------------+-------------------+
| Method      | Signature                   | Behavior                           | Return Value      |
+-------------+-----------------------------+------------------------------------+-------------------+
| `add()`     | `add(value, [key])`         | Inserts record. Fails if key exists| Key of new record |
+-------------+-----------------------------+------------------------------------+-------------------+
| `put()`     | `put(value, [key])`         | Inserts or replaces existing record| Key of record     |
+-------------+-----------------------------+------------------------------------+-------------------+
| `get()`     | `get(key)`                  | Fetches record by primary key      | Object or undef   |
+-------------+-----------------------------+------------------------------------+-------------------+
| `getKey()`  | `getKey(query)`             | Fetches only the primary key       | Key value         |
+-------------+-----------------------------+------------------------------------+-------------------+
| `getAll()`  | `getAll([query], [count])`  | Fetches array of matching records  | Array of objects  |
+-------------+-----------------------------+------------------------------------+-------------------+
| `delete()`  | `delete(key)`               | Removes record by primary key      | `undefined`       |
+-------------+-----------------------------+------------------------------------+-------------------+
| `clear()`   | `clear()`                   | Deletes ALL records in the store   | `undefined`       |
+-------------+-----------------------------+------------------------------------+-------------------+
| `count()`   | `count([query])`            | Counts number of matching records  | Integer count     |
+-------------+-----------------------------+------------------------------------+-------------------+

The `IDBRequest` Event & Bubbling Lifecycle

Whenever a CRUD operation is invoked, it synchronously returns an IDBRequest object in the "pending" state. When the underlying disk I/O completes, the browser fires events that bubble up through three tiers:

                      +-----------------------------+
                      |   IDBRequest (Operation)    |
                      |   [onsuccess / onerror]     |
                      +-----------------------------+
                                     |
                                     v (Bubbles on error)
                      +-----------------------------+
                      |   IDBTransaction (Scope)    |
                      |   [oncomplete / onerror]    |
                      +-----------------------------+
                                     |
                                     v (Bubbles on error)
                      +-----------------------------+
                      |    IDBDatabase (Engine)     |
                      |   [onerror]                 |
                      +-----------------------------+

Crucial Rule: onsuccess events do not bubble. You must attach onsuccess directly to the IDBRequest. However, onerror events do bubble up to the parent IDBTransaction and IDBDatabase unless event.stopPropagation() or event.preventDefault() is called.

💻 Interactive Code Playground

Starter Code

Save this file as crud.html and open it in your browser.

Line-by-Line Code Breakdown

Line 72 (store.add(data)): Executes an insertion. If a record with id: "u101" already exists, this triggers request.onerror with a ConstraintError.
Line 87 (store.put(data)): Executes an upsert. If id: "u101" exists, it is cleanly overwritten with the new object; if it does not exist, it is inserted.
Lines 100–108 (store.get(id)): Fetches the record. Notice that a missing record is not an error; request.result is simply undefined.
Line 115 (store.getAll()): Fetches an array containing every record currently stored in the ObjectStore.
Line 129 (store.delete(id)): Deletes the specified key. Even if the key does not exist, delete() succeeds silently.
Line 139 (store.clear()): Truncates the entire ObjectStore, removing all records while preserving the store itself and its index definitions.

Expected Browser Render Output

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

HTML STARSHIP CODE TERMINAL playground.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>IndexedDB CRUD Lab</title>
  <style>
    body {
      font-family: system-ui, -apple-system, sans-serif;
      max-width: 850px;
      margin: 2rem auto;
      padding: 0 1rem;
      background: #0f172a;
      color: #f8fafc;
    }
    .form-group { display: flex; gap: 8px; margin-bottom: 1rem; flex-wrap: wrap; }
    input {
      padding: 0.6rem;
      border-radius: 6px;
      border: 1px solid #334155;
      background: #1e293b;
      color: #fff;
    }
    button {
      padding: 0.6rem 1rem;
      border-radius: 6px;
      border: none;
      background: #0284c7;
      color: white;
      font-weight: bold;
      cursor: pointer;
    }
    button:hover { background: #0369a1; }
    button.alt { background: #475569; }
    button.danger { background: #dc2626; }
    #outputLog {
      background: #000;
      color: #38bdf8;
      font-family: monospace;
      padding: 1rem;
      border-radius: 6px;
      min-height: 220px;
      white-space: pre-wrap;
    }
  </style>
</head>
<body>

<h1>IndexedDB CRUD Studio</h1>

<div class="form-group">
    <button id="addBtn">ADD (Strict)</button>
    <button id="putBtn">PUT (Upsert)</button>
    <button id="getBtn" class="alt">GET by ID</button>
    <button id="getAllBtn" class="alt">GET ALL</button>
    <button id="deleteBtn" class="danger">DELETE by ID</button>
    <button id="clearBtn" class="danger">CLEAR ALL</button>
  </div>

<div id="outputLog">Initializing DB...</div>

let db;
    const req = indexedDB.open('CrudStudioDB', 1);

req.onupgradeneeded = (e) => {
      const d = e.target.result;
      d.createObjectStore('users', { keyPath: 'id' });
      log('🛠️ Created ObjectStore: "users" with keyPath "id"');
    };

req.onsuccess = (e) => {
      db = e.target.result;
      log('✅ Database connected and ready.');
    };

function getFormValues() {
      return {
        id: document.getElementById('userId').value.trim(),
        name: document.getElementById('userName').value.trim(),
        role: document.getElementById('userRole').value.trim(),
        updatedAt: new Date().toISOString()
      };
    }

// 1. ADD (Strict insert)
    document.getElementById('addBtn').addEventListener('click', () => {
      const data = getFormValues();
      if (!data.id) return alert('Enter a User ID');

const tx = db.transaction('users', 'readwrite');
      const store = tx.objectStore('users');
      const request = store.add(data);

request.onsuccess = () => log(`➕ ADD Success: Inserted key "${request.result}"`);
      request.onerror = (e) => {
        log(`❌ ADD Failed: ${request.error.name} - ${request.error.message}`);
        e.preventDefault(); // Prevent transaction rollback
      };
    });

// 2. PUT (Upsert / Overwrite)
    document.getElementById('putBtn').addEventListener('click', () => {
      const data = getFormValues();
      if (!data.id) return alert('Enter a User ID');

const tx = db.transaction('users', 'readwrite');
      const store = tx.objectStore('users');
      const request = store.put(data);

request.onsuccess = () => log(`🔄 PUT Success: Upserted key "${request.result}"`);
      request.onerror = () => log(`❌ PUT Failed: ${request.error.message}`);
    });

// 3. GET
    document.getElementById('getBtn').addEventListener('click', () => {
      const id = document.getElementById('userId').value.trim();
      if (!id) return alert('Enter a User ID');

const tx = db.transaction('users', 'readonly');
      const store = tx.objectStore('users');
      const request = store.get(id);

request.onsuccess = () => {
        if (request.result) {
          log(`🔍 GET Result: ${JSON.stringify(request.result)}`);
        } else {
          log(`ℹ️ GET: No record found with key "${id}"`);
        }
      };
    });

// 4. GET ALL
    document.getElementById('getAllBtn').addEventListener('click', () => {
      const tx = db.transaction('users', 'readonly');
      const store = tx.objectStore('users');
      const request = store.getAll();

request.onsuccess = () => {
        log(`📚 GET ALL (${request.result.length} records):\n` +
          JSON.stringify(request.result, null, 2));
      };
    });

// 5. DELETE
    document.getElementById('deleteBtn').addEventListener('click', () => {
      const id = document.getElementById('userId').value.trim();
      if (!id) return alert('Enter a User ID');

const tx = db.transaction('users', 'readwrite');
      const store = tx.objectStore('users');
      const request = store.delete(id);

request.onsuccess = () => log(`🗑️ DELETE: Record "${id}" removed.`);
    });

// 6. CLEAR
    document.getElementById('clearBtn').addEventListener('click', () => {
      const tx = db.transaction('users', 'readwrite');
      const store = tx.objectStore('users');
      const request = store.clear();

request.onsuccess = () => log('💥 CLEAR: All records deleted from "users" store.');
    });
  </script>
</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

[02:45:00] 🛠️ Created ObjectStore: "users" with keyPath "id"
[02:45:00] ✅ Database connected and ready.
[02:45:05] ➕ ADD Success: Inserted key "u101"
[02:45:10] ❌ ADD Failed: ConstraintError - Key already exists in the object store.
[02:45:15] 🔄 PUT Success: Upserted key "u101"
[02:45:20] 🔍 GET Result: {"id":"u101","name":"Sarah Connor","role":"Admin","updatedAt":"2026-08-21T02:45:15.100Z"}

🏋️ Hands-On Exercise

🎯 The Challenge: Build a Resilient Shopping Cart Store

Instructions:

Open database ECommerceApp at Version 1 with store cart_items (keyPath: "sku").
Create an addToCart(item) function that checks if an item already exists:
- If it does not exist, insert it with quantity: 1.
- If it already exists, increment its quantity by 1 and update it using put().
Test by adding an item { sku: "AIR-JORDAN-1", name: "Nike Air Jordan 1", price: 180 } three times and verify the final quantity is 3.

🏁 Starter Code Sandbox

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

STARTER CODE SANDBOX exercise.html

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Shopping Cart Challenge</title>
  <style>
    body { font-family: sans-serif; margin: 2rem; background: #0f172a; color: #f8fafc; }
    pre { background: #000; color: #38bdf8; padding: 1rem; border-radius: 6px; }
    button { padding: 0.6rem 1.2rem; cursor: pointer; background: #38bdf8; border: none; border-radius: 4px; font-weight: bold; }
  </style>
</head>
<body>
  <h1>Shopping Cart Manager</h1>
  <button id="addMultipleBtn">Add Sneaker 3 Times</button>
  <pre id="output"></pre>

  <script>
    const output = document.getElementById('output');
    const log = (msg) => output.textContent += `${msg}\n`;

    const openReq = indexedDB.open('ECommerceApp', 1);
    openReq.onupgradeneeded = (e) => {
      e.target.result.createObjectStore('cart_items', { keyPath: 'sku' });
    };

    openReq.onsuccess = (e) => {
      const db = e.target.result;

      function addItemToCart(itemData, onDone) {
        const tx = db.transaction('cart_items', 'readwrite');
        const store = tx.objectStore('cart_items');
        const getReq = store.get(itemData.sku);

        getReq.onsuccess = () => {
          const existing = getReq.result;
          if (existing) {
            existing.quantity += 1;
            store.put(existing);
            log(`🛒 Incremented "${existing.name}" quantity to ${existing.quantity}`);
          } else {
            const newItem = { ...itemData, quantity: 1 };
            store.add(newItem);
            log(`🛒 Added new item "${newItem.name}" with quantity 1`);
          }
        };

        tx.oncomplete = () => {
          if (onDone) onDone();
        };
      }

      document.getElementById('addMultipleBtn').addEventListener('click', () => {
        output.textContent = '';
        const item = { sku: 'AIR-JORDAN-1', name: 'Nike Air Jordan 1', price: 180 };

        addItemToCart(item, () => {
          addItemToCart(item, () => {
            addItemToCart(item, () => {
              // Verify final state
              const tx = db.transaction('cart_items', 'readonly');
              const finalReq = tx.objectStore('cart_items').get('AIR-JORDAN-1');
              finalReq.onsuccess = () => {
                log(`\n🎉 Final Cart State: ${JSON.stringify(finalReq.result)}`);
              };
            });
          });
        });
      });
    };
  </script>
</body>
</html>

Why this works: Because both the get() inspection and the subsequent put() mutation take place within the same atomic readwrite transaction, data integrity is guaranteed. Chaining the operations ensures that each sequential update reads the committed state of the previous transaction.

⚠️ Common Pitfalls

Expecting get() on a Missing Key to Trigger onerror: If a key does not exist, store.get("missing_key") succeeds normally and sets request.result to undefined. Always test if (req.result !== undefined) in onsuccess.
Using add() when put() is Intended: Using add() in forms or synchronization routines will cause unexpected ConstraintError exceptions when records are re-submitted.
Uncontrolled getAll() Memory Spikes: Calling store.getAll() on an ObjectStore containing tens of thousands of large objects loads the entire dataset into JavaScript heap memory at once, potentially causing tab crashes. Use Cursors (Lesson 49.7) for large datasets.

💡 Pro Tips

Use count() for Existence Checks: If you only need to know whether a record exists or count matching items, call store.count(key). This checks the index B-tree without deserializing the underlying object payload into JavaScript memory.
Leverage getKey() to Avoid Payload Cloning: If you only need the primary key of a query match, store.getKey(query) avoids the Structured Clone overhead of the entire value object.

📌 Key Takeaways

add() is an insert-only operation that fails with ConstraintError if the primary key already exists.
put() is an upsert operation that inserts new records or overwrites existing ones.
get() returns the matching record or undefined (it does not fail if the key is missing).
delete() removes a record by primary key silently, even if the key is not present.
getAll() retrieves an array of all records; use with caution on large datasets.
onsuccess events do not bubble, while onerror events bubble to the parent IDBTransaction and IDBDatabase.
--

⭐ LEARN: HTML 🌟 ⚔️ QUIZ BATTLE ARENA // ACTIVE

? Question 1 / 3

What is the value of `request.result` when `store.get('non_existent_key')` finishes?

Topic: HTML Fundamentals

? Question 2 / 3

What happens if you execute `store.add(record)` with a primary key that already exists in the ObjectStore?

Topic: HTML Fundamentals

? Question 3 / 3

Which method should you call if you need to know how many records exist without loading their full object contents into memory?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

CRUD Methods on IDBObjectStore

The IDBRequest Event & Bubbling Lifecycle

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Expected Browser Render Output

🏋️ Hands-On Exercise

🎯 The Challenge: Build a Resilient Shopping Cart Store

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

What is the value of request.result when store.get('non_existent_key') finishes?

What happens if you execute store.add(record) with a primary key that already exists in the ObjectStore?

Which method should you call if you need to know how many records exist without loading their full object contents into memory?

CRUD Methods on `IDBObjectStore`

The `IDBRequest` Event & Bubbling Lifecycle

What is the value of `request.result` when `store.get('non_existent_key')` finishes?

What happens if you execute `store.add(record)` with a primary key that already exists in the ObjectStore?