diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index a0151e5..1056d54 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,6 +1,6 @@ { "name": "prisma", - "description": "Curated Prisma skills for ORM, Prisma Client, Prisma Postgres, Prisma Compute deployments, driver adapters, migrations, upgrades, and database workflows, plus official Prisma MCP integration.", + "description": "Curated Prisma skills for ORM, Prisma Client, Prisma Postgres, Prisma Compute deployments, driver adapters, migrations, upgrades, MongoDB upgrade paths, and database workflows, plus official Prisma MCP integration.", "owner": { "name": "Prisma" }, @@ -8,10 +8,11 @@ { "name": "prisma", "source": "./", - "description": "Curated Prisma skills for ORM, Prisma Client, Prisma Postgres, Prisma Compute deployments, driver adapters, migrations, upgrades, and database workflows, plus official Prisma MCP integration.", - "version": "0.3.0", + "description": "Curated Prisma skills for ORM, Prisma Client, Prisma Postgres, Prisma Compute deployments, driver adapters, migrations, upgrades, MongoDB upgrade paths, and database workflows, plus official Prisma MCP integration.", + "version": "0.4.0", "author": { "name": "Prisma", + "email": "support@prisma.io", "url": "https://www.prisma.io/" }, "repository": "https://github.com/prisma/prisma-plugin", @@ -21,6 +22,7 @@ "orm", "database", "postgresql", + "mongodb", "migrations", "prisma-client", "prisma-postgres", diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index c799110..07d046a 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,9 +1,10 @@ { "name": "prisma", - "version": "0.3.0", - "description": "Curated Prisma skills for ORM, Prisma Client, Prisma Postgres, Prisma Compute deployments, driver adapters, migrations, upgrades, and database workflows, plus official Prisma MCP integration.", + "version": "0.4.0", + "description": "Curated Prisma skills for ORM, Prisma Client, Prisma Postgres, Prisma Compute deployments, driver adapters, migrations, upgrades, MongoDB upgrade paths, and database workflows, plus official Prisma MCP integration.", "author": { "name": "Prisma", + "email": "support@prisma.io", "url": "https://www.prisma.io/" }, "homepage": "https://www.prisma.io/docs", @@ -14,6 +15,7 @@ "orm", "database", "postgresql", + "mongodb", "migrations", "prisma-client", "prisma-postgres", diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 72c43fe..1bf8bcb 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,9 +1,10 @@ { "name": "prisma", - "version": "0.3.0", - "description": "Curated Prisma skills for ORM, Prisma Client, Prisma Postgres, Prisma Compute deployments, driver adapters, migrations, upgrades, and database workflows, plus official Prisma MCP integration.", + "version": "0.4.0", + "description": "Curated Prisma skills for ORM, Prisma Client, Prisma Postgres, Prisma Compute deployments, driver adapters, migrations, upgrades, MongoDB upgrade paths, and database workflows, plus official Prisma MCP integration.", "author": { "name": "Prisma", + "email": "support@prisma.io", "url": "https://www.prisma.io/" }, "homepage": "https://www.prisma.io/docs", @@ -14,6 +15,7 @@ "orm", "database", "postgresql", + "mongodb", "migrations", "prisma-client", "prisma-postgres", @@ -28,7 +30,7 @@ "interface": { "displayName": "Prisma", "shortDescription": "Curated Prisma skills with official MCP integration", - "longDescription": "Bring Prisma expertise into Codex with curated skills for Prisma CLI, Prisma Client, database setup, Prisma Postgres provisioning and operations, Prisma Compute app deployment, Prisma ORM v7 upgrades, and Prisma driver adapter implementation, plus official Prisma MCP server configuration for schema-aware and account-aware database workflows.", + "longDescription": "Bring Prisma expertise into Codex with curated skills for Prisma CLI, Prisma Client, database setup, Prisma Postgres provisioning and operations, Prisma Compute app deployment, Prisma ORM v7 upgrades, MongoDB v6 upgrade decisions, and Prisma driver adapter implementation, plus official Prisma MCP server configuration for schema-aware and account-aware database workflows.", "developerName": "Prisma", "category": "Coding", "capabilities": [ diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index f47756d..64570e8 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "prisma", - "version": "0.3.0", - "description": "Curated Prisma skills for ORM, Prisma Client, Prisma Postgres, Prisma Compute deployments, driver adapters, migrations, upgrades, and database workflows, plus official Prisma MCP integration.", + "version": "0.4.0", + "description": "Curated Prisma skills for ORM, Prisma Client, Prisma Postgres, Prisma Compute deployments, driver adapters, migrations, upgrades, MongoDB upgrade paths, and database workflows, plus official Prisma MCP integration.", "author": { "name": "Prisma", "email": "support@prisma.io", @@ -17,6 +17,7 @@ "schema", "migration", "postgresql", + "mongodb", "mysql", "sqlite", "prisma-postgres", diff --git a/.plugin/plugin.json b/.plugin/plugin.json index c799110..07d046a 100644 --- a/.plugin/plugin.json +++ b/.plugin/plugin.json @@ -1,9 +1,10 @@ { "name": "prisma", - "version": "0.3.0", - "description": "Curated Prisma skills for ORM, Prisma Client, Prisma Postgres, Prisma Compute deployments, driver adapters, migrations, upgrades, and database workflows, plus official Prisma MCP integration.", + "version": "0.4.0", + "description": "Curated Prisma skills for ORM, Prisma Client, Prisma Postgres, Prisma Compute deployments, driver adapters, migrations, upgrades, MongoDB upgrade paths, and database workflows, plus official Prisma MCP integration.", "author": { "name": "Prisma", + "email": "support@prisma.io", "url": "https://www.prisma.io/" }, "homepage": "https://www.prisma.io/docs", @@ -14,6 +15,7 @@ "orm", "database", "postgresql", + "mongodb", "migrations", "prisma-client", "prisma-postgres", diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..3160740 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Prisma + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 7b7a2d2..98fa83c 100644 --- a/README.md +++ b/README.md @@ -8,14 +8,27 @@ Prisma plugin for agent tools, including curated skills for Prisma ORM, Prisma C npx plugins add prisma/prisma-plugin ``` +## Agent Plugins Standard + +This repository conforms to the [Agent Plugins](https://agent-plugins.org) open standard (v1.0.0): + +- `plugin.json` — the portable manifest at the repository root +- `mcp.json` — the portable MCP server declaration (official Prisma MCP over streamable HTTP) +- `skills/` — one directory per skill with an Agent Skills `SKILL.md` + +Any Agent Plugins–compatible client (ChatGPT/Codex, Cursor, GitHub Copilot, VS Code, Kiro, and others) can consume these files directly. The client-specific directories (`.claude-plugin/`, `.codex-plugin/`, `.cursor-plugin/`, `.plugin/`) are kept for clients and installers that predate the standard; the portable files at the root are the source of truth. + ## Supported Tools | Tool | Support | | --- | --- | +| Agent Plugins clients (VS Code, Copilot, Kiro, …) | Skills and Prisma MCP via the portable standard files | | OpenAI Codex | Skills and Prisma MCP | | Claude Code | Skills and Prisma MCP | | Cursor | Rules, skills, and Prisma MCP metadata | +Codex also discovers this repository directly as a plugin marketplace via `.agents/plugins/marketplace.json`; the repo-root plugin path (`"./"`) requires Codex 0.142.0 or newer. + ## What's Included - Prisma CLI guidance for setup, migrations, database commands, Studio, and MCP @@ -26,6 +39,7 @@ npx plugins add prisma/prisma-plugin - Prisma Compute guidance for app deployment, `prisma.compute.ts`, `@prisma/cli app deploy`, `create-prisma --deploy`, framework readiness, logs, env vars, domains, and monorepos - Prisma driver adapter implementation guidance for Prisma ORM v7 adapter contracts - Prisma ORM 7 upgrade guidance +- Prisma MongoDB upgrade decision guidance for v6 projects (stay on v6 vs Prisma Next) - Cursor rules for Prisma schema and migration best practices ## Skills @@ -35,6 +49,7 @@ npx plugins add prisma/prisma-plugin - `prisma-compute` - `prisma-database-setup` - `prisma-driver-adapter-implementation` +- `prisma-mongodb-upgrade` - `prisma-postgres` - `prisma-postgres-setup` - `prisma-upgrade-v7` diff --git a/mcp.json b/mcp.json new file mode 100644 index 0000000..39554be --- /dev/null +++ b/mcp.json @@ -0,0 +1,9 @@ +{ + "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json", + "mcpServers": { + "prisma": { + "type": "streamable-http", + "url": "https://mcp.prisma.io/mcp" + } + } +} diff --git a/plugin.json b/plugin.json new file mode 100644 index 0000000..b64463a --- /dev/null +++ b/plugin.json @@ -0,0 +1,29 @@ +{ + "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", + "name": "prisma", + "version": "0.4.0", + "description": "Curated Prisma skills for ORM, Prisma Client, Prisma Postgres, Prisma Compute deployments, driver adapters, migrations, upgrades, MongoDB upgrade paths, and database workflows, plus official Prisma MCP integration.", + "author": { + "name": "Prisma", + "email": "support@prisma.io", + "url": "https://www.prisma.io/" + }, + "homepage": "https://www.prisma.io/docs", + "repository": "https://github.com/prisma/prisma-plugin", + "license": "MIT", + "keywords": [ + "prisma", + "orm", + "database", + "postgresql", + "mongodb", + "migrations", + "prisma-client", + "prisma-postgres", + "prisma-compute", + "driver-adapters", + "upgrades", + "deployment", + "mcp" + ] +} diff --git a/skills/prisma-database-setup/SKILL.md b/skills/prisma-database-setup/SKILL.md index 1de91a6..51643e7 100644 --- a/skills/prisma-database-setup/SKILL.md +++ b/skills/prisma-database-setup/SKILL.md @@ -170,7 +170,7 @@ generator client { } ``` -For MongoDB, stay on the latest Prisma 6.x line and keep the connection URL in `schema.prisma`. Do not move a MongoDB project to the Prisma 7 SQL adapter setup. +For MongoDB, stay on the latest Prisma 6.x line and keep the connection URL in `schema.prisma`. Do not move a MongoDB project to the Prisma 7 SQL adapter setup. If a MongoDB project asks about upgrading Prisma versions, route to the `prisma-mongodb-upgrade` skill (stay-on-v6 vs Prisma Next is the real decision; Prisma 7 is not an option). ## Rule Files diff --git a/skills/prisma-mongodb-upgrade/SKILL.md b/skills/prisma-mongodb-upgrade/SKILL.md new file mode 100644 index 0000000..99e1be7 --- /dev/null +++ b/skills/prisma-mongodb-upgrade/SKILL.md @@ -0,0 +1,92 @@ +--- +name: prisma-mongodb-upgrade +description: 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 Next. Triggers on "upgrade prisma mongodb", "prisma 7 mongodb", "mongodb prisma migration", "prisma next mongodb". +license: MIT +metadata: + author: prisma + version: "0.1.0" +--- + +# 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 Next](https://github.com/prisma/prisma-next), where MongoDB support is in Early +Access with GA planned after Postgres. This skill frames the real decision — migrate to +Prisma Next (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 + +| Version | MongoDB status | +|---------|----------------| +| Prisma ORM v6 | Fully supported (`mongodb` provider); latest 6.x is the current stable path; maintenance line | +| Prisma ORM v7 | **No MongoDB connector — not an option, ever** | +| Prisma Next | MongoDB support in **Early Access**, actively developed, GA planned after Postgres — the successor path for MongoDB projects | + +## The decision, up front + +**Migrating to Prisma Next is the encouraged path.** MongoDB support in Prisma Next is Early +Access: functional and moving quickly, with GA planned after Postgres — 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: the Next Mongo façade does not wrap transactions yet (the underlying driver +is available directly; this is expected to change soon), and pre-1.0 minors can carry +breaking changes with published upgrade recipes. + +### Decision table + +| Signal | Direction | +|--------|-----------| +| No blockers below apply | Migrate to Next; run the `verify-cutover-checklist` and share feedback with the Prisma team | +| Greenfield / prototype / internal tool | Migrate to Next | +| Codebase uses multi-document transactions (`$transaction`) — check with grep, do not ask | Plan raw-driver session equivalents first (see `client-api-mapping`), or stay on v6 until the façade wrapper lands | +| Team cannot absorb pre-1.0 breaking upgrades between minors | Stay on v6 until GA | +| Risk-averse but interested | Run a staged Next round-trip on a copy (see `verify-cutover-checklist`), then migrate | + +Note: the transactions gap is expected to close soon — this section will be updated when +façade transactions merge in Prisma Next. + +### 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-database-setup` for the v6 MongoDB shape). +- Re-evaluate when Prisma Next's MongoDB is GA, or when blockers for trying EA are resolved. + +## Reference files + +| Reference | What it covers | +|-----------|----------------| +| `references/decision-stay-or-migrate.md` | The full decision framing, blocker checks, and stay-hygiene detail | +| `references/schema-contract-mapping.md` | v6 schema (`mongodb` provider, `@db.ObjectId`, composite types) → Next contract concepts | +| `references/client-api-mapping.md` | v6 client calls → Next equivalents, incl. raw escape hatches and transactions — names map, parity does not | +| `references/migrations-mapping.md` | v6 `db push`-only story → Next's plan/migrate/verify/sign flow | +| `references/verify-cutover-checklist.md` | No-data-moves verification: same DB, index parity, staged round-trip before cutover | + +## Verified against + +Behavioral claims about Prisma Next in this skill were verified against +[prisma/prisma-next](https://github.com/prisma/prisma-next) at commit +`a2791c5dd59d579b4b3052942ae7f8fe5e2ee852` (pre-1.0, ~v0.14/0.15 line). Prisma Next moves +quickly in Early Access: **before acting on any Next-side claim, verify it against the +version actually installed** (check the project's `@prisma-next/*` versions and the +prisma-next skills installed with it). Next's Mongo target requires MongoDB 8.0+ and expects +`mongodb@^7` as a user-supplied peer dependency. + +## Hand-off rule + +This skill is the **discovery bridge**, not a replacement for Prisma Next's own +documentation. After a project switches to Prisma Next, run Prisma Next's `init`/skill +installation and follow its own skills (quickstart, contract, queries, migrations, runtime) +for day-to-day work — do not keep working from this skill's summaries. diff --git a/skills/prisma-mongodb-upgrade/references/client-api-mapping.md b/skills/prisma-mongodb-upgrade/references/client-api-mapping.md new file mode 100644 index 0000000..242d2bd --- /dev/null +++ b/skills/prisma-mongodb-upgrade/references/client-api-mapping.md @@ -0,0 +1,61 @@ +# client-api-mapping + +How v6 Prisma Client calls map to Prisma Next's Mongo client — names map, parity does not. + +## Priority + +CRITICAL + +## Why It Matters + +The v6 and Next client APIs look superficially similar, but none of the v6 MongoDB raw +methods exist under their old names, aggregation moved to a different lane entirely, and +transactions go through the driver rather than a façade wrapper. Assuming parity produces +code that does not compile — or, in the transactions case, code that silently loses +atomicity. + +## The mapping + +| v6 call | Prisma Next equivalent | Notes | +|---------|------------------------|-------| +| `prisma.user.findMany(...)` | `db.orm.users.where(...).all()` | Fluent ORM lane; storage-name keys (see `schema-contract-mapping.md`) | +| `prisma.user.findFirst(...)` | `db.orm.users.where(...).first()` | | +| `create` / `update` / `upsert` / `delete` / `updateMany` / `deleteMany` | `create` / `update` / `upsert` / `delete` / `updateAll` / `deleteAll` on `db.orm.` | See Prisma Next's `prisma-next-queries` skill | +| `prisma.user.aggregate(...)`, `groupBy(...)` | **No ORM equivalent.** Use the typed aggregation-pipeline builder: `db.query.from(...).match(...).group(...).build()` | Prisma Next's `prisma-next-queries` skill covers the builder lane | +| `$runCommandRaw(...)` ([v6 docs](https://www.prisma.io/docs/orm/prisma-client/using-raw-sql/raw-queries#runcommandraw)) | **Name does not exist in Next.** Raw lane is `mongoRaw(...)` → a raw collection with `aggregate`, `insertOne/Many`, `updateOne/Many`, `deleteOne/Many`, `findOneAndUpdate/Delete`. For arbitrary database commands, use the underlying `mongodb` driver directly — it is a user-supplied peer dependency and fully accessible | Check the installed version's raw surface | +| `.findRaw(...)` ([v6 docs](https://www.prisma.io/docs/orm/prisma-client/using-raw-sql/raw-queries#findraw)) | `mongoRaw(...)` collection reads (e.g. `aggregate` with a `$match` stage) | No direct `findRaw` name | +| `.aggregateRaw(...)` ([v6 docs](https://www.prisma.io/docs/orm/prisma-client/using-raw-sql/raw-queries#aggregateraw)) | `mongoRaw(...).aggregate(...)` or the typed pipeline builder | | +| `$transaction(...)` — works on v6 with a replica set ([v6 docs](https://www.prisma.io/docs/orm/overview/databases/mongodb#replica-set-configuration)) | The façade does not wrap `db.transaction(...)` yet, **but the underlying `mongodb` driver is directly available** (user-supplied peer dependency): multi-document atomicity works today via driver sessions (`client.startSession()` / `session.withTransaction(...)`) on a replica set | A façade wrapper is expected soon; this row will be updated when it merges | +| `$connect` / `$disconnect` | `connect()` / `close()` on the Mongo façade client | | + +## Bad + +```typescript +// Assuming v6 names exist in Prisma Next: +await db.user.$runCommandRaw({ collStats: 'users' }); // no such method +await db.transaction(async (tx) => { ... }); // no such method on the Mongo façade +``` + +## Good + +```typescript +// Raw lane under its Next name: +const raw = mongoRaw(db); +await raw.users.aggregate([{ $match: { status: 'active' } }]); + +// Aggregation through the typed pipeline builder: +const stats = await db.query.from('users').group({ _id: '$role', n: { $count: {} } }).build(); + +// Multi-document atomicity today: the mongodb driver (a direct dependency of the +// project) exposes sessions and transactions as usual: +const session = mongoClient.startSession(); +await session.withTransaction(async () => { + // ...writes... +}); +``` + +## References + +- [v6 MongoDB raw queries](https://www.prisma.io/docs/orm/prisma-client/using-raw-sql/raw-queries#raw-queries-with-mongodb) +- [v6 replica set requirement for transactions](https://www.prisma.io/docs/orm/overview/databases/mongodb#replica-set-configuration) +- Prisma Next queries + runtime skills (`skills/prisma-next-queries`, incl. its dedicated `mongo.md`; `skills/prisma-next-runtime`) — authoritative for the Next side; verified @ `a2791c5dd59d579b4b3052942ae7f8fe5e2ee852` diff --git a/skills/prisma-mongodb-upgrade/references/decision-stay-or-migrate.md b/skills/prisma-mongodb-upgrade/references/decision-stay-or-migrate.md new file mode 100644 index 0000000..93feda2 --- /dev/null +++ b/skills/prisma-mongodb-upgrade/references/decision-stay-or-migrate.md @@ -0,0 +1,87 @@ +# decision-stay-or-migrate + +How to decide between migrating a MongoDB project to Prisma Next 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 Next. Advising an impossible v7 upgrade, or +silently rewriting the app onto SQL, are both serious failure modes. The encouraged path is +migrating to Prisma Next — 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 Next side (verified against prisma/prisma-next @ `a2791c5dd59d579b4b3052942ae7f8fe5e2ee852`; +status confirmed by the Prisma team 2026-07): + +- **MongoDB support is Early Access**, actively developed, with GA planned after Postgres. +- The implementation is deep, not a stub: a full package family (ORM, typed + aggregation-pipeline builder, raw lane, driver over the official `mongodb` package), + first-class contract-driven migrations, and extensive tests against real in-memory MongoDB. +- **The Mongo client façade does not wrap `db.transaction(...)` yet** — multi-document + atomicity is done through the MongoDB driver's session API, which is directly available + (the `mongodb` package is a user-supplied peer dependency). A façade wrapper is expected; + this skill will be updated when it merges. +- Early Access means pre-1.0 minors can carry breaking changes, with published upgrade + recipes (e.g. 0.11→0.12 changed Mongo validator emission and made `mongodb` a + user-supplied peer dependency). Floor: 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](https://www.prisma.io/docs/orm/overview/databases/mongodb#replica-set-configuration)). +- v6 MongoDB has no Prisma Migrate; the workflow is `db push` + ([no support for Prisma Migrate](https://www.prisma.io/docs/orm/overview/databases/mongodb#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 the façade wrapper lands. +- **Check the MongoDB server version** (must be 8.0+ for Next; v6 tolerated older). +- **Confirm the team can absorb pre-1.0 upgrades.** Next publishes versioned upgrade recipes + between minors; someone has to run them. For a production app, confirm the user accepts + Early Access status before migrating. + +## Bad + +```text +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 + +```text +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 Next, 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 Next's MongoDB is GA, or when blockers for trying EA are resolved. + +## References + +- [Prisma Next repository](https://github.com/prisma/prisma-next) +- [Prisma v6 MongoDB documentation](https://www.prisma.io/docs/orm/overview/databases/mongodb) diff --git a/skills/prisma-mongodb-upgrade/references/migrations-mapping.md b/skills/prisma-mongodb-upgrade/references/migrations-mapping.md new file mode 100644 index 0000000..c666428 --- /dev/null +++ b/skills/prisma-mongodb-upgrade/references/migrations-mapping.md @@ -0,0 +1,65 @@ +# migrations-mapping + +How the v6 MongoDB "no migrations" story maps onto Prisma Next's first-class migration flow. + +## Priority + +HIGH + +## Why It Matters + +This is the largest workflow change in the migration — in v6, MongoDB explicitly has no +Prisma Migrate, while in Prisma Next MongoDB participates in the full migration lifecycle. +Teams porting a `db push` habit into Next without understanding the plan/verify/sign flow +will fight the tooling or bypass its safety rails. + +## v6: `db push` only + +MongoDB on v6 has no Prisma Migrate and no plans to add it — "MongoDB projects do not rely +on internal schemas" ([no support for Prisma Migrate](https://www.prisma.io/docs/orm/overview/databases/mongodb#no-support-for-prisma-migrate)). +The workflow is `prisma db push` to sync indexes and unique constraints, with no migration +history on disk. + +## Prisma Next: first-class, contract-driven migrations (Mongo included) + +Migration authoring in Next is first-class for Postgres **and Mongo** (prisma-next +`skills/prisma-next-migrations/SKILL.md`) — MongoDB is not a push-only special case: + +- **Flow:** contract *emit* → diff → *plan* (writes a content-hashed migration package) → + *migrate* (apply in graph order) → *verify* (live schema vs destination contract) → + *sign* (advance the marker after a verify pass). +- **Mongo migration ops** come from dedicated factories: `createCollection`, + `dropCollection`, `validatedCollection`, `setValidation`, `createIndex`, `dropIndex`, + `collMod`, and `dataTransform` for data backfills. +- **Marker storage:** Next records migration state in a document in the + `_prisma_migrations` collection (per space) — the same collection name family v6 users + know from SQL, repurposed for Mongo state. +- **DDL is not transactional on Mongo:** the runner applies operations, verifies the live + schema against the destination contract, and only advances the marker on a verify pass — + making interrupted runs resumable rather than atomic (see Prisma Next's + `prisma-next-migrations` skill). +- **Push-style alternative still exists:** `db update` diffs the live database against the + contract and applies directly without writing a migration directory — the closest + analogue to the v6 `db push` habit, at the cost of no history. +- Validators: Next emits closed `$jsonSchema` validators by default since 0.12 (prisma-next + `CHANGELOG.md`) — collections gain schema enforcement v6 never applied. + +## Bad + +```text +Porting the v6 habit: run the Next equivalent of `db push` for every change in production, +accumulating no migration history, and hand-editing collections when verification fails. +``` + +## Good + +```text +Adopt the Next lifecycle: emit the contract, plan a migration package, apply it with +migrate, let verify gate the marker, and sign. Reserve `db update` for local prototyping, +mirroring how `db push` was used on v6. +``` + +## References + +- [v6: no Prisma Migrate for MongoDB](https://www.prisma.io/docs/orm/overview/databases/mongodb#no-support-for-prisma-migrate) +- Prisma Next migrations skill (`skills/prisma-next-migrations`) — authoritative for the Next side; verified @ `a2791c5dd59d579b4b3052942ae7f8fe5e2ee852` diff --git a/skills/prisma-mongodb-upgrade/references/schema-contract-mapping.md b/skills/prisma-mongodb-upgrade/references/schema-contract-mapping.md new file mode 100644 index 0000000..fae18bb --- /dev/null +++ b/skills/prisma-mongodb-upgrade/references/schema-contract-mapping.md @@ -0,0 +1,52 @@ +# schema-contract-mapping + +How v6 MongoDB schema concepts map onto Prisma Next's contract model. + +## Priority + +HIGH + +## Why It Matters + +Prisma Next does not consume the v6 `schema.prisma` as-is: the schema becomes a *contract* +(authored in PSL or TypeScript via the contract builder), and several v6 MongoDB idioms have +different — or deliberately absent — equivalents. Translating mechanically without knowing +the mapping produces contracts that fail verification or, worse, silently change collection +addressing. + +## The mapping + +| v6 concept | Prisma Next equivalent | Notes | +|------------|------------------------|-------| +| `datasource db { provider = "mongodb" }` + `url = env(...)` ([v6 docs](https://www.prisma.io/docs/orm/overview/databases/mongodb#example)) | `defineConfig` from `@prisma-next/mongo/config` wiring the mongo family/target/adapter/driver descriptors | Next selects MongoDB by importing the `@prisma-next/mongo` façade, not by a provider string in the schema; `prisma-next init` accepts `mongodb` as a target name | +| `@id @default(auto()) @map("_id") @db.ObjectId` ([using ObjectId](https://www.prisma.io/docs/orm/overview/databases/mongodb#using-objectid)) | ObjectId-typed id field in the Next contract (PSL or TS builder) | Verify the exact attribute surface against the installed Next version's `prisma-next-contract` skill — the contract builder also exposes `index` and `valueObject` | +| Composite (embedded) types — MongoDB-only in v6 ([composite types](https://www.prisma.io/docs/orm/prisma-client/special-fields-and-types/composite-types)) | Value objects / embedded shapes in the Next contract (`valueObject` in the Mongo contract builder) | Same conceptual role: documents embedded in a parent document | +| Model names address the client (`prisma.user`) | **Collection storage names** address the ORM: `db.orm.users`, i.e. the `@@map(...)` name or the lowercased model name — not `db.orm.User` | prisma-next `skills/prisma-next/SKILL.md`, `skills/prisma-next-quickstart/SKILL.md`; the most common porting mistake | +| Indexes declared in schema, applied by `db push` | Indexes are contract-declared and applied through migrations (`createIndex`/`dropIndex` factories) | See `migrations-mapping.md` | +| No native polymorphism | No schema-layer polymorphism on Mongo either: `@@base`/`@@discriminator` are SQL-only in Next; model an explicit `discriminator` field | prisma-next `skills/prisma-next-contract/SKILL.md` | + +## Bad + +```typescript +// Ported from v6 and addressed by model name: +const user = await db.orm.User.first(); // undefined — Mongo ORM keys are storage names +``` + +## Good + +```typescript +// Mongo ORM keys are collection storage names (@@map or lowercased model name): +const user = await db.orm.users.first(); +``` + +## Environment requirements + +Prisma Next's Mongo target requires MongoDB 8.0+ and `mongodb@^7` installed by the user as a +peer dependency (prisma-next `CHANGELOG.md`, 0.11→0.12). v6 supports older MongoDB servers, +so check the server version before planning a migration. + +## References + +- [v6 MongoDB schema documentation](https://www.prisma.io/docs/orm/overview/databases/mongodb) +- [v6 composite types (MongoDB-only)](https://www.prisma.io/docs/orm/prisma-client/special-fields-and-types/composite-types) +- Prisma Next contract skill (`skills/prisma-next-contract`) in the prisma-next repository — authoritative for the Next side diff --git a/skills/prisma-mongodb-upgrade/references/verify-cutover-checklist.md b/skills/prisma-mongodb-upgrade/references/verify-cutover-checklist.md new file mode 100644 index 0000000..43144c3 --- /dev/null +++ b/skills/prisma-mongodb-upgrade/references/verify-cutover-checklist.md @@ -0,0 +1,60 @@ +# verify-cutover-checklist + +Verification checklist for a v6 → Prisma Next cutover: the data never moves — only the code does. + +## Priority + +CRITICAL + +## Why It Matters + +A v6 → Next migration is a *client and workflow* migration against the **same MongoDB +database** — there is no data export/import step, and introducing one (or pointing the new +stack at a fresh database) turns a code migration into an outage. The checklist below keeps +the cutover observable and reversible. + +## Ground rules + +- **No data moves.** The Next contract is authored to describe the existing collections; + both stacks read the same database during the staged phase. +- **v6 stays runnable until cutover is verified.** Do not delete the v6 client, schema, or + dependencies until the checklist passes. + +## Checklist + +1. **Same database, verified:** the Next config points at the same connection string / + database name the v6 app uses (minus v6-specific URL parameters that the `mongodb@^7` + driver rejects — validate the URL with the driver first). +2. **Server floor:** MongoDB server is 8.0+ (Next's requirement; v6 tolerated older). + Confirm before authoring any contract. +3. **Contract round-trip on a copy:** on a staging copy (or `mongodb-memory-server`), emit + the contract, run plan → migrate → verify → sign, and confirm `verify` passes against + data copied from production shape. Verification failures here are contract-mapping bugs, + not database problems. +4. **Index parity:** enumerate indexes on every collection (`db.collection.getIndexes()`) + and confirm the Next contract declares the same set — v6 `db push` may have created + indexes the new contract must re-declare, or verification and query performance will + diverge. +5. **Validator impact assessed:** Next emits closed `$jsonSchema` validators by default; + confirm legacy documents (extra fields, drifted shapes) pass them on the staging copy + before applying to production. +6. **Storage-name addressing audited:** every ported call site uses collection storage + names (`db.orm.users`), not model names (see `schema-contract-mapping.md`). +7. **Transaction inventory mapped:** grep the v6 app for `$transaction`; each hit gets a + driver-session equivalent (the `mongodb` driver is directly available; the façade wrapper + is expected soon — see `client-api-mapping.md`). +8. **Raw call inventory mapped:** every `$runCommandRaw` / `findRaw` / `aggregateRaw` call + has an explicit Next-side replacement (`mongoRaw(...)` lane or pipeline builder). +9. **Staged read-only soak:** run the Next stack read-only against staging/production data + alongside v6 and compare outputs before allowing writes. +10. **Cutover + rollback:** switch writes to Next only after the soak; keep the v6 branch + deployable as the rollback path. Rolling back is a code rollback — the data was never + moved. + +After cutover, install and follow Prisma Next's own skills for ongoing work (see the +hand-off rule in `SKILL.md`). + +## References + +- [v6 MongoDB documentation](https://www.prisma.io/docs/orm/overview/databases/mongodb) +- Prisma Next migrations + queries skills — authoritative for the Next side; verified @ `a2791c5dd59d579b4b3052942ae7f8fe5e2ee852` diff --git a/skills/prisma-upgrade-v7/SKILL.md b/skills/prisma-upgrade-v7/SKILL.md index 1ac08b9..23d4956 100644 --- a/skills/prisma-upgrade-v7/SKILL.md +++ b/skills/prisma-upgrade-v7/SKILL.md @@ -41,9 +41,15 @@ Reference this skill when: - `removed-features` - removed middleware, metrics, and legacy CLI behavior - `accelerate-users` - migration notes for Accelerate users +## Using MongoDB? This guide does not apply + +Prisma 7 has no MongoDB connector. Do not apply any step in this guide to a project with +`provider = "mongodb"` — see the `prisma-mongodb-upgrade` skill for the actual decision +(stay on v6 deliberately vs migrate to Prisma Next). + ## Important Notes -- **MongoDB projects should stay on Prisma 6.x** - do not migrate MongoDB apps to Prisma 7's SQL client path +- **MongoDB projects should stay on Prisma 6.x or migrate to Prisma Next** - do not migrate MongoDB apps to Prisma 7's SQL client path (see `prisma-mongodb-upgrade`) - **Node.js 20.19.0+** required - **TypeScript 5.4.0+** required - **Latest stable Prisma ORM version**: `7.6.0`