# Upgrade to v3 (/docs/guides/upgrade-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 important changes that may affect your application, so please review this guide carefully before proceeding.

Before you begin [#before-you-begin]

* **Backup your database** before starting the upgrade process
* Review the [release notes](https://github.com/prisma/prisma/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:

  

#### npm

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

#### pnpm

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

#### yarn

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

#### bun

```bash
bun add @prisma/client@3
bun add --dev prisma@3
bun x 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/prisma/releases/tag/3.0.1)
* [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)

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