prisma-helper

What this skill does

# Prisma Helper Agent

## What's New in Prisma 7+ (2025)

- **New `prisma-client` generator**: Replaces deprecated `prisma-client-js` with better ESM/Bun/Deno support
- **All-TypeScript engine**: Faster, lighter ORM without Rust binary engines
- **TypedSQL**: Write `.sql` files with full type safety (v5.19.0+)
- **`createManyAndReturn()`** and **`updateManyAndReturn()`**: Bulk operations returning results
- **`omit`**: Exclude fields from queries (opposite of `select`)
- **Relation load strategies**: Choose between `join` or `query` loading

## Core Concepts

Prisma consists of three main components:

1. **Prisma Schema**: Data model definition (models, relations, attributes)
2. **Prisma Migrate**: Database migration workflow
3. **Prisma Client**: Type-safe query builder

## CLI Commands

| Command                            | Purpose                                   |
| ---------------------------------- | ----------------------------------------- |
| `prisma init`                      | Initialize Prisma in project              |
| `prisma generate`                  | Generate Prisma Client from schema        |
| `prisma migrate dev --name <name>` | Create and apply migration (development)  |
| `prisma migrate deploy`            | Apply pending migrations (production)     |
| `prisma db push`                   | Push schema to database without migration |
| `prisma db pull`                   | Introspect database and update schema     |
| `prisma studio`                    | Open visual database editor               |
| `prisma format`                    | Format schema file                        |

## Schema Definition

### Generator Configuration

**Prisma 5.x/6.x (current stable):**

```prisma
generator client {
  provider = "prisma-client-js"
}
```

**Prisma 7+ (new format with runtime options):**

```prisma
generator client {
  provider = "prisma-client"   // replaces "prisma-client-js"
  output   = "./generated/client"
  runtime  = "bun"             // nodejs, deno, bun, workerd
  moduleFormat = "esm"         // esm or cjs
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}
```

### Model Definition

```prisma
model User {
  id        Int      @id @default(autoincrement())
  email     String   @unique
  name      String?
  posts     Post[]
  profile   Profile?
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  @@index([email])
  @@map("users")
}

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

  @@index([authorId])
}
```

### Field Attributes

| Attribute    | Purpose                    | Example                               |
| ------------ | -------------------------- | ------------------------------------- |
| `@id`        | Primary key                | `id Int @id`                          |
| `@@id`       | Composite primary key      | `@@id([a, b])`                        |
| `@unique`    | Unique constraint          | `email String @unique`                |
| `@@unique`   | Compound unique            | `@@unique([firstName, lastName])`     |
| `@default`   | Default value              | `@default(now())`, `@default(uuid())` |
| `@updatedAt` | Auto-update timestamp      | `updatedAt DateTime @updatedAt`       |
| `@relation`  | Define relationship        | See relations section                 |
| `@map`       | Map to database column     | `@map("user_name")`                   |
| `@@map`      | Map to database table      | `@@map("users")`                      |
| `@@index`    | Database index             | `@@index([title, content])`           |
| `@ignore`    | Exclude from Prisma Client | `legacyField String @ignore`          |

### Default Value Functions

| Function             | Purpose                   |
| -------------------- | ------------------------- |
| `autoincrement()`    | Auto-incrementing integer |
| `uuid()` / `uuid(7)` | UUID generation           |
| `cuid()` / `cuid(2)` | CUID generation           |
| `ulid()`             | ULID generation           |
| `nanoid(length)`     | Nano ID generation        |
| `now()`              | Current timestamp         |
| `dbgenerated(expr)`  | Database-level default    |

## Relations

### One-to-One

```prisma
model User {
  id      Int      @id @default(autoincrement())
  profile Profile?
}

model Profile {
  id     Int  @id @default(autoincrement())
  userId Int  @unique
  user   User @relation(fields: [userId], references: [id])
}
```

### One-to-Many

```prisma
model User {
  id    Int    @id @default(autoincrement())
  posts Post[]
}

model Post {
  id       Int  @id @default(autoincrement())
  authorId Int
  author   User @relation(fields: [authorId], references: [id])
}
```

### Many-to-Many (Implicit)

```prisma
model Post {
  id         Int        @id @default(autoincrement())
  categories Category[]
}

model Category {
  id    Int    @id @default(autoincrement())
  posts Post[]
}
```

### Referential Actions

```prisma
@relation(fields: [authorId], references: [id], onDelete: Cascade, onUpdate: Cascade)
```

Options: `Cascade`, `Restrict`, `NoAction`, `SetNull`, `SetDefault`

## Prisma Client Queries

### CRUD Operations

```typescript
// Create
const user = await prisma.user.create({
  data: { email: '[email protected]', name: 'User' }
})

// Create with relation
const userWithPosts = await prisma.user.create({
  data: {
    email: '[email protected]',
    posts: {
      create: [{ title: 'Post 1' }, { title: 'Post 2' }]
    }
  },
  include: { posts: true }
})

// Read
const user = await prisma.user.findUnique({ where: { id: 1 } })
const user = await prisma.user.findUniqueOrThrow({ where: { id: 1 } })
const users = await prisma.user.findMany({ where: { published: true } })
const first = await prisma.user.findFirst({ where: { name: { contains: 'John' } } })

// Update
const user = await prisma.user.update({
  where: { id: 1 },
  data: { name: 'Updated Name' }
})

// Upsert
const user = await prisma.user.upsert({
  where: { email: '[email protected]' },
  update: { name: 'Updated' },
  create: { email: '[email protected]', name: 'New' }
})

// Delete
await prisma.user.delete({ where: { id: 1 } })

// Bulk operations
await prisma.user.createMany({ data: [...], skipDuplicates: true })
await prisma.user.updateMany({ where: {...}, data: {...} })
await prisma.user.deleteMany({ where: {...} })
```

### Filtering

```typescript
// Comparison operators
where: { age: { gt: 18, lte: 65 } }
where: { name: { contains: 'john', mode: 'insensitive' } }
where: { email: { startsWith: 'admin', endsWith: '.com' } }
where: { id: { in: [1, 2, 3] } }
where: { id: { notIn: [4, 5, 6] } }

// Logical operators
where: { OR: [{ email: { contains: 'a' } }, { name: { contains: 'b' } }] }
where: { AND: [{ published: true }, { authorId: 1 }] }
where: { NOT: { email: { contains: 'test' } } }

// Relation filters
where: { posts: { some: { published: true } } }
where: { posts: { every: { published: true } } }
where: { posts: { none: { published: true } } }

// Null filtering
where: { profile: null }
where: { profile: { isNot: null } }
```

### Select and Include

```typescript
// Select specific fields
const user = await prisma.user.findUnique({
  where: { id: 1 },
  select: { id: true, email: true, posts: { select: { title: true } } },
});

// Include relations
const user = await prisma.user.findUnique({
  where: { id: 1 },
  include: { posts: true, profile: true },
});

// Omit fields (exclude sensitive data)
const user = await prisma.user.findUnique({
  where: { id: 1 },
  omit: { password: true },
});
```

### Pagination and Sorting

```typescript
// Pagination
const users = await prisma.user.findMany({
  skip: 10,
  take: 20,
  orderBy: { createdAt: 'desc' }
})

// Cursor-based pagination
const users = await prisma.user.findMany({
  take: 10,
  cursor: