Client

This page shows how to open the client in common situations. For a first setup, follow the Quick Start.

Open the database

createAutoMigratingIdbClient opens the database, applies any pending migrations, and resolves to a client. Cache the promise so the database opens once:

import { createAutoMigratingIdbClient } from "@prisma-idb/client-idb/client-auto";
import type { IdbClient } from "@prisma-idb/client-idb/client-auto";
import type { Contract } from "./prisma/contract";
import { contractSpace } from "./prisma/contract-space.generated";

let db: Promise<IdbClient<Contract>> | null = null;

export function getDb(): Promise<IdbClient<Contract>> {
  return (db ??= createAutoMigratingIdbClient({ contractSpace, dbName: "my-app" }));
}

dbName is the IndexedDB database name. Use a different name to keep separate databases in the same browser, for example one per tenant.

The client applies every pending migration as it was planned, including ones that delete data. Review those when you plan them; see Destructive changes.

Share one client and reset it on logout

createManagedAutoIdbClient wraps the same options in a singleton with a safe reset(). Use it when the app needs to wipe local data, for example so a different account signing in on the same browser never sees the previous user's rows.

import { createManagedAutoIdbClient } from "@prisma-idb/client-idb/client-auto";

const managedDb = createManagedAutoIdbClient({ contractSpace, dbName: "my-app" });

export const getDb = () => managedDb.get();
export const closeDb = () => managedDb.close();
export const resetDb = () => managedDb.reset(); // call on sign-out

reset() is safe to call at any time. It waits for an open that's in progress before deleting, and a get() called during a reset waits for the delete to finish, then opens a fresh database.

Using sync? Use createManagedAutoSyncIdbClient from @prisma-idb/sync-extension-idb/client instead. It works the same way. See Sync.

Wrap a different factory

createManagedAutoIdbClient is createManagedIdbClient with the factory already chosen. To wrap something else, such as createIdbClient on a database you migrate yourself, use createManagedIdbClient:

import { createIdbClient, createManagedIdbClient } from "@prisma-idb/client-idb/client";

const managedDb = createManagedIdbClient(async () => createIdbClient({ contract, dbName: "my-app" }), {
  dbName: "my-app", // must match the factory's dbName
});

createIdbClient returns a client synchronously. The async factory above adapts it to the promise-returning factory required by createManagedIdbClient.

createManagedIdbClient only uses its own dbName to delete the database in reset(). Nothing checks that it matches the factory's. If they differ, get() still opens the right database, but reset() deletes a different one and your data stays. Prefer createManagedAutoIdbClient unless you need a custom factory.

Add an extension

An extension adds its own object stores and ships its own migrations. Pass it in extensions, and its migrations run together with yours when the database opens:

import { createAutoMigratingIdbClient } from "@prisma-idb/client-idb/client-auto";
import { idbSyncExtension } from "@prisma-idb/sync-extension-idb/control";

const db = await createAutoMigratingIdbClient({
  contractSpace,
  dbName: "my-app",
  extensions: [idbSyncExtension],
});

You don't plan or edit an extension's migrations. The sync extension is currently the only one; see Sync.

Client reference