Prisma 6 Migration Guide

This skill guides you through upgrading from Prisma 5 to Prisma 6, handling all breaking changes systematically to prevent runtime failures and type errors.

1. •Buffer → Uint8Array: Bytes fields now use Uint8Array instead of Buffer
2. •Implicit m-n PKs: Many-to-many join tables now use compound primary keys
3. •NotFoundError → P2025: Error class removed, use error code checking
4. •Reserved Keywords: async, await, using are now reserved model/field names

Attempting to use Prisma 6 without these updates causes type errors, runtime failures, and migration issues. </overview>

Phase 1: Pre-Migration Assessment

1. •

   Identify all Bytes fields in schema

   • •Use Grep to find @db.ByteA, Bytes field types
   • •List all files using Buffer operations on Bytes fields
2. •

   Find implicit many-to-many relationships

   • •Search schema for relation fields without explicit join tables
   • •Identify models with @relation without relationName
3. •

   Locate NotFoundError usage

   • •Grep for NotFoundError imports and usage
   • •Find error handling that checks error class
4. •

   Check for reserved keywords

   • •Search schema for models/fields named async, await, using

Phase 2: Schema Migration

1. •

   Update reserved keywords in schema

   • •Rename any models/fields using reserved words
   • •Update all references in application code
2. •

   Generate migration for implicit m-n changes

   • •Run npx prisma migrate dev --name v6-implicit-mn-pks
   • •Review generated SQL for compound primary key changes

Phase 3: Code Migration

1. •

   Update Buffer → Uint8Array conversions

   • •Replace Buffer.from() with TextEncoder
   • •Replace .toString() with TextDecoder
   • •Update type annotations from Buffer to Uint8Array
2. •

   Update NotFoundError handling

   • •Replace error class checks with P2025 code checks
   • •Use isPrismaClientKnownRequestError type guard
3. •

   Test all changes

   • •Run existing tests
   • •Verify Bytes field operations
   • •Confirm error handling works correctly

Phase 4: Validation

1. •

   Run TypeScript compiler

   • •Verify no type errors remain
   • •Check all Buffer references resolved
2. •

   Run database migrations

   • •Apply migrations to test database
   • •Verify compound PKs created correctly
3. •

   Runtime testing

   • •Test Bytes field read/write operations
   • •Verify error handling catches not-found cases
   • •Confirm implicit m-n queries work </workflow>

Quick Reference

Breaking Changes Summary:

Migration Command:

npx prisma migrate dev --name v6-upgrade

Validation Commands:

npx tsc --noEmit
npx prisma migrate status
npm test

MUST:

• •Backup production database before migration
• •Test migration in development/staging first
• •Review auto-generated migration SQL
• •Update all Buffer operations to TextEncoder/TextDecoder
• •Replace all NotFoundError checks with P2025 code checks
• •Run TypeScript compiler to verify no type errors

SHOULD:

• •Create helper functions for common error checks
• •Use @map() when renaming reserved keywords
• •Document breaking changes in commit messages
• •Update team documentation about Prisma 6 patterns

NEVER:

• •Run migrations directly in production without testing
• •Skip TypeScript compilation check
• •Leave Buffer references in code (causes type errors)
• •Use NotFoundError (removed in Prisma 6)
• •Use async, await, using as model/field names without @map() </constraints>

After completing migration:

1. •

   TypeScript Compilation:

   • •Run: npx tsc --noEmit
   • •Expected: Zero type errors
   • •If fails: Check remaining Buffer references, NotFoundError usage
2. •

   Database Migration Status:

   • •Run: npx prisma migrate status
   • •Expected: All migrations applied
   • •If fails: Apply pending migrations with npx prisma migrate deploy
3. •

   Runtime Testing:

   • •Test Bytes field write/read cycle
   • •Verify error handling catches P2025 correctly
   • •Test implicit m-n relationship queries
   • •Confirm no runtime errors in production-like environment
4. •

   Performance Check:

   • •Verify query performance unchanged
   • •Check connection pool behavior
   • •Monitor error rates in logs
5. •

   Rollback Readiness:

   • •Document rollback steps
   • •Keep Prisma 5 migration snapshot
   • •Test rollback procedure in staging </validation>

References

For detailed migration guides and examples:

• •Breaking Changes Details: See references/breaking-changes.md for complete API migration patterns, SQL examples, and edge cases
• •Migration Examples: See references/migration-examples.md for real-world migration scenarios with before/after code
• •Migration Checklist: See references/migration-checklist.md for step-by-step migration tasks
• •Troubleshooting Guide: See references/troubleshooting.md for common migration issues and solutions

For framework-specific migration patterns:

• •Next.js Integration: Consult Next.js plugin for App Router-specific Prisma 6 patterns
• •Serverless Deployment: See CLIENT-serverless-config skill for Prisma 6 + Lambda/Vercel

For error handling patterns:

• •Error Code Reference: See TRANSACTIONS-error-handling skill for comprehensive P-code handling