Chapter 49: IndexedDB Client-Side Database

Transactions & ACID Lifecycle

Mastering transactional scopes, ACID guarantees, transaction rollbacks, and the critical microtask auto-commit lifecycle.

LEARNING OBJECTIVES ⌵

Understand the 3 transaction modes: readonly, readwrite, and versionchange.
Define multi-store transaction scopes for cross-collection atomic operations.
Master the auto-commit mechanics of the JavaScript event loop and avoid the TransactionInactiveError trap.
Handle explicit rollbacks via transaction.abort(), error events, and durability configuration hints.

🎬 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 high-stakes bank transfer between two bank accounts: transferring $500 from Alice to Bob.

You must perform two separate actions:

Deduct $500 from Alice's account.
Add $500 to Bob's account.

If the browser crashes or encounters an error immediately after Step 1, Alice loses $500 and Bob gets nothing. The bank's ledger is now corrupted.

A Transaction creates a protective, isolated bubble around these actions:

Atomicity (All or Nothing): Either both operations succeed, or if anything fails, the entire transaction rolls back cleanly as if nothing ever happened.
Consistency: Data integrity rules (unique keys, valid paths) are strictly validated before committing.
Isolation: Other tabs or concurrent scripts cannot view intermediate states (Alice with -$500 before Bob receives it).
Durability: Once the transaction completes (oncomplete), changes are securely flushed to persistent disk storage.

Technical Deep Dive & Specifications

The 3 Transaction Modes

+----------------------------------------------------------------------------------------------------+
|                                    INDEXEDDB TRANSACTION MODES                                     |
+-------------------+--------------------+-----------------------+-----------------------------------+
| Mode              | Permitted Actions  | Concurrency / Locks   | Invocation / Scope                |
+-------------------+--------------------+-----------------------+-----------------------------------+
| `readonly`        | `get`, `getAll`,   | Multiple `readonly`   | `db.transaction(stores,           |
|                   | `count`, `cursor`  | tx can run in parallel|   'readonly')`                    |
+-------------------+--------------------+-----------------------+-----------------------------------+
| `readwrite`       | `add`, `put`,      | Exclusive lock on the | `db.transaction(stores,           |
|                   | `delete`, `clear`, | specified ObjectStores|   'readwrite')`                   |
|                   | plus all reads     | (other tx must wait)  |                                   |
+-------------------+--------------------+-----------------------+-----------------------------------+
| `versionchange`   | Create/delete      | Exclusive global lock | Created automatically inside      |
|                   | stores & indexes   | across entire database| `request.onupgradeneeded`         |
+-------------------+--------------------+-----------------------+-----------------------------------+

Multi-Store Scopes

A transaction can span across multiple ObjectStores by passing an array of store names:

// Creates an atomic transaction locking both 'accounts' and 'audit_trail'
const tx = db.transaction(['accounts', 'audit_trail'], 'readwrite');
const accountStore = tx.objectStore('accounts');
const auditStore = tx.objectStore('audit_trail');

accountStore.put(aliceUpdated);
accountStore.put(bobUpdated);
auditStore.add({ action: 'TRANSFER', amount: 500, date: new Date() });

The Microtask Auto-Commit Lifecycle

One of the most common pitfalls for JavaScript engineers working with IndexedDB is the Transaction Auto-Commit Mechanism.

+-----------------------------------------------------------------------------+
|                          JAVASCRIPT EVENT LOOP TURN                         |
+-----------------------------------------------------------------------------+
|                                                                             |
|  1. Open Transaction: const tx = db.transaction('store', 'readwrite')       |
|  2. Queue Request 1:  store.put(recordA)                                    |
|  3. Queue Request 2:  store.put(recordB)                                    |
|                                                                             |
|  -- Synchronous JS Execution completes --                                   |
|  -- Microtask Queue Drains (Promises resolve) --                            |
|                                                                             |
|  [Is there an active IDBRequest pending on tx?]                             |
|       /                      \                                              |
|     YES                       NO                                            |
|      |                         |                                            |
|   Keep Tx Open           AUTO-COMMIT TRANSACTION!                           |
|   Wait for I/O           (tx.state becomes "finished")                      |
|                                                                             |
+-----------------------------------------------------------------------------+

The Golden Rule of IndexedDB Transactions:
An IndexedDB transaction remains active only as long as new IDBRequest calls are queued in continuous microtask turns. If you introduce an asynchronous gap that is not an IndexedDB request—such as await fetch(), setTimeout(), or await crypto.subtle.digest()—the event loop completes its turn with no pending IDB requests. The browser automatically commits and closes the transaction!

If you subsequently call store.put() after that fetch(), the browser throws:
TransactionInactiveError: Failed to execute 'put' on 'IDBObjectStore': The transaction has finished.

Transaction Durability Options

Modern IndexedDB specifications allow tuning write durability performance via the transaction options dictionary:

const tx = db.transaction('metrics', 'readwrite', {
  durability: 'relaxed' // Options: 'default' | 'strict' | 'relaxed'
});

'strict': The browser will not fire oncomplete until the OS has physically flushed changes to non-volatile disk media (slower, zero data loss risk on power failure).
'relaxed': The browser fires oncomplete once data is written to the operating system write-buffer (higher throughput, ideal for high-frequency logs).

💻 Interactive Code Playground

Starter Code

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

Line-by-Line Code Breakdown

Line 73 (const tx = db.transaction(['accounts', 'transfers'], 'readwrite')): Opens an atomic transaction spanning two ObjectStores simultaneously with exclusive locks.
Lines 77–90 (accStore.put(...), transferStore.add(...)): Executes writes across multiple collections. If any single operation fails or is aborted, none of the changes will persist.
Line 92 (tx.oncomplete): Fires when all pending requests have successfully written to disk and the transaction is committed.
Lines 102–106 (accStore.put(...), tx.abort()): Demonstrates tx.abort(). Even though accStore.put() was invoked, calling tx.abort() immediately rolls back Alice's balance to its pre-transaction value.
Lines 120–127 (await new Promise(...)): Demonstrates the classic TransactionInactiveError. When the JavaScript event loop yields to setTimeout, the microtask queue empties, causing IndexedDB to auto-commit the transaction.

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 Transactions & Rollback 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;
    }
    .grid { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; margin-bottom: 1rem; }
    .card { background: #1e293b; padding: 1rem; border-radius: 8px; border: 1px solid #334155; }
    button {
      padding: 0.6rem 1.2rem;
      border: none;
      border-radius: 6px;
      font-weight: bold;
      cursor: pointer;
      color: white;
      width: 100%;
      margin-top: 0.5rem;
    }
    .btn-green { background: #10b981; }
    .btn-red { background: #ef4444; }
    .btn-orange { background: #f59e0b; }
    #logOutput {
      background: #000;
      color: #38bdf8;
      font-family: monospace;
      padding: 1rem;
      border-radius: 6px;
      min-height: 200px;
      white-space: pre-wrap;
    }
  </style>
</head>
<body>

<h1>Transaction Atomicity & Rollbacks</h1>

<div class="grid">
    <div class="card">
      <h3>1. Atomic Bank Transfer</h3>
      <p>Transfers $200 from Alice to Bob (Multi-store transaction).</p>
      <button id="transferBtn" class="btn-green">Execute Atomic Transfer</button>
    </div>

<div class="card">
      <h3>2. Explicit Rollback (Abort)</h3>
      <p>Simulates a failed audit check and calls <code>tx.abort()</code>.</p>
      <button id="abortBtn" class="btn-red">Trigger Transaction Abort</button>
    </div>

<div class="card">
      <h3>3. The Fetch Auto-Commit Trap</h3>
      <p>Demonstrates what happens when you <code>await fetch()</code> inside a transaction.</p>
      <button id="trapBtn" class="btn-orange">Trigger Auto-Commit Bug</button>
    </div>

<div class="card">
      <h3>4. Inspect Accounts</h3>
      <p>Displays the current balances of Alice and Bob.</p>
      <button id="inspectBtn" style="background:#6366f1;">Read Balances</button>
    </div>
  </div>

<div id="logOutput">Connecting to BankDB...</div>

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

req.onupgradeneeded = (e) => {
      const d = e.target.result;
      const accStore = d.createObjectStore('accounts', { keyPath: 'id' });
      d.createObjectStore('transfers', { autoIncrement: true });

// Seed initial accounts
      accStore.add({ id: 'alice', name: 'Alice', balance: 1000 });
      accStore.add({ id: 'bob', name: 'Bob', balance: 500 });
      log('🛠️ Created BankDB with initial balances (Alice: $1000, Bob: $500)');
    };

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

// 1. Atomic Transfer
    document.getElementById('transferBtn').addEventListener('click', () => {
      log('💸 Starting atomic transfer: $200 from Alice to Bob...');
      const tx = db.transaction(['accounts', 'transfers'], 'readwrite');
      const accStore = tx.objectStore('accounts');
      const transferStore = tx.objectStore('transfers');

const reqAlice = accStore.get('alice');
      reqAlice.onsuccess = () => {
        const alice = reqAlice.result;
        alice.balance -= 200;
        accStore.put(alice);

const reqBob = accStore.get('bob');
        reqBob.onsuccess = () => {
          const bob = reqBob.result;
          bob.balance += 200;
          accStore.put(bob);

transferStore.add({ from: 'alice', to: 'bob', amount: 200, timestamp: Date.now() });
        };
      };

tx.oncomplete = () => log('🎉 Transaction Committed! Both balances & audit log updated atomically.');
      tx.onerror = (err) => log(`❌ Transaction Failed: ${tx.error.message}`);
    });

// 2. Explicit Abort & Rollback
    document.getElementById('abortBtn').addEventListener('click', () => {
      log('💥 Executing transaction with deliberate tx.abort()...');
      const tx = db.transaction('accounts', 'readwrite');
      const accStore = tx.objectStore('accounts');

accStore.put({ id: 'alice', name: 'Alice', balance: 0 }); // Dangerously set Alice to 0

log('🚨 Security flag triggered! Calling tx.abort()...');
      tx.abort(); // Immediately cancels all mutations in this transaction

tx.onabort = () => {
        log('🛡️ Transaction onabort fired: All mutations rolled back safely.');
      };
    });

// 3. The Auto-Commit Trap
    document.getElementById('trapBtn').addEventListener('click', async () => {
      log('⚠️ Testing async gap inside transaction...');
      const tx = db.transaction('accounts', 'readwrite');
      const store = tx.objectStore('accounts');

log('   Step 1: Reading Alice record...');
      const reqA = store.get('alice');
      
      reqA.onsuccess = async () => {
        log('   Step 2: Simulating external network fetch (async gap)...');
        await new Promise(resolve => setTimeout(resolve, 50)); // Simulates network delay

try {
          log('   Step 3: Attempting store.put() after async gap...');
          store.put({ id: 'alice', name: 'Alice', balance: 9999 });
        } catch (err) {
          log(`❌ CAUGHT BUG: ${err.name} - ${err.message}`);
          log('💡 Explanation: Transaction auto-committed during setTimeout async gap!');
        }
      };
    });

// 4. Inspect Balances
    document.getElementById('inspectBtn').addEventListener('click', () => {
      const tx = db.transaction('accounts', 'readonly');
      const store = tx.objectStore('accounts');
      const reqA = store.get('alice');
      const reqB = store.get('bob');

tx.oncomplete = () => {
        log(`📊 Current Balances -> Alice: $${reqA.result.balance} | Bob: $${reqB.result.balance}`);
      };
    });
  </script>
</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

[02:50:00] 🛠️ Created BankDB with initial balances (Alice: $1000, Bob: $500)
[02:50:00] ✅ BankDB ready.
[02:50:05] 💸 Starting atomic transfer: $200 from Alice to Bob...
[02:50:05] 🎉 Transaction Committed! Both balances & audit log updated atomically.
[02:50:10] 📊 Current Balances -> Alice: $800 | Bob: $700
[02:50:15] ⚠️ Testing async gap inside transaction...
[02:50:15]    Step 1: Reading Alice record...
[02:50:15]    Step 2: Simulating external network fetch (async gap)...
[02:50:15] ❌ CAUGHT BUG: TransactionInactiveError - The transaction has finished.
[02:50:15] 💡 Explanation: Transaction auto-committed during setTimeout async gap!

🏋️ Hands-On Exercise

🎯 The Challenge: Atomic Inventory Checkout

Instructions:

Open database InventoryDB with stores stock (keyPath: "sku") and receipts (autoIncrement: true).
Seed stock with: { sku: "LAPTOP-01", name: "MacBook Pro", qty: 2 }.
Implement an orderItem(sku, requestedQty) function:
- Start a readwrite transaction locking ['stock', 'receipts'].
- Read the SKU stock.
- If stock.qty >= requestedQty, subtract the quantity, save the updated stock, write a receipt, and commit.
- If stock.qty < requestedQty, call tx.abort() with a log: "Out of stock! Transaction aborted."
Test ordering 3 laptops (which exceeds the 2 in stock) and verify that stock remains untouched at 2.

🏁 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>Inventory Checkout 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; margin-right: 0.5rem; cursor: pointer; background: #38bdf8; border: none; border-radius: 4px; font-weight: bold; }
  </style>
</head>
<body>
  <h1>Inventory Checkout</h1>
  <button id="buyValid">Order 1 Laptop (Valid)</button>
  <button id="buyExcess">Order 5 Laptops (Exceeds Stock)</button>
  <pre id="output"></pre>

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

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

    req.onupgradeneeded = (e) => {
      const d = e.target.result;
      const stock = d.createObjectStore('stock', { keyPath: 'sku' });
      d.createObjectStore('receipts', { autoIncrement: true });
      stock.add({ sku: 'LAPTOP-01', name: 'MacBook Pro', qty: 2 });
      log('🛠️ Initialized stock: 2 MacBook Pros.');
    };

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

    function processOrder(sku, quantity) {
      log(`\n🛒 Attempting to order ${quantity}x ${sku}...`);
      const tx = db.transaction(['stock', 'receipts'], 'readwrite');
      const stockStore = tx.objectStore('stock');
      const receiptStore = tx.objectStore('receipts');

      const getReq = stockStore.get(sku);

      getReq.onsuccess = () => {
        const item = getReq.result;
        if (!item) {
          log(`❌ Item ${sku} not found! Aborting...`);
          tx.abort();
          return;
        }

        if (item.qty < quantity) {
          log(`🚨 Insufficient stock! Requested: ${quantity}, Available: ${item.qty}. Aborting transaction...`);
          tx.abort(); // Rollback!
          return;
        }

        item.qty -= quantity;
        stockStore.put(item);
        receiptStore.add({ sku, quantity, timestamp: Date.now() });
      };

      tx.oncomplete = () => log(`🎉 Order SUCCESS! Deducted ${quantity} items.`);
      tx.onabort = () => log(`🛡️ Order ROLLED BACK. Stock remains untouched.`);
    }

    document.getElementById('buyValid').addEventListener('click', () => processOrder('LAPTOP-01', 1));
    document.getElementById('buyExcess').addEventListener('click', () => processOrder('LAPTOP-01', 5));
  </script>
</body>
</html>

Why this works: If the requested stock exceeds the available count, tx.abort() is called immediately. IndexedDB guarantees that neither the stockStore.put() nor any receipt records are persisted to disk. The onabort event gives the user immediate visual confirmation that the operation rolled back safely.

⚠️ Common Pitfalls

Placing fetch(), crypto, or setTimeout inside transactions: Any asynchronous operation that does not return an IDBRequest causes the transaction to auto-commit before the asynchronous work completes, resulting in TransactionInactiveError. Fetch all external network data before opening the transaction.
Over-scoping readwrite transactions: Opening a readwrite transaction across your entire database blocks all other read/write operations from executing concurrently. Only lock the specific ObjectStores you intend to modify.
Relying on Default Durability for Mission-Critical Logs: In high-reliability applications, specify { durability: 'strict' } to guarantee that data survives unexpected client hardware power outages.

💡 Pro Tips

Prefer readonly Transactions for Concurrency: Multiple readonly transactions on the same ObjectStore execute concurrently without waiting for locks. Never use readwrite when merely reading records.
Batch Multiple Mutations in a Single Transaction: Creating a new transaction for each individual store.put() in a loop of 1,000 items creates massive disk-sync overhead. Always wrap batch operations in a single readwrite transaction.

📌 Key Takeaways

Transactions provide full ACID guarantees (Atomicity, Consistency, Isolation, Durability) for client-side storage.
The three transaction modes are readonly (concurrent reads), readwrite (exclusive lock writes), and versionchange (schema upgrades).
Transactions can span multiple ObjectStores simultaneously (db.transaction(['a', 'b'], 'readwrite')).
An active transaction auto-commits as soon as the JavaScript microtask loop runs out of pending IDBRequest operations.
Calling tx.abort() cancels all pending operations and immediately restores data to its pre-transaction state.
--

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

? Question 1 / 3

Why does calling `await fetch('/api/user')` inside an active IndexedDB transaction cause a `TransactionInactiveError` on the next store operation?

Topic: HTML Fundamentals

? Question 2 / 3

What is the concurrency behavior of two separate `readonly` transactions targeting the same ObjectStore?

Topic: HTML Fundamentals

? Question 3 / 3

What happens to records modified in an ObjectStore during a transaction if `tx.abort()` is called before `tx.oncomplete` fires?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

The 3 Transaction Modes

Multi-Store Scopes

The Microtask Auto-Commit Lifecycle

Transaction Durability Options

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Expected Browser Render Output

🏋️ Hands-On Exercise

🎯 The Challenge: Atomic Inventory Checkout

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

Why does calling await fetch('/api/user') inside an active IndexedDB transaction cause a TransactionInactiveError on the next store operation?

What is the concurrency behavior of two separate readonly transactions targeting the same ObjectStore?

What happens to records modified in an ObjectStore during a transaction if tx.abort() is called before tx.oncomplete fires?

Why does calling `await fetch('/api/user')` inside an active IndexedDB transaction cause a `TransactionInactiveError` on the next store operation?

What is the concurrency behavior of two separate `readonly` transactions targeting the same ObjectStore?

What happens to records modified in an ObjectStore during a transaction if `tx.abort()` is called before `tx.oncomplete` fires?