IndexedDB should be used when it is necessary to store a large amount of structured data, support offline functions, conduct efficient queries or process binary files, including: 1. Store a large amount of structured data (such as documents, cached API responses); 2. Implement PWA or offline functions; 3. Efficiently query data through indexes (such as search by date, classification); 4. Process binary data such as pictures and audio (using Blobs). When only a small number of simple key-value pairs (such as user preferences, tokens), no complex queries or transactions, and the simplicity of implementation is pursued, localStorage or sessionStorage should be continued. IndexedDB is the most powerful client storage solution in the browser, suitable for complex applications, while localStorage is suitable for lightweight scenarios. The two are positioned differently and the choice should be based on actual needs. The final conclusion is: When strong storage capabilities are required, IndexedDB is irreplaceable, otherwise simple solutions will be preferred.

When building modern web applications, handling data efficiently on the client side is cruel — especially for offline functionality, performance, and smoother user experiences. While localStorage is simple and widely used, it falls short when dealing with large or structured data. That's where IndexedDB comes in.

IndexedDB is a low-level, asynchronous API for storing significant amounts of structured data in the browser, including files and blobs. It supports full-text search and complex queries via indexes. If you're building a PWA, offline-capable app, or just need robust client-side persistence, IndexedDB is the right tool — once you get past its step learning curve.

Here's a practical guide to help you use IndexedDB effectively.

? When to Use IndexedDB (and When Not To)

Use IndexedDB when:

• You need to store large amounts of structured data (eg, user documents, cached API responses, media metadata).
• You want offline support (eg, in PWAs).
• You need to query data efficiently using indexes (eg, search by date, category, etc.).
• Your app handles binary data like images or audio (via Blobs).

Stick with localStorage or sessionStorage when:

• You're storing small, simple key-value pairs (eg, user preferences, tokens).
• You don't need querying or transactions.
• Simplicity and quick implementation matter more than scalability.

? Think of localStorage as a notepad. IndexedDB is a full-fledged database.

? Core Concepts of IndexedDB

Before writing code, understand these key concepts:

• Database : A container for data (one per app or feature).
• Object Store : Like a table in SQL — holds records (objects).
• Key : A unique identifier for each record (can be auto-incremented).
• Transaction : All operations happen within a transaction (ensures consistency).
• Index : Allows querying object stores by properties other than the key.
• Cursor : Used to iterate over records efficiently.

IndexedDB is asynchronous and event-driven (though modern wrappers use Promises). You can't just “get” data synchronously — you request it and respond to success or error events.

?? Basic Setup and Usage (With Promises)

IndexedDB's native API uses callbacks, but wrapping it in Promises makes it much easier to work with. Here's a clean, minimal example:

 // Open or create a database
function openDB() {
  return new Promise((resolve, reject) => {
    const request = indexedDB.open('MyAppDB', 1);

    // Handle database upgrade (first time or version change)
    request.onupgradeneeded = (event) => {
      const db = event.target.result;

      // Create an object store for "products"
      if (!db.objectStoreNames.contains('products')) {
        const store = db.createObjectStore('products', { keyPath: 'id', autoIncrement: true });

        // Create an index to search by category
        store.createIndex('category', 'category', { unique: false });
      }
    };

    request.onsuccess = () => resolve(request.result);
    request.onerror = () => reject(request.error);
  });
}

Now, let's add, read, and query data.

Add Data

 async function addProduct(product) {
  const db = await openDB();
  const tx = db.transaction('products', 'readwrite');
  const store = tx.objectStore('products');

  store.add(product);
  return tx.done;
}

Get All Products

 async function getAllProducts() {
  const db = await openDB();
  const tx = db.transaction('products', 'readonly');
  const store = tx.objectStore('products');

  return new Promise((resolve, reject) => {
    const request = store.getAll();
    request.onsuccess = () => resolve(request.result);
    request.onerror = () => reject(request.error);
  });
}

Query by Index (eg, by Category)

 async function getProductsByCategory(category) {
  const db = await openDB();
  const tx = db.transaction('products', 'readonly');
  const store = tx.objectStore('products');
  const index = store.index('category');

  return new Promise((resolve, reject) => {
    const request = index.getAll(category);
    request.onsuccess = () => resolve(request.result);
    request.onerror = () => reject(request.error);
  });
}

? Remember: Every read/write happens in a transaction, and you must wait for it to complete ( tx.done ) if you want to catch errors properly.

? Tips for Real-World Use

1. Wrap IndexedDB in a Service or Utility

   • Don't scatter indexedDB.open() calls everywhere. Create a simple wrapper class or module for consistent access.

2. Handle Version Upgrades Carefully

   • Changing the schema requires incrementing the version number. Use onupgradeneeded to add/remove object stores or indexes.

3. Use Indexes for Performance

   • If you frequently query by a field (eg, status , createdAt ), create an index for it.

4. Watch for Quota Limits

   • Browsers limit storage (usually 50%–80% of disk). Listen for quotaerror and handle gracefully.

5. Clean Up Old Data

   • Especially in long-running apps, periodically clear outdated or unused records.

6. Use cursor for Large Datasets

   • Instead of getAll() , use cursors to process records one at a time and avoid memory issues.

 const request = store.openCursor();
request.onsuccess = (event) => {
  const cursor = event.target.result;
  if (cursor) {
    console.log('Item:', cursor.value);
    cursor.continue(); // Move to next
  }
};

? Alternatives and Wrappers

Because raw IndexedDB is verbose, consider these tools:

• Dexie.js – A popular, lightweight wrapper that simplifies queries and uses Promises/async-await.

   const db = new Dexie('MyAppDB');
  db.version(1).stores({ products: ' id, category' });
  await db.products.add({ name: 'Phone', category: 'electronics' });

• idb – A tiny (1.5KB) Promised-based library by Jake Archibald.
• LocalForage – Offers a localStorage -like API but uses IndexedDB under the hood.

These make IndexedDB much more approachable without sacrificing power.

---

? Final Thoughts

IndexedDB is powerful but complex. For simple needs, localStorage is fine. But when you need to store structured, searchable, or large data on the client, IndexedDB is the best option.

Start small: open a DB, create one object store, and perform basic CRUD operations. Use a wrapper like Dexie if you want faster progress. And always test storage behavior across browsers — especially around limits and user permissions.

Basically, IndexedDB isn't something you use every day, but when you need it, nothing else in the browser comes close.

The above is the detailed content of A Practical Guide to IndexedDB and Client-Side Storage. For more information, please follow other related articles on the PHP Chinese website!