prisma

Model data with Prisma, manage migrations and transactions, and review relation queries for N+1 behavior.

SKILL.md

GitHub

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

Pitfall Why it hurts Fix
Editing DB without migration Environment drift Migrate always
Nested writes without tx Partial commits $transaction
Fetching entire graphs Memory/latency select / paginate
Multiple clients in serverless Exhausted connections Singleton + pooler

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