---

name: handler-db-prisma description: Prisma-specific database operations handler model: claude-haiku-4-5

Prisma Database Handler Skill

This handler translates generic database operations into Prisma-specific CLI commands and manages Prisma client interactions.

<CRITICAL_RULES>

1. NEVER execute Prisma commands directly - ALWAYS use scripts
2. ALWAYS validate Prisma CLI is installed before operations
3. ALWAYS check prisma/schema.prisma exists for schema operations
4. ALWAYS output start/end messages for visibility
5. ALWAYS return structured JSON responses
6. NEVER expose database credentials in logs
7. ALWAYS validate connection string format
8. PRODUCTION SAFETY: Run prisma migrate deploy for production (not prisma migrate dev) </CRITICAL_RULES>

Example Request

Copy{
  "operation": "create-database",
  "parameters": {
    "database_name": "myapp_dev",
    "database_url_env": "DEV_DATABASE_URL",
    "working_directory": "/mnt/c/GitHub/myorg/myproject"
  }
}

Follow the workflow files in workflow/ for operation-specific instructions:

• workflow/create-database.md - Database creation workflow
• workflow/generate-migration.md - Migration generation workflow
• workflow/apply-migration.md - Migration deployment workflow
• workflow/check-status.md - Status checking workflow

High-level process:

1. Output start message with operation
2. Validate Prisma CLI is installed
3. Set working directory context (CLAUDE_DB_CWD)
4. Load configuration
5. Validate parameters for operation
6. Execute Prisma-specific operation via scripts
7. Validate operation results
8. Output end message with results
9. Return structured JSON response

Prisma CLI Commands Used:

• prisma init - Initialize Prisma in project
• prisma generate - Generate Prisma Client
• prisma migrate dev - Create and apply migration (dev)
• prisma migrate deploy - Apply migrations (production)
• prisma migrate status - Check migration status
• prisma migrate resolve - Resolve migration issues
• prisma db push - Push schema to database (prototyping)
• prisma db pull - Pull schema from database (introspection)

<COMPLETION_CRITERIA> You are complete when:

• Prisma CLI availability validated
• Operation-specific validation passed
• Prisma command executed successfully
• Results validated
• Success message output
• Structured JSON response returned

If any step fails:

• Log detailed error with Prisma output
• Suggest corrective actions
• Return error response with recovery steps </COMPLETION_CRITERIA>

Output structured messages:

Start:

Copy🎯 STARTING: Prisma Handler
Operation: create-database
Database: myapp_dev
───────────────────────────────────────

During execution, log key steps:

• ✓ Prisma CLI found (version 5.x.x)
• ✓ prisma/schema.prisma exists
• ✓ Database URL validated
• ✓ Creating database myapp_dev
• ✓ Running prisma migrate dev --name init
• ✓ Migration table created: _prisma_migrations
• ✓ Prisma Client generated

End (success):

Copy✅ COMPLETED: Prisma Handler
Operation: create-database
Database: myapp_dev
Migrations Applied: 1 (init)
Status: Ready
───────────────────────────────────────
Next: Add models to prisma/schema.prisma

Return JSON:

Success:

Copy{
  "status": "success",
  "operation": "create-database",
  "handler": "prisma",
  "result": {
    "database_name": "myapp_dev",
    "prisma_version": "5.8.0",
    "schema_path": "prisma/schema.prisma",
    "migrations_applied": 1,
    "migration_table": "_prisma_migrations",
    "client_generated": true
  },
  "message": "Database created and Prisma initialized successfully"
}

Error:

Copy{
  "status": "error",
  "operation": "create-database",
  "handler": "prisma",
  "error": "Prisma CLI not found",
  "recovery": {
    "suggestions": [
      "Install Prisma: npm install -D prisma @prisma/client",
      "Or use different migration tool: /faber-db:init --migration-tool typeorm"
    ],
    "prisma_docs": "https://www.prisma.io/docs/getting-started"
  }
}

<ERROR_HANDLING>

Common errors and handling:

Prisma CLI Not Found:

Copy{
  "status": "error",
  "error": "Prisma CLI not found in project",
  "recovery": {
    "suggestions": [
      "Install Prisma: npm install -D prisma @prisma/client",
      "Verify package.json has prisma in devDependencies",
      "Run npm install to install dependencies"
    ]
  }
}

Schema File Missing:

Copy{
  "status": "error",
  "error": "prisma/schema.prisma not found",
  "recovery": {
    "suggestions": [
      "Initialize Prisma: npx prisma init",
      "Or create schema file manually in prisma/ directory",
      "See: https://www.prisma.io/docs/concepts/components/prisma-schema"
    ]
  }
}

Migration Failed:

Copy{
  "status": "error",
  "error": "Migration failed: duplicate column name",
  "prisma_output": "Error: P3005 The database schema is not empty...",
  "recovery": {
    "suggestions": [
      "Review migration file: prisma/migrations/.../migration.sql",
      "Check for conflicting changes",
      "Reset database: npx prisma migrate reset (WARNING: data loss)",
      "Or manually fix schema and retry"
    ]
  }
}

Connection Failed:

Copy{
  "status": "error",
  "error": "Database connection failed",
  "prisma_output": "Error: P1001 Can't reach database server...",
  "recovery": {
    "suggestions": [
      "Verify DATABASE_URL environment variable is set correctly",
      "Check database server is running",
      "Test connection: psql $DATABASE_URL",
      "Verify firewall rules allow connection"
    ]
  }
}

</ERROR_HANDLING>

Prisma CLI Integration

All operations execute Prisma CLI commands via scripts:

Scripts Location: skills/handler-db-prisma/scripts/

• create-database.sh - Database initialization
• generate-migration.sh - Migration generation
• apply-migration.sh - Migration deployment
• check-status.sh - Status checking
• validate-schema.sh - Schema validation

Prisma Files Managed:

• prisma/schema.prisma - Database schema definition
• prisma/migrations/ - Migration history
• .env - Connection strings (not committed)
• node_modules/.prisma/client/ - Generated Prisma Client

Environment Variables

Prisma uses DATABASE_URL environment variable:

Copyexport DATABASE_URL="postgresql://user:password@localhost:5432/myapp_dev"

This handler maps environment-specific variables to DATABASE_URL before Prisma operations:

Copy# Map DEV_DATABASE_URL to DATABASE_URL for Prisma
export DATABASE_URL="${DEV_DATABASE_URL}"
npx prisma migrate dev

Operation-Specific Notes

Create Database

• Runs prisma init if schema doesn't exist
• Creates database using prisma migrate dev --name init
• Generates Prisma Client with prisma generate
• Validates migration table exists

Generate Migration

• Runs prisma migrate dev --name <name> for dev
• Creates migration file in prisma/migrations/<timestamp>_<name>/
• Includes both migration.sql and metadata

Apply Migration (Production)

• Uses prisma migrate deploy (NOT migrate dev)
• Applies pending migrations only
• No interactive prompts
• Idempotent (safe to run multiple times)

Check Status

• Runs prisma migrate status
• Shows pending migrations
• Shows applied migrations
• Detects drift between schema and database

Rollback Migration

• Prisma doesn't have built-in rollback
• Must manually write down migrations
• Or use custom rollback logic with raw SQL

Prisma Versions Supported

Minimum Version: Prisma 4.0.0 Recommended Version: Prisma 5.x.x Tested Version: Prisma 5.8.0

Version checked at runtime and reported in output.