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

> For the complete Prisma documentation index, see [llms.txt](https://www.prisma.io/docs/llms.txt). A markdown version of any docs page is available by appending `.md` to its URL.

Guide for upgrading to 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 breaking changes that may affect your application, so review this guide before upgrading.

## Before you begin [#before-you-begin]

* **Back up your database** before starting the upgrade
* Review the [release notes](https://github.com/prisma/orm/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](https://www.prisma.io/docs/orm/v7/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:

  

#### bun

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

#### pnpm

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

#### yarn

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

#### npm

```bash
npm install @prisma/client@4
npm install -D prisma@4
npx 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:

  

#### bun

```bash
bunx prisma validate
```

#### pnpm

```bash
pnpm prisma validate
```

#### yarn

```bash
yarn prisma validate
```

#### npm

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

   ```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:

  

#### bun

```bash
bunx prisma db pull
```

#### pnpm

```bash
pnpm prisma db pull
```

#### yarn

```bash
yarn prisma db pull
```

#### npm

```bash
npx 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/orm/releases/tag/4.0.0)
* [Prisma Schema Reference](https://www.prisma.io/docs/orm/v7/reference/prisma-schema-reference)
* [Prisma Client API Reference](https://www.prisma.io/docs/orm/v7/reference/prisma-client-reference)
* [Raw Database Access](https://www.prisma.io/docs/orm/v7/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/orm/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/orm/discussions)

## Related pages

- [`Prisma ORM 6 to 8 (MongoDB)`](https://www.prisma.io/docs/guides/upgrade-prisma-orm/mongodb): Migrate a MongoDB project from Prisma ORM 6 to Prisma ORM 8
- [`Prisma ORM 7 to 8 (PostgreSQL)`](https://www.prisma.io/docs/guides/upgrade-prisma-orm/postgresql): Migrate a PostgreSQL project from Prisma ORM 7 to Prisma ORM 8 incrementally, with both versions running side by side
- [`Upgrade to v1`](https://www.prisma.io/docs/guides/upgrade-prisma-orm/v1): Guide for upgrading from Prisma 1 to Prisma ORM
- [`Upgrade to v3`](https://www.prisma.io/docs/guides/upgrade-prisma-orm/v3): Guide for upgrading to Prisma ORM v3
- [`Upgrade to v5`](https://www.prisma.io/docs/guides/upgrade-prisma-orm/v5): Guide for upgrading to Prisma ORM v5