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

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

Location: Guides > Upgrade Prisma ORM > Upgrade to v3

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

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

* **Backup your database** before starting the upgrade process
* Review the [release notes](https://github.com/prisma/orm/releases/tag/3.0.1) for a complete list of changes
* Test the upgrade in a development or staging environment first

## Key changes [#key-changes]

### Referential Actions [#referential-actions]

Prisma ORM 3 introduces native support for referential actions, which changes how cascading deletes are handled:

* The safety net that previously prevented cascading deletes at runtime has been removed
* You now have more control over referential actions
* You should explicitly define referential actions in your schema

#### Before (Prisma 2.x): [#before-prisma-2x]

```prisma
model User {
  id      Int      @id @default(autoincrement())
  posts   Post[]
}

model Post {
  id       Int  @id @default(autoincrement())
  author   User @relation(fields: [authorId], references: [id])
  authorId Int
}
```

#### After (Prisma 3.x): [#after-prisma-3x]

```prisma
model User {
  id      Int      @id @default(autoincrement())
  posts   Post[]
}

model Post {
  id       Int  @id @default(autoincrement())
  author   User @relation(
    fields: [authorId], 
    references: [id], 
    onDelete: Cascade,  // Explicit action required
    onUpdate: Cascade   // Optional: define update behavior
  )
  authorId Int
}
```

**Action Required**: Review all your relation fields and add appropriate `onDelete` and `onUpdate` actions.

### Named Constraints and Indexes [#named-constraints-and-indexes]

Prisma ORM 3 changes how constraints and indexes are named:

* New naming convention for constraints and indexes
* Clear distinction between `map` (database-level name) and `name` (Prisma Client API name)
* Primary and foreign key names are now part of the schema for supporting databases

#### Option 1: Keep Existing Constraint Names [#option-1-keep-existing-constraint-names]

If you need to maintain existing constraint names (for compatibility with other tools or conventions):

1. Run `prisma db pull` to update your schema with existing constraint names
2. The schema will include `@map` attributes for non-default constraint names

#### Option 2: Use New Default Naming Convention [#option-2-use-new-default-naming-convention]

To use Prisma ORM's new default naming convention:

1. Run `prisma migrate dev` to generate a migration updating constraint names
2. Apply the migration to all environments

**Example of constraint naming in schema**:

```prisma
model User {
  id    Int    @id(map: "Custom_Primary_Key") @default(autoincrement())
  email String @unique(map: "Custom_Unique_Constraint")
  posts Post[]
}

model Post {
  id        Int    @id @default(autoincrement())
  title     String
  author    User   @relation(fields: [authorId], references: [id], map: "Custom_Foreign_Key")
  authorId  Int
}
```

### `$queryRaw` Method Changes [#queryraw-method-changes]

The `$queryRaw` method now only supports template literals for security:

#### Before (Prisma 2.x): [#before-prisma-2x-1]

```typescript
// String syntax (no longer supported in v3)
const result = await prisma.$queryRaw('SELECT * FROM User WHERE id = 1');
```

#### After (Prisma 3.x): [#after-prisma-3x-1]

```typescript
// Template literal syntax (recommended)
const userId = 1;
const result = await prisma.$queryRaw`SELECT * FROM User WHERE id = ${userId}`;

// Or use $queryRawUnsafe (use with caution)
const unsafeResult = await prisma.$queryRawUnsafe(
  'SELECT * FROM User WHERE id = $1', 
  userId
);
```

**Action Required**: Update all `$queryRaw` calls in your codebase to use template literals or switch to `$queryRawUnsafe` with proper parameterization.

### JSON Null Handling [#json-null-handling]

Prisma ORM 3 introduces more precise handling of null values in JSON fields:

* `{ equals: null }` now checks for database NULL values
* New types are available for different null representations:
  * `Prisma.JsonNull`: Represents a JSON null value
  * `Prisma.DbNull`: Represents a database NULL value
  * `Prisma.AnyNull`: Matches either JSON null or database NULL

#### Before (Prisma 2.x): [#before-prisma-2x-2]

```typescript
// Ambiguous behavior in v2
const result = await prisma.log.findMany({
  where: {
    meta: {
      equals: null // Could mean either JSON null or database NULL
    }
  }
});
```

#### After (Prisma 3.x): [#after-prisma-3x-2]

```typescript
import { Prisma } from '@prisma/client';

// Check for JSON null
const jsonNullResults = await prisma.log.findMany({
  where: {
    meta: {
      equals: Prisma.JsonNull
    }
  }
});

// Check for database NULL
const dbNullResults = await prisma.log.findMany({
  where: {
    meta: {
      equals: Prisma.DbNull
    }
  }
});

// Check for either
const anyNullResults = await prisma.log.findMany({
  where: {
    meta: {
      equals: Prisma.AnyNull
    }
  }
});

// Creating with specific null types
await prisma.log.create({
  data: {
    meta: Prisma.JsonNull // or Prisma.DbNull
  }
});
```

**Action Required**: Update all JSON field operations that involve null values to use the appropriate null type.

## Update packages [#update-packages]

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

  

#### bun

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

#### pnpm

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

#### yarn

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

#### npm

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

> [!NOTE]
> For yarn, use `yarn up prisma@3 @prisma/client@3`. For pnpm, use `pnpm upgrade prisma@3 @prisma/client@3`.

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

## Upgrade steps [#upgrade-steps]

1. **Add Referential Actions**: Update your schema to include explicit `onDelete` and `onUpdate` actions for all relations.
2. **Handle Constraint Naming**: Decide whether to keep existing constraint names or migrate to the new naming convention.
3. **Update JSON Fields**: Modify any JSON field operations that involve null values to use the new null types.

### 4. Update Application Code [#4-update-application-code]

1. **Update Raw Queries**: Convert all `$queryRaw` calls to use template literals or switch to `$queryRawUnsafe`.
2. **Test Thoroughly**: Pay special attention to:
   * Relations and cascading deletes
   * JSON field operations
   * Any raw SQL queries
   * Custom constraints and indexes

### 5. Migration Strategy for Production [#5-migration-strategy-for-production]

1. **Test in Development**: Test the upgrade in a development or staging environment first.
2. **Create a Backup**: Always create a backup of your production database before upgrading.
3. **Schedule Downtime**: Plan for a maintenance window if needed.
4. **Deploy Updates**: Update your application with the new Prisma ORM 3 packages.
5. **Monitor**: Keep an eye on your application after the upgrade.

## Troubleshooting [#troubleshooting]

### Common Issues [#common-issues]

1. **Missing Referential Actions**
   * **Symptom**: Unexpected behavior with cascading deletes
   * **Solution**: Add explicit `onDelete` and `onUpdate` actions to your relations

2. **JSON Null Handling**
   * **Symptom**: Type errors when filtering JSON fields
   * **Solution**: Use `Prisma.JsonNull`, `Prisma.DbNull`, or `Prisma.AnyNull`

3. **Raw Query Errors**
   * **Symptom**: Errors with `$queryRaw`
   * **Solution**: Convert to template literals or use `$queryRawUnsafe`

## Next Steps [#next-steps]

* [Prisma ORM 3 Release Notes](https://github.com/prisma/orm/releases/tag/3.0.1)
* [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)

## 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 v4`](https://www.prisma.io/docs/guides/upgrade-prisma-orm/v4): Guide for upgrading to Prisma ORM v4
- [`Upgrade to v5`](https://www.prisma.io/docs/guides/upgrade-prisma-orm/v5): Guide for upgrading to Prisma ORM v5