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.

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

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()

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

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