AutoGineer
Generated banner for Prisma Mongodb Upgrade
Generated logo for Prisma Mongodb Upgrade

Prisma Mongodb Upgrade

PrismaOfficialCreated by prisma

  • Skill
  • Guidelines
  • Software development
  • MIT
  • No issues found
Download ZIP

From the author

Decision and migration guide for Prisma ORM MongoDB projects on v6, which have no upgrade path to v7. Use when a MongoDB project asks about upgrading Prisma, when "upgrade to prisma 7" comes up in a project with provider = "mongodb", or when evaluating a move to Prisma 8. Triggers on "upgrade prisma mongodb", "prisma 7 mongodb", "mongodb prisma migration", "prisma 8 mongodb".
— the description by prisma

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a critical decision framework for Prisma ORM users on MongoDB. Because Prisma 7 does not support MongoDB, v6 is the final classic-ORM version for this database. The skill guides users through the transition to Prisma 8, which currently offers MongoDB support in Early Access. It emphasizes that users should not attempt to upgrade to Prisma 7 and provides a structured approach to evaluating whether to migrate to Prisma 8 or maintain a stable v6 environment based on specific project requirements and technical blockers.

What it does

  • Explains the version landscape for MongoDB support in Prisma ORM.
  • Provides a decision matrix for choosing between migrating to Prisma 8 or staying on v6.
  • Outlines hygiene practices for projects choosing to remain on the v6 maintenance line.
  • Maps common v6 client API calls to their Prisma 8 equivalents.
  • Identifies technical blockers such as multi-document transaction usage.
  • Offers a verification checklist for the cutover process.

When to use it

  • When a user asks about upgrading a Prisma MongoDB project to version 7.
  • When evaluating a migration path from Prisma v6 to Prisma 8 for MongoDB.
  • When determining if a project is ready to move to Early Access software.
  • When needing to map existing v6 MongoDB client code to the new Prisma 8 API.

Advantages

  • Prevents invalid upgrade attempts to unsupported versions.
  • Provides clear, actionable criteria for assessing migration readiness.
  • Reduces risk by identifying specific code patterns that require refactoring.
  • Ensures stable maintenance for projects that cannot yet adopt Early Access features.

Usage examples

“Should I upgrade my Prisma 6 MongoDB project to version 7?”
The agent explains that Prisma 7 does not support MongoDB and directs the user to the Prisma 8 migration path, while checking for potential blockers.
“How do I handle transactions when moving from Prisma 6 to Prisma 8 with MongoDB?”
The agent clarifies that Prisma 8 does not yet have a native transaction method and provides guidance on using the MongoDB driver's session API.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/prisma/prisma-mongodb-upgrade/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip prisma-mongodb-upgrade.zip -d .agents/skills

Documentation by prisma

Prisma MongoDB Upgrade Path

MongoDB projects are the one Prisma cohort with no road into Prisma 7: v6 is the terminal classic-ORM major for MongoDB, and v7 never ships a MongoDB connector. The successor path is Prisma 8, where MongoDB support is in Early Access while PostgreSQL is a release candidate. The official Prisma ORM 6 to 8 (MongoDB) guide is the source of truth for the migration steps. This skill frames the real decision — migrate to Prisma 8 (the encouraged path), or stay on v6 where a hard blocker applies — and carries the migration mechanics.

Never do either of these:

  • Never advise a MongoDB project to "upgrade to Prisma 7". The connector does not exist there. The prisma-upgrade-v7 guide does not apply to MongoDB projects.

  • Never solve the version question by rewriting the app onto a SQL database. Changing the database engine is a separate, much larger decision that is not yours to make implicitly.

The version landscape

VersionMongoDB status
Prisma ORM v6Fully supported (mongodb provider); latest 6.x is the current stable path; maintenance line
Prisma ORM v7No MongoDB connector — not an option, ever
Prisma 8MongoDB support in Early Access through @prisma/orm-mongo; still changes between release candidates — the successor path for MongoDB projects

The decision, up front

Migrating to Prisma 8 is the encouraged path. MongoDB support in Prisma 8 is Early Access: functional and moving quickly — and the Prisma team wants MongoDB users to migrate early and share feedback. The migration mechanics are detailed in the references.

Staying on the latest v6 remains a legitimate choice where a hard blocker applies — stated plainly: Prisma 8 has no MongoDB transaction method yet (multi-document writes use the mongodb driver's sessions directly), and MongoDB behavior can still change between Prisma 8 release candidates.

Decision table
SignalDirection
No blockers below applyMigrate to Prisma 8; run the verify-cutover-checklist and share feedback with the Prisma team
Greenfield / prototype / internal toolMigrate to Prisma 8
Codebase uses multi-document transactions ($transaction) — check with grep, do not askPlan raw-driver session equivalents first (see client-api-mapping), or stay on v6 until Prisma 8 adds a MongoDB transaction method
Team cannot absorb breaking changes between release candidatesStay on v6 until MongoDB support leaves Early Access
Risk-averse but interestedPoint Prisma 8 at the v6 schema with prisma6Schema(...) (see schema-contract-mapping), rehearse on a copy (see verify-cutover-checklist), then migrate

Note: this section will be updated when Prisma 8 adds a MongoDB transaction method.

If staying on v6: hygiene (a deliberate stay, not neglect)

  • Pin the Prisma packages to the latest 6.x line and keep taking 6.x patch releases.

  • Track Prisma release notes and security advisories for the 6.x line.

  • Keep the classic v6 MongoDB setup: url = env("DATABASE_URL") in the schema, db push workflow, no SQL driver adapters (see prisma-orm-setup for the v6 MongoDB shape).

  • Re-evaluate when Prisma 8's MongoDB support leaves Early Access, or when the blockers are resolved.

Reference files

ReferenceWhat it covers
references/decision-stay-or-migrate.mdThe full decision framing, blocker checks, and stay-hygiene detail
references/schema-contract-mapping.mdv6 schema (mongodb provider, @db.ObjectId, composite types) → Prisma 8 contract concepts
references/client-api-mapping.mdv6 client calls → Prisma 8 equivalents, incl. raw escape hatches and transactions — names map, parity does not
references/migrations-mapping.mdv6 db push-only story → Prisma 8's plan/migrate/verify/sign flow
references/verify-cutover-checklist.mdNo-data-moves verification: same DB, index parity, staged round-trip before cutover

Verified against

Prisma 8 claims in this skill were checked against the Prisma ORM 6 to 8 (MongoDB) guide, written for @prisma/orm-mongo 8.0.0-rc.13, and the prisma-8 skill in prisma/orm at commit 75c1460515fa2f11971533f6a1dec5dab35d4123. MongoDB support still changes between release candidates: before acting on any Prisma 8 claim, check the installed version (npm ls @prisma/orm-mongo) and its synced prisma-8 skill.

Prisma 8 on MongoDB requires Node.js 22.18+ (24.11+ on the 24 line; 24 recommended), TypeScript 5.9+, MongoDB 8.0+, and mongodb@7 as a peer dependency. The mongodb@7 driver no longer accepts AWS credentials in the connection string.

Hand-off rule

This skill is the discovery bridge, not a replacement for Prisma 8's own documentation. After a project switches to Prisma 8, run prisma skills sync, read the synced prisma-8/SKILL.md, and follow it for day-to-day work — do not keep working from this skill's summaries.

Files

references/decision-stay-or-migrate.md

decision-stay-or-migrate

How to decide between migrating a MongoDB project to Prisma 8 and staying on Prisma v6.

Priority

CRITICAL

Why It Matters

MongoDB projects cannot follow the general "upgrade Prisma" advice: Prisma 7 has no MongoDB connector, so the forward path is Prisma 8. Advising an impossible v7 upgrade, or silently rewriting the app onto SQL, are both serious failure modes. The encouraged path is migrating to Prisma 8 — its MongoDB support is Early Access and the Prisma team wants early adopters' feedback — with a deliberate stay on v6 where a hard blocker applies.

The facts the decision rests on

Prisma 8 side (supported databases, 6 to 8 MongoDB guide):

  • MongoDB support is Early Access in @prisma/orm-mongo; PostgreSQL is a release candidate.

  • The implementation is not a stub: an ORM client, a typed aggregation-pipeline builder, a raw lane, and first-class contract-driven migrations.

  • Prisma 8 has no MongoDB transaction method yet — there is no db.transaction(...) on the MongoDB client. Multi-document atomicity uses the mongodb driver's session API on a replica set. This skill will be updated when a transaction method ships.

  • Early Access means MongoDB behavior can change between release candidates. Floor: Node.js 22.18+, TypeScript 5.9+, MongoDB 8.0+, and mongodb@7.

Prisma v6 side:

  • v6 fully supports MongoDB, including transactions on replica sets — "MongoDB only allows you to start a transaction on a replica set. Prisma ORM uses transactions internally" (replica set configuration).

  • v6 MongoDB has no Prisma Migrate; the workflow is db push (no support for Prisma Migrate).

Blocker checks before migrating

Run these checks yourself — from the codebase, not by asking the user:

  • Search the codebase for $transaction usage (grep for $transaction). If present, plan the raw-driver session equivalents before migrating (see client-api-mapping.md) — or stay on v6 until Prisma 8 adds a MongoDB transaction method.

  • Check the MongoDB server version (must be 8.0+ for Prisma 8; v6 tolerated older).

  • Confirm the team can absorb changes between release candidates. Someone has to follow the release notes and update the code. For a production app, confirm the user accepts Early Access status before migrating.

Bad

User: "We're on Prisma 6 with MongoDB. Should we upgrade to Prisma 7?"
Agent: "Yes — here's the v7 upgrade guide. Step 1: install a driver adapter..."

Prisma 7 has no MongoDB connector; this migration is impossible and the SQL driver-adapter steps corrupt a working v6 setup.

Good

User: "We're on Prisma 6 with MongoDB. Should we upgrade to Prisma 7?"
Agent: "Prisma 7 does not support MongoDB — v6 is the last classic-ORM
major for MongoDB. The path forward is Prisma 8, the successor: its MongoDB support is
Early Access and migrating is encouraged. Let me check the codebase for blockers first —
searching for $transaction usage and checking the MongoDB server version..."

Stay-on-v6 hygiene

Staying is a decision, not a default-by-neglect:

  • Pin prisma and @prisma/client to the latest 6.x and keep taking 6.x patches.

  • Watch Prisma release notes and security advisories for the 6.x maintenance line.

  • Keep the classic setup (url = env("DATABASE_URL") in the schema; db push; no SQL driver adapters).

  • Re-evaluate when Prisma 8's MongoDB support leaves Early Access, or when the blockers are resolved.

References

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
prisma
Publisher
Prisma (Official)
Source
prisma/skills · prisma-mongodb-upgrade · commit 8ea289b
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by prisma or Prisma.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download prisma-mongodb-upgrade.zip