prisma-8

---
name: prisma-8
description: >-
  Use when working in a project that depends on @prisma/orm-postgres,
  @prisma/orm-sqlite, or @prisma/orm-mongo (Prisma 8, formerly Prisma Next): editing
  contract.prisma or a contract.ts builder, running `prisma contract emit`,
  planning or applying migrations, editing migration.ts, writing db.orm /
  db.sql / db.query queries, wiring db.ts or middleware, integrating a build
  tool, using the Supabase extension or RLS, or reading a dotted error code
  such as MIGRATION.HASH_MISMATCH. Use when the user asks "what is Prisma
  8", "where do I start", or compares it to another ORM. Use when the user
  asks to upgrade or bump Prisma 8 in an app or an extension package. Use when
  you see @internal/* or @prisma/orm-* imports, prisma.config.ts with
  definePrismaConfig, or contract.json / contract.d.ts. Do not use for Prisma
  ORM 7 or earlier (schema.prisma + @prisma/client).
metadata:
  library: '@prisma/orm-postgres'
  library_version: '8.0.0-rc.17'
  version: '2026-09-12'
---

# Prisma 8 (Prisma 8)

> **Edit your data contract. Prisma handles the rest.**

Prisma 8 moves fast, and your training data about it is very likely outdated. This skill ships inside the installed Prisma packages, so it describes the exact version this project has — treat it and its reference files as the source of truth, over anything you remember about Prisma.

## Pre-conditions

Check these before acting on anything below. Halt on the first one that fails and tell the user what is missing.

1. **The project is on Prisma 8.** `prisma.config.ts` exports `definePrismaConfig({ orm: ... })`, and `package.json` depends on `@prisma/orm-postgres`, `@prisma/orm-sqlite`, or `@prisma/orm-mongo`. A project with `schema.prisma` and `@prisma/client` is Prisma 7 or earlier; this skill does not apply to it, and its instructions will break such a project.
2. **The skill matches the installed version.** Compare `metadata.library_version` in this file's frontmatter with the installed `@prisma/orm-*` version in `package.json`. If they differ, run `prisma skills sync` and re-read this file before continuing.
3. **The contract artefacts exist.** `contract.json` and `contract.d.ts` sit next to the contract source named by `prisma.config.ts`. If they are missing or older than the source, run `prisma contract emit` first; every query and migration instruction below assumes current artefacts.

**Import paths in the references.** The reference files spell façade imports as `@internal/<target>/<subpath>` and `@internal/extension-<name>/<subpath>`. In an application those packages are published as `@prisma/orm-<target>/<subpath>` (`@prisma/orm-postgres/runtime`, `@prisma/orm-mongo/config`, `@prisma/orm-sqlite/runtime`) and `@prisma/orm-extension-<name>/<subpath>` (`@prisma/orm-extension-pgvector/control`). Write the `@prisma/orm-*` name in user code; the two spellings are the same package. Paths already written as `@prisma/orm-*` in the references are exact. The `metadata.library_version` in this file's frontmatter is the version it was published with; if it does not match the project's installed Prisma packages, run `prisma skills sync` and re-read.

Prisma 8 is a contract-first data layer. This skill routes every Prisma 8 task to the right reference file — open the reference before writing code; do not answer from this file alone.

## The canonical model (one paragraph)

You author a **data contract** (a `contract.prisma` file, or a TypeScript builder). The framework emits machine-readable artifacts (`contract.json`, `contract.d.ts`) and gives you two runtime surfaces on SQL targets: a typed SQL query builder (`db.sql.<ns>.<table>`) and a typed ORM client (`db.orm.<ns>.<Model>`). On MongoDB targets only the ORM lane exists, and its keys are collection storage names (`db.orm.users`) rather than PSL model names — [`references/queries.md`](references/queries.md) § *MongoDB ORM addressing* covers the rule. Migrations are planned from the contract diff; you review them, optionally edit the `migration.ts` for data transforms, and apply.

Three steps the user does:

1. **Edit your data contract.** ([`references/contract.md`](references/contract.md))
2. **The system plans the migrations for you.** ([`references/migrations.md`](references/migrations.md))
3. **If you need data migrations, you edit `migration.ts` and execute it.** ([`references/migrations.md`](references/migrations.md))

Everything else — queries, runtime wiring, build integration, debugging, feedback — sits on top of those three.

One cross-cutting migration fact: `migration plan` does **not** chain from the newest migration on disk. Its origin is `--from`, else the `db` ref, else an empty database — so a project with no ref keeps planning from scratch. Over existing migrations the CLI refuses that (`MIGRATION.PLAN_ORIGIN_UNKNOWN`) instead of writing a full-create package; choose the exit that matches your intent rather than reflexively passing `--from @empty`. [`references/migration-model.md`](references/migration-model.md) § *The trap* explains which to choose.

## Routing table

Open the reference whose triggers match the task. If more than one matches, open each — they are written to compose.

| Task | Reference | Triggers |
| --- | --- | --- |
| Adopt / set up / first steps | [`references/quickstart.md`](references/quickstart.md) | new project, existing database, "what can I do with Prisma 8", "where do I start", "just ran createprisma", `npx create-prisma`, first steps, first query, `prisma orm init` greenfield setup, `contract infer` + `db sign` brownfield adoption, connect-write-read first arc, day-to-day commands (`contract emit`, `db init`, `db update`, `migration plan`, `db migrate`, `db schema`, `db verify`), flags `--target` / `--authoring` / `--schema-path` / `--probe-db` / `--output` |
| Edit the data contract | [`references/contract.md`](references/contract.md) | schema, models, fields, attributes, relations, indexes, enums, value objects (composite types), type aliases, namespaces (Postgres schemas), cross-contract foreign keys (cross-space FK), polymorphic types (`@@discriminator` / `@@base`), extension namespaces (`pgvector.Vector(...)`, `postgis.Geometry(...)`), `prisma.config.ts` / `definePrismaConfig` / `ormConfig`, `prisma contract emit`, PSL, `contract.prisma`, `contract.ts`, `contract.json`, `contract.d.ts`, `@internal/postgres/config`, `@internal/postgres/contract-builder`, `@internal/mongo/config`, `extensions:`, pgvector, postgis, paradedb, Temporal / `temporal-polyfill` / `RUNTIME.TEMPORAL_UNAVAILABLE`, `@@control`, control policy (managed / tolerated / external / observed), soft delete, validations, callbacks |
| Author migrations | [`references/migrations.md`](references/migrations.md) | `db update` vs `migration plan`, `db migrate`, `migration new`, `migration show`, `db update --dry-run`, `db verify`, `db sign`, data migration, `dataTransform`, placeholder sentinels in framework-rendered `migration.ts`, `MIGRATION.HASH_MISMATCH`, `MIGRATION.UNFILLED_PLACEHOLDER`, data-loss questions (`--delete`, `--rename`, `--allow`, `CLI.CONSENT_REQUIRED`), schema drift |
| Migration graph, refs, plan origin | [`references/migration-model.md`](references/migration-model.md) | migration graph, refs, `migration ref set` / `list` / `delete`, the `db` ref, `--advance-ref`, `--no-advance-ref`, `migration plan --from`, `from: (baseline)` in plan output, greenfield / from-scratch plan, baseline, first migration before deploy (Composer / CD-managed databases), chaining migrations, retrofitting migrations onto an existing database, `MIGRATION.HASH_NOT_IN_GRAPH`, `MIGRATION.PATH_UNREACHABLE` at plan/chain time |
| Review migrations on deploy | [`references/migration-review.md`](references/migration-review.md) | "what migrations are going to run", "what runs on deploy / merge", merge conflict, diamond convergence, concurrent migrations, migration status, ref management for CI, staging / production environment refs, `MIGRATION.MARKER_NOT_IN_HISTORY`, `MIGRATION.MISSING_INVARIANTS`, `db migrate --show` |
| Write queries | [`references/queries.md`](references/queries.md) | query, where, select, project, orderBy, limit, offset, take, skip, include, lookup, first, all, count, aggregate, groupBy, create, update, delete, upsert, returning, transaction, `db.orm`, `db.sql`, `runtime.query(plan)` vs `runtime.execute(plan)`, `db.prepare` / prepared statements, streaming / `for await`, many-to-many `include` and nested `connect`, `and` / `or` / `not` from `@prisma/orm-postgres/orm-client`, `db.query.from(...)` (Mongo pipeline), namespace-aware accessors, `.all()` Thenable, single-use iterators (`RUNTIME.ITERATOR_CONSUMED`), target-declared aggregate types (`count`, integer `sum`, and integer `avg` are `number`; `count` and integer `sum` throw outside ±(2^53 − 1) rather than round, while `avg` is a fraction already and carries no guard; `countBigInt` / `sumBigInt` / `avgDecimal` are the lossless forms, `avgDecimal` on PostgreSQL only), custom collection class (`extends Collection`), `with` and query fragments (`QueryFragment`, `Filtered`, `Ordered`), shared query fragments and scopes (`db.orm.fragment(fields, body)` for a filter on every model with given fields, `CodecField`, `db.orm.public.Post.fragment(...)` for a shared `select` / `include`, `orderByField` for an order or sort parameter from a request), drizzle-style, kysely-style. Naming types (§ *Naming model and result types*): "type of my model", "return type of a query", `ResultType`, `Scalars`, `Shape`, `models` / `Models` namespace in `contract.d.ts`, `Models.public_User`, Prisma 7 `Prisma.User` / `GetPayload` / `UserGetPayload` equivalents. Postgres/SQLite specifics: [`references/queries-postgres.md`](references/queries-postgres.md); Mongo specifics: [`references/queries-mongo.md`](references/queries-mongo.md) |
| Wire the runtime | [`references/runtime.md`](references/runtime.md) | `db.ts`, `postgres<Contract>(...)` / `sqlite<Contract>(...)` / `mongo<Contract>(...)` façades, middleware composition (lints, budgets, cache via `@prisma/orm-extension-middleware-cache`, custom `afterQuery` middleware, `@prisma/orm-postgres/family-runtime`), `DATABASE_URL`, `.env`, connection pool / `poolOptions`, dev vs prod config, transactions, read replicas, multi-database, script won't exit / hangs, `db.close` / `pool.end`, `await using` / `[Symbol.asyncDispose]` |
| Build-tool integration | [`references/build.md`](references/build.md) | Vite plugin (`@internal/vite-plugin-contract-emit`, Vite 7/8), `vite.config.ts`, contract emit on save, HMR / dev server, Next.js / Webpack / esbuild / Rollup / Turbopack (named gaps, not fabricated) |
| Supabase | [`references/supabase.md`](references/supabase.md) | `@internal/extension-supabase`, RLS, row level security, policies (`policy_select` / `policy_update` / `@@rls`, `auth.uid()`), role binding (`asUser(jwt)` / `asAnon()` / `asServiceRole()`), `auth.users`, cross-space FKs to `supabase:auth.AuthUser`, JWT / JWKS (`SUPABASE_JWKS_URL`, `SUPABASE_JWT_SECRET`), `SUPABASE.JWT_INVALID`, `SUPABASE.CONFIG_INVALID`, `RoleBoundDb`, session pooler |
| Debug an error | [`references/debug.md`](references/debug.md) | any structured error envelope (code, severity, why, fix, nextActions, meta), emit failed, query won't typecheck, query crashed, migration won't apply, `MIGRATION.HASH_MISMATCH`, `MIGRATION.RUNNER_FAILED`, `BUDGET.ROWS_EXCEEDED`, `BUDGET.TIME_EXCEEDED`, `RUNTIME.ABORTED`, `RUNTIME.TEMPORAL_UNAVAILABLE`, `PLAN.HASH_MISMATCH`, `CONTRACT.MARKER_MISSING`, `CONFIG.*` / `CLI.*` / `CONTRACT.*` / `MIGRATION.*` / `ORM.*` / `RUNTIME.*` codes, legacy `PN-*` codes, exit code 4 findings, drift, capability missing, planner conflict, EXPLAIN, query log, script won't exit / close connection |
| Upgrade Prisma in an app | [`references/upgrade-app.md`](references/upgrade-app.md) | "upgrade Prisma", "upgrade Prisma 8", "bump Prisma 8", "move to Prisma 8 X.Y", `@internal/*` version bump in an application, per-transition upgrade instructions in [`upgrading/app/upgrades/`](upgrading/app/upgrades/), extension-pin pre-flight, `PN-UPGRADE-*` |
| Upgrade Prisma in an extension | [`references/upgrade-extension.md`](references/upgrade-extension.md) | the same request in a package that *is* a Prisma extension (`@internal/contract` / SPI dependency, `^@.*/extension-` name), `prisma-8-check-pins`, exact-pin rule, per-transition instructions in [`upgrading/extension/upgrades/`](upgrading/extension/upgrades/) |
| File feedback / ask the team | [`references/feedback.md`](references/feedback.md) | bug report, file an issue, feature request, missing feature, capability gap, "this is broken", surprising behaviour, Q&A / design discussion, ask the Prisma team, Prisma Discord (pris.ly/discord), extension-author questions |

## Routing rules

If the task clearly matches a row, open that reference directly without asking.

For a vague prompt, ask **one** disambiguating question. Pick from:

- *"Are you new to Prisma 8 and asking what you can do with it, or where to start?"* → [`references/quickstart.md`](references/quickstart.md) (first-touch orientation path).
- *"Do you want to set up a new Prisma 8 project, or wire it into an existing database?"* → [`references/quickstart.md`](references/quickstart.md).
- *"Do you want to edit your data contract (add a model / field / relation), or work with the database (migrations, queries)?"* → [`references/contract.md`](references/contract.md) vs the others.
- *"Is this about authoring a migration, or about reviewing what's going to run on deploy?"* → [`references/migrations.md`](references/migrations.md) vs [`references/migration-review.md`](references/migration-review.md). If it's about where a plan starts, refs, or an unexpected from-scratch plan → [`references/migration-model.md`](references/migration-model.md).
- *"Is this about wiring Prisma 8 into your build tool (Vite / Next.js / …), or about wiring `db.ts` and middleware at runtime?"* → [`references/build.md`](references/build.md) vs [`references/runtime.md`](references/runtime.md).
- *"What error or symptom are you seeing?"* → [`references/debug.md`](references/debug.md).
- *"Do you want to report this as a bug to the Prisma 8 team, or is this a feature request?"* → [`references/feedback.md`](references/feedback.md).
- *"Is the project you want to upgrade an application, or a Prisma extension package?"* → [`references/upgrade-app.md`](references/upgrade-app.md) vs [`references/upgrade-extension.md`](references/upgrade-extension.md).

If you still can't tell which reference applies, ask the user what they want to do. Do not guess.

## Checklist

- [ ] If the task matches a routing-table row, open that reference before writing code.
- [ ] If the prompt is vague, ask one disambiguating question.
- [ ] Do not attempt to answer from this file alone — the references carry the verified tool surface.
- [ ] If the user describes a missing feature or a misbehaviour they want fixed, open [`references/feedback.md`](references/feedback.md).

From prisma/orm at 7ae50f1, shown as plain text under its license: Apache-2.0 (permissive). The license text is in LICENSE.

• SKILL.md15 KB · b43b71150030
• references/
• build.md9.3 KB · bc4730b852b9
• contract.md44 KB · 29fa21683263
• debug.md21 KB · 509e92df27cf
• feedback.md17 KB · d2c87c2e0ff0
• migration-model.md19 KB · 48753a4edbe5
• migration-review.md21 KB · 49033926537e
• migrations.md52 KB · ddab6c0f460a
• queries-mongo.md13 KB · 51a9f9494bca
• queries-postgres.md48 KB · f0fb32b88fc4
• queries.md23 KB · 1773dd9e16f8
• quickstart.md32 KB · 18974d801f8a
• runtime.md38 KB · 136ae7932c08
• supabase.md21 KB · 98c7367c5f48
• upgrade-app.md11 KB · fda4fc950e91
• upgrade-extension.md10 KB · cdb45ee01418
• upgrading/
• app/
• upgrades/
• 0.10-to-0.11/
• instructions.md1.9 KB · b8b930f43755
• 0.11-to-0.12/
• instructions.md22 KB · 98a02ec28e82
• re-emit-closed-mongo-contracts.ts7.0 KB · 347fb3ede1d7
• re-emit-domain-namespaced-contracts.ts6.3 KB · 074821e25bde
• re-emit-postgres-public-default.ts6.4 KB · a1fc1dbf2e82
• strip-migration-labels-hints.ts13 KB · 9c8475d71e3d
• 0.12-to-0.13/
• instructions.md17 KB · 68cb9fc5f56c
• re-emit-mti-variant-link-columns.ts7.8 KB · 4037fccf51a8
• 0.13-to-0.14/
• instructions.md30 KB · b359d5e13167
• migration-op-factories-to-methods.ts10 KB · e31d2212df17
• uuid-preset-rename.ts1.3 KB · 3c792a22ceed
• 0.14-to-0.15/
• instructions.md21 KB · 87d5dc789370
• 0.15-to-0.16/
• instructions.md11 KB · 2a9cdc269105
• 0.16-to-0.17/
• instructions.md55 KB · 5ec5667bea41
• strip-sha256-hash-prefixes.ts15 KB · 2f08edc0255c
• 0.17-to-8.0.0-rc.1/
• instructions.md5.0 KB · 8c836136bc7d
• 0.7-to-0.8/
• instructions.md183 B · 55ef2ca791b2
• 0.8-to-0.9/
• instructions.md2.8 KB · 4d02fe935617
• strip-inline-contracts.ts8.0 KB · 56047244523a
• 0.9-to-0.10/
• instructions.md5.5 KB · 2b8806301b2b
• stamp-storage-types-kind.ts13 KB · f9c6c709a93b
• 8.0.0-rc.1-to-8.0.0-rc.2/
• instructions.md40 KB · 332cbeb06185
• 8.0.0-rc.10-to-8.0.0-rc.11/
• instructions.md1.6 KB · af1149b0ac0a
• 8.0.0-rc.11-to-8.0.0-rc.12/
• instructions.md50 KB · bd84f9dac9d9
• scripts/
• multifile-psl/
• add-use-prisma-8-directive.mjs1.8 KB · bfc431b98f37
• psl-verbatim-table-names/
• add-model-map.mjs8.7 KB · a3a9a753d2c8
• 8.0.0-rc.12-to-8.0.0-rc.13/
• instructions.md25 KB · a52f1e3fbcd2
• scripts/
• execution-ref-entry-field/
• rename-execution-ref-keys.ts6.7 KB · d61f1460ecf4
• 8.0.0-rc.13-to-8.0.0-rc.14/
• instructions.md38 KB · 3422938826d5
• 8.0.0-rc.14-to-8.0.0-rc.15/
• instructions.md110 KB · c815f31f80c5
• scripts/
• data-type-in-contract/
• data-type-in-contract.ts56 KB · 629388b21a2b
• 8.0.0-rc.15-to-8.0.0-rc.16/
• instructions.md9.5 KB · b0aef4cc1ae2
• 8.0.0-rc.16-to-8.0.0-rc.17/
• instructions.md72 KB · c1a76c8e8570
• 8.0.0-rc.2-to-8.0.0-rc.3/
• instructions.md56 B · 5010e1f08390
• 8.0.0-rc.3-to-8.0.0-rc.4/
• instructions.md7.7 KB · 9f0a49059f8b
• 8.0.0-rc.4-to-8.0.0-rc.5/
• instructions.md2.3 KB · 1a007fedd494
• 8.0.0-rc.5-to-8.0.0-rc.6/
• instructions.md9.7 KB · 63e932259313
• 8.0.0-rc.6-to-8.0.0-rc.7/
• instructions.md1.8 KB · 372ad45fbf3a
• 8.0.0-rc.7-to-8.0.0-rc.8/
• instructions.md1.8 KB · 2112a8ee5425
• 8.0.0-rc.8-to-8.0.0-rc.9/
• instructions.md5.2 KB · be3835ea14f6
• 8.0.0-rc.9-to-8.0.0-rc.10/
• instructions.md5.2 KB · 3426311c2d3f
• extension/
• upgrades/
• 0.10-to-0.11/
• instructions.md15 KB · 034ebd21d63a
• 0.11-to-0.12/
• instructions.md43 KB · 7ba84a0cadef
• migrate-contract-testing-imports.ts2.8 KB · 5baa26723092
• regenerate-extension-public-baseline.ts7.3 KB · 032ce7fa6960
• strip-migration-labels-hints.ts13 KB · 9c8475d71e3d
• 0.12-to-0.13/
• instructions.md15 KB · ea176ac52f9e
• 0.13-to-0.14/
• instructions.md26 KB · b239aaac7ada
• migration-op-factories-to-methods.ts10 KB · e31d2212df17
• uuid-preset-rename.ts1.3 KB · 3c792a22ceed
• 0.14-to-0.15/
• instructions.md49 KB · 0f4d7f585214
• 0.15-to-0.16/
• instructions.md15 KB · fee73c08d5bc
• 0.16-to-0.17/
• instructions.md57 KB · ea49c0ac50ad
• strip-sha256-hash-prefixes.ts15 KB · 2f08edc0255c
• 0.17-to-8.0.0-rc.1/
• instructions.md12 KB · 95f07b1570af
• 0.7-to-0.8/
• instructions.md188 B · 0815967474a2
• 0.8-to-0.9/
• instructions.md5.3 KB · 99f4d493d759
• strip-inline-contracts.ts8.0 KB · 56047244523a
• 0.9-to-0.10/
• instructions.md8.9 KB · 7cefe8f3daae
• stamp-storage-types-kind.ts13 KB · f9c6c709a93b
• 8.0.0-rc.1-to-8.0.0-rc.2/
• instructions.md49 KB · 4c1e9731e41b
• 8.0.0-rc.10-to-8.0.0-rc.11/
• instructions.md1.7 KB · d529f1221c9c
• 8.0.0-rc.11-to-8.0.0-rc.12/
• instructions.md62 KB · 448d7c4457a8
• scripts/
• psl-verbatim-table-names/
• add-model-map.mjs8.7 KB · a3a9a753d2c8
• 8.0.0-rc.12-to-8.0.0-rc.13/
• instructions.md38 KB · fb438dfe9c15
• scripts/
• execution-ref-entry-field/
• rename-execution-ref-keys.ts6.7 KB · d61f1460ecf4
• 8.0.0-rc.13-to-8.0.0-rc.14/
• instructions.md9.8 KB · ade9d26d35f4
• 8.0.0-rc.14-to-8.0.0-rc.15/
• instructions.md147 KB · a7449760f375
• scripts/
• data-type-in-contract/
• data-type-in-contract.ts56 KB · 629388b21a2b
• 8.0.0-rc.15-to-8.0.0-rc.16/
• instructions.md17 KB · 76f03b7032fd
• 8.0.0-rc.16-to-8.0.0-rc.17/
• instructions.md47 KB · 92393439e8f1
• 8.0.0-rc.2-to-8.0.0-rc.3/
• instructions.md56 B · 5010e1f08390
• 8.0.0-rc.3-to-8.0.0-rc.4/
• instructions.md7.0 KB · d396104717d6
• 8.0.0-rc.4-to-8.0.0-rc.5/
• instructions.md8.2 KB · 46d1439f15e8
• 8.0.0-rc.5-to-8.0.0-rc.6/
• instructions.md6.2 KB · 7fdd65109f7c
• 8.0.0-rc.6-to-8.0.0-rc.7/
• instructions.md1.9 KB · ee25a42596b7
• 8.0.0-rc.7-to-8.0.0-rc.8/
• instructions.md1.8 KB · 444bfcb12cf1
• 8.0.0-rc.8-to-8.0.0-rc.9/
• instructions.md9.8 KB · e339ad48f63f
• 8.0.0-rc.9-to-8.0.0-rc.10/
• instructions.md3.7 KB · 1b66f6991863

95 files, 1.9 MB in total. Each file has a sha256 in the pin's manifest; the first 12 characters are shown.