idb

When performing database upgrades where the schema is changing (e.g., renaming a store), you can cast the database instance to a previous version of your schema using IDBPDatabase<OldSchema>. This allows you to interact with old stores that are no longer present in your current DBSchema definition. You can also cast to a typeless database using db as IDBPDatabase.

import { openDB, DBSchema, IDBPDatabase } from 'idb';

interface MyDBV1 extends DBSchema {
  'favourite-number': { key: string; value: number };
}

interface MyDBV2 extends DBSchema {
  'fave-num': { key: string; value: number };
}

const db = await openDB<MyDBV2>('my-db', 2, {
  async upgrade(db, oldVersion) {
    // Cast a reference of the database to the old schema to access old stores
    const v1Db = db as unknown as IDBPDatabase<MyDBV1>;

    if (oldVersion < 1) {
      v1Db.createObjectStore('favourite-number');
    }
    if (oldVersion < 2) {
      const store = v1Db.createObjectStore('favourite-number');
      store.name = 'fave-num';
    }
  },
});

To enable full TypeScript support and IDE autocompletion, extend the DBSchema interface. Define your object stores as keys in the interface. For each store, specify the value type, the key type, and an optional indexes map containing index names and their key types. Pass this interface as a generic to openDB<MyDB>(...).

import { openDB, DBSchema } from 'idb';

interface MyDB extends DBSchema {
  'favourite-number': {
    key: string;
    value: number;
  };
  products: {
    value: {
      name: string;
      price: number;
      productCode: string;
    };
    key: string;
    indexes: { 'by-price': number };
  };
}

async function demo() {
  const db = await openDB<MyDB>('my-db', 1, {
    upgrade(db) {
      db.createObjectStore('favourite-number');
      const productStore = db.createObjectStore('products', {
        keyPath: 'productCode',
      });
      productStore.createIndex('by-price', 'price');
    },
  });

  // This is type-safe
  await db.put('favourite-number', 7, 'Jen');
}

The enhanced IDBDatabase provides shortcuts to perform operations directly on the database instance without manually creating transactions for every single call.

Object Store Shortcuts: These methods take storeName as the first argument, followed by the standard IDBObjectStore arguments:

• get(storeName, key)
• getKey(storeName, key)
• getAll(storeName)
• getAllKeys(storeName)
• count(storeName, ...)
• put(storeName, value, key)
• add(storeName, value, key)
• delete(storeName, key)
• clear(storeName)

Index Shortcuts: These methods take storeName and indexName as the first two arguments, followed by standard IDBIndex arguments:

• getFromIndex(storeName, indexName, key)
• getKeyFromIndex(storeName, indexName, key)
• getAllFromIndex(storeName, indexName)
• getAllKeysFromIndex(storeName, indexName)
• countFromIndex(storeName, indexName, ...)

// Get a value from a store:
const value = await db.get(storeName, key);

// Set a value in a store:
await db.put(storeName, value, key);

// Get a value from an index:
const value = await db.getFromIndex(storeName, indexName, key);

The openDB method opens a database and returns a promise for an enhanced IDBDatabase. It accepts a name, an optional version, and an options object to handle lifecycle events.

Options:

• upgrade(db, oldVersion, newVersion, transaction, event): Called if the version is new. Use this to define the schema.
• blocked(currentVersion, blockedVersion, event): Called if older versions of the database are open on the origin, preventing this version from opening.
• blocking(currentVersion, blockedVersion, event): Called if this connection is blocking a future version from opening.
• terminated(): Called if the browser abnormally terminates the connection.

const db = await openDB(name, version, {
  upgrade(db, oldVersion, newVersion, transaction, event) {
    // …
  },
  blocked(currentVersion, blockedVersion, event) {
    // …
  },
  blocking(currentVersion, blockedVersion, event) {
    // …
  },
  terminated() {
    // …
  },
});

The IDBPDatabase interface provides several shortcut methods that create a single-action transaction automatically. These are useful for simple, one-off operations.

Available shortcuts:

• add(storeName, value, key?): Adds a value. Rejects if the key exists.
• clear(storeName): Deletes all records in a store.
• count(storeName, key?): Returns the number of records matching a query.
• countFromIndex(storeName, indexName, key?): Counts records in an index.
• delete(storeName, key): Deletes a specific record.
• get(storeName, query): Retrieves the first matching value (returns undefined if not found).
• getFromIndex(storeName, indexName, query): Retrieves the first matching value from an index.
• getAll(storeName, query?, count?): Retrieves all matching values.
• getAllFromIndex(storeName, indexName, query?, count?): Retrieves all matching values from an index.
• getAllKeys(storeName, query?, count?): Retrieves all matching keys.
• getAllKeysFromIndex(storeName, indexName, query?, count?): Retrieves all matching keys from an index.
• getKey(storeName, query): Retrieves the key of the first matching record.
• getKeyFromIndex(storeName, indexName, query): Retrieves the key of the first matching record from an index.
• put(storeName, value, key?): Adds or replaces a value.