Prisma ORM User Guide

Prisma ORM is a next-generation, type-safe ORM for Node.js and TypeScript. It lets you model your database in a declarative schema, run database migrations, and query your data with an auto-generated, fully type-safe client. This guide covers everything you need to install Prisma, model your data, evolve your database, and query it from your application.

Prisma is made up of three tools that work together:

• Prisma Client — an auto-generated, type-safe query builder for your database.
• Prisma Migrate — a declarative migration system that keeps your database schema in sync with your Prisma schema.
• Prisma Studio — a local GUI to view and edit the data in your database.

You drive all of these from a single command-line tool: prisma.

Note

This guide documents Prisma ORM v7. In v7, the generated client is written as TypeScript source by the prisma-client generator, a driver adapter is required when instantiating PrismaClient, and Prisma CLI configuration lives in a prisma.config.ts file. If you are upgrading from v5/v6, review the Configuration and Connecting Prisma Client sections carefully.

Table of Contents

1. Quick Start
2. Requirements
3. Installation
4. The Prisma Schema
5. Configuration: prisma.config.ts
6. Using Prisma Client
7. Everyday Tasks (CLI)
8. Common Workflows
9. Querying Your Data
10. Supported Databases
11. Troubleshooting
12. FAQ
13. Command Reference
14. Environment Variable Reference

1. Quick Start

The fastest way to go from nothing to a working, type-safe database client.

# 1. Install the CLI (dev dependency) and the client runtime
npm install prisma --save-dev
npm install @prisma/client

# 2. Scaffold a Prisma project (creates prisma/schema.prisma, prisma.config.ts, .env)
npx prisma init --datasource-provider postgresql

# 3. Edit prisma/schema.prisma to define your models, then create your first migration
npx prisma migrate dev --name init

# 4. Generate the type-safe Prisma Client
npx prisma generate

# 5. Open Prisma Studio to browse your data
npx prisma studio

✔ Generated Prisma Client to ./generated/prisma in 412ms

After step 4 you can import the generated client and start querying:

import { PrismaClient } from './generated/prisma/client'
import { PrismaPg } from '@prisma/adapter-pg'

const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL })
const prisma = new PrismaClient({ adapter })

const users = await prisma.user.findMany()
console.log(users)

Tip

If you don't have a database yet, run npx prisma dev to start a local Prisma Postgres server in your terminal — no Docker and no configuration required. To provision a free cloud database instead, run npx create-db.

2. Requirements

Important

Prisma ORM does not automatically load .env files for you. To populate environment variables from a .env file, either import a loader such as dotenv/config at the top of your prisma.config.ts, run your app with node --env-file=.env / tsx --env-file=.env, or use Bun (which loads .env automatically).

3. Installation

Install the Prisma CLI as a development dependency and the Prisma Client runtime as a regular dependency.

npm

npm install prisma --save-dev
npm install @prisma/client

pnpm

pnpm add -D prisma
pnpm add @prisma/client

yarn

yarn add -D prisma
yarn add @prisma/client

bun

bun add -d prisma
bun add @prisma/client

You will also need a driver adapter package for your database (required in v7). Install the one that matches your database:

# Example: PostgreSQL with node-postgres
npm install @prisma/adapter-pg

Tip

Run npx prisma version (or npx prisma -v) at any time to print the installed Prisma, client, and engine versions. Add --json for machine-readable output.

4. The Prisma Schema

Every Prisma project starts with a Prisma schema file (prisma/schema.prisma). It defines three things: your data source, your generator, and your data models.

// Data source — which database you connect to
datasource db {
  provider = "postgresql"
}

// Generator — what to generate (here: Prisma Client)
generator client {
  provider = "prisma-client"
  output   = "../generated/prisma"
}

// Data model — your application's tables/collections
model Post {
  id        Int     @id @default(autoincrement())
  title     String
  content   String?
  published Boolean @default(false)
  author    User?   @relation(fields: [authorId], references: [id])
  authorId  Int?
}

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
  posts Post[]
}

What each block does:

datasource : Specifies your database provider (one of postgresql, mysql, sqlite, sqlserver, mongodb, cockroachdb, or prisma+postgres). This determines which features and field types are available. The connection URL itself is supplied through prisma.config.ts (see next section).

generator : Declares what to generate. The default and recommended generator is prisma-client, which emits a TypeScript client to the output path. You can declare multiple generators and run them selectively.

model : Represents a table (relational databases) or collection (MongoDB). Each model field maps to a column. Attributes like @id, @unique, @default(...), @relation(...), and @map(...) configure keys, constraints, defaults, and relationships.

Note

A model has two jobs: it represents a table in your database, and it is the foundation for the queries Prisma Client exposes. When you add a User model, Prisma Client gains a fully typed prisma.user API with findMany, create, update, and more.

Getting a data model

There are two ways to get models into your schema:

• Write them by hand and apply them to the database with Prisma Migrate (prisma migrate dev).
• Introspect an existing database with prisma db pull, which reads your database structure and writes the corresponding models into your schema.

5. Configuration: prisma.config.ts

In Prisma v7, CLI subcommands like migrate, db, and studio read their configuration from a prisma.config.ts file in your project root. prisma init creates this file for you.

import 'dotenv/config'
import { defineConfig, env } from 'prisma/config'

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
  },
  datasource: {
    url: env('DATABASE_URL'),
  },
})

The env() helper reads a variable from process.env in a type-safe way and throws a clear error at runtime if it is missing. You can also type the available variables:

import { defineConfig, env } from 'prisma/config'

type Env = {
  DATABASE_URL: string
}

export default defineConfig({
  schema: 'prisma/schema.prisma',
  datasource: {
    url: env<Env>('DATABASE_URL'),
  },
})

Key configuration keys:

Warning

Environment variables from .env files are not loaded automatically. The example above imports dotenv/config at the top of the config file to load them. If you use Bun, .env files are loaded for you and you can omit the import.

Important

If you point the CLI at a custom config path, pass --config ./path/to/prisma.config.ts to any command. Almost every command accepts --config and --schema to override these locations.

6. Using Prisma Client

6.1 Generate the client

After defining your models, generate the client:

npx prisma generate

✔ Generated Prisma Client (prisma-client) to ./generated/prisma in 480ms

Start by importing your Prisma Client (See: https://pris.ly/d/importing-client)

You must re-run prisma generate every time you change your data model so the generated types match your schema.

Tip

Run prisma generate --watch during development to automatically regenerate the client whenever you save a change to your schema. Use --no-hints to suppress the informational hints (errors and warnings are still shown).

6.2 Instantiate Prisma Client with a driver adapter

In v7, you pass a driver adapter to the PrismaClient constructor. The adapter wraps the native database driver for your database.

import { PrismaClient } from './generated/prisma/client'
import { PrismaPg } from '@prisma/adapter-pg'

const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL })
const prisma = new PrismaClient({ adapter })

Note

The import path (./generated/prisma/client above) is whatever you set as the output in your generator client block. If you used npx prisma init defaults, it is ./generated/prisma.

To load environment variables for your application code, use dotenv (import 'dotenv/config'), node --env-file=.env, tsx --env-file=.env, or run with Bun.

6.3 Run queries

All Prisma Client queries return plain JavaScript objects, and when using TypeScript the results are statically typed:

// Get every user
const allUsers = await prisma.user.findMany()

// Get every user, including their posts
const usersWithPosts = await prisma.user.findMany({
  include: { posts: true },
})

// Create a user and a related post in a single query
const user = await prisma.user.create({
  data: {
    name: 'Alice',
    email: '[email removed]',
    posts: {
      create: { title: 'Hello World' },
    },
  },
})

See Querying Your Data for the full set of operations.

7. Everyday Tasks (CLI)

The prisma CLI is your main interface. Run npx prisma with no arguments to see the top-level help.

Prisma is a modern DB toolkit to query, migrate and model your database

Usage
  $ prisma [command]

Commands
        init   Set up Prisma for your app
   bootstrap   Bootstrap a Prisma Postgres project
         dev   Start a local Prisma Postgres server for development
    generate   Generate artifacts (e.g. Prisma Client)
          db   Manage your database schema and lifecycle
     migrate   Migrate your database
      studio   Browse your data with Prisma Studio
    validate   Validate your Prisma schema
      format   Format your Prisma schema
     version   Displays Prisma version info
       debug   Displays Prisma debug info
    platform   Prisma Data Platform commands
    postgres   Manage Prisma Postgres databases
         mcp   Starts an MCP server to use with AI development tools

prisma init — Set up a new project

Scaffolds a prisma/ folder with a starter schema.prisma, a prisma.config.ts, a .env file, and a .gitignore entry for the generated client.

# Default: PostgreSQL, ready for `prisma dev` (local Prisma Postgres)
npx prisma init

# Choose a different database
npx prisma init --datasource-provider mysql

# Add an example User model to the generated schema
npx prisma init --with-model

# Initialize with an existing connection string
npx prisma init --url postgresql://user:password@localhost:5432/mydb

Note

prisma init will refuse to run (and exit) if a schema.prisma file or a prisma/ folder already exists, to avoid clobbering an existing project.

prisma generate — Generate Prisma Client

npx prisma generate                 # generate from the configured schema
npx prisma generate --watch         # regenerate on every schema change
npx prisma generate --sql           # also generate the typed SQL module
npx prisma generate --generator client1 --generator client2  # only named generators

prisma studio — Browse your data

Opens a local web GUI to view and edit rows.

npx prisma studio

Prisma Studio is up on http://localhost:5555

Caution

Prisma Studio connects directly to your database and no longer supports Accelerate URLs (prisma:// or prisma+postgres://). Use a direct database connection string for Studio. Set the BROWSER environment variable to control which browser opens.

prisma validate and prisma format

npx prisma validate                 # check the schema is valid
npx prisma format                   # auto-format the schema file
npx prisma format --check           # exit non-zero if any file is unformatted (CI-friendly)

prisma version, prisma debug

npx prisma version                  # print versions (alias: prisma -v)
npx prisma version --json           # machine-readable
npx prisma debug                    # print environment + paths for bug reports

8. Common Workflows

8.1 Develop with migrations (recommended)

Use this workflow when you want a tracked, reproducible migration history (most production apps).

# 1. Edit prisma/schema.prisma to add or change models
# 2. Create and apply a migration, then regenerate the client
npx prisma migrate dev --name add_posts_table

prisma migrate dev:

1. Validates your schema.
2. Creates the database if it does not exist.
3. Generates a new SQL migration in prisma/migrations/ from your schema changes.
4. Applies the migration to your development database.
5. Triggers generators (e.g. regenerates Prisma Client).

# Create a migration file but do NOT apply it (edit it first)
npx prisma migrate dev --name custom_change --create-only

Important

prisma migrate dev is intended for development databases only. It may prompt to reset the database if your migration history has drifted. For production and staging, use prisma migrate deploy (see below).

8.2 Prototype quickly without migrations

Use db push when you want to iterate on your schema rapidly without creating migration files (e.g. early prototyping).

npx prisma db push                       # sync schema → database
npx prisma db push --accept-data-loss    # don't prompt on potentially destructive changes
npx prisma db push --force-reset         # drop and recreate the database first

🚀  Your database is now in sync with your Prisma schema. Done in 320ms

Warning

db push does not create migration files, so it leaves no migration history. Do not mix db push and migrate dev on the same database without understanding the consequences. --force-reset drops your database and all its data.

8.3 Deploy to production / staging

# Apply all pending migrations (no schema generation, no prompts)
npx prisma migrate deploy

2 migrations found in prisma/migrations

The following migration(s) have been applied:
  20260101000000_init
  20260102093000_add_posts_table

All migrations have been successfully applied.

Check migration status without changing anything:

npx prisma migrate status

8.4 Adopt Prisma on an existing database (introspection)

# 1. Point DATABASE_URL at your existing database, then introspect it
npx prisma db pull

# 2. Generate the client from the introspected schema
npx prisma generate

✔ Introspected 12 models and wrote them into prisma/schema.prisma in 1.2s
Run prisma generate to generate Prisma Client.

8.5 Baseline an existing production database

If you start using Prisma Migrate on a database that already has tables, baseline it so Prisma does not try to recreate them:

# Mark your initial migration as already applied
npx prisma migrate resolve --applied 20260101000000_init

8.6 Recover from a failed migration

# After fixing the database by hand (hotfix), mark the migration as applied
npx prisma migrate resolve --applied 20260102093000_add_posts_table

# Or, if you manually rolled it back
npx prisma migrate resolve --rolled-back 20260102093000_add_posts_table

Run prisma migrate status first — it tells you exactly which resolve command to run.

8.7 Seed your database

Configure a seed command in prisma.config.ts:

export default defineConfig({
  migrations: {
    seed: 'tsx ./prisma/seed.ts',
  },
  datasource: { url: env('DATABASE_URL') },
})

npx prisma db seed
# Pass extra arguments through to your seed script after a -- separator
npx prisma db seed -- --environment development

🌱  The seed command has been executed.

Note

prisma db seed runs as part of prisma migrate dev and prisma migrate reset automatically once a seed command is configured.

8.8 Compare two schemas (migrate diff)

migrate diff is a read-only command that computes the difference between any two schema sources. It is the building block for generating ad-hoc SQL.

# Diff your config datasource against a target schema, as a SQL script
npx prisma migrate diff \
  --from-config-datasource \
  --to-schema next.prisma \
  --script

# Pipe the SQL straight into the database
npx prisma migrate diff --from-[...] --to-[...] --script \
  | npx prisma db execute --stdin

One --from-... and one --to-... source must be provided. Valid sources are --from-empty/--to-empty, --from-schema/--to-schema, --from-migrations/--to-migrations, and --from-config-datasource/--to-config-datasource.

Note

In v7, --from-url, --to-url, and --from/to-schema-datasource were removed. Use --from-config-datasource / --to-config-datasource together with a prisma.config.ts datasource instead.

8.9 Run raw SQL against your database

# Execute a SQL file
npx prisma db execute --file ./script.sql

# Execute SQL from stdin
echo 'TRUNCATE TABLE "Post";' | npx prisma db execute --stdin

Caution

db execute reports only success or failure — it is not meant to return rows. It is not supported on MongoDB.

9. Querying Your Data

Once Prisma Client is generated, every model exposes a typed query API. Below are the operations you will use most.

Read

// One record by unique field (returns null if not found)
const user = await prisma.user.findUnique({ where: { email: '[email removed]' } })

// One record, throwing if not found
const post = await prisma.post.findUniqueOrThrow({ where: { id: 1 } })

// First match for a filter
const draft = await prisma.post.findFirst({ where: { published: false } })

// Many records with filtering, ordering, pagination
const posts = await prisma.post.findMany({
  where: {
    OR: [
      { title: { contains: 'prisma' } },
      { content: { contains: 'prisma' } },
    ],
  },
  orderBy: { id: 'desc' },
  take: 10,
  skip: 0,
})

Create, update, delete

// Create
await prisma.user.create({ data: { email: '[email removed]', name: 'Bob' } })

// Create many
await prisma.user.createMany({ data: [{ email: '[email removed]' }, { email: '[email removed]' }] })

// Update one
await prisma.post.update({ where: { id: 42 }, data: { published: true } })

// Update many
await prisma.post.updateMany({ where: { published: false }, data: { published: true } })

// Upsert (update or create)
await prisma.user.upsert({
  where: { email: '[email removed]' },
  update: { name: 'Alice A.' },
  create: { email: '[email removed]', name: 'Alice' },
})

// Delete
await prisma.post.delete({ where: { id: 42 } })
await prisma.post.deleteMany({ where: { published: false } })

Relations, selection, and aggregation

// Include related records
const withPosts = await prisma.user.findMany({ include: { posts: true } })

// Select specific fields (partial result type is inferred)
const emails = await prisma.user.findMany({ select: { email: true } })

// Nested writes
await prisma.user.create({
  data: {
    email: '[email removed]',
    posts: { create: [{ title: 'First' }, { title: 'Second' }] },
  },
})

// Aggregate and group
const stats = await prisma.post.aggregate({ _count: true, _avg: { id: true } })
const grouped = await prisma.post.groupBy({ by: ['published'], _count: true })

Transactions

// Sequential operations as one atomic transaction
const [deleted, created] = await prisma.$transaction([
  prisma.post.deleteMany({ where: { published: false } }),
  prisma.post.create({ data: { title: 'New' } }),
])

// Interactive transaction
await prisma.$transaction(async (tx) => {
  const u = await tx.user.create({ data: { email: '[email removed]' } })
  await tx.post.create({ data: { title: 'Hi', authorId: u.id } })
})

Tip

All of these queries are statically typed. If you select a subset of fields, the result type only includes those fields, and accessing a field that doesn't exist is a compile-time error.

10. Supported Databases

Prisma ORM supports the following databases. Set the matching provider in your datasource block and install the corresponding driver adapter.

Default connection-string shapes generated by prisma init:

postgresql  postgresql://johndoe:randompassword@localhost:5432/mydb?schema=public
mysql       mysql://johndoe:randompassword@localhost:3306/mydb
sqlserver   sqlserver://localhost:1433;database=mydb;user=SA;password=randompassword;
mongodb     mongodb+srv://root:[email removed]/mydb
sqlite      file:./dev.db
cockroachdb postgresql://johndoe:randompassword@localhost:26257/mydb?schema=public

Note

Some connection-string query parameters (such as schema, connection_limit, pool_timeout, pgbouncer, socket_timeout) are Prisma-specific and are stripped before being handed to the underlying driver. This is expected behavior.

11. Troubleshooting

Error: P1001 — Can't reach database server

Cause: Prisma cannot open a TCP connection to the database at the host/port in your connection string.

Solution: Verify the database is running and reachable, and that DATABASE_URL (host, port, credentials) is correct. For cloud databases, confirm your IP is allowlisted.

Prevention: Use prisma debug to confirm which environment variables are set, and test connectivity before deploying.

Error: P1003 — Database does not exist

Cause: The connection succeeds but the named database/schema does not exist (commonly seen during db pull).

Solution: Create the database, or point DATABASE_URL at an existing one. migrate dev, db push, and migrate deploy will attempt to create the database automatically if it is missing.

Error: P1012 — Schema validation/parsing failed

Cause: Your schema.prisma is invalid (syntax error, unknown attribute, broken relation).

Solution: Run npx prisma validate (or use the Prisma VS Code extension) to see exactly what is wrong, fix it, and re-run. During db pull, you can pass --force to overwrite the broken local schema with a fresh introspection (local edits will be lost).

Error: P4001 — The introspected database was empty

Cause: prisma db pull ran against a database with no tables, so no models could be created.

Solution: Create at least one table in the database, or point at a non-empty database, then re-run prisma db pull.

prisma migrate dev wants to reset my database

Cause: Your local migration history has diverged from the database state (drift), so Prisma cannot apply migrations cleanly.

Solution: In development, allow the reset (all data is lost) or investigate the drift. In production, never use migrate dev — use migrate deploy and resolve history issues with migrate resolve. Run prisma migrate status to diagnose.

prisma migrate status reports failed or diverged migrations

Cause: A migration failed partway, or the database's _prisma_migrations table differs from your local prisma/migrations folder.

Solution: Follow the exact prisma migrate resolve --applied <name> or --rolled-back <name> command that migrate status prints. See Recover from a failed migration.

db push warns about data loss

Cause: The schema change would drop a column/table or otherwise destroy data.

Solution: Review the warnings. If the loss is acceptable, confirm the prompt or pass --accept-data-loss. To start clean, use --force-reset (drops the whole database).

Studio fails on SQL Server or with an Accelerate URL

Cause: Prisma Studio requires a direct connection string. Accelerate URLs (prisma://, prisma+postgres://) are unsupported in Studio, and some providers have known Studio issues (see GitHub issue #29620 for MSSQL).

Solution: Use a direct database connection string for Studio. Check the Prisma issue tracker for provider-specific status.

$connect() succeeds even though the database is unreachable

Cause: With some driver adapters, the client establishes connections lazily, so $connect() may not fail immediately (see GitHub issues #28959, #25418).

Solution: Don't rely on $connect() to verify reachability. Issue a trivial query (e.g. SELECT 1) at startup if you need an eager connectivity check.

Unknown binaryTarget error

Cause: Prisma can't find a compatible engine binary for your platform/OS (e.g. a newer Node.js or OpenSSL version — see issue #29589).

Solution: Upgrade to the latest Prisma version, which ships updated binary targets. As a workaround you can set engine-related environment variables (see the reference) or specify binaryTargets in your generator block.

TypeScript compilation is slow with a large schema

Cause: Very large generated clients can stress the TypeScript compiler (issues #29011, #16418).

Solution: Keep your client up to date, split very large schemas where possible, and ensure skipLibCheck is enabled in your tsconfig.json.

12. FAQ

Q: Do I need to run prisma generate every time I change my schema? Yes. The generated client is derived from your data model, so re-run prisma generate (or use --watch) after any schema change to keep types in sync. migrate dev runs it for you automatically.

Q: Why does Prisma not read my .env file? By design, Prisma ORM does not auto-load .env. Import dotenv/config in your prisma.config.ts, run with node --env-file=.env / tsx --env-file=.env, or use Bun. The .env written by prisma init is a convenience, not an auto-loaded file.

Q: What is the difference between db push and migrate dev? db push syncs your schema directly to the database with no migration files — great for prototyping. migrate dev creates versioned SQL migration files and applies them — use it when you need a reproducible history for teams and production.

Q: What is the difference between migrate dev and migrate deploy? migrate dev is for development: it creates migrations, may prompt, and may reset. migrate deploy is for production/staging: it only applies already-created migrations, never prompts, and never resets.

Q: How do I use Prisma with an existing database? Run prisma db pull to introspect the database into your schema, then prisma generate. To start tracking migrations, baseline with prisma migrate resolve --applied <initial_migration>.

Q: Do I really need a driver adapter in v7? Yes. In v7 you pass an adapter (e.g. new PrismaPg({ connectionString })) to the PrismaClient constructor. Install the adapter package matching your database.

Q: What databases does Prisma support? PostgreSQL, Prisma Postgres, MySQL/MariaDB, SQLite, SQL Server, MongoDB, and CockroachDB. See Supported Databases.

Q: How do I get a database quickly for development? Run npx prisma dev for a local Prisma Postgres server (no Docker), or npx create-db for a free cloud Prisma Postgres database.

Q: Can I run Prisma on serverless or edge runtimes? Yes — use the serverless/edge driver adapters such as @prisma/adapter-neon, @prisma/adapter-planetscale, or @prisma/adapter-d1 (Cloudflare D1).

Q: How do I generate typed SQL for raw queries? Run prisma generate --sql to generate a typed SQL module from .sql files, giving you type-safe raw queries.

Q: Where are migration files stored, and can I change that? By default in prisma/migrations. Override it with migrations.path in prisma.config.ts.

Q: How do I see which Prisma and engine versions I'm running? Run prisma version (or prisma -v), optionally with --json. For a fuller environment dump useful in bug reports, run prisma debug.

Q: How do I silence the "update available" message? Set the PRISMA_HIDE_UPDATE_MESSAGE environment variable. Use PRISMA_DISABLE_WARNINGS to hide warnings and PRISMA_HIDE_PREVIEW_FLAG_WARNINGS to hide preview-feature warnings.

Q: I'm running a destructive command inside an AI coding agent and it asks for extra confirmation. Why? Prisma adds an extra safety checkpoint for destructive commands (migrate reset, db push --force-reset, db drop) when it detects it is running inside an AI agent environment. This is intentional — confirm only if you really intend to lose data.

13. Command Reference

Global flags available on most commands: --help / -h, --config <path>, --schema <path>. Top-level flags: --version / -v, --preview-feature.

Note

prisma db drop exists but is a Preview command — you must opt in with --preview-feature and it requires --force (or an interactive confirmation) because it deletes the database.

14. Environment Variable Reference

These variables are read by the Prisma CLI and runtime. Run prisma debug to see which are currently set.

Tip

For a complete, current list of Prisma environment variables, run npx prisma debug — it prints every variable Prisma inspects along with whether it is currently set.