📖 Guide
Prisma — Complete Reference
Complete Prisma ORM cheat sheet — schema, queries, migrations, and CLI.
85 commands across 10 categories
CLI CommandsSchemaModels & FieldsRelationsQueries (CRUD)Filtering & SortingAggregationsMigrationsSeedingCommon Patterns
CLI Commands
| Command | Description |
|---|---|
npx prisma init | Initialize Prisma in your project with a schema file and .env |
npx prisma generate | Generate Prisma Client based on your schema |
npx prisma db push | Push schema changes directly to the database without migrations |
npx prisma db pull | Introspect the database and update your schema file |
npx prisma migrate dev --name init | Create and apply a new migration in development |
npx prisma migrate deploy | Apply pending migrations in production |
npx prisma studio | Open Prisma Studio GUI to browse and edit data |
npx prisma validate | Validate the Prisma schema file for errors |
npx prisma format | Format the Prisma schema file |
npx prisma db seed | Run the seed script defined in package.json |
Schema
| Command | Description |
|---|---|
datasource db {
provider = "postgresql"
url = env("DATABASE_URL")
} | Define the database connection |
generator client {
provider = "prisma-client-js"
} | Configure the Prisma Client generator |
provider = "postgresql" | PostgreSQL provider (also: mysql, sqlite, sqlserver, mongodb, cockroachdb) |
url = env("DATABASE_URL") | Read database URL from environment variable |
shadowDatabaseUrl = env("SHADOW_DATABASE_URL") | Shadow database for migration diffing (required for some hosted DBs) |
previewFeatures = ["fullTextSearch"] | Enable preview features in the generator block |
binaryTargets = ["native", "linux-musl"] | Specify binary targets for deployment (e.g., Docker) |
enum Role {
USER
ADMIN
} | Define an enum type in the schema |
Models & Fields
| Command | Description |
|---|---|
id Int @id @default(autoincrement()) | Auto-incrementing integer primary key |
id String @id @default(cuid()) | CUID string primary key |
id String @id @default(uuid()) | UUID string primary key |
email String @unique | Unique constraint on a field |
name String @default("Unknown") | Field with a default value |
createdAt DateTime @default(now()) | Timestamp defaulting to creation time |
updatedAt DateTime @updatedAt | Automatically updated timestamp |
bio String? | Optional (nullable) field |
@@index([email, name]) | Composite index on multiple fields |
@@unique([firstName, lastName]) | Composite unique constraint |
Relations
| Command | Description |
|---|---|
posts Post[] | One-to-many: User has many Posts |
author User @relation(fields: [authorId], references: [id])
authorId Int | Many-to-one: Post belongs to User |
profile Profile?
user User @relation(fields: [userId], references: [id])
userId Int @unique | One-to-one relation (unique foreign key) |
categories Category[] @relation("PostCategories")
posts Post[] @relation("PostCategories") | Implicit many-to-many relation |
@relation(onDelete: Cascade) | Cascade delete when parent is removed |
@relation(onDelete: SetNull) | Set foreign key to null on parent delete |
writtenPosts Post[] @relation("WrittenPosts")
editedPosts Post[] @relation("EditedPosts") | Multiple relations between same models using named relations |
@@map("comments") | Map model name to a different database table name |
Queries (CRUD)
| Command | Description |
|---|---|
prisma.user.findUnique({ where: { id: 1 } }) | Find a single record by unique field |
prisma.user.findFirst({ where: { name: "Alice" } }) | Find the first matching record |
prisma.user.findMany() | Find all records (supports filtering, sorting, pagination) |
prisma.user.create({ data: { name: "Alice", email: "a@b.com" } }) | Create a new record |
prisma.user.update({ where: { id: 1 }, data: { name: "Bob" } }) | Update a record by unique field |
prisma.user.upsert({ where: { email: "a@b.com" }, update: { name: "Alice" }, create: { name: "Alice", email: "a@b.com" } }) | Create or update a record |
prisma.user.delete({ where: { id: 1 } }) | Delete a record by unique field |
prisma.user.createMany({ data: [{ name: "A" }, { name: "B" }] }) | Create multiple records in one query |
prisma.user.deleteMany({ where: { active: false } }) | Delete multiple records matching a condition |
prisma.user.updateMany({ where: { role: "USER" }, data: { verified: true } }) | Update multiple records matching a condition |
Filtering & Sorting
| Command | Description |
|---|---|
where: { name: { contains: "ali", mode: "insensitive" } } | Case-insensitive substring search |
where: { age: { gte: 18, lte: 65 } } | Range filter (gte, gt, lte, lt) |
where: { email: { startsWith: "admin" } } | Starts with filter (also: endsWith) |
where: { role: { in: ["ADMIN", "EDITOR"] } } | Filter by list of values (also: notIn) |
where: { OR: [{ name: "Alice" }, { name: "Bob" }] } | OR condition across multiple filters |
where: { NOT: { role: "ADMIN" } } | Negate a condition |
orderBy: { createdAt: "desc" } | Sort results by a field |
orderBy: [{ role: "asc" }, { name: "asc" }] | Sort by multiple fields |
skip: 10, take: 5 | Pagination with offset and limit |
cursor: { id: 100 }, take: 10 | Cursor-based pagination |
Aggregations
| Command | Description |
|---|---|
prisma.user.count() | Count all records |
prisma.user.count({ where: { active: true } }) | Count records matching a condition |
prisma.post.aggregate({ _avg: { views: true }, _sum: { views: true } }) | Aggregate: average and sum |
prisma.post.aggregate({ _min: { createdAt: true }, _max: { createdAt: true } }) | Aggregate: min and max values |
prisma.post.groupBy({ by: ["authorId"], _count: { id: true } }) | Group by a field with count |
prisma.post.groupBy({ by: ["category"], _sum: { views: true }, orderBy: { _sum: { views: "desc" } } }) | Group by with ordering |
prisma.user.findMany({ select: { name: true, email: true } }) | Select specific fields only |
prisma.user.findMany({ include: { posts: true } }) | Include related records in the result |
Migrations
| Command | Description |
|---|---|
npx prisma migrate dev --name add_users_table | Create a new migration and apply it |
npx prisma migrate dev --create-only | Create migration SQL without applying it |
npx prisma migrate deploy | Apply all pending migrations (production) |
npx prisma migrate reset | Reset database: drop, recreate, apply all migrations, run seed |
npx prisma migrate status | Check the status of migrations |
npx prisma migrate resolve --applied 20240101000000_init | Mark a migration as applied (fix drift) |
npx prisma db execute --file ./fix.sql | Execute raw SQL file against the database |
Seeding
| Command | Description |
|---|---|
"prisma": { "seed": "ts-node prisma/seed.ts" } | Configure seed command in package.json |
npx prisma db seed | Run the seed script |
await prisma.user.createMany({ data: users, skipDuplicates: true }) | Seed with skipDuplicates to avoid errors on re-run |
await prisma.user.upsert({ where: { email: "admin@test.com" }, update: {}, create: { ... } }) | Idempotent seeding with upsert |
const { PrismaClient } = require("@prisma/client")
const prisma = new PrismaClient() | Initialize Prisma Client in seed file |
await prisma.$disconnect() | Disconnect client at the end of the seed script |
Common Patterns
| Command | Description |
|---|---|
prisma.$transaction([query1, query2]) | Run multiple queries in a transaction |
prisma.$transaction(async (tx) => { ... }) | Interactive transaction with custom logic |
prisma.$queryRaw`SELECT * FROM users WHERE id = 1`e.g. Use Prisma.sql for parameterized queries | Execute raw SQL query |
prisma.user.findMany({ where: { posts: { some: { published: true } } } }) | Filter by related records (relation filters) |
prisma.post.create({ data: { title: "Hi", author: { connect: { id: 1 } } } }) | Connect an existing relation on create |
prisma.user.update({ where: { id: 1 }, data: { posts: { create: { title: "New" } } } }) | Create a related record via nested write |
const prisma = new PrismaClient({ log: ["query", "info", "warn", "error"] }) | Enable query logging |
prisma.$use(async (params, next) => { ... return next(params) }) | Middleware for intercepting queries |
📖 Free, searchable command reference. Bookmark this page for quick access.