Prisma Next is built around a single organizing principle: your schema should produce a verifiable artifact — a data contract — rather than executable client code. That contract is pure data: deterministic, hashable, diffable, and machine-readable. Every query, migration, and runtime check flows from it.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/prisma/prisma-next/llms.txt
Use this file to discover all available pages before exploring further.
What is a data contract?
A data contract (contract.json) is a canonical JSON description of your application’s data model. It records the models and fields your code depends on, the physical storage layout (tables, columns, indexes, foreign keys), the capabilities your queries may use, and the hashes that tie everything together. It carries no executable logic — it is data that gates execution.
Because the contract is pure JSON, any tool, agent, or human can read it without running application code. The emitter that produces it follows strict canonicalization rules (lexicographic key ordering, normalized scalars, stable array ordering), so the same schema always produces the same bytes — and the same hash.
What contract.json contains
Here is a minimal example from a real Prisma Next project:| Section | Purpose |
|---|---|
roots | Maps ORM accessor names to model names (e.g. "user": "User") |
models | Domain-level description: fields, relations, and the storage bridge |
storage | Physical layout: tables, columns, PK/FK/indexes, and the storageHash |
capabilities | Feature flags that queries are allowed to use when lowering to SQL |
extensionPacks | Extension-contributed types, codecs, and capability declarations |
The three hashes
The contract carries three distinct hashes, each covering a different concern:storageHash — computed from the physical storage layout: tables, columns, types, constraints. When this hash changes, the database schema has changed. The runtime compares the storageHash embedded in each query plan against the hash stored in the database marker before executing. A mismatch means the database is out of sync with the contract.
profileHash — computed from the capability profile declared by the contract: the capability keys and any explicit adapter pins. It does not change when you rename a column, but it does change when you enable a new capability such as pgvector.cosine. The migration runner writes this hash to the database marker after verifying that the live database satisfies all declared capabilities.
executionHash (optional) — computed from the execution section when execution defaults (such as UUID generation or now() timestamps) are declared. Plans that depend on execution defaults embed this hash.
Schema drift detection at runtime
Every compiled query plan includesstorageHash (and profileHash) in its meta block. Before executing any plan, the runtime reads the database marker — a small internal schema Prisma Next maintains — and checks that the plan’s hashes match what is recorded there. If the database has been migrated without updating the contract (or vice versa), execution fails immediately with a structured error rather than silently returning wrong data.
This check happens at query time with no additional network round-trip on most adapters, because the marker is cached after the first connection.
Control Plane vs Execution Plane
Prisma Next is organized around two planes that both read the samecontract.json:
Control Plane (build time): responsible for authoring the contract (PSL or TypeScript), planning migrations as contract-to-contract edges, running preflight checks against shadow databases, and applying migrations idempotently. The Control Plane writes storageHash and profileHash to the database marker.
Execution Plane (runtime): responsible for compiling queries into immutable plans, verifying marker hashes before execution, applying guardrail plugins (lints, budgets, telemetry), and streaming results through codec-aware adapters. The Execution Plane only reads the marker.
Both planes are driven entirely by the contract. Neither evaluates application code at plan time.
Comparison with Prisma ORM codegen
| Feature | Prisma ORM | Prisma Next |
|---|---|---|
| Schema model | Generates executable client code | Generates contract IR + TypeScript types |
| Code generation | Heavy, runtime-bound prisma generate | Minimal: contract.json + contract.d.ts only |
| Query interface | Generated methods (prisma.user.findMany()) | Composable DSL (sql().from(...).select(...)) |
| Machine readability | Opaque generated code | Structured JSON artifact |
| Drift detection | None | storageHash + runtime marker check |
| Extensibility | Monolithic client | Extension packs, adapters, plugins |
| Artifact diff | Hard; code diffs are noisy | Easy; JSON diffs are semantic |
The contract is data, not code. Unlike Prisma ORM’s generated client — which is executable TypeScript tied to a specific runtime —
contract.json carries no executable logic. Any tool, agent, or CI process can read, diff, and reason about it without running your application. This separation is what makes deterministic hashing, runtime drift detection, and agent-friendly workflows possible.