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

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

- **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

### System requirements

- **Minimum Node.js version**: 14.17.0 or later
- **Database versions**: Check [system requirements](/guides/reference-6-v7-reference-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:

#### 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

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:

#### 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

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

#### 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

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

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:

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

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

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](https://github.com/prisma/orm/releases/tag/4.0.0)
- [Prisma Schema Reference](/guides/reference-6-v7-reference-prisma-schema-reference)
- [Prisma Client API Reference](/guides/reference-6-v7-reference-prisma-client-reference)
- [Raw Database Access](/guides/prisma-client-v7-using-raw-sql-raw-queries)

## 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)`](/guides/upgrade-prisma-orm-mongodb): Migrate a MongoDB project from Prisma ORM 6 to Prisma ORM 8
- [`Prisma ORM 7 to 8 (PostgreSQL)`](/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`](/guides/guides-3-upgrade-prisma-orm-v1): Guide for upgrading from Prisma 1 to Prisma ORM
- [`Upgrade to v3`](/guides/guides-3-upgrade-prisma-orm-v3): Guide for upgrading to Prisma ORM v3
- [`Upgrade to v5`](/guides/guides-3-upgrade-prisma-orm-v5): Guide for upgrading to Prisma ORM v5

## Related pages

- [Authentication & Tools](./authentication-tools-index.md)
- [Build](./build-index.md)
- [Changelog](../changelog.md)
- [Concepts](./concepts-index.md)
- [Console commands](./console-commands-index.md)
- [Contract Authoring](./contract-authoring-index.md)
- [Core Concepts](./core-concepts-index.md)
- [Data Modeling](./data-modeling-index.md)
- [Database](./database-index.md)
- [DB commands](./db-commands-index.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.