# Upgrade to v4 (/docs/guides/upgrade-prisma-orm/v4)

Location: Guides > Upgrade Prisma ORM > 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 [#before-you-begin]

* **Back up your database** before starting the upgrade
* Review the [release notes](https://github.com/prisma/prisma/releases/tag/4.0.0) 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 [#key-changes]

System requirements [#system-requirements]

* **Minimum Node.js version**: 14.17.0 or later
* **Database versions**: Check [system requirements](/orm/reference/system-requirements) for database version compatibility

Breaking changes [#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 [#update-packages]

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

  

#### npm

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

#### pnpm

```bash
pnpm add @prisma/client@4
pnpm add -D prisma@4
pnpm dlx prisma generate
```

#### yarn

```bash
yarn add @prisma/client@4
yarn add --dev prisma@4
yarn dlx prisma generate
```

#### bun

```bash
bun add @prisma/client@4
bun add --dev prisma@4
bun x prisma generate
```

> [!CAUTION]
> Before you upgrade, check each breaking change below to see how the upgrade might affect your application.

Upgrade steps [#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 [#update-schema]

Handle Schema Validation Errors [#handle-schema-validation-errors]

Run the following command to check for schema validation errors:

  

#### npm

```bash
npx prisma validate
```

#### pnpm

```bash
pnpm dlx prisma validate
```

#### yarn

```bash
yarn dlx prisma validate
```

#### bun

```bash
bunx --bun 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

   ```prisma
   // 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`

   ```prisma
   // 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 [#pull-latest-schema-changes]

After fixing validation errors, pull the latest schema changes:

  

#### npm

```bash
npx prisma db pull
```

#### pnpm

```bash
pnpm dlx prisma db pull
```

#### yarn

```bash
yarn dlx prisma db pull
```

#### bun

```bash
bunx --bun prisma db pull
```

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

Update application code [#update-application-code]

Handle queryRaw Return Type Changes [#handle-queryraw-return-type-changes]

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

| Data Type  | Before 4.0.0 | From 4.0.0 |
| ---------- | ------------ | ---------- |
| `DateTime` | `String`     | `Date`     |
| `BigInt`   | `String`     | `BigInt`   |
| `Bytes`    | `String`     | `Buffer`   |
| `Decimal`  | `String`     | `Decimal`  |

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

Update JSON Handling [#update-json-handling]

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

```typescript
// 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 [#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 [#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 [#new-features-in-prisma-4]

1. Improved Index Configuration (GA) [#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:

```prisma
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 [#2-scalar-list-defaults]

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

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

3. Better Type Safety [#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 [#migration-checklist]

Before Upgrading [#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 [#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 [#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 [#troubleshooting]

Common Issues [#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 [#next-steps]

* [Prisma 4.0.0 Release Notes](https://github.com/prisma/prisma/releases/tag/4.0.0)
* [Prisma Schema Reference](/orm/reference/prisma-schema-reference)
* [Prisma Client API Reference](/orm/reference/prisma-client-reference)
* [Raw Database Access](/orm/prisma-client/using-raw-sql/raw-queries)

Getting Help [#getting-help]

If you encounter issues during the upgrade:

1. Check the [GitHub Issues](https://github.com/prisma/prisma/issues) for known problems
2. Ask for help in the [Prisma Slack](https://slack.prisma.io/)
3. Open a [GitHub Discussion](https://github.com/prisma/prisma/discussions)

## Related pages

- [`Upgrade to v1`](https://www.prisma.io/docs/guides/upgrade-prisma-orm/v1): Comprehensive guide for upgrading from Prisma 1 to Prisma ORM v1
- [`Upgrade to v3`](https://www.prisma.io/docs/guides/upgrade-prisma-orm/v3): Comprehensive guide for upgrading to Prisma ORM v3
- [`Upgrade to v5`](https://www.prisma.io/docs/guides/upgrade-prisma-orm/v5): Comprehensive guide for upgrading to Prisma ORM v5
- [`Upgrade to v6`](https://www.prisma.io/docs/guides/upgrade-prisma-orm/v6): Comprehensive guide for upgrading to Prisma ORM v6
- [`Upgrade to v7`](https://www.prisma.io/docs/guides/upgrade-prisma-orm/v7): Comprehensive guide for upgrading to Prisma ORM v7