How to Migrate from Mongoose to Prisma

TL;DR

• Bottom line: Install Prisma alongside Mongoose, introspect your MongoDB database with prisma db pull, convert Mongoose schemas to Prisma models (mapping _id with @map("_id") @db.ObjectId), then incrementally replace Mongoose queries with type-safe Prisma Client calls.
• Key tool/command: npx prisma db pull (introspects existing MongoDB into a Prisma schema)
• Watch out for: Prisma Migrate (prisma migrate) does not support MongoDB — always use prisma db push to sync schema changes. Also: Prisma v7 does not yet support MongoDB — stay on v6.19.
• Works with: Prisma 6.x (use v6.19 for MongoDB), MongoDB 4.2+, Node.js 18+, TypeScript 5.x.

Constraints

• Prisma ORM v7 does not support MongoDB — use Prisma v6.19 (latest v6) for all MongoDB projects until v7 MongoDB support ships. [src7]
• prisma migrate dev and prisma migrate deploy are not supported for MongoDB — always use prisma db push to sync schema changes. [src3]
• MongoDB must run as a replica set for Prisma transactions — standalone mongod will fail on any prisma.$transaction() call. [src3]
• Prisma introspection (prisma db pull) should be run once for initial schema — repeated runs overwrite custom relations, composite types, and @ignore attributes. [src1]
• Composite types in Prisma MongoDB views cause Engine Panic in Prisma 6.13+ — remove composite type fields from view definitions. [src4]
• Never instantiate PrismaClient per request — use a singleton; each new PrismaClient() opens a fresh connection pool. [src2]

Quick Reference

Decision Tree

START
├── Is your MongoDB running as a replica set?
│   ├── NO → Enable replica set first (required for Prisma transactions)
│   └── YES ↓
├── Are you on Prisma v7?
│   ├── YES → Prisma v7 doesn't support MongoDB yet — downgrade to v6.19
│   └── NO (v6.x) ↓
├── Do you need Prisma Migrate (SQL-style migrations)?
│   ├── YES → Prisma Migrate doesn't support MongoDB — use prisma db push instead
│   └── NO ↓
├── Does your Mongoose schema use middleware (pre/post hooks)?
│   ├── YES → Convert to Prisma Client extensions ($extends) — not $use() (removed in v7)
│   └── NO ↓
├── Does your schema use embedded subdocuments?
│   ├── YES → Convert to Prisma composite types (use type keyword in schema)
│   └── NO ↓
├── Does your schema use discriminators (polymorphic models)?
│   ├── YES → Prisma doesn't support discriminators — flatten into separate models
│   └── NO ↓
└── DEFAULT → Introspect with prisma db pull, add relations manually, replace queries incrementally

Step-by-Step Guide

1. Install Prisma alongside Mongoose

Add Prisma to your existing project without removing Mongoose. Both ORMs can coexist and query the same database during migration. [src1]

npm install @prisma/client@6
npm install -D prisma@6
npx prisma init --datasource-provider mongodb

Verify: ls prisma/schema.prisma exists and contains provider = "mongodb".

2. Configure the database connection

Set your MongoDB connection string in the .env file. The format is identical to what Mongoose uses. [src3, src6]

# .env
DATABASE_URL="mongodb+srv://username:[email protected]/mydb?retryWrites=true&w=majority"

If you get SCRAM failure: Authentication failed, append ?authSource=admin to the connection string.

Verify: npx prisma db pull connects without errors.

3. Introspect the existing MongoDB database

Prisma samples up to 1,000 documents per collection to infer the schema. Ensure your database has representative data before running introspection. Fields with inconsistent types across documents will be mapped to Json with a warning. [src1, src3]

npx prisma db pull

This generates models in prisma/schema.prisma. Review the output — it will have no relations defined. You must add those manually.

Verify: Open prisma/schema.prisma — each collection should appear as a model block.

4. Add relations and fix the schema

Introspection won't detect relations or embedded documents automatically. Add @relation attributes for references between collections, and convert embedded subdocuments to composite type blocks. Map collection names with @@map() since Mongoose auto-pluralizes. [src1, src4, src5]

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

generator client {
  provider = "prisma-client-js"
}

model User {
  id    String  @id @default(auto()) @map("_id") @db.ObjectId
  email String  @unique
  name  String?
  posts Post[]
  address Address?   // embedded document (composite type)
  v     Int?    @map("__v") @ignore  // Mongoose version key
  @@map("users")  // Mongoose auto-pluralizes collection names
}

model Post {
  id       String @id @default(auto()) @map("_id") @db.ObjectId
  title    String
  content  String?
  authorId String @db.ObjectId
  author   User   @relation(fields: [authorId], references: [id])
  @@map("posts")
}

// Composite type for embedded documents
type Address {
  street String
  city   String
  zip    String
}

Verify: npx prisma validate returns no errors.

5. Generate the Prisma Client and push schema

Generate the type-safe client and sync indexes/constraints to MongoDB. [src1]

npx prisma generate
npx prisma db push

Verify: npx prisma studio opens a GUI showing your collections and data.

6. Replace Mongoose queries with Prisma Client

Migrate one route/service at a time. Import PrismaClient alongside your Mongoose models and switch queries incrementally. [src1, src2]

// BEFORE: Mongoose
const mongoose = require('mongoose');
const User = mongoose.model('User');

app.get('/users/:id', async (req, res) => {
  const user = await User.findById(req.params.id).populate('posts');
  res.json(user);
});

// AFTER: Prisma
const { PrismaClient } = require('@prisma/client');
const prisma = new PrismaClient();

app.get('/users/:id', async (req, res) => {
  const user = await prisma.user.findUnique({
    where: { id: req.params.id },
    include: { posts: true },
  });
  res.json(user);
});

Verify: API responses match between Mongoose and Prisma versions for the same endpoints.

7. Remove Mongoose and clean up

Once all queries are migrated, uninstall Mongoose and remove schema files. [src1]

npm uninstall mongoose
# Delete Mongoose model files (e.g., models/User.js, models/Post.js)
# Remove mongoose.connect() from your entry point
grep -rn 'mongoose' --include='*.js' --include='*.ts' | grep -v node_modules

Verify: grep returns zero results. App runs without Mongoose loaded.

Code Examples

JavaScript: Converting a Mongoose CRUD service to Prisma

Full script: javascript-converting-a-mongoose-crud-service-to-p.js (61 lines)

// Input:  Express route handlers using Mongoose for User CRUD
// Output: Same handlers using Prisma Client with full error handling

const { PrismaClient } = require('@prisma/client');
const prisma = new PrismaClient();

// CREATE
async function createUser(req, res) {
  try {
    const user = await prisma.user.create({
      data: {
        email: req.body.email,
        name: req.body.name,
        address: { set: { street: req.body.street, city: req.body.city, zip: req.body.zip } },
      },
    });
    res.status(201).json(user);
  } catch (err) {
    if (err.code === 'P2002') res.status(409).json({ error: 'Email already exists' });
    else res.status(500).json({ error: err.message });
  }
}

TypeScript: Converting Mongoose middleware to Prisma Client extensions

Full script: typescript-converting-mongoose-middleware-to-prism.ts (49 lines)

// Input:  Mongoose pre-save hooks and virtuals
// Output: Prisma Client extensions that replicate the same behavior

import { PrismaClient } from '@prisma/client';

// Mongoose middleware equivalent via Prisma Client extensions
const prisma = new PrismaClient().$extends({
  query: {
    user: {
      async create({ args, query }) {
        if (args.data.email) {
          args.data.email = (args.data.email as string).toLowerCase().trim();
        }
        args.data.createdAt = args.data.createdAt ?? new Date();
        args.data.updatedAt = new Date();
        return query(args);
      },
    },
  },
});

TypeScript: Converting Mongoose schema with embedded documents to Prisma

Full script: typescript-converting-mongoose-schema-with-embedde.ts (68 lines)

// Input:  Mongoose schema with nested subdocuments and arrays
// Output: Equivalent Prisma schema + TypeScript query code

import { PrismaClient } from '@prisma/client';
const prisma = new PrismaClient();

// Create order with embedded documents
async function createOrder(customerId: string) {
  return prisma.order.create({
    data: {
      customerId,
      items: [
        { product: 'Keyboard', quantity: 1, price: 79.99 },
        { product: 'Mouse', quantity: 2, price: 29.99 },
      ],
      shippingAddress: { set: { street: '123 Main St', city: 'Berlin', country: 'DE' } },
      status: 'pending',
    },
    include: { customer: true },
  });
}

Anti-Patterns

Wrong: Using prisma migrate with MongoDB

# ❌ BAD — prisma migrate does not support MongoDB
# This will fail with: "Error: Prisma Migrate does not support MongoDB"
npx prisma migrate dev --name add_users

Correct: Use prisma db push for MongoDB schema changes

# ✅ GOOD — db push syncs your schema to MongoDB without migration files
npx prisma db push

Wrong: Using _id directly in Prisma queries

// ❌ BAD — Prisma maps _id to id via @map("_id")
const user = await prisma.user.findUnique({
  where: { _id: '507f1f77bcf86cd799439011' },  // Error: Unknown field _id
});

Correct: Use the mapped field name id

// ✅ GOOD — Use the Prisma field name, not the MongoDB field name
const user = await prisma.user.findUnique({
  where: { id: '507f1f77bcf86cd799439011' },
});

Wrong: Instantiating PrismaClient per request

// ❌ BAD — Creates a new connection pool on every request
app.get('/users', async (req, res) => {
  const prisma = new PrismaClient();  // New instance per request!
  const users = await prisma.user.findMany();
  res.json(users);
});

Correct: Use a singleton PrismaClient instance

// ✅ GOOD — Single instance reused across all requests
const { PrismaClient } = require('@prisma/client');
const prisma = new PrismaClient();

process.on('beforeExit', async () => {
  await prisma.$disconnect();
});

app.get('/users', async (req, res) => {
  const users = await prisma.user.findMany();
  res.json(users);
});

Wrong: Manually converting ObjectId strings

// ❌ BAD — Manually creating ObjectId like in Mongoose
const { ObjectId } = require('mongodb');
const user = await prisma.user.findUnique({
  where: { id: new ObjectId('507f1f77bcf86cd799439011') },
});

Correct: Pass plain strings — Prisma handles ObjectId conversion

// ✅ GOOD — Prisma auto-converts strings to ObjectId when @db.ObjectId is declared
const user = await prisma.user.findUnique({
  where: { id: '507f1f77bcf86cd799439011' },
});

Wrong: Using Mongoose-style $operators in Prisma filters

// ❌ BAD — Mongoose/MongoDB query syntax doesn't work in Prisma
const users = await prisma.user.findMany({
  where: { age: { $gte: 18, $lte: 65 } },
});

Correct: Use Prisma's filter syntax without dollar prefix

// ✅ GOOD — Prisma uses its own filter operators
const users = await prisma.user.findMany({
  where: { age: { gte: 18, lte: 65 } },
});

Wrong: Using prisma.$use() middleware (removed in Prisma 7)

// ❌ BAD — $use() middleware is deprecated in v6 and removed in v7
prisma.$use(async (params, next) => {
  params.args.data.updatedAt = new Date();
  return next(params);
});

Correct: Use Prisma Client extensions ($extends)

// ✅ GOOD — $extends is the stable API for query interception
const prisma = new PrismaClient().$extends({
  query: {
    $allModels: {
      async $allOperations({ args, query }) {
        if (args.data) args.data.updatedAt = new Date();
        return query(args);
      },
    },
  },
});

Common Pitfalls

• Introspection returns no relations: MongoDB has no foreign key constraints, so prisma db pull cannot detect references between collections. Fix: Manually add @relation(fields: [...], references: [...]) attributes and reference fields with @db.ObjectId. [src1]
• Mongoose __v version key breaks Prisma schema: Mongoose adds a __v field to every document. After introspection, Prisma includes it but doesn't need it. Fix: Add @ignore to the v field: v Int? @map("__v") @ignore. [src5]
• Collection name mismatch: Mongoose auto-pluralizes and lowercases model names (e.g., User becomes users). Prisma uses the model name as-is. Fix: Add @@map("users") to your Prisma model to match the existing collection name. [src5]
• Replica set required for transactions: Prisma transactions require a MongoDB replica set. Standalone instances will fail. Fix: Use mongod --replSet rs0 locally or ensure your Atlas cluster is a replica set (default for Atlas). [src3]
• Mixed data types in fields: MongoDB allows different types in the same field across documents. Prisma enforces a single type per field. Fix: Clean up inconsistent data before introspection, or review type conflict warnings — Prisma maps mixed-type fields to Json. [src3]
• Composite type query limitations: findUnique() cannot filter on composite type fields, and aggregation operations do not support composite types. Fix: Use findFirst() with composite type filters instead. [src4]
• Composite types in views cause Engine Panic: Since Prisma 6.13, using composite types in MongoDB view definitions causes an Engine Panic. Fix: Remove composite type fields from view blocks or refactor views to exclude embedded document fields. [src4]
• Mongoose middleware/hooks have no direct equivalent: Prisma does not have pre('save') or post('find') hooks. The $use() middleware API is deprecated in v6 and removed in v7. Fix: Use Prisma Client extensions ($extends) for query-level middleware, or move logic to your application service layer. [src2, src7]

Diagnostic Commands

# Check Prisma version and MongoDB connection
npx prisma --version
npx prisma db pull --print

# Validate your Prisma schema for errors
npx prisma validate

# Open Prisma Studio to browse data visually
npx prisma studio

# Generate the Prisma Client after schema changes
npx prisma generate

# Push schema changes to MongoDB (not migrate!)
npx prisma db push

# Check for remaining Mongoose references in codebase
grep -rn 'mongoose\|Schema\|\.populate(' --include='*.js' --include='*.ts' | grep -v node_modules | wc -l

# Check MongoDB replica set status (mongosh)
# rs.status()

# Verify Prisma is on v6 (not v7) for MongoDB projects
npx prisma --version | head -1
# Expected: prisma                  : 6.19.x

Version History & Compatibility

When to Use / When Not to Use

Important Caveats

• Prisma ORM v7 does not yet support MongoDB. Use Prisma v6.19 (the latest v6 release) for full MongoDB compatibility. MongoDB support in v7 is planned but has no announced ship date.
• prisma migrate dev and prisma migrate deploy are not supported for MongoDB — always use prisma db push to sync schema changes.
• Prisma introspection for MongoDB is designed to be run once for the initial schema. Running it repeatedly will overwrite custom changes (relations, composite types, @ignore attributes).
• MongoDB transactions require a replica set. Local development with a standalone mongod instance will fail on any operation that uses prisma.$transaction().
• Mongoose's .lean() returns plain objects; Prisma Client always returns plain objects by default (no hydration overhead).
• Composite types (embedded documents) are only available with the MongoDB connector and cannot be used with relational databases.
• The prisma.$use() middleware API is deprecated in Prisma 6 and completely removed in Prisma 7. Use $extends for all new query interception logic.
• When Prisma v7 adds MongoDB support, a second migration from v6 to v7 will be needed (ESM-only, driver adapters mandatory, new generator syntax). Plan for this.