Upgrade to v4

This guide helps you upgrade your project to Prisma ORM 4. Version 4 includes several important changes that may affect your application, so please review this guide carefully before proceeding.

Before you begin

• Back up your database before starting the upgrade
• Review the release notes for a complete list of changes
• Test the upgrade in a development or staging environment first
• Ensure you're using Node.js 14.17.0 or later (required for Prisma 4+)

Key changes

System requirements

• Minimum Node.js version: 14.17.0 or later
• Database versions: Check system requirements for database version compatibility

Breaking changes

1. Schema Changes

   • Explicit @unique constraints for one-to-one relations
   • Enforced @unique or @id for one-to-one and one-to-many relations in MySQL/MongoDB
   • Scalar list defaults
   • Index configuration improvements
   • Better string literal grammar

2. Client changes

   • queryRaw return type changes
   • JSON null handling updates
   • MongoDB composite type default fields
   • Removed deprecated APIs

Update packages

To upgrade to Prisma ORM 4 from an earlier version, you need to update both the prisma and @prisma/client packages:

npm install @prisma/client@4
npm install -D prisma@4
npx prisma generate

Upgrade steps

1. Update Schema: Review and update your schema to handle breaking changes
2. Update Application Code: Make necessary changes to your application code
3. Test Thoroughly: Test all functionality, especially:
   • One-to-one relations
   • JSON field operations
   • Raw queries
   • Index configurations

Update schema

Handle Schema Validation Errors

Run the following command to check for schema validation errors:

npx prisma validate

Address any validation errors, paying special attention to:

1. Explicit @unique constraints for one-to-one relations

   • Add @unique to relation scalar fields in one-to-one relations

   // Before
   model User {
     id      Int      @id @default(autoincrement())
     profile Profile? @relation(fields: [profileId], references: [id])
     profileId Int?
   }
   
   // After
   model User {
     id        Int      @id @default(autoincrement())
     profile   Profile? @relation(fields: [profileId], references: [id])
     profileId Int?     @unique  // Added @unique
   }

2. Enforced @unique or @id for relations in MySQL/MongoDB

   • Ensure referenced fields in one-to-one and one-to-many relations have @unique or @id

   // Before (MySQL/MongoDB)
   model User {
     id    Int    @id @default(autoincrement())
     email String  // Missing @unique
     posts Post[]
   }
   
   // After (MySQL/MongoDB)
   model User {
     id    Int    @id @default(autoincrement())
     email String @unique  // Added @unique
     posts Post[]
   }

3. Update SQLite connection strings

   • Remove the sqlite: protocol prefix if present
   • Change from: sqlite:./dev.db
   • To: file:./dev.db

4. String literals

   • Update any string literals that use the old grammar
   • Change from: a string with \"quotes\"
   • To: a string with \"quotes\" or a string with "quotes"

Pull Latest Schema Changes

After fixing validation errors, pull the latest schema changes:

npx prisma db pull

This will update your schema with new capabilities like improved index configuration.

Update application code

Handle queryRaw Return Type Changes

In Prisma 4, the return types of queryRaw and queryRawUnsafe have changed:

Update your code to handle these type changes, especially if you're using TypeScript or performing type checks.

Update JSON Handling

Prisma 4 changes how JSON null values are handled. If you're working with JSON fields:

// Before
const result = await prisma.model.findMany({
  where: {
    jsonField: { equals: null }
  }
});

// After
import { Prisma } from '@prisma/client';

const result = await prisma.model.findMany({
  where: {
    jsonField: { equals: Prisma.JsonNull }
  }
});

MongoDB Composite Types

For MongoDB users, Prisma 4 changes how default fields on composite types work. If you're using MongoDB with composite types, test your queries to ensure they return the expected results.

Test application

After updating your schema and code, thoroughly test your application:

1. Run your test suite to catch any type errors or runtime issues
2. Test database operations including:
   • CRUD operations
   • Relations and nested queries
   • Transactions
   • Raw queries
3. Verify performance of common operations
4. Check error handling for edge cases

New Features in Prisma 4

1. Improved Index Configuration (GA)

The extendedIndexes feature is now generally available, with support for:

• Length configuration for MySQL indexes
• Sort order configuration for indexes
• Additional index types for PostgreSQL:
  • Hash
  • GIN
  • GiST
  • SP-GiST
  • BRIN
• Index clustering for SQL Server

Example usage:

model User {
  id    Int    @id
  email String @unique(sort: Desc)
  name  String

  @@index([name(sort: Asc, length: 10)])
  @@index([email], type: Hash)  // PostgreSQL specific
}

2. Scalar List Defaults

You can now set default values for scalar lists in your schema:

model User {
  id             Int      @id @default(autoincrement())
  favoriteColors String[] @default(["red", "blue", "green"])
  luckyNumbers   Int[]    @default([7, 42])
}

3. Better Type Safety

Prisma 4 improves type safety with:

• Stricter validation of relation fields
• Better error messages for common mistakes
• Improved type inference for complex queries

Migration checklist

Before Upgrading

• Back up your database
• Check Node.js version (14.17.0 or later required)
• Review breaking changes in this guide
• Set up a testing environment

During Upgrade

• Update dependencies to Prisma 4
• Fix schema validation errors
• Update relation fields with required @unique constraints
• Update raw query handling for new return types
• Test JSON field operations
• Verify MongoDB composite type behavior if applicable

After Upgrading

• Run your full test suite
• Test all critical paths in your application
• Monitor performance in production
• Update any documentation that references Prisma versions

Troubleshooting

Common Issues

1. Schema Validation Errors

   • Symptom: Errors about missing @unique constraints
   • Solution: Add @unique to required relation fields

2. Type Errors in queryRaw

   • Symptom: Type errors after upgrade
   • Solution: Update type definitions to match new return types

3. JSON Null Handling

   • Symptom: Different behavior with JSON nulls
   • Solution: Use Prisma.JsonNull, Prisma.DbNull, or Prisma.AnyNull explicitly

Next Steps

• Prisma 4.0.0 Release Notes
• Prisma Schema Reference
• Prisma Client API Reference
• Raw Database Access

Getting Help

If you encounter issues during the upgrade:

1. Check the GitHub Issues for known problems
2. Ask for help in the Prisma Slack
3. Open a GitHub Discussion