Upgrade to v4

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

• 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+)

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

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

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

bun add @prisma/client@4

bun add --dev prisma@4

bunx prisma generate

pnpm add @prisma/client@4
pnpm add -D prisma@4
pnpm prisma generate

yarn add @prisma/client@4
yarn add --dev prisma@4
yarn prisma generate

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

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

Run the following command to check for schema validation errors:

bunx prisma validate

pnpm prisma validate

yarn prisma validate

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"

After fixing validation errors, pull the latest schema changes:

bunx prisma db pull

pnpm prisma db pull

yarn prisma db pull

npx prisma db pull

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

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.

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 }

  }

});

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.

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

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

}

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

}

Prisma 4 improves type safety with:

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

• 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

• 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

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

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

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

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