Prisma

Prisma ORM AI Skill Guide

Overview & Engine Architecture

Prisma maps a declarative schema.prisma to a generated TypeScript client. Migrations evolve the database; the client provides type-safe queries. Agents treat schema as source of truth, never edit prod schema by hand, use transactions for multi-step writes, and select only needed fields/relations to control payload size and N+1 risk.

schema.prisma -> migrate -> database
       \
        -> prisma generate -> @prisma/client
                              |
                         app query layer

When to use this skill

• Modeling data and relations in Prisma
• Creating and applying migrations safely
• Writing typed queries and transactions
• Debugging client validation vs DB constraint errors

Operational directives

1. Change schema -> migrate dev (local) / migrate deploy (CI/prod) - do not drift.
2. Use include / select intentionally; default wide includes hide cost.
3. Wrap multi-model writes in $transaction.
4. Keep a single PrismaClient instance (avoid new client per request in serverless without care).
5. Never commit .env with production DATABASE_URL.

Schema + query sketch

model Item {
  id        String   @id @default(cuid())
  sku       String   @unique
  qty       Int      @default(0)
  createdAt DateTime @default(now())
  ownerId   String
  owner     User     @relation(fields: [ownerId], references: [id])
}

model User {
  id    String @id @default(cuid())
  email String @unique
  items Item[]
}

import { PrismaClient } from "@prisma/client";

const prisma = new PrismaClient();

export async function createItem(ownerId: string, sku: string, qty: number) {
  return prisma.item.create({
    data: { ownerId, sku, qty },
    select: { id: true, sku: true, qty: true },
  });
}

export async function listOwnerItems(ownerId: string) {
  return prisma.item.findMany({
    where: { ownerId },
    orderBy: { createdAt: "desc" },
    take: 50,
  });
}

Commands

npx prisma init
npx prisma migrate dev --name add_items
npx prisma generate
npx prisma studio
npx prisma migrate deploy

Common pitfalls

Best practices

• Use connection pooling (PgBouncer / Prisma Accelerate) for serverless.
• Add DB-level constraints that match schema uniqueness/FKs.
• Prefer migrate diff in CI to detect schema drift.
• Seed deterministic fixtures for tests; reset carefully.

Limitations

• Raw SQL is still needed for complex reports and some locks.
• Multi-schema and exotic DB features vary by provider support.
• Prisma Accelerate / Pulse features are optional paid platform pieces.

Related skills

• @nodejs / @typescript - runtime hosting the client
• @supabase / @supabase-rls - Postgres + RLS alongside Prisma
• @graphql-apis - Prisma under GraphQL resolvers