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

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

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

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

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

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

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

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

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

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

#### Before (Prisma 2.x):

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

#### After (Prisma 3.x):

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

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

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

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

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

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

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

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

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

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

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