Prisma IDB FaviconPrisma IDB

Quick Start

Set up Prisma 8 IDB in a project and run your first query

In this tutorial you add Prisma 8 IDB to a browser app, create the database from a schema, and write and read your first rows. It takes about ten minutes. You need a project with a bundler, such as Vite or SvelteKit.

1. Install the packages

The app needs the client at run time:

npm install @prisma-idb/client-idb @prisma/orm-toolchain

The CLIs and the rest of the stack are only needed at build time:

npm install --save-dev prisma@latest @prisma/cli-engine @prisma/orm-framework \
  @prisma-idb/family-idb @prisma-idb/target-idb \
  @prisma-idb/adapter-idb @prisma-idb/driver-idb

2. Write a schema

Create src/prisma/schema.prisma. You don't need a generator or datasource block.

// use prisma-8

model User {
  id    String  @id
  name  String
  email String? @unique
  todos Todo[]
}

model Todo {
  id     String  @id
  title  String
  done   Boolean
  userId String
  user   User    @relation(fields: [userId], references: [id], onDelete: Cascade)
}

Keep // use prisma-8 as the first line. It selects the Prisma 8 language server in the Prisma VS Code extension, enabling scalar type hints, attribute completion, hover descriptions, and IDB diagnostics. The extension uses the project's local prisma CLI and prisma.config.ts; without the directive it routes the file to the legacy language server. See Editor Setup for setup and troubleshooting.

3. Configure the CLIs

Create prisma.config.ts in the project root. Both prisma and prisma-idb read it.

import { definePrismaConfig } from "@prisma/cli-engine";
import { defineConfig as ormConfig } from "@prisma-idb/family-idb/config-types";
import { prismaIdbContract } from "@prisma-idb/family-idb/contract-psl";
import idbFamily from "@prisma-idb/family-idb/control";
import idbTarget from "@prisma-idb/target-idb/control";
import idbAdapter from "@prisma-idb/adapter-idb/control";
import idbDriver from "@prisma-idb/driver-idb/control";

export default definePrismaConfig({
  orm: ormConfig({
    family: idbFamily,
    target: idbTarget,
    adapter: idbAdapter,
    driver: idbDriver,
    db: { connection: ":memory:" },
    contract: prismaIdbContract("src/prisma/schema.prisma"),
    migrations: { dir: "migrations" },
  }),
});

The framework requires driver and db.connection, but IndexedDB doesn't use them. See Schema & Config for what each field does.

4. Create the first migration

Run these four commands:

npx prisma-idb contract emit
npx prisma-idb migration plan
npx prisma-idb migration contract-space
npx prisma-idb migration preflight

In order, they:

  1. Write src/prisma/contract.json, contract.d.ts, and contract.runtime.ts, a typed default export of your schema.
  2. Write the first migration package to migrations/app/<timestamp>_baseline/, and a copy of the contract to migrations/snapshots/.
  3. Write src/prisma/contract-space.generated.ts, which bundles the migrations so your app can import them.
  4. Apply every migration to an in-memory IndexedDB, to check that they run.

Commit all of these files.

5. Open the database

Create src/db.ts:

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" }));
}

The first call opens the database named my-app, applies any pending migrations, and returns a client. Later calls reuse the same client.

6. Write and read rows

From any browser code:

import { getDb } from "./db";

const db = await getDb();

const user = await db.orm.user.create({ id: crypto.randomUUID(), name: "Alice", email: null });
await db.orm.todo.create({ id: crypto.randomUUID(), title: "Try Prisma 8 IDB", done: false, userId: user.id });

const users = await db.orm.user.include("todos").all();
console.log(users);
// [{ id: "…", name: "Alice", email: null, todos: [{ id: "…", title: "Try Prisma 8 IDB", … }] }]

Open your browser's developer tools and look under Application → IndexedDB → my-app. You'll see a user and a todo store holding your rows, and _prisma_next_marker, which records the schema the database is at.

Next steps

On this page