HTML IndexedDB Insert

Introduction

IndexedDB is a low-level browser API for storing large amounts of structured data on the client. Unlike localStorage, it supports indexes, transactions, and complex JavaScript objects—including files and blobs. It is the modern replacement for the deprecated Web SQL API.

This tutorial focuses specifically on inserting data into IndexedDB: opening a database, creating an object store, running add() and put() inside readwrite transactions, and handling success and errors safely.

What You’ll Learn

What Is IndexedDB?

IndexedDB is a transactional, key-value database built into modern browsers. Data is organized in object stores (similar to tables) inside a named database. Each record is a JavaScript object; you choose a keyPath (like id) or let the browser auto-generate keys with autoIncrement: true.

The API is asynchronous—operations use requests and event callbacks instead of blocking the main thread. That keeps your UI responsive while large datasets are read or written.

Creating an IndexedDB Database

Before inserting data, open the database and define an object store where records will live. Schema changes happen only in onupgradeneeded when you bump the version number.

const request = indexedDB.open('myDatabase', 1);

request.onupgradeneeded = function (event) {
  const db = event.target.result;
  const store = db.createObjectStore('contacts', {
    keyPath: 'id',
    autoIncrement: true
  });
  store.createIndex('emailIndex', 'email', { unique: false });
};

request.onsuccess = function (event) {
  const db = event.target.result;
  console.log('Database ready');
};

request.onerror = function (event) {
  console.error('Open failed:', event.target.error.message);
};

• indexedDB.open(name, version) — opens an existing database or creates a new one.
• onupgradeneeded — runs when the version increases; create object stores and indexes here.
• keyPath: 'id' — tells IndexedDB which property is the primary key.
• autoIncrement: true — generates numeric ids when you omit id on insert.
• createIndex — optional secondary lookup on email (used later for queries).

Opening a Database

After the first setup, you open the same database on every page load. If the version matches, onupgradeneeded does not run—you go straight to onsuccess.

const request = indexedDB.open('myDatabase', 1);

request.onsuccess = function (event) {
  const db = event.target.result;
  // db is ready — start transactions here
};

request.onerror = function (event) {
  console.error('Database error:', event.target.error.message);
};

Keep a reference to db in a variable or module. Close it with db.close() when your app unloads if you manage connections manually.

Inserting Data

To insert a record, start a readwrite transaction on the object store, then call add() with a plain JavaScript object:

const request = indexedDB.open('myDatabase', 1);

request.onsuccess = function (event) {
  const db = event.target.result;
  const tx = db.transaction(['contacts'], 'readwrite');
  const store = tx.objectStore('contacts');

  const item = { name: 'John Doe', age: 30 };
  const addRequest = store.add(item);

  addRequest.onsuccess = function () {
    console.log('Added with id:', addRequest.result);
  };

  addRequest.onerror = function (event) {
    console.error('Add failed:', event.target.error.message);
  };
};

With autoIncrement: true, you can omit id—IndexedDB assigns one and returns it in addRequest.result. If you provide an id that already exists, add() fails with a ConstraintError.

add() vs put()

• store.add(item) — insert only; fails if the key already exists.
• store.put(item) — insert or replace; updates an existing record with the same key.

Handling Transactions

Transactions group one or more operations. For inserts, always use 'readwrite' mode and listen for completion and errors:

const tx = db.transaction(['contacts'], 'readwrite');

tx.oncomplete = function () {
  console.log('Transaction committed successfully');
};

tx.onerror = function (event) {
  console.error('Transaction error:', event.target.error.message);
};

const store = tx.objectStore('contacts');
store.add({ name: 'Jane Doe', age: 25 });

If any request in the transaction fails and the error is not handled, the transaction aborts and none of its writes are saved. Chain multiple add() calls in one transaction for atomic batch inserts.

Error Handling

IndexedDB errors can occur when opening the database, exceeding storage quotas, using a closed connection, or violating key constraints. Handle errors at both the request and transaction levels:

const openReq = indexedDB.open('myDatabase', 1);

openReq.onerror = function (event) {
  console.error('Open error:', event.target.error.message);
};

openReq.onsuccess = function (event) {
  const db = event.target.result;
  const tx = db.transaction(['contacts'], 'readwrite');

  tx.onerror = function (event) {
    console.error('Transaction aborted:', event.target.error.message);
  };

  const addReq = tx.objectStore('contacts').add({ id: 1, name: 'Sam' });

  addReq.onerror = function (event) {
    console.error('Add error:', event.target.error.message);
    /* Duplicate key? Try put() instead of add(). */
  };
};

Note: use event.target.error.message, not the legacy errorCode property shown in older tutorials.

Common Pitfalls

1. Schema in the wrong place — create object stores only in onupgradeneeded, not inside a normal insert transaction.
2. Wrong transaction mode — add() and put() require 'readwrite'; 'readonly' will fail.
3. Duplicate keys with add() — calling add() twice with the same id throws; use put() for upserts.
4. Version bumps — to add a new object store later, increment the version in open() and migrate in onupgradeneeded.
5. Storing non-cloneable values — objects must be structured-cloneable (no functions or DOM nodes in the record).

Examples Gallery

These examples follow the IndexedDB insert pattern. Use Try It Yourself to run live demos in the editor. IndexedDB works in all modern browsers.

const openReq = indexedDB.open('myDatabase', 1);

openReq.onupgradeneeded = function (event) {
  event.target.result.createObjectStore('contacts', {
    keyPath: 'id',
    autoIncrement: true
  });
};

openReq.onsuccess = function (event) {
  const db = event.target.result;
  const tx = db.transaction(['contacts'], 'readwrite');
  const addReq = tx.objectStore('contacts').add({
    name: 'John Doe',
    email: 'john@example.com'
  });

  addReq.onsuccess = function () {
    console.log('New id:', addReq.result);
  };
};

New id: 1

function addContact(db, contact) {
  return new Promise(function (resolve, reject) {
    const tx = db.transaction(['contacts'], 'readwrite');
    const addReq = tx.objectStore('contacts').add(contact);

    addReq.onsuccess = function () {
      resolve(addReq.result);
    };
    addReq.onerror = function () {
      reject(addReq.error);
    };
  });
}

addContact(db, { name: 'Notebook', email: 'shop@example.com' })
  .then(function (id) { console.log('Saved id', id); })
  .catch(function (err) { console.error(err.message); });

Saved id 2

const contacts = [
  { name: 'Apple', email: 'a@fruit.com' },
  { name: 'Banana', email: 'b@fruit.com' },
  { name: 'Cherry', email: 'c@fruit.com' }
];

const tx = db.transaction(['contacts'], 'readwrite');
const store = tx.objectStore('contacts');

contacts.forEach(function (c) {
  store.add(c);
});

tx.oncomplete = function () {
  console.log('All', contacts.length, 'contacts saved');
};

All 3 contacts saved

function saveNote(db, note) {
  const tx = db.transaction(['notes'], 'readwrite');
  tx.objectStore('notes').put(note);
}

saveNote(db, { id: 1, title: 'Draft' });
saveNote(db, { id: 1, title: 'Final version' }); /* replaces first */

id 1 → title: "Final version"

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>IndexedDB Insert Example</title>
</head>
<body>
  <h1>IndexedDB Insert Example</h1>
  <button type="button" id="addData">Add Contact</button>
  <p id="status"></p>

  <script>
    let db;

    const dbRequest = indexedDB.open('myDatabase', 1);

    dbRequest.onupgradeneeded = function (event) {
      event.target.result.createObjectStore('contacts', {
        keyPath: 'id',
        autoIncrement: true
      });
    };

    dbRequest.onsuccess = function (event) {
      db = event.target.result;
      document.getElementById('status').textContent = 'Database ready.';
    };

    dbRequest.onerror = function (event) {
      document.getElementById('status').textContent =
        'Error: ' + event.target.error.message;
    };

    document.getElementById('addData').addEventListener('click', function () {
      const tx = db.transaction(['contacts'], 'readwrite');
      const addReq = tx.objectStore('contacts').add({
        name: 'Jane Doe',
        age: 25
      });

      addReq.onsuccess = function () {
        document.getElementById('status').textContent =
          'Added contact id ' + addReq.result;
      };

      addReq.onerror = function (event) {
        document.getElementById('status').textContent =
          'Add failed: ' + event.target.error.message;
      };
    });
  </script>
</body>
</html>

Added contact id 1

🚀 Common Use Cases

• Offline form drafts — save user input locally before syncing to a server.
• Shopping cart cache — persist cart items between page reloads.
• Activity logs — append timestamped events to a local store.
• Progressive Web Apps — queue actions for background sync when offline.
• Media caches — store blobs (images, PDFs) alongside metadata objects.

📝 Notes

• Create object stores only in onupgradeneeded, not during normal inserts.
• Inserts require a readwrite transaction on the correct store name.
• Validate data in JavaScript before writing (required fields, types, size limits).
• add() rejects duplicate keys; put() overwrites them.
• Storage is per-origin; other sites cannot read your IndexedDB data.
• For reading inserted data, continue to the Retrieve tutorial.

💡 Best Practices