skillsmcpSign in
← All packs
skill pack

Prisma

Prisma's skills for the ORM, the CLI, the client API and Prisma Postgres.

11 skills by Prisma · prisma/skills · MIT licence · checked on 18 Nov 2026

  • prisma-cliPrisma ORM 7 CLI reference for existing Prisma 7 applications or explicitly selected Prisma 7 workflows. Covers prisma init, generate, migrate, db, dev, studio, and mcp. For setup, connection repair, or Prisma 8, use prisma-orm-setup; not the Prisma Platform CLI.Read
    ---
    name: prisma-cli
    description: Prisma ORM 7 CLI reference for existing Prisma 7 applications or explicitly selected Prisma 7 workflows. Covers prisma init, generate, migrate, db, dev, studio, and mcp. For setup, connection repair, or Prisma 8, use prisma-orm-setup; not the Prisma Platform CLI.
    license: MIT
    metadata:
      author: prisma
      version: "7.9.1"
    ---
    
    # Prisma ORM 7 CLI reference
    
    These commands and examples apply to **Prisma ORM 7** only. For setup, connection repair, or a Prisma 8 application, load [prisma-orm-setup](../prisma-orm-setup/SKILL.md).
    
    Use the project's version-matched CLI. Do not install a floating `prisma@latest` to run these commands.
    
    ## Boundary: Platform and Compute
    
    Do not confuse the stable ORM command (`prisma`) with the public-beta Platform package (`@prisma/cli`, binary `prisma-cli`). Use `prisma-compute` for Compute apps and workspace auth, and `prisma-postgres-setup` for Platform projects and databases.
    
    ## When to Apply
    
    Reference this skill when:
    - Setting up an explicitly selected Prisma 7 project (`prisma init`)
    - Generating Prisma Client (`prisma generate`)
    - Running database migrations (`prisma migrate`)
    - Managing database state (`prisma db push/pull`)
    - Using local development database (`prisma dev`)
    - Debugging Prisma issues (`prisma debug`)
    - Generating shell completions (`prisma complete`)
    
    ## Rule Categories by Priority
    
    | Priority | Category | Impact | Prefix |
    |----------|----------|--------|--------|
    | 1 | Setup | HIGH | `init` |
    | 2 | Generation | HIGH | `generate` |
    | 3 | Development | HIGH | `dev` |
    | 4 | Database | HIGH | `db-` |
    | 5 | Migrations | CRITICAL | `migrate-` |
    | 6 | Utility | MEDIUM | `complete`, `studio`, `validate`, `format`, `debug`, `mcp` |
    
    ## Command Categories
    
    | Category | Commands | Purpose |
    |----------|----------|---------|
    | Setup | `init` | Initialize a Prisma project |
    | Generation | `generate` | Generate Prisma Client |
    | Validation | `validate`, `format` | Schema validation and formatting |
    | Development | `dev` | Local Prisma Postgres for development |
    | Database | `db pull`, `db push`, `db seed`, `db execute` | Direct database operations |
    | Migrations | `migrate dev`, `migrate deploy`, `migrate reset`, `migrate status`, `migrate diff`, `migrate resolve` | Schema migrations |
    | Utility | `complete`, `studio`, `mcp`, `version`, `debug` | Shell, development, and AI tooling |
    
    ## Quick Reference
    
    ### Project Setup
    
    ```bash
    # Initialize new project (creates prisma/ folder and prisma.config.ts)
    prisma init
    
    # Initialize with specific database
    prisma init --datasource-provider postgresql
    prisma init --datasource-provider mysql
    prisma init --datasource-provider sqlite
    
    # Initialize with Prisma Postgres (cloud)
    prisma init --db
    
    # Initialize with an example model
    prisma init --with-model
    
    ```
    
    ### Client Generation
    
    ```bash
    # Generate Prisma Client
    prisma generate
    
    # Watch mode for development
    prisma generate --watch
    
    # Generate specific generator only
    prisma generate --generator client
    ```
    
    ### Bun Runtime
    
    When using Bun, always add the `--bun` flag so Prisma runs with the Bun runtime (otherwise it falls back to Node.js because of the CLI shebang):
    
    ```bash
    bunx --bun prisma init
    bunx --bun prisma generate
    ```
    
    ### Local Development Database
    
    ```bash
    # Start local Prisma Postgres
    prisma dev
    
    # Start with specific name
    prisma dev --name myproject
    
    # Start in background (detached)
    prisma dev --detach
    
    # List all local instances
    prisma dev ls
    
    # Stop instance
    prisma dev stop myproject
    
    # Remove instance data
    prisma dev rm myproject
    ```
    
    ### Database Operations
    
    ```bash
    # Pull schema from existing database
    prisma db pull
    
    # Push schema to database (no migrations)
    prisma db push
    
    # Seed database
    prisma db seed
    
    # Execute raw SQL
    prisma db execute --file ./script.sql
    ```
    
    ### Migrations (Development)
    
    ```bash
    # Create and apply migration
    prisma migrate dev
    
    # Create migration with name
    prisma migrate dev --name add_users_table
    
    # Create migration without applying
    prisma migrate dev --create-only
    
    # Reset database and apply all migrations
    prisma migrate reset
    ```
    
    ### Migrations (Production)
    
    ```bash
    # Apply pending migrations (CI/CD)
    prisma migrate deploy
    
    # Check migration status
    prisma migrate status
    
    # Compare schemas and generate diff
    prisma migrate diff --from-config-datasource --to-schema schema.prisma --script
    ```
    
    ### Utility Commands
    
    ```bash
    # Open Prisma Studio (database GUI)
    prisma studio
    
    # Start Prisma's MCP server for AI tools
    prisma mcp
    
    # Show version info
    prisma version
    prisma -v
    
    # Debug information
    prisma debug
    
    # Validate schema
    prisma validate
    
    # Format schema
    prisma format
    
    # Generate shell completion code
    prisma complete zsh
    ```
    
    ## AI Safety Checkpoint
    
    Prisma blocks destructive commands when it detects an AI agent until the agent has obtained explicit user consent. This covers `migrate reset`, `db push --force-reset`, and `db push --accept-data-loss`.
    
    - Explain the exact data-loss impact and ask for consent immediately before running the command.
    - Do not infer consent from earlier or unrelated messages.
    - If automation needs the consent variable, set `PRISMA_USER_CONSENT_FOR_DANGEROUS_AI_ACTION` to the user's exact consent message. Do not invent the text.
    - The Prisma MCP server deliberately has no `migrate-reset` tool.
    
    Read `references/agent-safety.md` before any destructive Prisma command.
    
    ## Current Prisma CLI Setup
    
    ### New Configuration File
    
    Use `prisma.config.ts` for CLI configuration:
    
    ```typescript
    import 'dotenv/config'
    import { defineConfig, env } from 'prisma/config'
    
    export default defineConfig({
      schema: 'prisma/schema.prisma',
      migrations: {
        path: 'prisma/migrations',
        seed: 'tsx prisma/seed.ts',
      },
      datasource: {
        url: env('DATABASE_URL'),
      },
    })
    ```
    
    ### Current Command Behavior
    
    - Run `prisma generate` explicitly after `migrate dev`, `db push`, or other schema syncs when you need fresh client output
    - Run `prisma db seed` explicitly after `migrate dev` or `migrate reset` when you need seed data
    - Use `prisma db execute --file ...` for raw SQL scripts
    
    ### Environment Variables
    
    Load environment variables explicitly in `prisma.config.ts`, commonly with `dotenv`:
    
    ```typescript
    // prisma.config.ts
    import 'dotenv/config'
    ```
    
    ## Rule Files
    
    See individual rule files for detailed command documentation:
    
    ```
    references/init.md           - Project initialization
    references/generate.md       - Client generation
    references/dev.md            - Local development database
    references/db-pull.md        - Database introspection
    references/db-push.md        - Schema push
    references/db-seed.md        - Database seeding
    references/db-execute.md     - Raw SQL execution
    references/migrate-dev.md    - Development migrations
    references/migrate-deploy.md - Production migrations
    references/migrate-reset.md  - Database reset
    references/migrate-status.md - Migration status
    references/migrate-resolve.md - Migration resolution
    references/migrate-diff.md   - Schema diffing
    references/studio.md         - Database GUI
    references/mcp.md            - Prisma MCP server
    references/complete.md       - Shell completion generation
    references/agent-safety.md   - AI consent checkpoint for destructive commands
    references/validate.md       - Schema validation
    references/format.md         - Schema formatting
    references/debug.md          - Debug info
    ```
    
    ## How to Use
    
    Use the command categories above for navigation, then open the specific command reference file you need.
    
    Original on GitHub
  • prisma-client-apiPrisma Client API reference covering model queries, filters, operators, and client methods. Use when writing database queries, using CRUD operations, filtering data, or configuring Prisma Client. Triggers on "prisma query", "findMany", "create", "update", "delete", "$transaction".Read
    ---
    name: prisma-client-api
    description: Prisma Client API reference covering model queries, filters, operators, and client methods. Use when writing database queries, using CRUD operations, filtering data, or configuring Prisma Client. Triggers on "prisma query", "findMany", "create", "update", "delete", "$transaction".
    license: MIT
    metadata:
      author: prisma
      version: "7.9.1"
    ---
    
    # Prisma Client API Reference
    
    Complete API reference for Prisma Client. This skill provides guidance on model queries, filtering, relations, and client methods for current Prisma projects.
    
    ## When to Apply
    
    Reference this skill when:
    - Writing database queries with Prisma Client
    - Performing CRUD operations (create, read, update, delete)
    - Filtering and sorting data
    - Working with relations
    - Using transactions
    - Configuring client options
    
    ## Rule Categories by Priority
    
    | Priority | Category | Impact | Prefix |
    |----------|----------|--------|--------|
    | 1 | Client Construction | HIGH | `constructor` |
    | 2 | Model Queries | CRITICAL | `model-queries` |
    | 3 | Query Shape | HIGH | `query-options` |
    | 4 | Filtering | HIGH | `filters` |
    | 5 | Relations | HIGH | `relations` |
    | 6 | Transactions | CRITICAL | `transactions` |
    | 7 | Raw SQL | CRITICAL | `raw-queries` |
    | 8 | Client Methods | MEDIUM | `client-methods` |
    
    ## Quick Reference
    
    - `constructor` - `PrismaClient` setup, adapter wiring, logging, and SQL commenter plugins
    - `model-queries` - CRUD operations and bulk operations
    - `query-options` - `select`, `include`, `omit`, sort, pagination
    - `filters` - scalar and logical filter operators
    - `relations` - relation reads and nested writes
    - `transactions` - array and interactive transaction patterns
    - `raw-queries` - `$queryRaw` and `$executeRaw` safety
    - `client-methods` - lifecycle methods, extensions, and `satisfies` patterns for `prisma-client`
    
    ## Client Instantiation
    
    ```typescript
    import { PrismaClient } from '../generated/client'
    import { PrismaPg } from '@prisma/adapter-pg'
    
    const adapter = new PrismaPg({
      connectionString: process.env.DATABASE_URL
    })
    
    const prisma = new PrismaClient({ adapter })
    ```
    
    ## Model Query Methods
    
    | Method | Description |
    |--------|-------------|
    | `findUnique()` | Find one record by unique field |
    | `findUniqueOrThrow()` | Find one or throw error |
    | `findFirst()` | Find first matching record |
    | `findFirstOrThrow()` | Find first or throw error |
    | `findMany()` | Find multiple records |
    | `create()` | Create a new record |
    | `createMany()` | Create multiple records |
    | `createManyAndReturn()` | Create multiple and return them |
    | `update()` | Update one record |
    | `updateMany()` | Update multiple records |
    | `updateManyAndReturn()` | Update multiple and return them |
    | `upsert()` | Update or create record |
    | `delete()` | Delete one record |
    | `deleteMany()` | Delete multiple records |
    | `count()` | Count matching records |
    | `aggregate()` | Aggregate values (sum, avg, etc.) |
    | `groupBy()` | Group and aggregate |
    
    ## Query Options
    
    | Option | Description |
    |--------|-------------|
    | `where` | Filter conditions |
    | `select` | Fields to include |
    | `include` | Relations to load |
    | `omit` | Fields to exclude |
    | `orderBy` | Sort order |
    | `take` | Limit results |
    | `skip` | Skip results (pagination) |
    | `cursor` | Cursor-based pagination |
    | `distinct` | Unique values only |
    
    ## Client Methods
    
    | Method | Description |
    |--------|-------------|
    | `$connect()` | Explicitly connect to database |
    | `$disconnect()` | Disconnect from database |
    | `$transaction()` | Execute transaction |
    | `$queryRaw()` | Execute raw SQL query |
    | `$executeRaw()` | Execute raw SQL command |
    | `$on()` | Subscribe to events |
    | `$extends()` | Add extensions |
    
    ## Quick Examples
    
    ### Find records
    
    ```typescript
    // Find by unique field
    const user = await prisma.user.findUnique({
      where: { email: 'alice@prisma.io' }
    })
    
    // Find with filter
    const users = await prisma.user.findMany({
      where: { role: 'ADMIN' },
      orderBy: { createdAt: 'desc' },
      take: 10
    })
    ```
    
    ### Create records
    
    ```typescript
    const user = await prisma.user.create({
      data: {
        email: 'alice@prisma.io',
        name: 'Alice',
        posts: {
          create: { title: 'Hello World' }
        }
      },
      include: { posts: true }
    })
    ```
    
    ### Update records
    
    ```typescript
    const user = await prisma.user.update({
      where: { id: 1 },
      data: { name: 'Alice Smith' }
    })
    ```
    
    ### Delete records
    
    ```typescript
    await prisma.user.delete({
      where: { id: 1 }
    })
    ```
    
    ### Transactions
    
    ```typescript
    const [user, post] = await prisma.$transaction([
      prisma.user.create({ data: { email: 'alice@prisma.io' } }),
      prisma.post.create({ data: { title: 'Hello', authorId: 1 } })
    ])
    ```
    
    ## Rule Files
    
    Detailed API documentation:
    
    ```
    references/constructor.md        - PrismaClient constructor options
    references/model-queries.md      - CRUD operations
    references/query-options.md      - select, include, omit, where, orderBy
    references/filters.md            - Filter conditions and operators
    references/relations.md          - Relation queries and nested operations
    references/transactions.md       - Transaction API
    references/raw-queries.md        - $queryRaw, $executeRaw
    references/client-methods.md     - $connect, $disconnect, $on, $extends
    ```
    
    ## Filter Operators
    
    | Operator | Description |
    |----------|-------------|
    | `equals` | Exact match |
    | `not` | Not equal |
    | `in` | In array |
    | `notIn` | Not in array |
    | `lt`, `lte` | Less than |
    | `gt`, `gte` | Greater than |
    | `contains` | String contains |
    | `startsWith` | String starts with |
    | `endsWith` | String ends with |
    | `mode` | Case sensitivity |
    
    ## Relation Filters
    
    | Operator | Description |
    |----------|-------------|
    | `some` | At least one related record matches |
    | `every` | All related records match |
    | `none` | No related records match |
    | `is` | Related record matches (1-to-1) |
    | `isNot` | Related record doesn't match |
    
    ## Resources
    
    - [Prisma Client API Reference](https://www.prisma.io/docs/orm/reference/prisma-client-reference)
    - [CRUD Operations](https://www.prisma.io/docs/orm/prisma-client/queries/crud)
    - [Filtering and Sorting](https://www.prisma.io/docs/orm/prisma-client/queries/filtering-and-sorting)
    
    ## How to Use
    
    Pick the category from the table above, then open the matching reference file for implementation details and examples.
    
    Original on GitHub
  • prisma-computeDeploy and operate apps on Prisma Compute with the Prisma 8 CLI. Use whenever the user mentions Prisma Compute, deploying or hosting a Prisma app, `prisma deploy`, `prisma dev module.ts`, Prisma Composer apps (`module.ts`, `compute()`, the `composer` section of `prisma.config.ts`), preview stages, deploy on push (`prisma git connect`, `prisma/cloud-deploy-action`), `prisma service` logs, versions, rollback, or custom domains, `project env`, `PRISMA_SERVICE_TOKEN`, regions, 504s, sleeping instances, or `waitUntil`; also when a project still uses the removed `@prisma/cli app deploy`, `prisma.compute.ts`, `defineComputeConfig`, `compute:deploy`, or `build logs` surface.Read
    ---
    name: prisma-compute
    description: Deploy and operate apps on Prisma Compute with the Prisma 8 CLI. Use whenever the user mentions Prisma Compute, deploying or hosting a Prisma app, `prisma deploy`, `prisma dev module.ts`, Prisma Composer apps (`module.ts`, `compute()`, the `composer` section of `prisma.config.ts`), preview stages, deploy on push (`prisma git connect`, `prisma/cloud-deploy-action`), `prisma service` logs, versions, rollback, or custom domains, `project env`, `PRISMA_SERVICE_TOKEN`, regions, 504s, sleeping instances, or `waitUntil`; also when a project still uses the removed `@prisma/cli app deploy`, `prisma.compute.ts`, `defineComputeConfig`, `compute:deploy`, or `build logs` surface.
    license: MIT
    metadata:
      author: prisma
      version: "2.1.0"
    ---
    
    # Prisma Compute
    
    Deploy TypeScript apps to Prisma Compute and operate them afterwards. Every deploy goes through a Prisma Composer app (a `module.ts` root module) and the Prisma 8 CLI, `prisma`.
    
    Verified against `prisma` 8.0.0-rc.21 (published identically as `@prisma/cli`), `@prisma/composer` and `@prisma/composer-prisma-cloud` 0.28.0, `@prisma/compute` 0.1.0-beta.0, and `create-prisma` 0.14.1. Re-checked against `prisma` 8.0.0-rc.23, whose command surface matches rc.21, and Composer 0.30.0, which adds `node()`'s `dependencies` option (0.29.0) and narrows the supported Node.js versions. The CLI moves fast: run `npx prisma <group> --help` before using a flag this skill does not show.
    
    ## Version-Matched Skills
    
    The installed packages ship their own agent skills, matched to the installed version:
    
    - `prisma-platform-core-concepts`, inside `prisma`: projects, branches, services, versions, env vars, deploy on push.
    - `prisma-composer-core-concepts`, inside `@prisma/composer`: declaring services, modules, databases, and builds; `dev`, `deploy`, and teardown.
    
    `npx prisma skills sync` copies them into the agent skill directories (`.claude/skills`, `.cursor/skills`, `.agents/skills`, `.devin/skills`), and `npx prisma skills list` shows what is installed. `npx prisma init` does the same and adds a `postinstall` hook that keeps them current. When those skills are installed, use them for API details. This skill covers the deploy and operations workflow and its pitfalls.
    
    ## Removed Surface
    
    The Compute CLI from before Composer is gone. Its commands fail with `CLI.UNKNOWN_COMMAND` (removed flags with `CLI.INVALID_ARGUMENTS`), its config files are not read, and its environment variables are ignored:
    
    | Removed | Use instead |
    |---------|-------------|
    | `@prisma/cli app deploy`, `app build`, `app run` | Your own build script, then `npx prisma deploy module.ts`; `npx prisma dev module.ts` to run locally |
    | `prisma.compute.ts`, `prisma.compute.json`, `defineComputeConfig` | `module.ts`, a `service.ts` per server declared with `compute()`, and the `composer` section of `prisma.config.ts` |
    | `init` writing a compute config | `npx prisma init` now writes a `prisma.config.ts` with only a `skills` section, adds `prisma` as a dev dependency, and syncs skills. Add the `composer` section yourself |
    | `compute:deploy` script | `npx prisma deploy module.ts`, or the `deploy` script current `create-prisma` generates |
    | `app deploy --branch <name>` | `npx prisma deploy module.ts --stage <name>` |
    | `app deploy --prod`, `--no-promote`, `app promote` | No `--stage` deploys production; `service version promote <version-id>` |
    | `app show`, `app open`, `app list-deploys`, `app show-deploy` | `service show <service>`, `service open <service>`, `service version list <service>`, `service version show <version-id>` |
    | `app logs` | `service logs <service>` |
    | `app rollback --to <id> --yes` | `service version rollback <service> --to <id> --confirm <id>` |
    | `app domain ...` | `service domain ... --service <service>` |
    | `app remove` | Remove the `provision()` from `module.ts` and deploy, or `service delete <service> --confirm <service>` |
    | `build logs <build-id>` | The GitHub Actions run log or the Console; `GET /v1/builds/{buildId}` for state and failing step |
    | `database ...` | `postgres ...` |
    | `project env remove` | `project env delete` |
    | `auth logout --workspace <id>` | `auth workspace logout <id>` |
    | `agent install`, `agent update`, `agent status` | `npx skills add prisma/skills --skill prisma-compute`; `npx prisma skills sync` for package skills |
    | `PRISMA_PROJECT_ID`, `PRISMA_APP_ID`, `PRISMA_SERVICE_ID` | `--project <id-or-name>`, the service as a positional argument, and `.prisma/local.json` from `project link` |
    | `/v1/apps` REST endpoints | `/v1/services` (the `/v1/apps` paths are deprecated) |
    
    A repository with `prisma.compute.ts` or a `compute:deploy` script was set up for the removed flow. Port it to Composer ([`app-composer-setup.md`](references/app-composer-setup.md)) instead of running the old commands.
    
    ## When to Apply
    
    - Deploying a new or existing app to Prisma Compute
    - Finishing the Console's **Set up Prisma Cloud deploys** pull request (`prisma-cloud/setup`)
    - Porting a project that uses `prisma.compute.ts`, `compute:deploy`, or `@prisma/cli app deploy`
    - Setting up preview stages, deploy on push, or CI deploys
    - Reading service logs, listing versions, promoting, or rolling back
    - Managing env vars, custom domains, Prisma Postgres databases, or buckets in a Compute project
    - Debugging a failed deploy, an unreachable service, a `504`, or work that stops when an instance sleeps
    
    ## Rule Categories by Priority
    
    | Priority | Category | Impact | Prefix |
    |----------|----------|--------|--------|
    | 1 | CLI surface | CRITICAL | `cli-` |
    | 2 | App declaration | CRITICAL | `app-` |
    | 3 | Runtime | CRITICAL | `runtime-` |
    | 4 | Deploy | HIGH | `deploy-` |
    | 5 | Operations | HIGH | `ops-` |
    | 6 | Debugging | HIGH | `debug-` |
    | 7 | Automation | MEDIUM | `automation-` |
    
    ## Quick Reference
    
    ### 1. CLI surface (CRITICAL)
    
    - `cli-prisma-8-binary` - Platform and deploy commands exist only in the Prisma 8 CLI. In a Prisma 6 or 7 project, `npx prisma` runs that version's ORM CLI, which has no `auth`, `project`, `service`, or `deploy`; Prisma 7's `dev` starts a local database instead. Check `npx prisma --version`; outside a Prisma 8 project use `npx @prisma/cli@latest <command>`.
    - `cli-help-first` - Command groups are `auth`, `project` (with `project env`), `postgres`, `bucket`, `branch`, `git`, and `service` (with `service version` and `service domain`), plus `deploy`, `dev`, `init`, `skills`, and `feedback`. Read `--help` before using a flag.
    - `cli-json` - Pass `--json`, and `--no-interactive` in scripts. Branch on `error.code` (`NAMESPACE.SUBCODE`) and follow `nextActions`; do not parse messages.
    - `cli-explicit-targets` - Name the service as the first argument, the project with `--project` (or link the directory), and a preview with `--branch`. Without `--branch` a command targets the production branch; the CLI does not read the current Git branch.
    - `cli-consent-tokens` - Destructive commands need `--confirm <token>` with an exact id, name, or hostname. `--yes` cannot grant consent. Run them only when the user asked for that action.
    
    ### 2. App declaration (CRITICAL)
    
    - `app-composer-required` - A deployable app has `module.ts` (default export `module(name, ...)`), a `service.ts` per server (`compute({ name, deps, build })`), and a `composer` section in `prisma.config.ts` with `prismaCloud()`, `nodeBuild()` (plus `nextjsBuild()` for Next.js), and `state: prismaState()`.
    - `app-build-adapter` - `node({ module: import.meta.url, entry })` for one self-contained bundle, `node({ module, dir, entry })` for a built directory, `nextjs({ module, appDir })` for Next.js standalone. Add `dependencies: "external"` to `node()` when the build leaves packages as imports. See [`app-framework-builds.md`](references/app-framework-builds.md).
    - `app-region` - The first deploy creates the project and needs a region: `prismaCloud({ region: "eu-central-1" })` or `PRISMA_REGION`. The region cannot change later.
    - `app-databases` - `rawPostgres()` (package root) delivers `{ url }`; `postgres(contract)` from `@prisma/composer-prisma-cloud/orm` adds a typed client and applies committed migrations on deploy. Read both through `service.load()`, not `process.env.DATABASE_URL`.
    - `app-names` - Provision ids and service names allow `[A-Za-z0-9]` only, and the platform rejects ids shorter than three characters. The root module name becomes the project name.
    
    ### 3. Runtime (CRITICAL)
    
    - `runtime-bind-all-interfaces` - Listen on `service.port()` (also exported as `PORT`, default 3000) and bind `0.0.0.0`. A loopback listener is unreachable.
    - `runtime-bun` - Services run on Bun. By default (`dependencies: "bundled"`) a deploy ships only the build output, never the project's `node_modules`, so the build must inline every dependency except runtime built-ins. A build that leaves packages as imports (`tsc`, Astro's Node adapter) sets `dependencies: "external"` on `node()`, and the deploy stages the installed packages its entry imports.
    - `runtime-first-byte-60s` - A request that sends no bytes for 60 seconds gets `504 Gateway Time-out` and is cancelled. Respond first, then continue under `waitUntil` or from a queue.
    - `runtime-sleep` - Idle instances are snapshotted and resumed. Timers and floating promises can stall. `waitUntil` and `KeepAwakeGuard` from `@prisma/compute` keep an instance awake on a best-effort basis; they do not make work durable.
    - `runtime-no-websockets` - WebSocket servers are not supported.
    
    ### 4. Deploy (HIGH)
    
    - `deploy-build-first` - `deploy` and `dev` do not build. Run the build, then `npx prisma deploy module.ts`.
    - `deploy-dev-first` - `npx prisma dev module.ts` runs the whole app locally with no credentials. Verify each local URL before deploying.
    - `deploy-production-intent` - A deploy without `--stage`, and a push to the default branch of a connected repository, change production. Get the user's go-ahead first; use `--stage <name>` for previews.
    - `deploy-auth` - On a workstation the user runs `npx prisma auth login` (browser). In CI set `PRISMA_SERVICE_TOKEN` and `PRISMA_WORKSPACE_ID`. Check `npx prisma auth whoami --json` (`envelope.result.authenticated`, `envelope.result.workspace`) before deploying.
    - `deploy-link-after` - `deploy` finds or creates the project by the root module name (or `--name`) and does not write `.prisma/local.json`. Run `npx prisma project link <app-name>` afterwards, or pass `--project`, before `service`, `git`, or `project env` commands.
    - `deploy-on-push` - Deploy on push needs both `npx prisma git connect` (interactive) and a workflow running `prisma/cloud-deploy-action@v1`. Connecting alone deploys nothing.
    - `deploy-existing-app` - An existing server built with `tsc` deploys through `module.mjs` and `src/service.mts`, takes its client from `service.load().db.client` (`DATABASE_URL` is the placeholder `-` on Compute), and ships `views/`, `public/` and other runtime files inside `dist/`. The Console's setup pull request gets some of this wrong. See [`deploy-existing-app.md`](references/deploy-existing-app.md); a Prisma 6 or 7 app upgrades with `prisma-postgres-upgrade` first.
    - `deploy-verify-url` - Take each service URL from the deploy output (`--json` result or `--report <path>`) and request it.
    
    ### 5. Operations (HIGH)
    
    - `ops-logs` - `service logs <service>` reads the live version; `--version-id <id>` reads another, `--follow` streams. Build output lives in the CI log or the Console, not the CLI.
    - `ops-versions` - `service version promote <version-id>` rebuilds with production env vars. `service version rollback <service> --to <id> --confirm <id>` switches back without a rebuild.
    - `ops-env-write-only` - `project env add|update|list|delete` with `--role production`, `--role preview`, or `--branch <name>`. Values are never returned and apply on the next deploy.
    - `ops-domains` - `service domain add <hostname> --service <service>`, create the CNAME it reports, then `service domain wait`. Production branch only.
    - `ops-secrets-once` - `postgres create`, `postgres connection create|rotate`, and `bucket key create` print credentials once. Store them; never echo them.
    
    ### 6. Debugging (HIGH)
    
    - `debug-error-code-first` - Read `error.code` and `nextActions` from `--json` output, or `failure.code` from the `--report` file, before changing anything.
    - `debug-public-url` - Test the printed public URL, not `localhost`. A deploy that converged but does not answer is usually host binding, the port, or a crash at boot; read `service logs`.
    - `debug-report-cli-bugs` - Report unresolvable CLI failures with `npx prisma feedback "<message>"` without secrets.
    
    ### 7. Automation (MEDIUM)
    
    - `automation-create-prisma` - `create-prisma` scaffolds a new Prisma 8 project that is already a Composer app. Its `--json` mode deploys unless `--no-deploy` is passed.
    - `automation-control-api` - `@prisma/composer/control` exposes `deploy`, `destroy`, `dev`, and `log`. Teardown of a stage is `destroy`; it reads only `PRISMA_SERVICE_TOKEN` and `PRISMA_WORKSPACE_ID`.
    - `automation-rest-api` - Use `/v1/services`, `/v1/deployments/{deploymentId}/logs`, and `/v1/builds` from `https://api.prisma.io/v1/doc`. Do not build new deploy tooling on `@prisma/compute-sdk`.
    
    ## Preferred Workflow
    
    1. Inspect `package.json` (is `prisma` 8.x a dev dependency, are `@prisma/composer` and `@prisma/composer-prisma-cloud` installed?), `module.ts`, `prisma.config.ts`, the build script, and leftovers from the removed flow (`prisma.compute.ts`, `compute:deploy`).
    2. Install what is missing and sync the package skills. In an existing project, pin the Composer packages with `--save-exact` to the version that matches the installed `prisma` and `@prisma/orm-postgres` (see [`deploy-existing-app.md`](references/deploy-existing-app.md)); unpinned installs take the latest release, which may not work with them:
       ```bash
       npm install @prisma/composer @prisma/composer-prisma-cloud
       npm install -D prisma
       npx prisma skills sync
       ```
    3. Declare or port the app: [`app-composer-setup.md`](references/app-composer-setup.md) and [`app-framework-builds.md`](references/app-framework-builds.md).
    4. Build, run `npx prisma dev module.ts`, and request each local URL it prints.
    5. Run `npx prisma auth whoami --json`. If `envelope.result.authenticated` is `false`, ask the user to run `npx prisma auth login`.
    6. Deploy a preview with `npm run build && npx prisma deploy module.ts --stage <name> --json`, or production without `--stage` once the user confirms. A new project needs a region.
    7. Request each printed URL, then `npx prisma project link <app-name>` and `npx prisma service list --json` (add `--branch <stage>` for a preview).
    8. Report the app name, stage, service ids, URLs, and database ids. Never report secret values.
    
    ## Avoid
    
    - Do not run `@prisma/cli app ...`, `build logs`, or `database ...`, and do not create `prisma.compute.ts`.
    - Do not run platform commands through a Prisma 6 or 7 `prisma` binary.
    - Do not read the port or connection strings from `process.env` in a Composer service.
    - Do not expect `deploy` to build, to migrate a `rawPostgres()` database, or to copy production data into a stage.
    - Do not pass `--yes` to destructive commands; it cannot grant consent.
    - Do not run `auth login` or `git connect` non-interactively; both need a person at a browser.
    - Do not push to the default branch of a connected repository without the user's go-ahead; it deploys production.
    
    ## References
    
    - [`cli-command-map.md`](references/cli-command-map.md): every verified command, global flags, JSON envelope, targeting, consent tokens
    - [`app-composer-setup.md`](references/app-composer-setup.md): the minimum declaration, region, databases, config and secrets, porting from `prisma.compute.ts`
    - [`app-framework-builds.md`](references/app-framework-builds.md): build output and `build:` adapter per framework
    - [`runtime-requirements.md`](references/runtime-requirements.md): Bun, host and port, 60-second first byte, sleep, keep-awake, regions
    - [`deploy-cli-and-ci.md`](references/deploy-cli-and-ci.md): `prisma deploy`, stages, credentials, output, CI, teardown
    - [`deploy-on-push.md`](references/deploy-on-push.md): GitHub connection and the `prisma/cloud-deploy-action` workflow
    - [`deploy-existing-app.md`](references/deploy-existing-app.md): an existing `tsc` server, the Console's setup pull request and its fixes, and the same files without one
    - [`ops-services-and-config.md`](references/ops-services-and-config.md): services, versions, logs, domains, env vars, databases, buckets
    - [`debug-deploy-failures.md`](references/debug-deploy-failures.md): symptoms, causes, and fixes
    - [`automation-create-prisma.md`](references/automation-create-prisma.md): scaffolding a new Composer app
    - [`automation-rest-api.md`](references/automation-rest-api.md): REST API paths, the control API, and the status of `@prisma/compute-sdk`
    
    Docs: [Compute](https://www.prisma.io/docs/compute), [Deploy your first app](https://www.prisma.io/docs/prisma-compute/deploy), [Composer](https://www.prisma.io/docs/composer), [CLI reference](https://www.prisma.io/docs/cli).
    
    ## Feedback
    
    `npx prisma feedback "<message>"` sends anonymous feedback to the CLI team with the CLI version, Node.js version, and OS platform. Add `--email <address>` for a reply. Never include tokens, connection URLs, or user data.
    
    Original on GitHub
  • prisma-database-setupDeprecated compatibility name for prisma-orm-setup. Use only when a user or existing integration explicitly invokes prisma-database-setup; otherwise select prisma-orm-setup.Read
    ---
    name: prisma-database-setup
    description: Deprecated compatibility name for prisma-orm-setup. Use only when a user or existing integration explicitly invokes prisma-database-setup; otherwise select prisma-orm-setup.
    license: MIT
    metadata:
      author: prisma
      version: "8.0.0"
    ---
    
    # Deprecated: prisma-database-setup
    
    Load `prisma-orm-setup` with the host's skill loader or read its installed `SKILL.md`. If unavailable, install it from [prisma/skills](https://github.com/prisma/skills/tree/main/prisma-orm-setup) before continuing. It covers Prisma 6, 7, and 8 setup and connection repair.
    
    This compatibility entry contains no setup recipes. Keep it until consumers have migrated to the replacement.
    
    Original on GitHub
  • prisma-driver-adapter-implementationRequired reference for Prisma ORM 7 SQL driver adapter work. Use when implementing or modifying adapters, adding database drivers, or touching SqlDriverAdapter, Transaction, savepoint, result mapping, or DriverAdapterError behavior. Covers current transaction lifecycle, optional savepoint hooks, original database-error preservation, and verification.Read
    ---
    name: prisma-driver-adapter-implementation
    description: Required reference for Prisma ORM 7 SQL driver adapter work. Use when implementing or modifying adapters, adding database drivers, or touching SqlDriverAdapter, Transaction, savepoint, result mapping, or DriverAdapterError behavior. Covers current transaction lifecycle, optional savepoint hooks, original database-error preservation, and verification.
    license: MIT
    metadata:
      author: prisma
      version: "7.9.1"
    ---
    
    # Prisma SQL Driver Adapter Implementation
    
    Use this guide with the exact `@prisma/driver-adapter-utils` version installed by the target Prisma release. Driver adapters are a protocol boundary: type-compatible code can still corrupt values, leak connections, or break transactions.
    
    ## When to Apply
    
    - Implementing `SqlDriverAdapterFactory`, `SqlMigrationAwareDriverAdapterFactory`, `SqlDriverAdapter`, or `Transaction`
    - Adding nested-transaction/savepoint support
    - Mapping driver values, column metadata, bind arguments, or database errors
    - Debugging `P2039`, transaction leaks, shadow-database failures, or adapter-specific query behavior
    
    ## Contract snapshot
    
    ```typescript
    interface SqlDriverAdapterFactory extends AdapterInfo {
      connect(): Promise<SqlDriverAdapter>
    }
    
    interface SqlMigrationAwareDriverAdapterFactory extends SqlDriverAdapterFactory {
      connectToShadowDb(): Promise<SqlDriverAdapter>
    }
    
    interface SqlDriverAdapter extends AdapterInfo {
      queryRaw(query: SqlQuery): Promise<SqlResultSet>
      executeRaw(query: SqlQuery): Promise<number>
      executeScript(script: string): Promise<void>
      startTransaction(isolationLevel?: IsolationLevel): Promise<Transaction>
      getConnectionInfo?(): ConnectionInfo
      dispose(): Promise<void>
    }
    
    interface Transaction extends AdapterInfo {
      readonly options: { usePhantomQuery: boolean }
      queryRaw(query: SqlQuery): Promise<SqlResultSet>
      executeRaw(query: SqlQuery): Promise<number>
      commit(): Promise<void>
      rollback(): Promise<void>
      createSavepoint?(name: string): Promise<void>
      rollbackToSavepoint?(name: string): Promise<void>
      releaseSavepoint?(name: string): Promise<void>
    }
    ```
    
    `IsolationLevel` currently includes `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READ`, `SNAPSHOT`, and `SERIALIZABLE`; validate what the concrete database supports.
    
    ## Priority rules
    
    | Priority | Rule | Impact |
    |----------|------|--------|
    | CRITICAL | One dedicated connection per transaction | Prevents interleaving and leaks |
    | CRITICAL | `commit`/`rollback` are lifecycle cleanup hooks | Prevents duplicate COMMIT/ROLLBACK |
    | CRITICAL | Savepoints live on `Transaction`, not adapter-global depth | Makes nested scopes connection-local |
    | CRITICAL | Preserve original database error code/message | Enables useful `P2039` fallback |
    | HIGH | Map arguments and result metadata exactly | Prevents silent value corruption |
    | HIGH | Shadow databases are isolated and always cleaned up | Makes Migrate safe |
    | HIGH | Dispose only resources the adapter owns | Prevents shutting down caller-owned pools |
    
    ## Query implementation
    
    `SqlQuery` contains `sql`, `args`, and parallel `argTypes`. Map each argument using both value and `ArgType`; do not discard type/arity information. Execute in the driver's array/tuple row mode so column order is stable.
    
    ```typescript
    class ExampleQueryable {
      readonly provider = 'postgres' as const
      readonly adapterName = '@acme/adapter-example'
    
      constructor(protected readonly connection: DriverConnection) {}
    
      async queryRaw(query: SqlQuery): Promise<SqlResultSet> {
        try {
          const result = await this.connection.query({
            text: query.sql,
            values: query.args.map((value, index) =>
              mapArg(value, query.argTypes[index]),
            ),
            rowMode: 'array',
          })
    
          return {
            columnNames: result.fields.map((field) => field.name),
            columnTypes: result.fields.map(mapColumnType),
            rows: result.rows,
          }
        } catch (error) {
          throwAdapterError(error)
        }
      }
    
      async executeRaw(query: SqlQuery): Promise<number> {
        try {
          const result = await this.connection.execute(
            query.sql,
            query.args.map((value, index) => mapArg(value, query.argTypes[index])),
          )
          return result.rowsAffected ?? 0
        } catch (error) {
          throwAdapterError(error)
        }
      }
    }
    ```
    
    ### Result mapping
    
    Return `columnNames`, `columnTypes`, and `rows` with identical lengths/order. Map driver metadata to `ColumnTypeEnum` deliberately:
    
    - signed integer widths to `Int32`/`Int64`; preserve 64-bit values without JS number truncation
    - decimal/numeric to `Numeric` using the representation expected by Prisma
    - binary to `Uint8Array`/`Bytes`
    - date-only, time-only, and timestamp to `Date`, `Time`, and `DateTime`
    - UUID, JSON, enum, arrays, and provider-specific unknown values to their explicit types
    - unsupported native types to `DriverAdapterError({ kind: 'UnsupportedNativeDataType', type })`
    
    Test `null`, empty arrays, array element types, big integers, decimals, byte arrays, JSON, dates, and user-defined/unknown native types.
    
    ### Script execution
    
    `executeScript` must execute a migration script as the provider expects. Prefer the driver's native multi-statement/script facility or a real SQL parser. Naively splitting on `;` breaks functions, triggers, quoted strings, and dialect-specific blocks.
    
    ## Transaction protocol
    
    `startTransaction` must acquire one dedicated connection, start the database transaction, apply the requested isolation level, and return a `Transaction` bound to that same connection. If setup fails, release it immediately.
    
    ```typescript
    async startTransaction(level?: IsolationLevel): Promise<Transaction> {
      const connection = await this.pool.acquire()
      try {
        const tx = new ExampleTransaction(connection, () => connection.release())
        await tx.executeRaw({ sql: 'BEGIN', args: [], argTypes: [] })
        if (level) {
          await tx.executeRaw({
            sql: `SET TRANSACTION ISOLATION LEVEL ${validateLevel(level)}`,
            args: [],
            argTypes: [],
          })
        }
        return tx
      } catch (error) {
        connection.release(error)
        throwAdapterError(error)
      }
    }
    ```
    
    ### Commit and rollback
    
    Prisma coordinates the SQL `COMMIT`/`ROLLBACK` through `executeRaw`. The transaction object's `commit()` and `rollback()` methods are lifecycle hooks: detach listeners and release the dedicated connection exactly once. They must not issue a second SQL commit/rollback.
    
    ```typescript
    class ExampleTransaction extends ExampleQueryable implements Transaction {
      readonly options = { usePhantomQuery: false }
      #closed = false
    
      constructor(connection: DriverConnection, private readonly release: () => void) {
        super(connection)
      }
    
      async commit() { this.finish() }
      async rollback() { this.finish() }
    
      private finish() {
        if (this.#closed) return
        this.#closed = true
        this.release()
      }
    
      async createSavepoint(name: string) {
        await this.control(`SAVEPOINT ${safeSavepoint(name)}`)
      }
    
      async rollbackToSavepoint(name: string) {
        await this.control(`ROLLBACK TO SAVEPOINT ${safeSavepoint(name)}`)
      }
    
      async releaseSavepoint(name: string) {
        await this.control(`RELEASE SAVEPOINT ${safeSavepoint(name)}`)
      }
    
      private async control(sql: string) {
        await this.executeRaw({ sql, args: [], argTypes: [] })
      }
    }
    ```
    
    Implement the optional savepoint methods only where the provider supports them. Validate/quote savepoint identifiers. For providers whose savepoints are intentionally no-ops, document and test that limitation.
    
    Never keep transaction depth on the shared adapter. Parallel transactions make adapter-global depth incorrect; nested state belongs to the returned transaction connection and Prisma's savepoint calls.
    
    ## Error mapping
    
    Wrap recognized driver failures in `DriverAdapterError`. Map known conditions to `MappedError` kinds such as constraint violations, authentication/reachability, missing table/column/database, timeouts, closed transactions, invalid input, value range, and write conflicts.
    
    For database errors, preserve `originalCode` and `originalMessage` even when falling back to the provider-specific raw variant:
    
    ```typescript
    import {
      DriverAdapterError,
      type Error as DriverAdapterErrorObject,
      type MappedError,
    } from '@prisma/driver-adapter-utils'
    
    function convertDriverError(error: DatabaseError): DriverAdapterErrorObject {
      return {
        originalCode: String(error.code),
        originalMessage: error.message,
        ...mapKnownOrRaw(error),
      }
    }
    
    function mapKnownOrRaw(error: DatabaseError): MappedError {
      if (error.code === '23505') {
        return { kind: 'UniqueConstraintViolation', constraint: parsedConstraint(error) }
      }
      return {
        kind: 'postgres',
        code: String(error.code ?? 'N/A'),
        severity: error.severity ?? 'N/A',
        message: error.message,
        detail: error.detail,
        column: error.column,
        hint: error.hint,
      }
    }
    
    function throwAdapterError(error: unknown): never {
      if (!isDatabaseError(error)) throw error
      throw new DriverAdapterError(convertDriverError(error))
    }
    ```
    
    Prisma uses preserved original details when an unmapped driver error becomes `P2039`. Do not replace every unknown exception with a fabricated `GenericJs` id; rethrow genuinely unexpected non-driver errors so programming bugs remain visible.
    
    ## Factory, ownership, and shadow database
    
    - `connect()` returns a fresh usable adapter connection/pool wrapper.
    - Track whether the factory created the pool. `dispose()` closes owned pools and only detaches listeners from caller-owned pools unless an explicit option transfers ownership.
    - Implement `SqlMigrationAwareDriverAdapterFactory` only when `connectToShadowDb()` can create an isolated shadow database, connect to it, and drop it during disposal/failure cleanup.
    - Never point the shadow adapter at the primary database. Quote generated identifiers and use cryptographically unique names.
    - `getConnectionInfo()` should accurately report `schemaName`, `maxBindValues` when applicable, and `supportsRelationJoins`.
    
    ## Verification checklist
    
    - [ ] Typecheck against the exact target `@prisma/driver-adapter-utils` version
    - [ ] `queryRaw` preserves column order, types, nulls, and precision
    - [ ] `executeRaw` reports affected rows correctly
    - [ ] `executeScript` handles provider-specific multi-statement syntax
    - [ ] Concurrent interactive transactions use distinct dedicated connections
    - [ ] Success commits and releases once; failure rolls back and releases once
    - [ ] Nested transaction tests exercise create/rollback/release savepoint hooks
    - [ ] Unsupported isolation levels fail as `InvalidIsolationLevel`
    - [ ] Known constraints map to structured errors
    - [ ] Unmapped database errors retain original code/message and surface useful `P2039`
    - [ ] Dispose ownership is tested for internal and external pools
    - [ ] Shadow database creation, use, failure cleanup, and disposal are isolated
    - [ ] Run Prisma Client integration/E2E tests, not only adapter unit tests
    
    ## Source references
    
    - [Driver adapter interfaces](https://github.com/prisma/prisma/blob/v7/packages/driver-adapter-utils/src/types.ts)
    - [PostgreSQL adapter transaction implementation](https://github.com/prisma/prisma/blob/v7/packages/adapter-pg/src/pg.ts)
    - [PostgreSQL adapter error mapping](https://github.com/prisma/prisma/blob/v7/packages/adapter-pg/src/errors.ts)
    
    Original on GitHub
  • prisma-mongodb-upgradeDecision 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".Read
    ---
    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 8. Triggers on "upgrade prisma mongodb", "prisma 7 mongodb", "mongodb prisma migration", "prisma 8 mongodb".
    license: MIT
    metadata:
      author: prisma
      version: "0.2.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 8, where MongoDB support is in [Early Access](https://www.prisma.io/docs/orm/supported-databases)
    while PostgreSQL is a release candidate. The official
    [Prisma ORM 6 to 8 (MongoDB) guide](https://www.prisma.io/docs/guides/upgrade-prisma-orm/mongodb)
    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
    
    | 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 8 | MongoDB 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
    
    | Signal | Direction |
    |--------|-----------|
    | No blockers below apply | Migrate to Prisma 8; run the `verify-cutover-checklist` and share feedback with the Prisma team |
    | Greenfield / prototype / internal tool | Migrate to Prisma 8 |
    | 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 Prisma 8 adds a MongoDB transaction method |
    | Team cannot absorb breaking changes between release candidates | Stay on v6 until MongoDB support leaves Early Access |
    | Risk-averse but interested | Point 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`](../prisma-orm-setup/references/v6-mongodb.md) for the v6 MongoDB shape).
    - Re-evaluate when Prisma 8's MongoDB support leaves Early Access, or when the blockers 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) → Prisma 8 contract concepts |
    | `references/client-api-mapping.md` | v6 client calls → Prisma 8 equivalents, incl. raw escape hatches and transactions — names map, parity does not |
    | `references/migrations-mapping.md` | v6 `db push`-only story → Prisma 8'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
    
    Prisma 8 claims in this skill were checked against the
    [Prisma ORM 6 to 8 (MongoDB) guide](https://www.prisma.io/docs/guides/upgrade-prisma-orm/mongodb),
    written for `@prisma/orm-mongo` 8.0.0-rc.13, and the `prisma-8` skill in
    [prisma/orm](https://github.com/prisma/orm/tree/main/skills/prisma-8) 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.
    
    Original on GitHub
  • prisma-orm-setupSet up Prisma ORM in an application, connect its database, or troubleshoot the connection of an existing Prisma 6, 7, or 8 app. Defaults new applications to Prisma ORM 8 and loads the package-owned prisma-8 skill; keeps existing Prisma 6/7 apps on their version with provider references for PostgreSQL, MySQL, SQLite, SQL Server, CockroachDB, MongoDB, and Prisma Postgres.Read
    ---
    name: prisma-orm-setup
    description: Set up Prisma ORM in an application, connect its database, or troubleshoot the connection of an existing Prisma 6, 7, or 8 app. Defaults new applications to Prisma ORM 8 and loads the package-owned prisma-8 skill; keeps existing Prisma 6/7 apps on their version with provider references for PostgreSQL, MySQL, SQLite, SQL Server, CockroachDB, MongoDB, and Prisma Postgres.
    license: MIT
    metadata:
      author: prisma
      version: "1.0.0"
    ---
    
    # Prisma ORM setup
    
    This skill owns ORM version selection for setup and connection work. Preserve the application's ORM version and intended database. A connection repair does not require a major upgrade.
    
    New applications default to **Prisma ORM 8**. Detailed Prisma 8 configuration, queries, migrations, and runtime code belong to the versioned [prisma-8 skill](https://github.com/prisma/orm/tree/main/skills/prisma-8) shipped with the ORM package.
    
    ## 1. Detect the starting point
    
    Read the package manifest, lockfile, Prisma configuration, schema, and application imports. Identify the ORM version, database provider, and runtime. The CLI version alone does not identify the application's version: a Prisma 8 CLI can coexist with a legacy client, so inspect `@prisma/client`, `@prisma/prisma7`, and the schema and configuration.
    
    | Starting point                                          | Path                                                     |
    | ------------------------------------------------------- | -------------------------------------------------------- |
    | Prisma 8 application                                    | Step 4, without reinitializing                           |
    | New application without a version choice                | Step 3                                                   |
    | Prisma 6 or 7 application, or an explicit earlier major | [Step 5](#5-set-up-or-repair-an-earlier-version)         |
    
    For a new application, check the selected Prisma 8 release's [provider support](https://www.prisma.io/docs/orm/supported-databases) and runtime requirements before installing. If the provider is unsupported, explain the limitation and offer an explicitly selected earlier version. Keep the requested database; do not silently fall back or invent a supported target.
    
    Use an existing database when supplied. Load `prisma-postgres-setup` only when Prisma Postgres is needed and no connection has been selected yet; return here once connected.
    
    ## 2. Handle requested major upgrades separately
    
    When the user requests a major upgrade, load a workflow that supports the source version and provider. For PostgreSQL 6 or 7 to 8 in one pass, use [prisma-postgres-upgrade](../prisma-postgres-upgrade/SKILL.md); for PostgreSQL 7-to-8 one route at a time, use the [route-by-route guide](https://www.prisma.io/docs/guides/upgrade-prisma-orm/postgresql-incremental); for MongoDB 6-to-8, use [prisma-mongodb-upgrade](../prisma-mongodb-upgrade/SKILL.md). Other providers need an explicitly supported migration path. `prisma-upgrade-v7` covers **6 to 7**; the package-owned `prisma-8` upgrade reference covers updates within 8.
    
    ## 3. Bootstrap a new Prisma 8 application
    
    Check the selected release's [runtime requirements](https://www.prisma.io/docs/orm/release-status) and [initialization guide](https://www.prisma.io/docs/cli/orm-init). Resolve and pin a published Prisma CLI **8** release, including its prerelease suffix if needed; verify its version before initialization. Do not rely on a floating `latest` remaining version 8.
    
    Use the project's package manager to run the installed CLI. For PostgreSQL and Prisma schema language authoring:
    
    ```bash
    prisma orm init --yes --target postgres --authoring psl
    ```
    
    Use the supported target for the selected provider. Preserve existing application files and connection configuration; do not let setup provision an unrelated database. Verify that the resolved ORM package is version 8 before proceeding.
    
    ## 4. Load the installed Prisma 8 guidance
    
    Run the installed CLI through the project's package manager:
    
    ```bash
    prisma skills sync
    ```
    
    Then **read** the synced `prisma-8/SKILL.md`, for example `.agents/skills/prisma-8/SKILL.md`, and follow its preconditions and selected references. Syncing alone does not load the instructions. If the package-owned guidance cannot be loaded, report the blocker. Continue with step 6.
    
    ## 5. Set up or repair an earlier version
    
    For a new setup that explicitly selects an earlier version, pin packages to that major and use its runtime requirements. Keep the CLI, client, and SQL adapter releases compatible. Existing dependencies need not change for a connection repair.
    
    - **Prisma 7 SQL:** use the provider reference below and [client setup](references/v7-client-setup.md).
    - **Prisma 6 MongoDB:** use [MongoDB setup](references/v6-mongodb.md). SQL driver adapters do not apply.
    - **Prisma 6 SQL:** preserve its generator, schema URL, and client initialization. Use the provider's connection details below and the [Prisma 6 documentation](https://www.prisma.io/docs/orm/v6); do not copy the Prisma 7 configuration or adapter examples into it.
    
    | Database                         | Reference                                                 |
    | -------------------------------- | --------------------------------------------------------- |
    | PostgreSQL                       | [PostgreSQL](references/v7-postgresql.md)                 |
    | MySQL / MariaDB / PlanetScale    | [MySQL](references/v7-mysql.md)                           |
    | SQLite / Turso                   | [SQLite](references/v7-sqlite.md)                         |
    | Microsoft SQL Server / Azure SQL | [SQL Server](references/v7-sqlserver.md)                  |
    | CockroachDB                      | [CockroachDB](references/v7-cockroachdb.md)               |
    | MongoDB / Atlas on Prisma 6      | [MongoDB](references/v6-mongodb.md)                       |
    | Prisma Postgres with Prisma 7    | [Prisma Postgres](references/v7-prisma-postgres.md)       |
    
    The Prisma 7 SQL examples were verified with Prisma 7.10.0; the MongoDB examples with Prisma 6.19.3.
    
    ## 6. Connect and verify
    
    The CLI and the application can load different environment files. Load the intended environment for each without printing secrets, and keep credentials in ignored environment files or the host's secret configuration. For SQL adapters, make the adapter's runtime options address the same database as the CLI connection URL.
    
    For an existing app, preserve schema, migrations, and generator configuration unless the requested work requires changes. Diagnose the connection before running schema-changing commands.
    
    Run the project's relevant checks and a read-only query through the application's client against the intended database. Report the ORM version, the loaded `prisma-8` skill version where applicable, and the query result. Package installation or a successful skill sync alone is not a completed setup.
    
    Original on GitHub
  • prisma-postgresDeprecated compatibility name for prisma-postgres-setup. Use only when a user or existing integration explicitly invokes prisma-postgres; otherwise select prisma-postgres-setup.Read
    ---
    name: prisma-postgres
    description: Deprecated compatibility name for prisma-postgres-setup. Use only when a user or existing integration explicitly invokes prisma-postgres; otherwise select prisma-postgres-setup.
    license: MIT
    metadata:
      author: prisma
      version: "8.0.0"
    ---
    
    # Deprecated: prisma-postgres
    
    Load `prisma-postgres-setup` with the host's skill loader or read its installed `SKILL.md`. If unavailable, install it from [prisma/skills](https://github.com/prisma/skills/tree/main/prisma-postgres-setup) before continuing.
    
    This compatibility entry contains no setup recipes. Keep it until consumers have migrated to the replacement.
    
    Original on GitHub
  • prisma-postgres-setupObtain or reuse a Prisma Postgres database and connect an application. Use when the user needs a database and has none configured ("I need a database", "add a Postgres database", "set up a database for this app"), runs or mentions `create-db` or `npx create-db`, or asks to set up or connect Prisma Postgres, including in v0 and the Vercel Marketplace. Hands Prisma ORM configuration to prisma-orm-setup; reuses an existing connection first and honors an explicit provider, driver, alternative ORM, or database-only choice.Read
    ---
    name: prisma-postgres-setup
    description: Obtain or reuse a Prisma Postgres database and connect an application. Use when the user needs a database and has none configured ("I need a database", "add a Postgres database", "set up a database for this app"), runs or mentions `create-db` or `npx create-db`, or asks to set up or connect Prisma Postgres, including in v0 and the Vercel Marketplace. Hands Prisma ORM configuration to prisma-orm-setup; reuses an existing connection first and honors an explicit provider, driver, alternative ORM, or database-only choice.
    license: MIT
    metadata:
      author: prisma
      version: "2.3.1"
    ---
    
    # Prisma Postgres setup
    
    Connect the intended database, then verify it from the application. Keep provisioning separate from ORM configuration so an existing database is reused.
    
    ## 1. Inspect the project
    
    Check the user's requested ORM or driver, installed packages, database connection, and environment-loading files. Check secret presence without printing values.
    
    - Honor explicit choices such as Drizzle, `pg`, or database-only setup.
    - For query or schema work in an already configured app, use its version-matched ORM guidance; do not restart setup.
    
    ## 2. Reuse or obtain a database
    
    | Situation                                    | Action                                                                                                           |
    | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
    | Existing connection or connected integration | Verify its project, database, and environment; reuse it.                                                         |
    | v0, Vercel Marketplace, or a Vercel project  | Read [Marketplace setup](references/vercel-marketplace.md) and use the native integration flow.                  |
    | No database yet and no provider named        | Offer `npx create-db@latest` for a working database now with no account (it is deleted after 24 hours unless claimed, and claiming needs a free Prisma account; read the create-db section in [provisioning](references/provisioning.md)), or a persistent database through [provisioning](references/provisioning.md). Ask which one when the request does not say. |
    | Standalone persistent database               | Read [provisioning](references/provisioning.md); use an authenticated CLI, MCP tool, Console, or Management API. |
    | Temporary development database requested     | Read the `create-db` section in [provisioning](references/provisioning.md), including expiry and claiming.       |
    
    Resolve the workspace, project, and region before creation. If several resources fit, ask which one to use. If provisioning is blocked by permissions or quota, report the blocker; do not delete another resource or switch workspaces to get around it.
    
    ## 3. Connect the application
    
    Use the connection appropriate to the chosen driver and runtime. Store it in the project's secret environment configuration, never source code or chat. Preserve unrelated entries, update the intended variable once, and ensure local secret files are ignored by Git.
    
    Application processes and CLI commands may load different environment files. For example, a framework may load `.env.development.local` while a shell command does not. A variable missing from the shell does not mean the database is missing: load the intended file for that command without displaying credentials, and do not provision another database.
    
    ## 4. Configure the ORM and verify
    
    For Prisma ORM setup, read [prisma-orm-setup/SKILL.md](https://github.com/prisma/skills/blob/main/prisma-orm-setup/SKILL.md) directly, or load the installed `prisma-orm-setup` skill when the host resolves sibling skills by name. It owns ORM version selection and configuration. If that handoff is unavailable, report it.
    
    For an explicitly selected alternative, keep that ORM or driver and use its documented setup. For database-only setup, stop after verifying connectivity.
    
    Run a read-only query against the intended database through the application's chosen ORM or driver. Report what was connected, the selected ORM/version, and the query result without secrets. If any step is blocked or untested, say so instead of claiming setup is complete.
    
    For Studio, SDK integrations, or database operations beyond initial setup, read [operations](references/operations.md).
    
    Original on GitHub
  • prisma-postgres-upgradeUpgrade a PostgreSQL app from Prisma ORM 6 or 7 straight to Prisma 8 in one pass, keeping the existing schema.prisma, database and data. Use when a Postgres project on Prisma 6 or 7 wants Prisma 8, including before deploying it on Prisma Compute, which runs only Prisma 8. Triggers on "upgrade prisma 6 to 8", "upgrade prisma 7 to 8", "upgrade to prisma 8 postgres", "prisma7Schema", "migrations/app", "move off @prisma/client", "Console says move to Prisma 8".Read
    ---
    name: prisma-postgres-upgrade
    description: Upgrade a PostgreSQL app from Prisma ORM 6 or 7 straight to Prisma 8 in one pass, keeping the existing schema.prisma, database and data. Use when a Postgres project on Prisma 6 or 7 wants Prisma 8, including before deploying it on Prisma Compute, which runs only Prisma 8. Triggers on "upgrade prisma 6 to 8", "upgrade prisma 7 to 8", "upgrade to prisma 8 postgres", "prisma7Schema", "migrations/app", "move off @prisma/client", "Console says move to Prisma 8".
    license: MIT
    metadata:
      author: prisma
      version: "2.0.0"
    ---
    
    # Prisma Postgres Upgrade: Prisma ORM 6 or 7 to Prisma 8
    
    Move a Node.js server on Prisma ORM 6 or 7 and PostgreSQL to Prisma 8 in one pass. The schema,
    the database and its data stay, and the app keeps running wherever it runs today.
    
    This skill is the bridge. It covers only what is specific to leaving Prisma ORM 6 or 7. Prisma 8
    itself (the contract, migrations, queries, errors) is covered by the `prisma-8` skill that ships
    inside `@prisma/orm-postgres`, which step 2 installs. Follow it for anything Prisma 8 specific;
    it matches the installed version, and this skill does not.
    
    `prisma-8` says it does not apply to a project that still has `schema.prisma` and
    `@prisma/client`. That is expected mid-upgrade: this skill keeps both until step 5, and
    `prisma7Schema(...)` reads that `schema.prisma`. Use `prisma-8` for the Prisma 8 side anyway.
    
    The [Prisma ORM 6 or 7 to 8 (PostgreSQL) guide](https://www.prisma.io/docs/guides/upgrade-prisma-orm/postgresql)
    is the source of truth for the steps.
    
    **Never do either of these:**
    
    - Never route a PostgreSQL Prisma ORM 6 app through Prisma ORM 7 first. Prisma 8 reads a
      Prisma ORM 6 `schema.prisma` unchanged, so `prisma-upgrade-v7` is only for apps that stay on 7.
    - Never install `prisma@latest` or `@prisma/orm-postgres@latest` when the app will deploy on
      Prisma Compute: the latest pair does not work with the Composer version the Console's setup
      installs, so the deploy fails.
    
    ## When to Apply
    
    - A PostgreSQL project on Prisma ORM 6 or 7 asks to upgrade to Prisma 8 in one pass
    - A Prisma ORM 6 or 7 app wants to deploy on Prisma Compute, or the Console blocked its setup
      with "move to Prisma 8": upgrade here, then deploy with `prisma-compute`
    
    Not for: deploying on Compute (use `prisma-compute`, `deploy-existing-app`), MongoDB (use
    `prisma-mongodb-upgrade`), a Prisma ORM 7 app moving one route at a time beside Prisma 8
    (follow the [route-by-route guide](https://www.prisma.io/docs/guides/upgrade-prisma-orm/postgresql-incremental)),
    a project already on Prisma 8 (use the synced `prisma-8` skill), or a new project (use
    `prisma-orm-setup`).
    
    ## Versions
    
    Install exact versions with `--save-exact`. For an app headed to Compute, use the versions the
    Console's setup uses: today `prisma` `8.0.0-rc.27` (dev dependency) and `@prisma/orm-postgres`
    `8.0.0-rc.20`. If the Console's message or an existing setup pull request names other versions,
    use those. Use Node.js 24.11 or newer if the app will run under `prisma dev`.
    
    ## The path
    
    | Step | What happens | Where the detail is |
    |------|--------------|---------------------|
    | 0 | Run the repo's own checks and record the results | `verify-upgrade-checklist` |
    | 1 | Remove `prisma`, install the versions above, remove `prisma generate` from scripts | this file |
    | 2 | Write the Prisma 8 `prisma.config.ts`, then `npx prisma skills sync` | `adopt-schema-and-migrations` |
    | 3 | `contract emit`, `db sign`, baseline migration, retire `prisma/migrations` | `adopt-schema-and-migrations` |
    | 4 | Create the Prisma 8 client and rewrite every query | `client-api-mapping` |
    | 5 | Remove `@prisma/client`, the adapter and the generated client | this file |
    | 6 | Run the same checks again and start the app | `verify-upgrade-checklist` |
    
    In step 1, also remove `prisma generate` from `build`, `postinstall` and any other script: the
    Prisma 8 CLI has no `generate` and fails with `CLI.UNKNOWN_COMMAND`. Step 1 removes the only
    command that generated the old client. It keeps working locally, but a fresh install (CI, a new
    clone) has none, so finish step 4 before pushing to a branch CI builds.
    
    The sync in step 2 installs `prisma-8`, `prisma-platform-core-concepts` and
    `prisma-composer-core-concepts` in one go, because the CLI depends on Composer. It writes them
    for every agent it knows unless `skills.agents` in the config lists only the ones the repository
    uses. In a Prisma ORM 7 app, replace the old `prisma.config.ts` before syncing: the sync fails
    with `CLI.CONFIG_UNREADABLE` while the old one is in place.
    
    Commit what Prisma 8 writes: `src/prisma/contract.json`, `src/prisma/contract.d.ts` and the
    whole `migrations/` folder. There is no generate step to recreate them in CI.
    
    In step 5, `npm uninstall @prisma/client` leaves the generated client behind; delete
    `node_modules/.prisma` too, then run a fresh install and the checks so nothing still imports it.
    
    ## Deploying on Compute
    
    When the upgrade is done and the checks pass, deploy with the `prisma-compute` skill
    (`references/deploy-existing-app.md`). Compute runs only Prisma 8, so the upgrade has to be
    finished first.
    
    ## What the user does
    
    The agent cannot do these; stop and ask:
    
    - Decide what to do about a database time zone other than UTC (see `client-api-mapping`).
    - Sign every other existing database (staging, production) with `npx prisma db sign`. The agent
      has only the local one.
    - Review the change before it ships, especially when the repository has no tests.
    
    ## Reference files
    
    | Reference | What it covers |
    |-----------|----------------|
    | `references/adopt-schema-and-migrations.md` | The first `prisma.config.ts`, keeping `schema.prisma` as the contract, CommonJS `tsconfig`, the baseline, retiring the old migration setup |
    | `references/client-api-mapping.md` | The Prisma 8 client, Prisma ORM 6/7 calls to Prisma 8, and the differences that break rewrites |
    | `references/verify-upgrade-checklist.md` | Proving the upgrade with the repo's own checks |
    
    ## Verified against
    
    A Prisma ORM 6.19 app (Express 4, EJS, `tsc`, CommonJS) on PostgreSQL 18, with `prisma`
    8.0.0-rc.27 and `@prisma/orm-postgres` 8.0.0-rc.20. Two agents with no context and only these
    skills upgraded it: pages and API output were identical before and after against the same
    database, and `prisma db verify` passed.
    
    ## Hand-off rule
    
    Once the app runs on Prisma 8, use the synced `prisma-8` skill for day-to-day work and
    `prisma-compute` to deploy and operate it on Compute. This skill covers the upgrade only.
    
    Original on GitHub
  • prisma-upgrade-v7Complete migration guide from Prisma ORM v6 to v7 covering all breaking changes. Use when upgrading Prisma versions, encountering v7 errors, or migrating existing projects. Triggers on "upgrade to prisma 7", "prisma 7 migration", "prisma-client generator", "driver adapter required".Read
    ---
    name: prisma-upgrade-v7
    description: Complete migration guide from Prisma ORM v6 to v7 covering all breaking changes. Use when upgrading Prisma versions, encountering v7 errors, or migrating existing projects. Triggers on "upgrade to prisma 7", "prisma 7 migration", "prisma-client generator", "driver adapter required".
    license: MIT
    metadata:
      author: prisma
      version: "7.6.0"
    ---
    
    # Upgrade to Prisma ORM 7
    
    Complete guide for migrating from Prisma ORM v6 to v7. This upgrade introduces significant breaking changes around the new `prisma-client` generator, driver adapters, `prisma.config.ts`, explicit environment loading, and generated client entrypoints.
    
    ## When to Apply
    
    Reference this skill when:
    - Upgrading from Prisma v6 to v7
    - Updating to the `prisma-client` generator
    - Setting up driver adapters
    - Configuring `prisma.config.ts`
    - Fixing import errors after upgrade
    
    ## Rule Categories by Priority
    
    | Priority | Category | Impact | Prefix |
    |----------|----------|--------|--------|
    | 1 | Schema Migration | CRITICAL | `schema-changes` |
    | 2 | Database Connectivity | CRITICAL | `driver-adapters` |
    | 3 | Module System | CRITICAL | `esm-support` |
    | 4 | Config and Env | HIGH | `prisma-config`, `env-variables` |
    | 5 | Removed Features | HIGH | `removed-features` |
    | 6 | Accelerate | HIGH | `accelerate-users` |
    
    ## Quick Reference
    
    - `schema-changes` - generator migration, required output paths, generated entrypoints, and `Prisma.validator` replacement
    - `driver-adapters` - required adapter installation for SQL providers, pool differences, and Prisma Postgres adapter choices
    - `esm-support` - ESM-first setup plus CommonJS fallback with `moduleFormat = "cjs"`
    - `prisma-config` - creating and using `prisma.config.ts`
    - `env-variables` - explicit environment loading
    - `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 8).
    
    ## Important Notes
    
    - **MongoDB projects should stay on Prisma 6.x or migrate to Prisma 8** - 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`
    
    ## Upgrade Steps Overview
    
    1. Update packages to v7
    2. Choose your module format (`esm` by default, `cjs` if needed)
    3. Update TypeScript configuration
    4. Update the schema generator block
    5. Create `prisma.config.ts`
    6. Install and configure a driver adapter for SQL providers
    7. Update Prisma Client imports
    8. Update client instantiation
    9. Replace deprecated helper patterns like `Prisma.validator`
    10. Run `prisma generate` and test
    
    ## Quick Upgrade Commands
    
    ```bash
    # Update packages
    npm install @prisma/client@7
    npm install -D prisma@7
    
    # Install a driver adapter (PostgreSQL or Prisma Postgres via direct TCP)
    npm install @prisma/adapter-pg pg
    
    # Install dotenv for env loading
    npm install dotenv
    
    # Regenerate client
    npx prisma generate
    ```
    
    ## Breaking Changes Summary
    
    | Change | v6 | v7 |
    |--------|----|----|
    | Module format | Implicit / mixed | ESM-first, `moduleFormat = "cjs"` supported |
    | Generator provider | `prisma-client-js` | `prisma-client` is the default, while `prisma-client-js` still exists for legacy setups |
    | Output path | Auto (node_modules) | Required explicit |
    | Driver adapters | Optional | Required for SQL providers |
    | Config file | `.env` + schema | `prisma.config.ts` |
    | Env loading | Automatic | Manual (dotenv) |
    | Generated entrypoints | Single package export | `client`, `browser`, `models`, `enums` entrypoints |
    | Type-safe query fragments | `Prisma.validator()` | TypeScript `satisfies` |
    | Middleware | `$use()` | Client Extensions |
    | Metrics | Preview feature | Removed |
    
    ## Rule Files
    
    Detailed migration guides for each breaking change:
    
    ```
    references/esm-support.md        - ESM and CommonJS configuration
    references/schema-changes.md     - Generator, output, imports, and generated entrypoints
    references/driver-adapters.md    - Required driver adapter setup
    references/prisma-config.md      - New configuration file
    references/env-variables.md      - Environment variable loading
    references/removed-features.md   - Middleware, metrics, and CLI flags
    references/accelerate-users.md   - Special handling for Accelerate
    ```
    
    ## Step-by-Step Migration
    
    ### 1. Update package.json for ESM-first projects
    
    ```json
    {
      "type": "module"
    }
    ```
    
    If you need to stay on CommonJS, keep your app as CJS and set `moduleFormat = "cjs"` in the generator block instead of forcing ESM.
    
    ### 2. Update tsconfig.json
    
    ```json
    {
      "compilerOptions": {
        "module": "ESNext",
        "moduleResolution": "bundler",
        "target": "ES2023",
        "strict": true,
        "esModuleInterop": true
      }
    }
    ```
    
    ### 3. Update schema.prisma
    
    ```prisma
    // Before (v6)
    generator client {
      provider = "prisma-client-js"
    }
    
    // After (v7)
    generator client {
      provider = "prisma-client"
      output   = "../generated/prisma"
      // Optional if you need CommonJS:
      // moduleFormat = "cjs"
    }
    ```
    
    ### 4. Create prisma.config.ts
    
    ```typescript
    import 'dotenv/config'
    import { defineConfig, env } from 'prisma/config'
    
    export default defineConfig({
      schema: 'prisma/schema.prisma',
      migrations: {
        path: 'prisma/migrations',
      },
      datasource: {
        url: env('DATABASE_URL'),
      },
    })
    ```
    
    ### 5. Install a driver adapter (SQL providers only)
    
    ```bash
    # PostgreSQL
    npm install @prisma/adapter-pg pg
    
    # MySQL
    npm install @prisma/adapter-mariadb mariadb
    
    # SQLite
    npm install @prisma/adapter-better-sqlite3 better-sqlite3
    
    # Prisma Postgres in standard Node.js apps (recommended)
    npm install @prisma/adapter-pg pg
    
    # Prisma Postgres serverless driver (edge/serverless)
    npm install @prisma/adapter-ppg @prisma/ppg
    
    # Neon
    npm install @prisma/adapter-neon
    ```
    
    MongoDB does not have a SQL `@prisma/adapter-*` package in the published Prisma 7.6.0 packages. If you're upgrading a MongoDB project, stop and keep that project on the latest Prisma 6.x release instead of following the standard Prisma 7 migration path.
    
    ### 6. Update client instantiation
    
    ```typescript
    // Before (v6)
    import { PrismaClient } from '@prisma/client'
    const prisma = new PrismaClient()
    
    // After (v7)
    import { PrismaClient } from '../generated/prisma/client'
    import { PrismaPg } from '@prisma/adapter-pg'
    
    const adapter = new PrismaPg({
      connectionString: process.env.DATABASE_URL
    })
    
    const prisma = new PrismaClient({ adapter })
    ```
    
    ### 7. Replace Prisma.validator with satisfies
    
    ```typescript
    import { Prisma } from '../generated/prisma/client'
    
    const userSelect = {
      id: true,
      email: true,
      name: true,
    } satisfies Prisma.UserSelect
    ```
    
    ### 8. Run migrations and generate
    
    ```bash
    npx prisma generate
    npx prisma migrate dev  # if needed
    ```
    
    ## Troubleshooting
    
    ### "Cannot find module" errors
    - Check that the generator `output` path matches your import path
    - Ensure `prisma generate` ran successfully
    
    ### SSL certificate errors
    - Add `ssl: { rejectUnauthorized: false }` to the adapter config if you need to preserve old behavior
    - Or configure your certificates properly with `NODE_EXTRA_CA_CERTS` / OpenSSL CA settings
    
    ### Connection timeout issues
    - Driver adapters use the underlying driver's defaults, which differ from v6
    - Configure pool settings explicitly on the adapter if needed
    
    ## Resources
    
    - [Official v7 Upgrade Guide](https://www.prisma.io/docs/orm/more/upgrades/to-v7)
    - [Driver Adapters Documentation](https://www.prisma.io/docs/orm/core-concepts/supported-databases/database-drivers)
    - [Prisma Config Reference](https://www.prisma.io/docs/orm/reference/prisma-config-reference)
    
    ## How to Use
    
    Follow `references/schema-changes.md` and `references/driver-adapters.md` first, then apply the remaining reference files based on your project setup.
    
    Original on GitHub

Author and licence

These skills were written and published by Prisma at github.com/prisma/skills under the MIT licence. skillsmcp copies them unchanged, checks the repository once a day, and is not affiliated with Prisma. A skill is a set of instructions an AI agent may follow, so read a skill before you let an agent use it.

Show the licence
MIT License

Copyright (c) 2025 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.