Prisma Migration Skill

Critical Rules

1. •NEVER edit files in /apps/agent-api/prisma/migrations/ directly - This is a "do not touch" zone per CLAUDE.md
2. •Always use Prisma CLI commands for migrations
3. •Run typecheck after migrations to ensure Prisma client types are updated

Before Any Schema Change

1. •Check the current schema at /apps/agent-api/prisma/schema.prisma
2. •Review existing models and relationships
3. •Plan changes carefully - migrations are permanent

Migration Workflow

Development Migration

# Generate migration and apply to dev database
pnpm --filter apps-agent-api prisma migrate dev --name <descriptive-name>

# Regenerate Prisma client after schema changes
pnpm --filter apps-agent-api prisma generate

Production Migration

# Apply pending migrations to production
pnpm --filter apps-agent-api prisma migrate deploy

After Migration

# Verify types are correct
pnpm typecheck

Naming Conventions

Best Practices

Indexes

Always include @@index for frequently queried fields:

model Agent {
  id          String @id @default(cuid())
  workspaceId String
  name        String

  @@index([workspaceId])
}

Soft Delete Pattern

Use for user-facing entities:

model User {
  id        String    @id @default(cuid())
  deletedAt DateTime?
}

Cascade Delete

Configure appropriately:

model Agent {
  workspace Workspace @relation(fields: [workspaceId], references: [id], onDelete: Cascade)
}

Troubleshooting

Related Files

• •Schema: /apps/agent-api/prisma/schema.prisma
• •Migrations: /apps/agent-api/prisma/migrations/ (read-only)
• •Seed: /apps/agent-api/prisma/seed.ts