--- # === IDENTITY === id: software/migrations/mongoose-to-prisma/2026 canonical_question: "How do I migrate from Mongoose to Prisma?" aliases: - "Mongoose to Prisma migration" - "replace Mongoose with Prisma" - "MongoDB Mongoose to Prisma ORM" - "switch from Mongoose to Prisma" - "convert Mongoose schemas to Prisma" - "Prisma MongoDB migration from Mongoose" - "Mongoose ODM to Prisma ORM" - "migrate Node.js app from Mongoose to Prisma" entity_type: software_reference domain: software > migrations > mongoose_to_prisma region: global jurisdiction: global temporal_scope: 2022-2026 # === VERIFICATION === last_verified: 2026-05-29 confidence: 0.88 version: 2.1 first_published: 2026-02-17 # === TEMPORAL VALIDITY === temporal_validity: status: evolving last_breaking_change: "Prisma 7.0 GA (2026-01) — Rust-free TypeScript engine, ESM-only, generated client emitted to project source (not node_modules); MongoDB still unsupported (coming via Prisma Next, not v7)" next_review: 2026-11-25 change_sensitivity: medium # === CONSTRAINTS === constraints: - "Prisma ORM v7 (GA Jan 2026) does not support MongoDB — use Prisma v6.19 (latest v6) for all MongoDB projects; MongoDB support is coming via Prisma Next, not v7" - "prisma migrate dev/deploy are not supported for MongoDB — always use prisma db push to sync schema changes" - "MongoDB must run as a replica set for Prisma transactions — standalone mongod will fail on prisma.$transaction()" - "Prisma introspection (prisma db pull) should be run once for initial schema — repeated runs overwrite custom relations, composite types, and @ignore attributes" - "Composite types in Prisma MongoDB views cause Engine Panic in Prisma 6.13+ — remove composite type fields from view definitions" - "Never instantiate PrismaClient per request — use a singleton; each new PrismaClient() opens a fresh connection pool" # === SKIP CONDITIONS === skip_this_unit_if: - condition: "User wants to migrate from Sequelize (SQL ORM) to Prisma, not from Mongoose (MongoDB)" use_instead: "software/migrations/sequelize-to-prisma/2026" - condition: "User wants to upgrade Prisma v6 to v7 (not migrating from Mongoose)" use_instead: "software/migrations/prisma-v6-to-v7/2026" - condition: "User wants to use Mongoose with TypeScript (not switch to Prisma)" use_instead: "software/debugging/mongoose-typescript-setup/2026" # === AGENT HINTS === inputs_needed: - key: mongoose_version question: "Which Mongoose version are you migrating from?" type: choice options: ["Mongoose 7.x", "Mongoose 8.x"] - key: schema_complexity question: "Does your Mongoose schema use embedded subdocuments, discriminators, or middleware hooks?" type: choice options: ["Simple schemas only", "Embedded subdocuments", "Discriminators (polymorphic)", "Middleware/hooks (pre/post)", "Multiple of these"] - key: mongodb_setup question: "Is your MongoDB running as a replica set?" type: choice options: ["Yes (Atlas or replica set)", "No (standalone mongod)", "Not sure"] # === DISTRIBUTION === canonical_source: "https://knowledgelib.io/software/migrations/mongoose-to-prisma/2026" suggested_citation: "Source: knowledgelib.io — AI Knowledge Library (verified 2026-05-29)" # === BUY LINKS === # (none — software_reference cards carry no affiliate products) buy_links: [] # === RELATED UNITS === related_kos: related_to: - id: "software/migrations/javascript-to-typescript/2026" label: "JavaScript to TypeScript Migration" - id: "software/migrations/rest-to-graphql/2026" label: "REST to GraphQL Migration" often_confused_with: - id: "software/migrations/mongodb-to-postgresql/2026" label: "MongoDB to PostgreSQL Migration (database-level, not ORM-level)" depends_on: [] alternative_to: [] solves: [] # === SOURCES === # Types: official_docs, technical_blog, rfc_spec, academic_paper, community_resource, industry_report # Reliability: high, moderate_high, moderate, moderate_low, low, authoritative sources: - id: src1 title: "How to migrate from Mongoose to Prisma ORM" author: Prisma url: https://www.prisma.io/docs/guides/migrate-from-mongoose type: official_docs published: 2025-06-01 reliability: authoritative - id: src2 title: "Prisma ORM vs Mongoose" author: Prisma url: https://www.prisma.io/docs/orm/more/comparisons/prisma-and-mongoose type: official_docs published: 2025-06-01 reliability: authoritative - id: src3 title: "MongoDB database connector" author: Prisma url: https://www.prisma.io/docs/orm/overview/databases/mongodb type: official_docs published: 2025-06-01 reliability: authoritative - id: src4 title: "Composite types (Embedded Documents)" author: Prisma url: https://www.prisma.io/docs/orm/prisma-client/special-fields-and-types/composite-types type: official_docs published: 2025-03-01 reliability: authoritative - id: src5 title: "Transitioning from Mongoose to Prisma ORM: A Comprehensive Guide" author: Chike Ibezim url: https://medium.com/jsexpert/transitioning-from-mongoose-to-prisma-orm-a-comprehensive-guide-3ce5abae20d5 type: technical_blog published: 2024-08-15 reliability: moderate_high - id: src6 title: "Tutorial: Integrate with Prisma" author: MongoDB url: https://www.mongodb.com/docs/drivers/node/current/integrations/prisma/ type: official_docs published: 2025-01-01 reliability: high - id: src7 title: "Upgrade to Prisma ORM 7" author: Prisma url: https://www.prisma.io/docs/orm/more/upgrade-guides/upgrading-versions/upgrading-to-prisma-7 type: official_docs published: 2025-05-01 reliability: authoritative - id: src8 title: "Benefits of Prisma over Mongoose — Discussion #9076" author: Prisma Community url: https://github.com/prisma/prisma/discussions/9076 type: community_resource published: 2024-03-15 reliability: moderate_high - id: src9 title: "Roadmap for MongoDB support in Prisma v7 — Discussion #29338" author: Prisma url: https://github.com/prisma/prisma/discussions/29338 type: official_docs published: 2026-01-20 reliability: authoritative - id: src10 title: "Prisma 7: Rust-Free Architecture and Performance Gains" author: InfoQ url: https://www.infoq.com/news/2026/01/prisma-7-performance/ type: industry_report published: 2026-01-20 reliability: high --- # How to Migrate from Mongoose to Prisma ## How do I 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 | Mongoose Pattern | Prisma Equivalent | Example | |---|---|---| | `new Schema({ name: String })` | `model User { name String }` | Define in `schema.prisma` instead of JS | | `mongoose.model('User', schema)` | `prisma.user` | Auto-generated from schema, no manual model registration | | `User.create({ name })` | `prisma.user.create({ data: { name } })` | Wrap fields in `data:` object | | `User.findById(id)` | `prisma.user.findUnique({ where: { id } })` | Use `where:` clause with unique field | | `User.find({ age: { $gt: 18 } })` | `prisma.user.findMany({ where: { age: { gt: 18 } } })` | Replace `$gt` with `gt` (no dollar prefix) | | `User.findOneAndUpdate(filter, update)` | `prisma.user.update({ where, data })` | Separate `where` and `data` arguments | | `User.deleteOne({ _id: id })` | `prisma.user.delete({ where: { id } })` | Use `id` not `_id` (mapped via `@map`) | | `User.find().populate('posts')` | `prisma.user.findMany({ include: { posts: true } })` | Type-safe eager loading via `include` | | `User.find().select('name email')` | `prisma.user.findMany({ select: { name: true, email: true } })` | Boolean field selection | | `User.find().sort({ name: 1 })` | `prisma.user.findMany({ orderBy: { name: 'asc' } })` | Replace `1`/`-1` with `'asc'`/`'desc'` | | `User.find().skip(10).limit(5)` | `prisma.user.findMany({ skip: 10, take: 5 })` | `limit` becomes `take` | | `User.countDocuments(filter)` | `prisma.user.count({ where: filter })` | Same filter syntax as `findMany` | | `Schema.pre('save', fn)` | Prisma Client extensions (`$extends`) | Use `$extends` — `$use()` middleware removed in Prisma 7 | | `subdoc: { type: AddressSchema }` | `type Address { ... }` + `address Address` | Use `type` keyword for embedded docs | ## 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 or use a type field │ └── NO ↓ └── DEFAULT → Introspect with `prisma db pull`, add relations manually, replace queries incrementally ``` ## Decision Logic Agent-facing if/then rules for recommending a Mongoose-to-Prisma path. Apply top-down; the first matching rule wins. ### If your project uses MongoDB --> Pin Prisma to v6.19 (the latest v6). Prisma v7 (GA January 2026) shipped without MongoDB; MongoDB support is coming via Prisma Next, not v7. Do not run `npm install prisma@latest`. [src9, src7] ### If you are already on Prisma v7 and need MongoDB --> Downgrade to `prisma@6` + `@prisma/client@6`. v7's Rust-free engine and ESM-only client do not yet carry the MongoDB connector. Track the `connector/mongodb` label and watch for an RC that explicitly names MongoDB. [src9, src10] ### If your Mongoose schema uses embedded subdocuments --> Convert each subdocument to a Prisma composite `type` block (MongoDB connector only) — not a separate `model`. Note `findUnique()` cannot filter composite fields and aggregation does not support them; use `findFirst()` instead. [src4] ### If your Mongoose schema uses discriminators (polymorphic models) --> Prisma has no discriminator equivalent. Flatten the variants into separate models, or use a single model with a `type` enum field plus nullable variant fields. Decide before introspection. [src1, src5] ### If your code relies on Mongoose middleware (`pre`/`post` hooks) --> Reimplement with Prisma Client extensions (`$extends`) at the query level, or move the logic into your service layer. Do not reach for `$use()` — it is removed in Prisma 7 and deprecated in v6. [src2, src7] ### If you need SQL-style migration history (versioned, reviewable) --> You cannot get it on MongoDB: `prisma migrate dev`/`deploy` are unsupported for the MongoDB connector. Use `prisma db push` and version your `schema.prisma` in git as the source of truth. [src3] ### If your MongoDB runs as a standalone `mongod` (no replica set) --> Enable a replica set before relying on `prisma.$transaction()` — standalone instances fail every transactional call. Atlas clusters are replica sets by default; locally use `mongod --replSet rs0`. [src3] ## 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 the migration. [src1] ```bash 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] ```bash # .env DATABASE_URL="mongodb+srv://username:password@cluster.mongodb.net/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] ```bash 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 // 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 — ignore @@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] ```bash 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] ```javascript // 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] ```bash npm uninstall mongoose # Delete Mongoose model files (e.g., models/User.js, models/Post.js) # Remove mongoose.connect() from your entry point ``` **Verify**: `grep -rn 'mongoose' --include='*.js' --include='*.ts' | grep -v node_modules` returns zero results. ## Code Examples ### JavaScript: Converting a Mongoose CRUD service to Prisma > Full script: [javascript-converting-a-mongoose-crud-service-to-p.js](scripts/javascript-converting-a-mongoose-crud-service-to-p.js) (61 lines) ```javascript // 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 # ... (see full script) ``` ### TypeScript: Converting Mongoose middleware to Prisma Client extensions > Full script: [typescript-converting-mongoose-middleware-to-prism.ts](scripts/typescript-converting-mongoose-middleware-to-prism.ts) (49 lines) ```typescript // Input: Mongoose pre-save hooks and virtuals // Output: Prisma Client extensions that replicate the same behavior import { PrismaClient, Prisma } from '@prisma/client'; // Mongoose middleware equivalent via Prisma Client extensions const prisma = new PrismaClient().$extends({ # ... (see full script) ``` ### TypeScript: Converting Mongoose schema with embedded documents to Prisma > Full script: [typescript-converting-mongoose-schema-with-embedde.ts](scripts/typescript-converting-mongoose-schema-with-embedde.ts) (68 lines) ```typescript // Input: Mongoose schema with nested subdocuments and arrays // Output: Equivalent Prisma schema + TypeScript query code // --- Mongoose schema (BEFORE) --- // const orderSchema = new Schema({ // customer: { type: Schema.Types.ObjectId, ref: 'User' }, # ... (see full script) ``` ## Anti-Patterns ### Wrong: Using `prisma migrate` with MongoDB ```javascript // ❌ 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 ```bash # ✅ GOOD — db push syncs your schema to MongoDB without migration files npx prisma db push ``` ### Wrong: Using `_id` directly in Prisma queries ```javascript // ❌ 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` ```javascript // ✅ 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 (like Mongoose models) ```javascript // ❌ 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 ```javascript // ✅ GOOD — Single instance reused across all requests const { PrismaClient } = require('@prisma/client'); const prisma = new PrismaClient(); // Graceful shutdown 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 ```javascript // ❌ 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 ```javascript // ✅ 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 ```javascript // ❌ 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 ```javascript // ✅ 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) ```javascript // ❌ 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`) ```javascript // ✅ 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 in your Prisma schema: `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 MongoDB 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 run `prisma db pull` and 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 (`aggregate`, `groupBy`, `count`) do not support composite types. Fix: Use `findFirst()` with composite type filters instead of `findUnique()`. [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 ```bash # 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 | Version | Status | Breaking Changes | Migration Notes | |---|---|---|---| | Prisma 7.x (GA 2026-01) | Current (no MongoDB) | Rust-free TypeScript engine (90% smaller bundle, ~3x faster queries), ESM-only, generated client emitted to project source instead of `node_modules`, `$use()` removed, `prisma-client` replaces `prisma-client-js` generator | Do NOT use for MongoDB — MongoDB ships via Prisma Next, not v7; stay on v6.19 [src7, src9, src10] | | Prisma 6.x (2025) | LTS for MongoDB | ESM-first client, new generator syntax | Use `prisma@6` + `@prisma/client@6` — v6.19 is the latest MongoDB-compatible release | | Prisma 5.x (2023) | Maintenance | `jsonProtocol` default, removed deprecated `rejectOnNotFound` | Upgrade: update error handling for not-found queries | | Prisma 4.x (2022) | EOL | `extendedIndexes`, `filterJson` promoted to GA | No MongoDB-specific breaking changes | | Prisma 3.12+ (2022) | EOL | Composite types GA | First version with stable embedded document support | | Mongoose 8.x (2024) | Current | Dropped Node.js 14 support, new `connection.asPromise()` | If migrating from Mongoose 8.x, note new default behaviors | | Mongoose 7.x (2023) | LTS | Dropped callback support, `strictQuery` default changed | Convert callbacks to async/await before migrating to Prisma | ## When to Use / When Not to Use | Use When | Don't Use When | Use Instead | |---|---|---| | You need full TypeScript type safety for queries | You rely heavily on Mongoose plugins (e.g., passport-local-mongoose) | Keep Mongoose or wrap plugins | | Your project uses multiple databases (Prisma supports PostgreSQL, MySQL, etc.) | Your app is MongoDB-only and deeply invested in aggregation pipelines | Mongoose with native driver for aggregation | | You want auto-generated types from your schema | You need MongoDB-specific features (change streams, GridFS, `$graphLookup`) | Mongoose or native MongoDB driver | | Your team is building a new service alongside a Mongoose legacy app | Your MongoDB data has highly inconsistent field types across documents | Clean data first, then consider Prisma | | You want visual database browsing via Prisma Studio | You need Mongoose-style middleware for complex business logic | Use Prisma `$extends` or application-layer middleware | | You want a single ORM for both SQL and MongoDB databases | Your project needs Prisma v7's Rust-free engine on MongoDB today | Stay on v6.19 and wait for MongoDB support in Prisma Next | ## Important Caveats - Prisma ORM v7 (GA January 2026, Rust-free TypeScript engine) does not support MongoDB. Use Prisma v6.19 (the latest v6 release) for full MongoDB compatibility. Per the official roadmap, MongoDB support is coming through **Prisma Next** — not v7 — with no announced ship date; track the `connector/mongodb` label for an RC. [src7, src9] - `prisma migrate dev` and `prisma migrate deploy` are not supported for MongoDB — always use `prisma db push` to sync schema changes. [src3] - 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). [src1] - MongoDB transactions require a replica set. Local development with a standalone `mongod` instance will fail on any operation that uses `prisma.$transaction()`. [src3] - Mongoose's `.lean()` returns plain objects; Prisma Client always returns plain objects by default (no hydration overhead). [src2] - Composite types (embedded documents) are only available with the MongoDB connector and cannot be used with relational databases. [src4] - The `prisma.$use()` middleware API is deprecated in Prisma 6 and completely removed in Prisma 7. Use `$extends` for all new query interception logic. [src7] - When MongoDB support lands (via Prisma Next), a second upgrade from v6 will be needed — expect ESM-only, the new Rust-free client generated into your project source (not `node_modules`), and the new `prisma-client` generator syntax. Plan for this. [src7, src9, src10] ## Related Units - [JavaScript to TypeScript Migration](/software/migrations/javascript-to-typescript/2026) - [REST to GraphQL Migration](/software/migrations/rest-to-graphql/2026) - [MongoDB to PostgreSQL Migration](/software/migrations/mongodb-to-postgresql/2026)