What Is Prisma? The Complete Guide for AI-Assisted Developers

Why AI Coders Need to Know This

Prisma is the most downloaded TypeScript ORM with over 6 million weekly npm downloads. In 2025, it became the default database layer for AI-generated Next.js, Remix, and Express TypeScript projects. When you ask Claude Code or Cursor to "add a database" to a TypeScript app, the response is overwhelmingly likely to include a prisma/schema.prisma file.

The problem: Prisma has a specific workflow that many vibe coders skip, and skipping steps causes confusing errors. The sequence is rigid:

1. Edit schema.prisma
2. Run npx prisma migrate dev (updates the database AND regenerates the client)
3. Use prisma.model.method() in your code

Break that sequence — edit the schema but forget to migrate, or use a client method before generating — and you get errors that look unrelated to what you actually did wrong. Understanding Prisma's three components prevents hours of debugging.

The Three Prisma Components

1. Prisma Schema

The prisma/schema.prisma file is the single source of truth for your database structure. It has three sections:

// prisma/schema.prisma

// 1. Generator — what to generate (the JS/TS client)
generator client {
  provider = "prisma-client-js"
}

// 2. Datasource — which database and how to connect
datasource db {
  provider = "postgresql"  // or "mysql", "sqlite", "sqlserver"
  url      = env("DATABASE_URL")
}

// 3. Models — your data structure (becomes database tables)
model User {
  id        Int      @id @default(autoincrement())
  email     String   @unique
  name      String?  // ? means optional (nullable)
  role      Role     @default(USER)  // enum reference
  posts     Post[]   // relation: one user has many posts
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt  // auto-updates on every save
}

model Post {
  id        Int      @id @default(autoincrement())
  title     String
  content   String?
  published Boolean  @default(false)
  author    User     @relation(fields: [authorId], references: [id])
  authorId  Int
  createdAt DateTime @default(now())

  @@index([authorId])
}

enum Role {
  USER
  ADMIN
  MODERATOR
}

2. Prisma Migrate

Migrations are version-controlled SQL scripts that transform your database to match the schema. The key commands:

# Create a migration and apply it to the database
npx prisma migrate dev --name add_user_table

# Apply pending migrations in production (no new migrations created)
npx prisma migrate deploy

# Reset the database and apply all migrations from scratch
npx prisma migrate reset

# Sync schema to DB without migration files (development only)
npx prisma db push

# Pull existing database schema into Prisma schema
npx prisma db pull

# Open Prisma Studio (visual database browser)
npx prisma studio

When you run migrate dev, Prisma compares your current schema to the last migration, generates SQL to make the database match, and runs it. It also runs prisma generate automatically so your client is always in sync.

3. Prisma Client

The Client is auto-generated TypeScript code that gives you methods for every model. After migration, your editor autocompletes every query:

import { PrismaClient } from '@prisma/client';
const prisma = new PrismaClient();

// findMany — get multiple records
const users = await prisma.user.findMany({
  where: { role: 'ADMIN' },
  orderBy: { createdAt: 'desc' },
  take: 10,  // LIMIT 10
  skip: 0    // OFFSET 0
});

// findUnique — get exactly one by unique field
const user = await prisma.user.findUnique({
  where: { email: 'chuck@example.com' },
  include: { posts: true }  // JOIN with posts
});

// create — insert a new record
const newUser = await prisma.user.create({
  data: {
    name: 'Chuck',
    email: 'chuck@example.com',
    posts: {
      create: [{ title: 'My First Post' }]  // Nested create
    }
  }
});

// update — modify an existing record
const updated = await prisma.user.update({
  where: { id: 1 },
  data: { name: 'Charles' }
});

// delete — remove a record
await prisma.user.delete({ where: { id: 1 } });

Real Scenario

Set up Prisma with PostgreSQL for a blog app:
- User model with name, email (unique), role (USER/ADMIN), createdAt
- Post model with title, content, published, authorId (relates to User)
- Show me the full setup: schema, .env, migration command, and singleton client
- Give me example queries for creating a user with a post, and fetching all
  published posts with author names

The Singleton Pattern (Critical for Next.js)

This is the most important Prisma pattern for AI-generated Next.js apps. Without it, you will hit "too many connections" errors:

// lib/prisma.ts — use this everywhere instead of new PrismaClient()
import { PrismaClient } from '@prisma/client';

const globalForPrisma = globalThis as unknown as {
  prisma: PrismaClient | undefined;
};

export const prisma =
  globalForPrisma.prisma ??
  new PrismaClient({
    log: process.env.NODE_ENV === 'development'
      ? ['query', 'error', 'warn']
      : ['error'],
  });

if (process.env.NODE_ENV !== 'production') {
  globalForPrisma.prisma = prisma;
}

Why this matters: Next.js hot reloads during development. Each reload would create a new PrismaClient instance, opening a new database connection. With the singleton pattern, the client is stored on globalThis and reused across reloads.

What AI Gets Wrong About Prisma

Forgetting to run migrate after schema changes

The most common Prisma workflow error. AI edits schema.prisma but does not remind you to run npx prisma migrate dev. Your code uses prisma.newModel.findMany() but the table does not exist yet. Error: "table does not exist" or "unknown field."

Rule: Schema change → always run npx prisma migrate dev.

Creating PrismaClient in API routes

AI generates const prisma = new PrismaClient() inside API route files. This creates a new connection on every request. Use the singleton pattern from a shared lib/prisma.ts file instead.

Migration drift in production

AI uses prisma db push in examples because it is faster to type. If you use db push in development but need migrate deploy in production, the migration history is incomplete and production deploys fail. Establish migrate dev early and stick with it.

Missing environment variable

AI generates schema and queries but the app fails with "Environment variable not found: DATABASE_URL." Make sure your .env file exists at the project root (not inside prisma/) and contains:

DATABASE_URL="postgresql://user:password@localhost:5432/mydb"

Cascading delete issues

If a Post belongs to a User, deleting the User fails if posts still exist (foreign key constraint). AI does not always add cascade behavior. Fix with:

model Post {
  author   User  @relation(fields: [authorId], references: [id], onDelete: Cascade)
  authorId Int
}

Common Prisma Errors and Fixes

• P2002 Unique constraint failed: You are trying to insert a duplicate value in a unique field (like email). Check for existing records first.
• P2025 Record not found: findUnique or update where clause matched nothing. The record does not exist.
• P1001 Cannot reach database: The database server is not running or the connection string is wrong. Check your DATABASE_URL and database status.
• P3006 Migration failed: The SQL migration had an error (often trying to add NOT NULL column to table with data). Read the migration file and fix the SQL.
• Type errors on prisma.model: You changed the schema but did not regenerate the client. Run npx prisma generate.

What to Learn Next

• What Is an ORM? — The broader concept Prisma implements.
• What Is PostgreSQL? — Prisma's most common database target.
• What Is SQL? — The language Prisma generates under the hood.
• What Are Environment Variables? — How DATABASE_URL works.

FAQ