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.

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

1. Set up Prisma Next

Scaffold the project:

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.

// 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']!,
  },
});

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

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:

// 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 };

2. Port the schema to a contract

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:

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

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

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

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:

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();

Common mistakes:

3b. Relations and polymorphism

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();

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.

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();

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

Prisma Next has no transaction method for MongoDB yet. For multi-document transactions, use the mongodb driver's Transaction API.

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();
}

3e. Raw operations

Aggregations

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

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();

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.

// 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 });

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. See Raw queries for the full surface.

Quick reference table

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

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, the starting point later migration plans diff from.

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

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

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)

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

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 for pipeline builder patterns, relation loading strategies, and advanced contract features. This guide gets you across the bridge; Prisma Next's docs are the source of truth from here on.