Coming from Prisma ORM 7

If you know Prisma ORM 7, this page tells you what each thing you already use is called in Prisma ORM 8. Two renamed things to know before the tables: the schema file is now called the contract (the same file, renamed), and generating the client types is now called emit. This page is a lookup table, not a tutorial: one table each for the schema, the command-line tool, and the query API, and a final section on what is missing.

To move a running application, follow Migrate from Prisma ORM 7 to 8 instead. It runs both versions side by side against the same database and moves one part of the app at a time. To decide whether to move at all, see Release status.

All examples use PostgreSQL.

Before you start

If you are adding Prisma ORM 8 to an application that runs Prisma ORM 7, do not run the new-project commands further down in that project, because npm install prisma installs version 8 in place of the version 7 command-line tool. Follow Migrate from Prisma ORM 7 to 8 instead. It runs both versions side by side against your existing database without changing its data, and ends with Prisma ORM 8 managing its migrations.

On PostgreSQL, the following command moves Prisma ORM 7 to the prisma7 command and prisma7.config.ts, and sets up Prisma ORM 8 to read your schema.prisma as its contract:

bunx prisma@latest orm init --from-prisma7-schema prisma/schema.prisma

It does not change prisma/ or the database. orm init on a Prisma ORM 7 project lists what it changes. Then run npx prisma db sign and continue with phase 3 of the guide, moving routes one at a time to the client in src/prisma/db.ts. Prisma ORM 7 keeps owning your migrations until the guide's phase 4, where Prisma ORM 8 takes them over. Phase 4 needs a contract file written for Prisma ORM 8. Before you start it, create one with the guide's steps 2.3 to 2.5, and set contract in prisma.config.ts to that file's path.

To set up Prisma ORM 8 in a new project, install prisma and @prisma/orm-postgres, then run orm init:

bun add --dev prisma
bun add @prisma/orm-postgres
bunx prisma orm init --write-env

orm init writes prisma.config.ts, a starter src/prisma/contract.prisma, src/prisma/db.ts, and .env. Put your connection string in .env as DATABASE_URL, write your models in the contract, and run npx prisma contract emit; db.ts imports the two files it writes.

Commands are written as prisma ... in the tables below. Run them as npx prisma ....

schema.prisma is now contract.prisma

schema.prisma is now src/prisma/contract.prisma. It is the same file, renamed: you still describe your models in it. In Prisma ORM 8, "schema" means a PostgreSQL schema, the namespace your tables live in, usually public.

The biggest visible change is in field types. Where Prisma ORM 7 wrote a Prisma type plus a @db. attribute, such as String @db.VarChar(255), Prisma ORM 8 writes the database type as the field type: VarChar(255).

native_enum Role {
  ADMIN = "ADMIN"
  USER  = "USER"
}

model User {
  id   Int           @id @default(autoincrement())
  role pg.enum(Role)
}

import "temporal-polyfill/full/global";

A many-to-many relation keeps the two list fields and adds a model for the join table. Its primary key must be the two foreign keys and nothing else, as @@id([postId, tagId]) below:

// use prisma-8

model Post {
  id   Int    @id @default(autoincrement())
  tags Tag[]
}

model Tag {
  id    Int    @id @default(autoincrement())
  posts Post[]
}

model PostTag {
  postId Int
  tagId  Int
  post   Post @relation(fields: [postId], references: [id])
  tag    Tag  @relation(fields: [tagId], references: [id])

  @@id([postId, tagId])
}

That is complete as written: you do not need a PostTag[] field on Post or Tag. .include("tags") gives you post.tags as a Tag[], and connect and disconnect work on it. set does not; see Not available below.

If the join table already exists from Prisma ORM 7, it is named _PostToTag with columns A and B. Keep the table by mapping the model to those names: @@map("_PostToTag") on the model, @map("A") on the field that points at the model whose name sorts first alphabetically (postId), and @map("B") on the other (tagId).

The config file replaces the generator and datasource blocks. This one is for PostgreSQL:

import "dotenv/config";
import { definePrismaConfig } from "prisma/config";
import { defineConfig as ormConfig } from "@prisma/orm-postgres/config";

export default definePrismaConfig({
  orm: ormConfig({
    contract: "./src/prisma/contract.prisma",
    db: {
      connection: process.env.DATABASE_URL!,
    },
  }),
});

The orm section takes these keys:

• contract: the path to your contract file, or a glob for a contract in several files. On PostgreSQL it can also be prisma7Schema("prisma/schema.prisma"), with prisma7Schema imported from @prisma/orm-postgres/config next to defineConfig. The schema stays in Prisma ORM 7 syntax, so the changes in the table above do not apply to it, and it needs no // use prisma-8 line. contract emit fails on any part of it that Prisma ORM 8 cannot read, such as a view block, and the error names the line and suggests a change to the Prisma ORM 7 schema; see Use a Prisma ORM 7 schema.
• db: the connection.
• output (optional): where contract.json and contract.d.ts are written. Default: next to the contract.
• extensions (optional): database extensions, for example extensions: [pgvector] with import pgvector from "@prisma/orm-extension-pgvector/control". See Using extensions.
• migrations (optional): { dir: "migrations" }, relative to prisma.config.ts. Your own migrations go in migrations/app/ under it.

There is no provider setting; importing from @prisma/orm-postgres/config is what selects PostgreSQL.

Commands

The Prisma ORM 8 command-line tool groups commands by what they act on: contract for your contract file, db for the database you are connected to, and migration for the migration files in your repository.

Day to day, the loop that replaces prisma migrate dev is: edit the contract, run prisma contract emit, then prisma db update to apply the change to your development database. db update --dry-run shows what it would change, and db update asks before it drops anything. When you want a migration file to commit, run prisma migration plan instead of db update; it writes a folder under migrations/app/ with a migration.ts you can read, edit, and commit. Then prisma db migrate applies it. See Generating a migration.

Four new commands you will meet first:

• prisma orm init sets up Prisma ORM 8 in a project: config file, starter contract, and db.ts (see Before you start).
• prisma db init creates the tables for your contract in an empty database. (db update is for a database that already has tables.)
• prisma db verify checks whether the database still matches your contract.
• prisma db sign records in the database that it matches your contract. Step 4 of the migration guide runs it for your existing database; you will rarely type it yourself.

The rest are in the CLI reference.

src/prisma/db.ts replaces PrismaClient

There is no generated PrismaClient: you create the client once, in src/prisma/db.ts, from the two files prisma contract emit wrote:

import "dotenv/config";
import postgres from "@prisma/orm-postgres/runtime";
import type { Contract } from "./contract.d";
import contractJson from "./contract.json" with { type: "json" };

export const db = postgres<Contract>({
  contractJson,
  url: process.env.DATABASE_URL!,
});

prisma orm init writes this file for you. Every example on this page imports db from it.

db has these parts:

• db.orm: your models, by model name (db.orm.public.User).
• db.sql: the SQL query builder. It holds your tables by table name, as in db.sql.public.User, and a table's name is its model's name unless you set @@map. On this page, the raw SQL examples use it only to give each column's type.
• db.raw.sql: lets you write a SQL query as text.
• db.runtime(): the connection. It runs raw queries.
• db.transaction: runs several queries in one transaction.

To add middleware, add a middleware: [...] key to the postgres({ ... }) call above. A middleware is a plain object with a name and one or more hook functions, for example { name: "log", async beforeQuery(plan) { console.log(plan.sql); } }. How middleware works lists the hooks.

Queries

A query is a chain of calls that you await as a whole. The last call (.all(), .first(), .create(...), and so on) says what you want back, instead of one method with one big options object.

Find with a filter

const users = await prisma.user.findMany({
  where: { active: true },
  select: { id: true, email: true },
  orderBy: { createdAt: "desc" },
  take: 10,
});

import { db } from "./prisma/db";

const users = await db.orm.public.User
  .where({ active: true })
  .select("id", "email")
  .orderBy((u) => u.createdAt.desc())
  .limit(10)
  .all();

Create a record

const user = await prisma.user.create({
  data: { email: "alice@prisma.io", name: "Alice" },
});

const user = await db.orm.public.User.create({
  email: "alice@prisma.io",
  name: "Alice",
});

Raw SQL

const rows = await prisma.$queryRaw`SELECT id, email FROM "User" WHERE active = true`;
await prisma.$executeRaw`UPDATE "User" SET active = false WHERE id = ${id}`;

// A query that returns rows must say what type each column is.
const user = db.sql.public.User;
const select = db.raw.sql`SELECT id, email FROM "User" WHERE active = true`
  .returnsRow({ id: user.columns.id, email: user.columns.email })
  .build();
const rows = await db.runtime().query(select);

// A statement that changes rows: ask for the count.
const update = db.raw.sql`UPDATE "User" SET active = false WHERE id = ${id}`
  .affectedCount()
  .build();
await db.runtime().execute(update);

The table is User, because a model without @@map names its table after the model. As in Prisma ORM 7, a value you put in the SQL with ${...}, such as ${id}, is sent to the database as a query parameter.

Every raw query that returns rows needs .returnsRow(...) with a type per column, and you take the type from the table, as above. A computed column has no table column to take it from, so write the type name as a string instead: for SELECT count(*) AS total FROM "User", write .returnsRow({ total: "pg/int8@1" }). Raw queries lists the type names. Finish the query with .build() and pass it to db.runtime().query() for rows, or to db.runtime().execute() for the number of rows a write changed. On PostgreSQL, db.runtime() returns the connection directly, so it needs no await.

Transaction

const [user, post] = await prisma.$transaction([
  prisma.user.create({ data: { email: "jane@prisma.io" } }),
  prisma.post.create({ data: { title: "Hello" } }),
]);

const result = await db.transaction(async (tx) => {
  const user = await tx.orm.public.User.create({ email: "jane@prisma.io" });
  const post = await tx.orm.public.Post.create({ title: "Hello", authorId: user.id });
  return { user, post };
});

Full-text search

Import the functions that build a search query from @prisma/orm-postgres/target/full-text. toTsquery takes PostgreSQL's operator syntax as written, such as cat & dog, and fails on text that is not valid syntax, so use it only for text your application writes. For text a user types into a search box, use websearchToTsquery, which accepts quoted phrases, or, and - in front of a word to exclude it. To sort by relevance, pass the same query to fullTextRank:

import { websearchToTsquery } from "@prisma/orm-postgres/target/full-text";

const query = websearchToTsquery('"cat food" -dog');
const posts = await db.orm.public.Post
  .where((p) => p.title.fullTextMatches(query))
  .orderBy((p) => p.title.fullTextRank(query).desc())
  .all();

Add @@fullTextIndex([title], name: "post_title_search") to the Post model so PostgreSQL can use an index for the search. Full-text search covers the other options.

Not available

Prisma ORM 7 features that have no direct form in Prisma ORM 8, with what to do instead. The status column says whether each feature is not available, available in a different form, or, for $extends, replaced by middleware.

const created = await db.orm.public.User.createAll(rows, {
  onConflict: "skip",
  conflictOn: ["email"],
});

Also not available today:

• Nested writes other than create, connect, and disconnect: connectOrCreate, nested update, updateMany, upsert, delete, deleteMany, and set on a relation. Change the related rows through their own model instead, for example db.orm.public.Post.where({ authorId }).updateAll({ ... }), inside db.transaction(...) if it must be atomic.

• The list filters has, hasEvery, hasSome, and isEmpty on String[] and other list fields. The fields themselves work, and you can filter on them with a raw SQL query written the same way as the raw SQL example above. For a Post model with a tags String[] field:

  const post = db.sql.public.Post;
  const query = db.raw.sql`SELECT id FROM "Post" WHERE ${tag} = ANY(tags)`
    .returnsRow({ id: post.columns.id })
    .build();
  const rows = await db.runtime().query(query);

• Transaction options: isolationLevel, timeout, maxWait, and transactions inside transactions.

• omit, relationLoadStrategy, Prisma.skip, and the automatic batching of findUnique calls.

• The P2002 / P2025 style error codes. Errors carry a code such as RUNTIME.NO_ROWS instead, and a database error such as a unique-constraint violation carries the standard SQL state code in error.sqlState (23505 for a unique violation, on every database), so catch it with if (error instanceof Error && "sqlState" in error && error.sqlState === "23505"). See the error reference.

• Prisma.sql, Prisma.join, Prisma.raw, Prisma.empty, and TypedSQL. Use db.raw.sql (example above); Raw queries covers building a query from pieces.

• Soft delete, validation rules in the schema, lifecycle hooks on models, and read replicas. For soft delete, add a nullable deletedAt field and filter on it, with one scope that every model with the field can use. Validate in your application code. Use middleware for hooks. For read replicas, create one client per database.

Where to go next

• Migrate from Prisma ORM 7 to 8, the step-by-step migration for a running PostgreSQL application.
• Core concepts, for what a contract is and what contract emit does.
• ORM client reference, for every query method.
• Reading data and Writing data, for the query API in full.
• Release status, for how close Prisma ORM 8 is to its final release, and how to stay on Prisma ORM 7.