# MongoDB (/docs/guides/next/upgrade-prisma-orm/mongodb)

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

Migrate a MongoDB project from Prisma v6 to Prisma Next

Location: Guides > Next > Upgrade Prisma ORM > MongoDB

This guide is for developers moving a Prisma ORM v6 MongoDB project to **Prisma Next**. Prisma 7 has **no MongoDB connector**, so Prisma Next is the successor path. This is a **code and workflow migration against the same database**: your data never moves.

> [!NOTE]
> Working with an AI coding agent?
> 
> Install the companion [prisma-mongodb-upgrade](https://github.com/prisma/skills/tree/main/prisma-mongodb-upgrade) skill with `npx skills add prisma/skills` to help your agent with this migration.

## Prerequisites [#prerequisites]

* **Node.js 24+**
* **TypeScript 5.9+**
* **MongoDB 8.0+**
* **The mongodb node driver 7.x** as a peer dependency
* **A replica set** if your app uses [transactions](https://www.prisma.io/docs/orm/prisma-client/queries/transactions). Prisma Next's ORM doesn't wrap `$transaction` yet, so multi-document atomicity goes through the driver's sessions (see step 3d), which MongoDB only allows on a replica set.

> [!NOTE]
> Prisma Next MongoDB is Early Access (GA planned after Postgres) and evolves quickly, so check anything below against the `@prisma-next/*` version you install. Every command and code example in this guide was validated against `@prisma-next/mongo@0.16.0`.

> [!WARNING]
> The `mongodb@^7` driver no longer accepts AWS credentials embedded in the connection string. See the [driver v7 breaking changes](https://github.com/mongodb/node-mongodb-native/blob/HEAD/etc/notes/CHANGES_7.0.0.md#-aws-authentication).

## 1. Set up Prisma Next [#1-set-up-prisma-next]

Scaffold the project:

```bash
npx prisma-next init --yes --target mongodb --authoring psl
```

`init` writes a `prisma-next.config.ts` at the repo root. MongoDB is selected by importing the `@prisma-next/mongo` facade, not by a `provider` string in the schema. Point the connection at the **same database** your v6 app uses.

  

#### After

```typescript
// prisma-next.config.ts
import 'dotenv/config';
import { defineConfig } from '@prisma-next/mongo/config';

export default defineConfig({
  contract: './src/prisma/contract.prisma',
  db: {
    connection: process.env['DATABASE_URL']!,
  },
});
```

#### Before

```prisma
// schema.prisma
datasource db {
  provider = "mongodb"
  url      = env("DATABASE_URL")
}

// Rest of schema...
```

### Generate the contract [#generate-the-contract]

Run `npx prisma-next contract emit` to generate `contract.json` from your `.prisma` contract file. Re-run this whenever you change the contract.

### Import the client [#import-the-client]

The way to instantiate the Prisma client now is from the emitted contract. Replace `my-app-db` with the database name your v6 connection string uses; if the connection URL already carries the database name in its path, omit `dbName` and the client reads it from the URL:

  

#### After

```typescript
// src/prisma/db.ts
import mongo from '@prisma-next/mongo/runtime';
import type { Contract } from './contract.d';
import contractJson from './contract.json' with { type: 'json' };

const db = mongo<Contract>({
  contractJson,
  url: process.env['DATABASE_URL']!,
  dbName: 'my-app-db',
});

export { db };
```

#### Before

```typescript
// src/prisma/db.ts
import { PrismaClient } from '../generated/prisma/client';

const prisma = new PrismaClient();

export { prisma };
```

## 2. Port the schema to a contract [#2-port-the-schema-to-a-contract]

> [!NOTE]
> Prisma Next addresses collections by **storage name**, not model name: `db.orm.users` (the `@@map` name, or the lowercased model name), never `db.orm.User`. Whatever you `@@map` in this step is the exact name every client call uses in step 3.

The v6 `schema.prisma` is not consumed as-is; it becomes a **contract**, authored in PSL (shown here) or TypeScript. The syntax is close to v6, with a few differences.

In the table below, the left column is how you wrote it in v6 and the right column is the Prisma Next equivalent:

> [!NOTE]
> You can use the [prisma-mongodb-upgrade](https://github.com/prisma/skills/tree/main/prisma-mongodb-upgrade) skill to help your agent map the contract to your schema.

| Concept           | v6 (`schema.prisma`)                                      | Prisma Next (`contract.prisma`)                                                                                                                                                        |
| ----------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Datasource        | `datasource db { provider = "mongodb" }`                  | no `provider` (configured in `prisma-next.config.ts`)                                                                                                                                  |
| Id field          | `id String @id @default(auto()) @map("_id") @db.ObjectId` | `id ObjectId @id @map("_id")`                                                                                                                                                          |
| Embedded document | `type Address { ... }`                                    | `type Address { ... }` (unchanged)                                                                                                                                                     |
| Index             | `@@index(...)`, synced by `db push`                       | `@@index(...)` / `@@unique(...)`, applied by migrations                                                                                                                                |
| Polymorphism      | not supported                                             | `@@discriminator(field)` on the base + `@@base(Base, "value")` on each variant. <br />See [Base models and variants](https://www.prisma.io/docs/orm/next/contract-authoring/psl-syntax#base-models-and-variants) |

A fuller contract putting together enum, embedded type, relation, and polymorphism:

```prisma
// src/prisma/contract.prisma
enum UserRole {
  @@type("mongo/string@1")
  Admin  = "admin"
  Author = "author"
  Reader = "reader"
}

type Address {
  street  String
  city    String
  country String
}

model User {
  id      ObjectId @id @map("_id")
  email   String
  role    UserRole
  address Address?
  posts   Post[]
  @@map("users")
}

model Post {
  id        ObjectId @id @map("_id")
  title     String
  kind      String
  authorId  ObjectId
  createdAt DateTime
  author    User @relation(fields: [authorId], references: [id])
  @@discriminator(kind)
  @@index([createdAt(sort: Desc), authorId])
  @@map("posts")
}

model Article {
  summary String
  @@base(Post, "article")
}
```

When you use `@@discriminator`, declare a variant for every value the field takes in your existing data: the generated validator only accepts declared values, so writes to documents with an undeclared value fail once the validators are live. A variant model must declare at least one field (an optional one is enough).

## 3. Port client calls [#3-port-client-calls]

Names look similar but parity does not hold. This section breaks down each category of operation.

### 3a. Basic CRUD [#3a-basic-crud]

Prisma Next uses a chained API instead of v6's single options object: you start from a collection (like `db.orm.users`), add filters and options step by step, then finish with a method that runs the query:

  

#### After

```typescript
import { db } from './db';

// Find one
await db.orm.users.where({ email: 'alice@example.com' }).first();

// Create
const user = await db.orm.users.create({ email: 'a@e.com', role: 'author', address: null });

// Update one
await db.orm.users.where({ _id: user._id }).update({ role: 'author' });

// Update many
await db.orm.users.where({ role: 'reader' }).updateAll({ role: 'author' });

// Delete one
await db.orm.users.where({ _id: user._id }).delete();
```

#### Before

```typescript
import { prisma } from './db';

// Find one
await prisma.user.findFirst({ where: { email } });

// Create
const user = await prisma.user.create({ data: { email, role: 'author' } });

// Update one
await prisma.user.update({ where: { id }, data: { role: 'author' } });

// Update many
await prisma.user.updateMany({ where: { role: 'reader' }, data: { role: 'author' } });

// Delete one
await prisma.user.delete({ where: { id } });
```

**Common mistakes:**

| Don't                                    | Do                            | Why                                                        |
| ---------------------------------------- | ----------------------------- | ---------------------------------------------------------- |
| `db.orm.User`                            | `db.orm.users`                | address by storage name, not model name                    |
| `.where({ email: { equals: 'x' } })`     | `.where({ email: 'x' })`      | `.where(...)` takes a plain equality object                |
| `.update({ ... })` with no `.where(...)` | `.where(...).update({ ... })` | every mutation except `create` needs a `.where(...)` first |
| `role: 'Author'`                         | `role: 'author'`              | enums read and write their storage value, not the key name |

### 3b. Relations and polymorphism [#3b-relations-and-polymorphism]

  

#### After

```typescript
import { db } from './db';

// Eager-load a relation
const withAuthor = await db.orm.posts.include('author').all();

// Query one variant of a polymorphic collection
const articles = await db.orm.posts.variant('Article').all();
```

#### Before

```typescript
import { prisma } from './db';

// Eager-load a relation
const withAuthor = await prisma.post.findMany({ include: { author: true } });

// Query one variant of a polymorphic collection
const articles = await prisma.post.findMany({ where: { kind: 'article' } });
```

### 3c. Aggregations [#3c-aggregations]

v6's `groupBy` / `aggregate` become a typed pipeline: build a plan with `db.query`, then run it with `db.execute`. `acc` provides the group totals (`acc.count()`, `acc.max(...)`, and friends), the equivalent of v6's `_count` / `_sum` / `_max`.

  

#### After

```typescript
import { acc } from '@prisma-next/mongo-query-builder';

const plan = db.query
  .from('posts')
  .group((f) => ({ _id: f.kind, postCount: acc.count(), latest: acc.max(f.createdAt) }))
  .sort({ postCount: -1 })
  .build();
const byKind = await db.execute(plan).toArray();
```

#### Before

```typescript
await prisma.post.groupBy({
  by: ['kind'],
  _count: { _all: true },
  _max: { createdAt: true },
  orderBy: { _count: { kind: 'desc' } },
});
```

> [!WARNING]
> ObjectId filters need a raw command
> 
> Don't add `.match((f) => f.authorId.eq(authorId))` to filter by an `ObjectId` field (`_id`, or a foreign key like `authorId`): the typed builder sends the id through as a plain string, so the stage silently matches nothing. Filter ObjectId fields with the ORM client instead (`db.orm.posts.where({ authorId })` encodes them for you), or run the aggregation as a raw command carrying a real `ObjectId`:
> 
> ```typescript
> import { RawAggregateCommand } from '@prisma-next/mongo-query-ast/execution';
> import { ObjectId } from 'mongodb';
>
> const plan = db.query.rawCommand(
>   new RawAggregateCommand('posts', [
>     { $match: { authorId: new ObjectId(String(authorId)) } },
>     { $group: { _id: '$kind', postCount: { $count: {} }, latest: { $max: '$createdAt' } } },
>     { $sort: { postCount: -1 } },
>   ]),
> );
> const byKind = await db.execute(plan).toArray();
> ```

### 3d. Transactions [#3d-transactions]

Prisma Next has no `transaction` method for MongoDB yet. For multi-document transactions, use the `mongodb` driver's [Transaction API](https://www.mongodb.com/docs/drivers/node/current/crud/transactions/transaction-conv/).

  

#### After

```typescript
import { MongoClient } from 'mongodb';

const client = new MongoClient(process.env['DATABASE_URL']!);
const session = client.startSession();
const mdb = client.db('my-app-db');

try {
  await session.withTransaction(async () => {
    // Pass { session } to EVERY operation: an op without it silently
    // runs outside the transaction.
    await mdb
      .collection('users')
      .insertOne({ email: 'a@e.com', role: 'author' }, { session });
    await mdb
      .collection('posts')
      .updateOne({ _id: postId }, { $set: { authorId } }, { session });
  });
} finally {
  await session.endSession();
}
```

#### Before

```typescript
await prisma.$transaction(async (tx) => {
  // ...writes...
});
```

### 3e. Raw operations [#3e-raw-operations]

#### Aggregations [#aggregations]

The direct replacement for v6's `findRaw` and `aggregateRaw` is `db.raw`.

  

#### After

```typescript
import { db } from './db';

// Raw aggregation on a collection, replaces v6's aggregateRaw / findRaw.
const plan = db.raw
  .collection('posts')
  .aggregate([ ... ])
  .build();
const rows = await db.execute(plan).toArray();
```

#### Before

```typescript
import { prisma } from './db';

// Raw aggregation on a collection.
const rows = await prisma.post.aggregateRaw({
  pipeline: [ ... ],
});
```

#### Commands [#commands]

`db.raw` is collection-scoped, so v6's database-level `$runCommandRaw` has no ORM equivalent. Construct your own `MongoClient` and pass it to the binding from step 1 in place of `url`: the same client then powers the typed ORM and runs arbitrary commands, sharing one connection pool.

  

#### After

```typescript
// src/prisma/db.ts
import mongo from '@prisma-next/mongo/runtime';
import { MongoClient } from 'mongodb';
import type { Contract } from './contract.d';
import contractJson from './contract.json' with { type: 'json' };

export const mongoClient = new MongoClient(process.env['DATABASE_URL']!);
export const db = mongo<Contract>({ contractJson, mongoClient, dbName: 'my-app-db' });

// Elsewhere: typed ORM and raw commands from the same client.
await db.orm.users.where({ email: 'alice@example.com' }).first();
await mongoClient.db('my-app-db').command({ ping: 1 });
```

#### Before

```typescript
import { prisma } from './db';

await prisma.$runCommandRaw({ ping: 1 });
```

For raw reads and writes scoped to a single collection (anything the typed builder can't express), you don't need the driver: `db.query.rawCommand(...)` packages a raw command into a plan, as shown in [3c](#3c-aggregations). See [Raw queries](https://www.prisma.io/docs/orm/next/reference/raw-queries) for the full surface.

### Quick reference table [#quick-reference-table]

| v6                                        | Prisma Next                                                                                         |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `prisma.user.findMany(...)`               | `db.orm.users.where({ ... }).all()`                                                                 |
| `prisma.user.findFirst(...)`              | `db.orm.users.where({ ... }).first()`                                                               |
| `create` / `update` / `delete` / `upsert` | same names on `db.orm.<collection>`                                                                 |
| `updateMany` / `deleteMany`               | `updateAll` / `deleteAll`                                                                           |
| `aggregate` / `groupBy`                   | `db.query.from(...).group(...).build()` → `db.execute(plan)`                                        |
| `findRaw` / `aggregateRaw`                | `db.raw.collection(...).aggregate(...).build()` → `db.execute(plan)`, or `db.query.rawCommand(...)` |
| `$runCommandRaw`                          | share a `MongoClient` with the binding, then `mongoClient.db(...).command(...)` (see 3e)            |
| `$transaction(...)`                       | no wrapper yet; driver sessions on a replica set (see 3d)                                           |
| `$connect` / `$disconnect`                | lazy connect on first use; `db.close()` to disconnect                                               |

## 4. Adopt the migration lifecycle [#4-adopt-the-migration-lifecycle]

v6 MongoDB had no Prisma Migrate, only `db push` (ephemeral, no history). Prisma Next gives MongoDB first-class, contract-driven migrations: reviewable diffs you commit, reproducible across environments, and an auditable schema history.

### Bring the v6 database under management [#bring-the-v6-database-under-management]

Your database already has collections and data, so bootstrap it with `db update`: it diffs the live database against your contract, applies the delta (the strict validators, plus any indexes the contract declares that v6 never created), and signs the database so Prisma Next recognizes it from then on. The `--advance-ref db` flag records the resulting contract state as the [`db` ref](https://www.prisma.io/docs/orm/next/migrations/the-migration-graph#name-important-states-with-refs), the starting point later migration plans diff from.

```bash
npx prisma-next contract emit
npx prisma-next db update --db "$DATABASE_URL" --dry-run   # preview the delta first
npx prisma-next db update --db "$DATABASE_URL" --advance-ref db
```

Don't reach for `db init` here. It bootstraps only additively, and on a populated database it refuses the validator changes this migration needs, because adding a validator to a collection with existing documents is classed destructive. `db update` applies them after a confirmation prompt.

### Every schema change after that [#every-schema-change-after-that]

Use `db update` for local experiments (the `db push` analogue, no history kept) and the migration workflow for shared branches and production:

```bash
npx prisma-next migration plan --name add_posts_indexes   # plans from the db ref
npx prisma-next migrate --db "$DATABASE_URL" --advance-ref db
npx prisma-next db verify --db "$DATABASE_URL"   # check the DB matches the contract
```

**Good to know:**

* You never hand-write migration steps: declare indexes and validators in the contract (step 2) and `migration plan` derives the changes.
* Interrupted `migrate` runs are resumable; just rerun. After fixing anything by hand, run `db sign` so the signature matches the database again.
* Prisma Next adds strict `$jsonSchema` validators by default. Make sure existing documents pass them before running in production: once the validators are live, writes to documents that don't match the contract fail with `Document failed validation`.

## 5. Pre-flight checklist (before production cutover) [#5-pre-flight-checklist-before-production-cutover]

Work through this list before you switch production traffic over:

* **Same database.** Your Prisma Next config points at the **same** database and connection string as v6.
* **Server version.** Your MongoDB server is on 8.0 or newer.
* **Dry run first.** Rehearse the whole flow on a throwaway copy of your database (`contract emit`, `db update --dry-run`, `db update`, `db verify`) and make sure `db verify` passes before you touch production.
* **Index parity.** The indexes on each collection (`db.collection.getIndexes()`) match your contract.
* **Validators.** Your existing documents pass the strict validators Prisma Next adds to each collection (see *Good to know* in step 4).
* **Addressing.** Every call site uses storage names like `db.orm.users`, not model names.
* **Transactions.** Every v6 `$transaction` now has a driver-session equivalent.
* **Raw calls.** Every `$runCommandRaw`, `findRaw`, and `aggregateRaw` has a pipeline-builder or `mongodb`-driver replacement.
* **Read-only trial run.** Run Prisma Next read-only alongside your v6 app for a while and compare the results. This surfaces any differences while v6 is still handling all the writes.
* **Cutover and rollback.** Switch writes over only once the trial run looks good, and keep the v6 branch deployable. Rolling back is just a code rollback since your data never moved.

Don't delete the v6 client, schema, or dependencies until this checklist passes.

## 6. Post-migration: adopting Next workflows [#6-post-migration-adopting-next-workflows]

Once you've cut over, this is the day-to-day workflow:

* **Schema changes.** Edit the contract, then run `contract emit`, `migration plan`, and `migrate` (same loop from step 4).
* **Troubleshooting.** `db verify` checks the database against your contract, and `db sign` records any fixes you make by hand.
* **Performance.** Your aggregations now compile to native MongoDB pipelines, so it's worth benchmarking them against your old v6 raw calls.

See the [Prisma Next docs](https://www.prisma.io/docs/orm/next) for [pipeline builder patterns](https://www.prisma.io/docs/orm/next/reference/pipeline-builder), [relation loading strategies](https://www.prisma.io/docs/orm/next/reference/orm-client), and [advanced contract features](https://www.prisma.io/docs/orm/next/contract-authoring/psl-syntax). This guide gets you across the bridge; Prisma Next's docs are the source of truth from here on.