--- title: "prisma/skills" description: "Agent Skills from prisma/skills." source: https://github.com/prisma/skills ref: main license: MIT licenseName: "MIT License" canonical: https://skillsdocs.com/prisma/skills base: https://github.com/prisma/skills/blob/main/ chapters: 9 inlined: 9 withheld: 0 words: 6089 updated: 2026-08-04T12:21:31Z generator: "Skills Docs" --- > **prisma/skills** — every Agent Skill in this repository, inlined verbatim. > > Canonical HTML: https://skillsdocs.com/prisma/skills > Per-chapter Markdown: https://skillsdocs.com/prisma/skills/.md > Machine manifest: https://skillsdocs.com/prisma/skills/.well-known/agent-skills/index.json > JSON: https://skillsdocs.com/api/v1/books/prisma/skills > Install: `npx skills add prisma/skills` > Upstream: https://github.com/prisma/skills @ `main` > Licence: MIT > > Content is mirrored from GitHub and © its authors, served unmodified. Takedown: https://github.com/kyleledbetter/skillsdocs/issues/new?labels=takedown&title=Takedown+request # prisma/skills - **Chapters:** 9 - **Inlined:** 9 (licence detected) - **Words:** 6,089 - **Reading time:** 29 min - **Stars:** 51 ## Table of contents 1. [prisma-cli](https://skillsdocs.com/prisma/skills/prisma-cli.md) — Prisma ORM CLI commands reference covering init, generate, migrate, db, dev, complete, studio, validate, format, debug, and mcp. Use for ORM/database CLI workf… 2. [prisma-client-api](https://skillsdocs.com/prisma/skills/prisma-client-api.md) — Prisma Client API reference covering model queries, filters, operators, and client methods. Use when writing database queries, using CRUD operations, filtering… 3. [prisma-compute](https://skillsdocs.com/prisma/skills/prisma-compute.md) — Prisma Compute deployment and hosting guide. Use whenever the user mentions Prisma Compute, `prisma.compute.ts`, `defineComputeConfig`, deploying or hosting a… 4. [prisma-database-setup](https://skillsdocs.com/prisma/skills/prisma-database-setup.md) — Guides for configuring Prisma with different database providers (PostgreSQL, MySQL, SQLite, MongoDB, etc.). Use when setting up a new project, changing databas… 5. [prisma-driver-adapter-implementation](https://skillsdocs.com/prisma/skills/prisma-driver-adapter-implementation.md) — Required reference for Prisma ORM 7 SQL driver adapter work. Use when implementing or modifying adapters, adding database drivers, or touching SqlDriverAdapter… 6. [prisma-mongodb-upgrade](https://skillsdocs.com/prisma/skills/prisma-mongodb-upgrade.md) — 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, w… 7. [prisma-postgres-setup](https://skillsdocs.com/prisma/skills/prisma-postgres-setup.md) — Set up a new Prisma Postgres database and connect it to a local project using the Management API. Use when asked to "set up a database", "create a Prisma Postg… 8. [prisma-postgres](https://skillsdocs.com/prisma/skills/prisma-postgres.md) — Prisma Postgres setup and operations guidance across Console, create-db CLI, Management API, and Management API SDK. Use when creating Prisma Postgres database… 9. [prisma-upgrade-v7](https://skillsdocs.com/prisma/skills/prisma-upgrade-v7.md) — Complete migration guide from Prisma ORM v6 to v7 covering all breaking changes. Use when upgrading Prisma versions, encountering v7 errors, or migrating exist… ## Front matter _The repository README, verbatim except that relative links are resolved against https://github.com/prisma/skills/blob/main/._ # Prisma Skills A collection of skills for AI coding agents working with Prisma ORM. Skills are packaged instructions that extend agent capabilities for database development. Skills follow the [Agent Skills](https://agentskills.io/) format and are compatible with `npx skills add`. ## Available Skills ### prisma-cli Complete reference for current Prisma ORM CLI commands. For Prisma Compute app deployment, use `prisma-compute`. **Use when:** - Running Prisma ORM/database commands - Setting up new projects (`prisma init`) - Managing migrations and database schema - Generating Prisma Client **Commands covered:** - `init`, `generate`, `dev` (local Prisma Postgres) - `migrate dev`, `migrate deploy`, `migrate reset` - `db push`, `db pull`, `db seed`, `db execute` - `studio`, `mcp` --- ### prisma-upgrade-v7 Step-by-step migration guide from Prisma v6 to v7, covering all breaking changes. **Use when:** - Upgrading existing projects to Prisma 7 - Troubleshooting v7 compatibility issues - Understanding what changed in v7 **Topics covered:** - ESM-first module configuration plus CommonJS fallback - Driver adapter requirements - New `prisma.config.ts` file - Manual environment variable loading - Generated client entrypoints (`client`, `browser`, `models`, `enums`) - `Prisma.validator` to `satisfies` migration - Removed features (middleware, metrics, CLI flags) - Special handling for Accelerate users --- ### prisma-mongodb-upgrade Decision and migration guide for MongoDB projects on Prisma v6, which have no path to Prisma 7. **Use when:** - A MongoDB project asks about upgrading Prisma versions - Evaluating a move from Prisma v6 to Prisma Next - Preventing an impossible "upgrade MongoDB to v7" plan **Topics covered:** - The version landscape (v6 terminal for MongoDB; v7 has no connector; Prisma Next is the successor path) - Stay-on-v6 vs migrate-now decision table with no-go signals - Schema/contract, client API, and migrations mapping between v6 and Prisma Next - No-data-moves cutover verification checklist --- ### prisma-client-api Comprehensive Prisma Client API reference. **Use when:** - Writing Prisma Client queries - Understanding query options (select, include, where) - Working with transactions - Using raw SQL queries **Topics covered:** - PrismaClient constructor and configuration - CRUD operations (findMany, create, update, delete) - Query options (select, include, omit, orderBy, pagination) - Filter operators and conditions - Transactions ($transaction) - Raw queries ($queryRaw, $executeRaw) - Client methods ($connect, $disconnect, $extends) --- ### prisma-driver-adapter-implementation Implementation guide for Prisma SQL driver adapter development. **Use when:** - Implementing a new SQL driver adapter - Modifying `SqlDriverAdapter` or `Transaction` behavior - Wiring migration-aware adapter factories - Debugging adapter type mapping or transaction issues **Topics covered:** - Required adapter interfaces and contracts - Transaction lifecycle protocol (including nested transactions) - `SqlQuery` argument mapping and `SqlResultSet` mapping - `ColumnTypeEnum` mapping strategy - Error conversion to `DriverAdapterError` / `MappedError` - Unit and E2E verification checklist --- ### prisma-database-setup Guides for configuring Prisma with different database providers. **Use when:** - Setting up a new project with a specific database - Connecting to PostgreSQL, MySQL, SQLite, MongoDB, etc. - Troubleshooting connection issues - Configuring connection strings **Databases covered:** - PostgreSQL & Prisma Postgres - MySQL / MariaDB - SQLite - MongoDB - SQL Server - CockroachDB --- ### prisma-postgres Prisma Postgres workflows across Console, `create-db`, Management API, and SDK integrations. **Use when:** - Setting up and managing Prisma Postgres in Prisma Console - Creating instant databases with `npx create-db` - Integrating programmatic provisioning with Management API - Building typed API integrations using `@prisma/management-api-sdk` - Handling auth, regions, claim flow, and connection details **Workflows covered:** - `npx create-db@latest` - `npx create-db@latest create --help` - `npx create-db@latest regions --help` - Programmatic `create-db` usage (`create()` and `regions()`) - Console operations (`https://console.prisma.io`) - Management API (`https://api.prisma.io/v1`) - Management API SDK (`@prisma/management-api-sdk`) --- ### prisma-compute Prisma Compute deployment and hosting workflows centered on the Prisma Platform CLI, with `create-prisma` covered as the new-project scaffold path, plus framework readiness, SDK automation, and operational debugging. **Use when:** - Creating a new Prisma app with optional Compute deploy - Deploying or redeploying an existing app to Prisma Compute - Checking framework deploy readiness for Hono, Elysia, Next.js, TanStack Start, Astro, Nuxt, Svelte, Nest, Turborepo, or custom/prebuilt artifacts - Managing Compute app logs, deployments, environment variables, branches, and domains - Building programmatic Compute integrations with SDK/API tooling **Workflows covered:** - `@prisma/cli app build/run/deploy` - Generated `compute:deploy` scripts - `create-prisma --deploy` for new project scaffolds - Framework-specific build output requirements - `@prisma/compute-sdk` and Management API App/Deployment concepts - Troubleshooting auth, env, build, deploy, log, and port issues ## Installation Install all skills: ```bash npx skills add prisma/skills ``` Or install specific skills: ```bash npx skills add prisma/skills --skill prisma-cli npx skills add prisma/skills --skill prisma-upgrade-v7 npx skills add prisma/skills --skill prisma-mongodb-upgrade npx skills add prisma/skills --skill prisma-client-api npx skills add prisma/skills --skill prisma-driver-adapter-implementation npx skills add prisma/skills --skill prisma-database-setup npx skills add prisma/skills --skill prisma-postgres npx skills add prisma/skills --skill prisma-compute ``` List available skills: ```bash npx skills add prisma/skills --list ``` List installed skills: ```bash npx skills list ``` ## Usage Skills are automatically available once installed. The agent will use them when relevant tasks are detected. **Examples:** ``` Help me run Prisma migrations in production ``` ``` Upgrade my project from Prisma 6 to Prisma 7 ``` ``` How do I use transactions in Prisma? ``` ## Skill Structure Each skill contains: - `SKILL.md` - Main instructions with YAML frontmatter (name, description, metadata) - `references/` (optional) - Individual reference files with detailed explanations and code examples ## Prisma Version The ORM-focused skills target **Prisma ORM 7.6.x**. The `prisma-compute` skill tracks the active Prisma Compute launch flow and instructs agents to verify the current Prisma Platform CLI and `create-prisma` command surfaces before acting. If you're upgrading from Prisma 6, use the `prisma-upgrade-v7` skill for migration-specific guidance. ## Contributing See [AGENTS.md](https://github.com/prisma/skills/blob/main/AGENTS.md) for guidelines on creating and modifying skills. ## License MIT --- ## 1. prisma-cli - **Source:** https://github.com/prisma/skills/blob/main/prisma-cli/SKILL.md - **Raw:** https://raw.githubusercontent.com/prisma/skills/main/prisma-cli/SKILL.md - **Markdown:** https://skillsdocs.com/prisma/skills/prisma-cli.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html Bundled files (20), referenced from this skill's directory: - `references/agent-safety.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-cli/references/agent-safety.md - `references/complete.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-cli/references/complete.md - `references/db-execute.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-cli/references/db-execute.md - `references/db-pull.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-cli/references/db-pull.md - `references/db-push.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-cli/references/db-push.md - `references/db-seed.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-cli/references/db-seed.md - `references/debug.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-cli/references/debug.md - `references/dev.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-cli/references/dev.md - `references/format.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-cli/references/format.md - `references/generate.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-cli/references/generate.md - `references/init.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-cli/references/init.md - `references/mcp.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-cli/references/mcp.md - `references/migrate-deploy.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-cli/references/migrate-deploy.md - `references/migrate-dev.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-cli/references/migrate-dev.md - `references/migrate-diff.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-cli/references/migrate-diff.md - `references/migrate-reset.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-cli/references/migrate-reset.md - `references/migrate-resolve.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-cli/references/migrate-resolve.md - `references/migrate-status.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-cli/references/migrate-status.md - `references/studio.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-cli/references/studio.md - `references/validate.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-cli/references/validate.md --- name: prisma-cli description: Prisma ORM CLI commands reference covering init, generate, migrate, db, dev, complete, studio, validate, format, debug, and mcp. Use for ORM/database CLI workflows, not the Prisma Platform CLI. Triggers on "prisma init", "prisma generate", "prisma migrate", "prisma db", "prisma complete", "prisma studio", "prisma mcp". license: MIT metadata: author: prisma version: "7.9.1" --- # Prisma CLI Reference Reference for Prisma ORM CLI commands. This skill provides guidance on command usage, options, and best practices for current Prisma ORM releases. ## 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` for Platform projects and databases. ## When to Apply Reference this skill when: - Setting up a new Prisma 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. --- ## 2. prisma-client-api - **Source:** https://github.com/prisma/skills/blob/main/prisma-client-api/SKILL.md - **Raw:** https://raw.githubusercontent.com/prisma/skills/main/prisma-client-api/SKILL.md - **Markdown:** https://skillsdocs.com/prisma/skills/prisma-client-api.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html Bundled files (8), referenced from this skill's directory: - `references/client-methods.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-client-api/references/client-methods.md - `references/constructor.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-client-api/references/constructor.md - `references/filters.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-client-api/references/filters.md - `references/model-queries.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-client-api/references/model-queries.md - `references/query-options.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-client-api/references/query-options.md - `references/raw-queries.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-client-api/references/raw-queries.md - `references/relations.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-client-api/references/relations.md - `references/transactions.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-client-api/references/transactions.md --- 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. --- ## 3. prisma-compute - **Source:** https://github.com/prisma/skills/blob/main/prisma-compute/SKILL.md - **Raw:** https://raw.githubusercontent.com/prisma/skills/main/prisma-compute/SKILL.md - **Markdown:** https://skillsdocs.com/prisma/skills/prisma-compute.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html Bundled files (6), referenced from this skill's directory: - `references/app-deploy-cli.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-compute/references/app-deploy-cli.md - `references/compute-config.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-compute/references/compute-config.md - `references/create-prisma.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-compute/references/create-prisma.md - `references/frameworks.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-compute/references/frameworks.md - `references/sdk-api.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-compute/references/sdk-api.md - `references/troubleshooting.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-compute/references/troubleshooting.md --- name: prisma-compute description: Prisma Compute deployment and hosting guide. Use whenever the user mentions Prisma Compute, `prisma.compute.ts`, `defineComputeConfig`, deploying or hosting a Prisma app, `@prisma/cli app deploy`, `compute:deploy`, `create-prisma --deploy`, `PRISMA_SERVICE_TOKEN`, Compute auth/workspaces, apps/deployments/build logs/domains, localhost vs `0.0.0.0`, deploy port binding, or framework deploy readiness for Hono, Elysia, Next.js, TanStack Start, Astro, Nuxt, Svelte, Nest, Turborepo, or custom/prebuilt artifacts. license: MIT metadata: author: prisma version: "1.5.1" --- # Prisma Compute Guide agents through Prisma Compute app creation, deployment, operations, and framework-specific deploy readiness. ## Prisma Compute CLI Surface Use the Prisma Platform CLI for Compute app workflows: ```bash bunx @prisma/cli@latest app deploy --help bunx @prisma/cli@latest app --help bunx @prisma/cli@latest build logs --help bunx create-prisma@latest --help ``` Use `@prisma/cli@latest` for Compute app deployment. Use `create-prisma@latest` for new-project scaffolding. ## Send Feedback and Report CLI Issues The CLI has a built-in feedback channel. Use it whenever a command crashes (`UNEXPECTED_ERROR`), a failure survives troubleshooting, or the user asks to send feedback to the Prisma team: ```bash bunx @prisma/cli@latest feedback "app deploy crashed: " bunx @prisma/cli@latest feedback "love the deploy flow" --email you@example.com ``` Crash output points here on its own: `--json` crash envelopes carry the exact pre-filled command as a `recover` entry in `nextActions` (run it verbatim), and human crash output ends with a `Tell us what happened:` hint. Feedback is anonymous unless `--email` is passed and attaches only the CLI version, node version, and OS platform/arch. Never include secrets, connection URLs, or user data in the message. ## Source-of-Truth Order Use evidence in this order when deciding what to edit or run: 1. The project's generated scripts and config, especially `prisma.compute.ts`, `compute:deploy`, framework config, and `package.json`. 2. CLI help output from `create-prisma` and `@prisma/cli`. 3. Local installed package code, generated artifacts, and type definitions. 4. Official docs. ## When to Apply Use this skill for: - Creating a new app that can deploy to Prisma Compute - Deploying an existing TypeScript app to Prisma Compute - Creating or updating a typed `prisma.compute.ts` deploy config - Deciding whether a framework is Compute-ready - Debugging `create-prisma --deploy`, `compute:deploy`, or `app deploy` - Managing Compute app logs, deployments, environment variables, and domains, and listing platform branches (`branch list`; there are no branch create/remove commands) - Inspecting GitHub/Console build logs and GitHub push-to-deploy status - Running non-interactive deploys with browser auth, multiple stored workspaces, or Prisma service tokens - Switching, selecting, listing, or logging out local Prisma Platform workspaces for `@prisma/cli` - Sending feedback about an unresolvable Compute CLI failure with `@prisma/cli feedback` - Programmatic deployments with `@prisma/compute-sdk` or Management API integrations ## Decision Tree 1. Existing project deployment or redeploy: Read [`references/app-deploy-cli.md`](references/app-deploy-cli.md). 2. Typed Compute config, monorepos, deploy targets, app roots, or build/env defaults: Read [`references/compute-config.md`](references/compute-config.md). 3. Framework-specific build/runtime work: Read [`references/frameworks.md`](references/frameworks.md). 4. New project from a scaffold: Read [`references/create-prisma.md`](references/create-prisma.md). 5. Programmatic deployment, SDKs, APIs, or low-level App/Deployment concepts: Read [`references/sdk-api.md`](references/sdk-api.md). 6. Build, auth, env, deploy, or runtime failures: Read [`references/troubleshooting.md`](references/troubleshooting.md). ## Rules by Priority | Priority | Category | Impact | Prefix | |----------|----------|--------|--------| | 1 | Command verification | CRITICAL | `verify-` | | 2 | Auth and workspace selection | CRITICAL | `auth-` | | 3 | Framework readiness | CRITICAL | `framework-` | | 4 | Runtime host and port binding | CRITICAL | `runtime-` | | 5 | Typed Compute config | HIGH | `config-` | | 6 | Branch, environment, and database wiring | HIGH | `env-` | | 7 | Deploy operations | HIGH | `deploy-` | | 8 | SDK and API automation | MEDIUM | `sdk-` | ## Quick Rules ### 1. Command Verification - `verify-help-first` - Use CLI help output to confirm command syntax while working. - `verify-prisma-vs-platform-cli` - Do not assume `prisma app deploy` exists in the ORM CLI; check whether the task should use `@prisma/cli`. - `verify-generated-scripts` - Prefer the generated `compute:deploy` script when a project already has one. - `verify-public-url` - After a real deploy, request the public deployment URL instead of trusting local or readiness-only checks. - `verify-config-support` - Treat `prisma.compute.ts` as the typed Compute config; inspect the project's config and generated scripts before editing or deploying. - `verify-auth-workspace-support` - Use `@prisma/cli auth workspace` commands for local workspace list/use/logout flows. ### 2. Auth and Workspace Selection - `auth-source-precedence` - A non-empty `PRISMA_SERVICE_TOKEN` is the active auth source for commands and local OAuth workspaces are ignored for execution. If it is set but empty, the CLI should fail instead of falling back to stored OAuth. - `auth-multi-workspace` - `auth login` can store OAuth sessions for multiple workspaces on the same machine. The active workspace pointer selects which stored OAuth grant normal commands use. - `auth-list-before-switch` - Use `auth workspace list --json` to inspect local sessions. Agents should prefer workspace ids from JSON over names because names can be ambiguous. - `auth-switch-explicitly` - Use `auth workspace use ` for non-interactive switching. Use `auth workspace use` with no argument only for an interactive picker or when exactly one local OAuth workspace exists. - `auth-no-fallthrough` - If the active OAuth workspace is logged out or fails refresh, the CLI should not silently fall through to another cached workspace. Run `auth workspace use ` to choose the next workspace. - `auth-single-workspace-logout` - Use `auth workspace logout ` or `auth logout --workspace ` to remove one local OAuth workspace session. Plain `auth logout` clears all local OAuth workspace sessions. - `auth-service-token-switching` - While `PRISMA_SERVICE_TOKEN` is set, `auth workspace use` is unavailable because the service token is the active auth source; unset the env var to switch local OAuth workspaces. Workspace logout still only cleans local OAuth state. - `auth-storage-awareness` - Local OAuth credentials live in the platform auth file, with workspace metadata in a sidecar context file. Project pins live in `.prisma/local.json`, and CLI app/project state lives in `.prisma/cli/state.json` near `prisma.compute.ts` when present. ### 3. Framework Readiness - `framework-cli-first` - Evaluate deploy readiness against `@prisma/cli app deploy`, not against what `create-prisma` can scaffold. - `framework-supported-cli-deploy` - Compute deploy supports `nextjs`, `nuxt`, `astro`, `hono`, `nestjs`, `tanstack-start`, `custom`, and `bun`. - `framework-create-prisma-defaults-only` - `create-prisma` can provide generated defaults and `compute:deploy`, but it is not the general deploy surface for existing apps. - `framework-build-output` - Compute needs a server entrypoint or framework artifact, not only static output. ### 4. Runtime Host and Port Binding - `runtime-bind-all-interfaces` - Deployed servers must bind on all interfaces (`0.0.0.0` or the framework equivalent), not hard-coded `localhost` or `127.0.0.1`. - `runtime-match-http-port` - The app must listen on the deployed HTTP port: read `process.env.PORT` when possible, or pass the matching `--http-port`. - `runtime-readiness-port-only` - Compute readiness watches listening ports; a loopback-only listener can look ready while public ingress cannot reach it. ### 5. Typed Compute Config - `config-optional-simple-app` - `prisma.compute.ts` is not required to deploy a normal single app; use flags when there is no durable config. - `config-init-formalizer` - Generate a fresh config with `bunx @prisma/cli@latest init`: it detects the framework, pins name/framework/httpPort (plus entry for Bun/Hono), and offers the Project link. `--format json` writes a dependency-free `prisma.compute.json` instead. `init` refuses when any config already exists, never scaffolds code, and never deploys. - `config-use-prisma-compute-ts` - Put reusable deploy defaults in `prisma.compute.ts` with `defineComputeConfig`, not in `prisma.config.ts`. - `config-app-vs-apps` - Use `app` for a single deploy target and `apps` for monorepos or multi-app repos; define exactly one. - `config-monorepo-roots` - For monorepos, use `prisma.compute.ts` to declare app targets, roots, framework defaults, entrypoints, ports, and env inputs. - `config-targets` - In multi-app configs, `@prisma/cli app deploy web` selects the `apps.web` target. Without `[app]`, commands can infer the target from the current directory; otherwise deploy can run all targets while build/run require one. - `config-region-new-app-only` - A config `region` is only a default for newly created apps; deploys to existing apps keep the app's current region. - `config-custom-artifact` - Use `framework: "custom"` with `build.outputDirectory` and `build.entrypoint` for prebuilt or custom-built artifacts. - `config-no-project-branch-secrets` - Do not commit Workspace, Project, Branch, production intent, service tokens, or secret values in `prisma.compute.ts`; keep those in flags, `.prisma/local.json`, env storage, or CI secrets. App-level defaults such as `region`, `root`, `framework`, `entry`, `httpPort`, and non-secret env file paths belong in config. - `config-flags-win` - Explicit deploy flags such as `--framework`, `--entry`, `--http-port`, `--region`, and `--env` override matching config values. ### 6. Branch, Environment, and Database - `env-do-not-leak-secrets` - Never print full `DATABASE_URL`, service tokens, or secret values. - `env-deploy-loads-dotenv` - Generated deploy scripts may load env via `prisma.compute.ts` or `--env .env`; inspect the actual script/config before redeploy. - `env-migrations-separate` - Redeploy scripts do not run migrations or seed data. Run the appropriate Prisma database scripts separately. - `env-cli-token-name` - `@prisma/cli` uses `PRISMA_SERVICE_TOKEN` for service-token auth. - `env-branch-scope` - Branch deploys, branch env vars, and branch databases must use the same branch name; pass `--branch ` explicitly when targeting a preview branch. - `env-production-vs-preview` - Use `--role production` for production env, `--role preview` for preview template env, and `--branch ` for branch-specific overrides. - `env-db-explicit` - Keep database and env wiring explicit through database and project env commands; deploy examples should not add database setup, and deploys do not run migrations, seed data, or create one database per app automatically. ### 7. Deploy Operations - `deploy-prod-intent` - Use `--prod --yes` only when the user intends a production deploy. The first production deploy of an App auto-promotes without `--prod`; the flag gates subsequent production-branch deploys. - `deploy-no-promote` - Use `app deploy --no-promote` for build-then-verify: it builds a candidate reachable at its own URL without touching the live deployment, promoted later with `app promote `. - `deploy-github-default-branch` - When a Compute app is connected to GitHub push-to-deploy, a merge to the default branch is the production deploy path; check deployment records or GitHub check runs instead of telling users to redeploy the merged PR branch or run a default-branch preview deploy. - `deploy-build-logs` - Use `@prisma/cli build logs ` for GitHub/Console build output. Use `app logs` for runtime deployment logs; the two ids are different. - `deploy-noninteractive-auth` - Non-interactive deploys need either the correct active stored OAuth workspace or a supported service token env var; never print the token. - `deploy-json-for-agents` - Use `--json --no-interactive` for scripts and agent-readable output. - `deploy-create-project` - Use `--create-project ` only when the user wants deploy to create and link a new project; it conflicts with `--project` and `PRISMA_PROJECT_ID`. - `deploy-ops-targets` - App show/open/logs/list-deploys/promote/rollback/remove and domain commands can also accept `[app]` targets from `prisma.compute.ts`. - `deploy-report-cli-bugs` - On `UNEXPECTED_ERROR` or an unresolvable failure, report it with the feedback command; see "Send Feedback and Report CLI Issues" above. ### 8. SDK and API - `sdk-use-cli-first` - Prefer `@prisma/cli app deploy` for app workflows; use `create-prisma` only to scaffold a new app unless the user is building lower-level automation. - `sdk-result-handling` - `@prisma/compute-sdk` returns `Result` values; check `isOk()`/`isErr()` instead of relying on exceptions. - `sdk-snapshot-detection` - Use `detectComputeApp` for repository snapshots that are not checked out to disk; enumerate workspaces yourself and call it once per candidate app root. ## Preferred Workflow 1. Inspect the project: package manager, template/framework, `package.json` scripts, Prisma version, Prisma client location, `prisma.compute.ts`, and existing `compute:deploy`. 2. Verify CLI help output for the package actually being used. 3. Verify auth context before project/app mutations: `auth whoami --json`, and when multiple local sessions may exist, `auth workspace list --json`. 4. Choose the path: - existing app deploy: config-backed target when present, generated `compute:deploy`, or `@prisma/cli app build/run/deploy` flags - new app scaffold: `create-prisma`, then generated `compute:deploy` or `@prisma/cli app deploy` - low-level automation: `@prisma/compute-sdk` or Management API 5. Check framework readiness plus host/port/env/runtime requirements, including project and branch scope. 6. Run a local build or `app build` before deploying when feasible. 7. Deploy with JSON output when automating, then request the public URL and summarize app URL, app id, deployment id, project id, workspace id, and follow-up steps. 8. For GitHub/Console builds, inspect the `Prisma Compute Deploy` check run or `build logs ` before guessing why a build failed. ## Avoid - Do not bury Compute deployment guidance in the generic `prisma-cli` skill. - Do not run `create-prisma` inside an existing app just to deploy it; use the generated `compute:deploy` script or `@prisma/cli app deploy`. - Do not tell users that every `create-prisma` template can auto-deploy. - Do not deploy with placeholder `DATABASE_URL` values. - Do not assume `next start` is the Compute runtime path; Next.js deploys need standalone output. --- ## 4. prisma-database-setup - **Source:** https://github.com/prisma/skills/blob/main/prisma-database-setup/SKILL.md - **Raw:** https://raw.githubusercontent.com/prisma/skills/main/prisma-database-setup/SKILL.md - **Markdown:** https://skillsdocs.com/prisma/skills/prisma-database-setup.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html Bundled files (8), referenced from this skill's directory: - `references/cockroachdb.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-database-setup/references/cockroachdb.md - `references/mongodb.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-database-setup/references/mongodb.md - `references/mysql.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-database-setup/references/mysql.md - `references/postgresql.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-database-setup/references/postgresql.md - `references/prisma-client-setup.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-database-setup/references/prisma-client-setup.md - `references/prisma-postgres.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-database-setup/references/prisma-postgres.md - `references/sqlite.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-database-setup/references/sqlite.md - `references/sqlserver.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-database-setup/references/sqlserver.md --- name: prisma-database-setup description: Guides for configuring Prisma with different database providers (PostgreSQL, MySQL, SQLite, MongoDB, etc.). Use when setting up a new project, changing databases, or troubleshooting connection issues. Triggers on "configure postgres", "connect to mysql", "setup mongodb", "sqlite setup". license: MIT metadata: author: prisma version: "7.6.0" --- # Prisma Database Setup Comprehensive guides for configuring Prisma ORM with various database providers. ## When to Apply Reference this skill when: - Initializing a new Prisma project - Switching database providers - Configuring connection strings and environment variables - Troubleshooting database connection issues - Setting up database-specific features - Generating and instantiating Prisma Client ## Rule Categories by Priority | Priority | Category | Impact | Prefix | |----------|----------|--------|--------| | 1 | Provider Guides | CRITICAL | provider names | | 2 | Prisma Postgres | HIGH | `prisma-postgres` | | 3 | Client Setup | CRITICAL | `prisma-client-setup` | ## System Prerequisites - **Node.js 20.19.0+** - **TypeScript 5.4.0+** ## Bun Runtime If you're using Bun, run Prisma CLI commands with `bunx --bun prisma ...` so Prisma uses the Bun runtime instead of falling back to Node.js. ## Supported Databases | Database | Provider String | Notes | |----------|-----------------|-------| | PostgreSQL | `postgresql` | Default, full feature support | | MySQL | `mysql` | Widespread support, some JSON diffs | | SQLite | `sqlite` | Local file-based, no enum/scalar lists | | MongoDB | `mongodb` | Mongo-specific workflow; do not apply SQL driver-adapter guidance | | SQL Server | `sqlserver` | Microsoft ecosystem | | CockroachDB | `cockroachdb` | Distributed SQL, Postgres-compatible | | Prisma Postgres | `postgresql` | Managed serverless database | ## Configuration Files Your configuration shape depends on the provider and Prisma major version: 1. **All providers** use **`prisma/schema.prisma`**. 2. **Prisma 7 SQL setups** typically use **`prisma.config.ts`** for datasource URLs. 3. **MongoDB projects should stay on Prisma 6.x**, keep `url = env("DATABASE_URL")` in the schema, and continue using the classic MongoDB setup. ## Driver Adapters The standard SQL workflow uses a driver adapter. Choose the adapter and driver for your database and pass the adapter to `PrismaClient`. | Database | Adapter | JS Driver | |----------|---------|-----------| | PostgreSQL | `@prisma/adapter-pg` | `pg` | | CockroachDB | `@prisma/adapter-pg` | `pg` | | Prisma Postgres (Node.js) | `@prisma/adapter-pg` | `pg` | | Prisma Postgres (edge/serverless) | `@prisma/adapter-ppg` | `@prisma/ppg` | | MySQL / MariaDB | `@prisma/adapter-mariadb` | `mariadb` | | SQLite | `@prisma/adapter-better-sqlite3` | `better-sqlite3` | | SQLite (Turso/LibSQL) | `@prisma/adapter-libsql` | `@libsql/client` | | SQL Server | `@prisma/adapter-mssql` | `node-mssql` | MongoDB should not follow the Prisma 7 SQL adapter workflow. Use the latest Prisma 6.x release for MongoDB projects and do not install a SQL `@prisma/adapter-*` package for it. Example (PostgreSQL): ```ts import 'dotenv/config' 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 }) ``` ## Prisma Client Setup (Required) Prisma Client must be installed and generated for any database. 1. Install Prisma CLI and Prisma Client: ```bash npm install prisma --save-dev npm install @prisma/client ``` 1. Add a generator block (`prisma-client` requires an explicit output path): ```prisma generator client { provider = "prisma-client" output = "../generated" } ``` 1. Generate Prisma Client: ```bash npx prisma generate ``` 1. For SQL providers, instantiate Prisma Client with the database-specific driver adapter: ```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 }) ``` 1. Re-run `prisma generate` after every schema change. ## Quick Reference ### PostgreSQL ```prisma datasource db { provider = "postgresql" } generator client { provider = "prisma-client" output = "../generated" } ``` ### MySQL ```prisma datasource db { provider = "mysql" } generator client { provider = "prisma-client" output = "../generated" } ``` ### SQLite ```prisma datasource db { provider = "sqlite" } generator client { provider = "prisma-client" output = "../generated" } ``` ### MongoDB ```prisma datasource db { provider = "mongodb" url = env("DATABASE_URL") } generator client { provider = "prisma-client-js" } ``` 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 See individual rule files for detailed setup instructions: ``` references/postgresql.md references/mysql.md references/sqlite.md references/mongodb.md references/sqlserver.md references/cockroachdb.md references/prisma-postgres.md references/prisma-client-setup.md ``` ## How to Use Choose the provider reference file for your database, then apply `references/prisma-client-setup.md` to complete client generation and adapter setup. For MongoDB, use `references/mongodb.md` instead of copying the SQL adapter examples or Prisma 7 config pattern. --- ## 5. prisma-driver-adapter-implementation - **Source:** https://github.com/prisma/skills/blob/main/prisma-driver-adapter-implementation/SKILL.md - **Raw:** https://raw.githubusercontent.com/prisma/skills/main/prisma-driver-adapter-implementation/SKILL.md - **Markdown:** https://skillsdocs.com/prisma/skills/prisma-driver-adapter-implementation.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html --- 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 } interface SqlMigrationAwareDriverAdapterFactory extends SqlDriverAdapterFactory { connectToShadowDb(): Promise } interface SqlDriverAdapter extends AdapterInfo { queryRaw(query: SqlQuery): Promise executeRaw(query: SqlQuery): Promise executeScript(script: string): Promise startTransaction(isolationLevel?: IsolationLevel): Promise getConnectionInfo?(): ConnectionInfo dispose(): Promise } interface Transaction extends AdapterInfo { readonly options: { usePhantomQuery: boolean } queryRaw(query: SqlQuery): Promise executeRaw(query: SqlQuery): Promise commit(): Promise rollback(): Promise createSavepoint?(name: string): Promise rollbackToSavepoint?(name: string): Promise releaseSavepoint?(name: string): Promise } ``` `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 { 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 { 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 { 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) --- ## 6. prisma-mongodb-upgrade - **Source:** https://github.com/prisma/skills/blob/main/prisma-mongodb-upgrade/SKILL.md - **Raw:** https://raw.githubusercontent.com/prisma/skills/main/prisma-mongodb-upgrade/SKILL.md - **Markdown:** https://skillsdocs.com/prisma/skills/prisma-mongodb-upgrade.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html Bundled files (5), referenced from this skill's directory: - `references/client-api-mapping.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-mongodb-upgrade/references/client-api-mapping.md - `references/decision-stay-or-migrate.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-mongodb-upgrade/references/decision-stay-or-migrate.md - `references/migrations-mapping.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-mongodb-upgrade/references/migrations-mapping.md - `references/schema-contract-mapping.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-mongodb-upgrade/references/schema-contract-mapping.md - `references/verify-cutover-checklist.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-mongodb-upgrade/references/verify-cutover-checklist.md --- 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. --- ## 7. prisma-postgres-setup - **Source:** https://github.com/prisma/skills/blob/main/prisma-postgres-setup/SKILL.md - **Raw:** https://raw.githubusercontent.com/prisma/skills/main/prisma-postgres-setup/SKILL.md - **Markdown:** https://skillsdocs.com/prisma/skills/prisma-postgres-setup.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html Bundled files (4), referenced from this skill's directory: - `references/api-basics.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-postgres-setup/references/api-basics.md - `references/auth.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-postgres-setup/references/auth.md - `references/endpoints.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-postgres-setup/references/endpoints.md - `references/prisma7-client.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-postgres-setup/references/prisma7-client.md --- name: prisma-postgres-setup description: Set up a new Prisma Postgres database and connect it to a local project using the Management API. Use when asked to "set up a database", "create a Prisma Postgres project", "get a connection string", "connect my app to Prisma Postgres", or "provision a database". license: MIT metadata: author: prisma version: "1.1.0" --- # Prisma Postgres Setup Procedural skill that guides you through provisioning a new Prisma Postgres database via the Management API and connecting it to a local project. ## When to Apply Use this skill when: - Setting up a new Prisma Postgres database for a project - Creating a Prisma Postgres project and connecting it locally - Obtaining a connection string for Prisma Postgres - Provisioning a database via the Management API (not the Console UI) Do **not** use this skill when: - Setting up CI/CD preview databases — use `prisma-postgres-cicd` - Building multi-tenant database provisioning into an app — use `prisma-postgres-integrator` - Working with a database that already exists and is connected (schema/migration tasks are standard Prisma CLI) ## Prerequisites - Node.js 18+ - A Prisma Postgres workspace (create one at https://console.prisma.io if needed) - A workspace service token (see `references/auth.md`) ## UX Guidelines When presenting choices to the user (region selection, project deletion, etc.), **use your platform's interactive selection mechanism** (e.g., `ask` tool in Claude Code, structured prompts in other agents). Do not print static tables and ask the user to type a value — present selectable options so the user can pick with minimal effort. ## Workflow Follow these steps in order. Each step includes the API call to make and how to handle the response. ### Step 1: Authenticate You need a service token. Try these methods in order: **1a. Token in the user's prompt** Check if the user included a service token in their initial message (e.g., "Set up Prisma Postgres with token eyJ..."). If so, use it **exactly as provided** — do not truncate, re-encode, or round-trip it through a file. Store it in a shell variable for subsequent calls. **1b. Token in the environment** Check for `PRISMA_SERVICE_TOKEN` in the environment or `.env` file. **1c. Ask the user to create one** If no token is available, instruct the user: > Create a service token in Prisma Console → Workspace Settings → Service Tokens. > Copy the token and paste it here. Read `references/auth.md` for details on service token creation. Once you have a token, store it in a shell variable (`PRISMA_SERVICE_TOKEN`) and use it for all subsequent API calls. ### Step 2: List available regions Fetch the list of available Prisma Postgres regions to let the user choose where to deploy. ```bash curl -s -H "Authorization: Bearer $PRISMA_SERVICE_TOKEN" \ https://api.prisma.io/v1/regions/postgres ``` The response contains an array of regions with `id`, `name`, and `status`. Only present regions where `status` is `available`. **Present the regions as an interactive menu** — let the user pick from options rather than typing a region ID manually. Read `references/endpoints.md` for the full response shape. ### Step 3: Create a project with a database ```bash curl -s -X POST https://api.prisma.io/v1/projects \ -H "Authorization: Bearer $PRISMA_SERVICE_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "", "region": "", "createDatabase": true }' ``` Use the current directory name as the project name by default. The response is wrapped in `{ "data": { ... } }`. Extract: - `data.id` — the project ID (prefixed with `proj_`) - `data.database.id` — the database ID (prefixed with `db_`) - `data.database.connections[0].endpoints.direct.connectionString` — the direct PostgreSQL connection string Use the **direct** connection string (`endpoints.direct.connectionString`). Do not use the pooled or accelerate endpoints — those are for legacy Accelerate setups and not needed for new projects. If the response status is `provisioning`, wait a few seconds and poll `GET /v1/databases/` until `status` is `ready`. **If creation fails due to a database limit**, list the user's existing projects and present them as an interactive menu for deletion. After the user picks one, delete it and retry. Read `references/endpoints.md` for the full request/response shapes. ### Step 4: Create a named connection (optional) If you need a dedicated connection (e.g., per-developer or per-environment), create one: ```bash curl -s -X POST https://api.prisma.io/v1/databases//connections \ -H "Authorization: Bearer $PRISMA_SERVICE_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "dev" }' ``` Extract the direct connection string from `data.endpoints.direct.connectionString`. ### Step 5: Configure the local project 1. Install dependencies: ```bash npm install prisma @prisma/client @prisma/adapter-pg pg dotenv ``` All five packages are required: - `prisma` — CLI for migrations, schema push, client generation - `@prisma/client` — the generated query client - `@prisma/adapter-pg` — Prisma 7 driver adapter for direct PostgreSQL connections - `pg` — Node.js PostgreSQL driver (used by the adapter) - `dotenv` — loads `.env` variables for `prisma.config.ts` 2. Write the direct connection string to `.env`. **Append** to the file if it already exists — do not overwrite existing entries: ``` DATABASE_URL="" ``` 3. Verify `.gitignore` includes `.env`. Create `.gitignore` if it does not exist. Warn the user if `.env` is not gitignored. 4. Ensure `package.json` has `"type": "module"` set (Prisma 7 generates ESM output). 5. If `prisma/schema.prisma` does not exist, run `npx prisma init` to scaffold the project. This creates both `prisma/schema.prisma` and `prisma.config.ts`. 6. Ensure `schema.prisma` has the `postgresql` provider and **no** `url` or `directUrl` in the datasource block (Prisma 7 manages connection URLs in `prisma.config.ts`, not in the schema): ```prisma datasource db { provider = "postgresql" } ``` 7. Ensure `prisma.config.ts` loads the connection URL from the environment: ```typescript import path from 'node:path' import { defineConfig } from 'prisma/config' import 'dotenv/config' export default defineConfig({ earlyAccess: true, schema: path.join(import.meta.dirname, 'prisma', 'schema.prisma'), datasource: { url: process.env.DATABASE_URL!, }, }) ``` **Important Prisma 7 notes:** - Connection URLs go in `prisma.config.ts`, never in `schema.prisma` - The provider in `schema.prisma` must be `"postgresql"` (not `"prismaPostgres"`) - `dotenv/config` must be imported in `prisma.config.ts` to load `.env` variables ### Step 6: Define schema and push If the schema already has models, skip to pushing. Otherwise, **present these options as an interactive menu**: 1. **"I'll define my schema manually"** — Tell the user to edit `prisma/schema.prisma` and come back when ready. Wait for them before proceeding. 2. **"Give me a starter schema"** — Add a Blog starter schema (User, Post, Comment with relations) to `prisma/schema.prisma`. Show the user what was added and ask if they want to adjust it before pushing. 3. **"I'll describe what I need"** — Ask the user to describe their data model in natural language (e.g., "I'm building a task manager with projects, tasks, and team members"). Generate a schema from the description, show it, and ask for confirmation before pushing. Once the schema has models and the user is ready, create a migration and generate the client: ```bash npx prisma migrate dev --name init ``` This creates migration files in `prisma/migrations/` **and** generates the client in one step. Migration history is essential for CI/CD workflows (`prisma migrate deploy`) and production deployments. Only use `npx prisma db push` if the user explicitly asks for prototyping-only mode (no migration history). In that case, follow it with `npx prisma generate`. ### Step 7: Verify the connection After generating the client, create and run a quick verification script to confirm everything works end-to-end. This is **critical** — do not skip this step. Create a file named `test-connection.ts`: ```typescript import 'dotenv/config' import pg from 'pg' import { PrismaPg } from '@prisma/adapter-pg' import { PrismaClient } from './generated/prisma/client.js' const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL }) const adapter = new PrismaPg(pool) const prisma = new PrismaClient({ adapter }) const result = await prisma.$queryRawUnsafe('SELECT 1 as connected') console.log('Connected to Prisma Postgres:', result) await prisma.$disconnect() await pool.end() ``` Run it: ```bash npx tsx test-connection.ts ``` **Prisma 7 client instantiation rules:** - Import from `./generated/prisma/client.js` (not `./generated/prisma`) - Create a `pg.Pool` with the `DATABASE_URL` connection string - Wrap it in a `PrismaPg` adapter - Pass `{ adapter }` to the `PrismaClient` constructor - Do **not** use `datasourceUrl` — that option does not exist in Prisma 7 - Do **not** use `new PrismaClient()` with no arguments — it will throw After verification succeeds, delete `test-connection.ts`. Then share links for the user to explore their database: - **Prisma Studio (CLI):** `npx prisma studio` — opens a visual data browser locally - **Console:** `https://console.prisma.io////dashboard` — strip the prefixes (`wksp_`, `proj_`, `db_`) from the IDs returned in Step 3 to build this URL Read `references/prisma7-client.md` for the full client instantiation reference. ## Error Handling Read `references/api-basics.md` for the full error reference. Key self-correction patterns: | HTTP Status | Error Code | Action | |---|---|---| | 401 | `authentication-failed` | Service token is invalid or expired. Ask the user to create a new one in Console → Workspace Settings → Service Tokens. | | 404 | `resource-not-found` | Check that the resource ID includes the correct prefix (`proj_`, `db_`, `con_`). | | 422 | `validation-error` | Check request body against the endpoint schema. Common: missing `name`, invalid `region`. | | 429 | `rate-limit-exceeded` | Back off and retry after a few seconds. | ## Reference Files Detailed API and usage information is in: ``` references/auth.md — Service token creation and usage references/api-basics.md — Base URL, envelope, IDs, errors, pagination references/endpoints.md — Endpoint details for projects, databases, connections, regions references/prisma7-client.md — Prisma 7 client instantiation and usage patterns ``` --- ## 8. prisma-postgres - **Source:** https://github.com/prisma/skills/blob/main/prisma-postgres/SKILL.md - **Raw:** https://raw.githubusercontent.com/prisma/skills/main/prisma-postgres/SKILL.md - **Markdown:** https://skillsdocs.com/prisma/skills/prisma-postgres.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html Bundled files (4), referenced from this skill's directory: - `references/console-and-connections.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-postgres/references/console-and-connections.md - `references/create-db-cli.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-postgres/references/create-db-cli.md - `references/management-api-sdk.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-postgres/references/management-api-sdk.md - `references/management-api.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-postgres/references/management-api.md --- name: prisma-postgres description: Prisma Postgres setup and operations guidance across Console, create-db CLI, Management API, and Management API SDK. Use when creating Prisma Postgres databases, working in Prisma Console, provisioning with create-db/create-pg/create-postgres, or integrating programmatic provisioning with service tokens or OAuth. license: MIT metadata: author: prisma version: "7.9.1" --- # Prisma Postgres Guidance for creating, managing, and integrating Prisma Postgres across interactive and programmatic workflows. ## When to Apply Reference this skill when: - Setting up Prisma Postgres from Prisma Console - Provisioning instant temporary databases with `create-db` - Linking an existing local project with `prisma postgres link` - Managing Prisma Postgres resources via Management API - Using `@prisma/management-api-sdk` in TypeScript/JavaScript - Handling claim URLs, connection strings, regions, and auth flows ## Rule Categories by Priority | Priority | Category | Impact | Prefix | |----------|----------|--------|--------| | 1 | CLI Provisioning | CRITICAL | `create-db-cli` | | 2 | Management API | CRITICAL | `management-api` | | 3 | Management API SDK | HIGH | `management-api-sdk` | | 4 | Console and Connections | HIGH | `console-and-connections` | ## Quick Reference - `create-db-cli` - instant databases and current CLI flags (`--ttl`, `--copy`, `--quiet`, `--open`) - `management-api` - service token and OAuth API workflows - `management-api-sdk` - typed SDK usage with token storage - `console-and-connections` - Console operations, `prisma postgres link`, direct TCP connections, and serverless-driver choices ## Core Workflows ### 1. Console-first workflow Use Prisma Console for manual setup and operations: - Open `https://console.prisma.io` - Create/select workspace and project - Use Studio in the project sidebar to view/edit data - Retrieve direct connection details from the project UI ### 2. Quick provisioning with create-db Use `create-db` when you need a database immediately: ```bash npx create-db@latest ``` Aliases: ```bash npx create-pg@latest npx create-postgres@latest ``` For app integrations, you can also use the programmatic API (`create()` / `regions()`) from the `create-db` npm package. Temporary databases auto-delete after ~24 hours unless claimed. ### 2b. Persistent databases with the Platform CLI For databases that belong to a Project (not throwaway `create-db` databases), use `@prisma/cli`: ```bash npx -y @prisma/cli@latest database create --help npx -y @prisma/cli@latest database list --json npx -y @prisma/cli@latest database connection create db_123 npx -y @prisma/cli@latest database usage db_123 npx -y @prisma/cli@latest database backup list db_123 ``` `database create` and `database connection create` print a one-time connection URL; store it immediately. Destructive commands (`remove`, `restore`) require exact `--confirm `. For automation, prefer `--json --no-interactive`, resolve ids before mutations, and verify the installed command's help because this CLI is beta. ### 3. Link an existing local project Use `prisma postgres link` when the database already exists and you want to wire a local project to it: ```bash prisma postgres link ``` For CI or other non-interactive environments: ```bash prisma postgres link --api-key "" --database "db_..." ``` This flow updates your local `.env` with `DATABASE_URL`, then you can run `prisma generate` and `prisma migrate dev`. ### 4. Programmatic provisioning with Management API Use API endpoints on: ```text https://api.prisma.io/v1 ``` Explore the schema and endpoints using: - OpenAPI docs: `https://api.prisma.io/v1/doc` - Swagger Editor: `https://api.prisma.io/v1/swagger-editor` Auth options: - Service token (workspace server-to-server) - OAuth 2.0 (act on behalf of users) ### 5. Type-safe integration with Management API SDK Install and use: ```bash npm install @prisma/management-api-sdk ``` Use `createManagementApiClient` for existing tokens, or `createManagementApiSdk` for OAuth + token refresh. The SDK exposes typed workspace service-token list, create, and revoke routes. A newly created token value is returned exactly once. Let the installed SDK types or OpenAPI document settle exact beta endpoint shapes. ## Rule Files Detailed guidance lives in: ``` references/console-and-connections.md references/create-db-cli.md references/management-api.md references/management-api-sdk.md ``` ## How to Use Start with `references/create-db-cli.md` for fast setup, then switch to `references/management-api.md` or `references/management-api-sdk.md` when you need programmatic provisioning. --- ## 9. prisma-upgrade-v7 - **Source:** https://github.com/prisma/skills/blob/main/prisma-upgrade-v7/SKILL.md - **Raw:** https://raw.githubusercontent.com/prisma/skills/main/prisma-upgrade-v7/SKILL.md - **Markdown:** https://skillsdocs.com/prisma/skills/prisma-upgrade-v7.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html Bundled files (7), referenced from this skill's directory: - `references/accelerate-users.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-upgrade-v7/references/accelerate-users.md - `references/driver-adapters.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-upgrade-v7/references/driver-adapters.md - `references/env-variables.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-upgrade-v7/references/env-variables.md - `references/esm-support.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-upgrade-v7/references/esm-support.md - `references/prisma-config.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-upgrade-v7/references/prisma-config.md - `references/removed-features.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-upgrade-v7/references/removed-features.md - `references/schema-changes.md` — https://raw.githubusercontent.com/prisma/skills/main/prisma-upgrade-v7/references/schema-changes.md --- 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 Next). ## Important Notes - **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` ## 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.