prisma/prisma

Architecture

Prisma is split between this repository (TypeScript) and prisma-engines (Rust). Within this repo, the codebase is organized as a pnpm workspace driven by Turborepo (turbo.json). At runtime, the major components are the CLI, the generators, the client runtime, the Wasm engine runtime, the driver adapters, and the schema engine binary that Migrate shells out to.

Two repositories, one product

graph LR
    subgraph "prisma-engines (Rust)"
        PSL[PSL parser]
        QC[Query compiler]
        SE[Schema Engine binary]
    end

    subgraph "prisma/prisma (TypeScript - this repo)"
        CLI[Prisma CLI]
        GEN[Client generators]
        CLIENT[Prisma Client runtime]
        CER[client-engine-runtime]
        ADAPTERS[Driver adapters]
    end

    PSL -->|compiled to Wasm| CLI
    QC -->|compiled to Wasm| CLIENT
    SE -->|downloaded as binary| CLI
    GEN -->|generates code that imports| CLIENT
    CLIENT -->|uses| CER
    CER -->|talks to DB through| ADAPTERS

The Rust components compile to two artifacts that this repo consumes:

@prisma/prisma-schema-wasm — used by the CLI for parsing/validation/formatting
@prisma/query-compiler-wasm — used by Prisma Client to plan SQL from JSON queries
@prisma/schema-engine — a native binary downloaded by @prisma/engines and shelled out to by prisma migrate

Read more in AGENTS.md, which is the canonical agent-facing knowledge base for this repo.

Workspace layout

The workspace root is managed by pnpm-workspace.yaml:

packages:
  - 'packages/*'

Turborepo (turbo.json) coordinates build/dev tasks across packages. Builds use a shared esbuild-based pipeline in helpers/compile/build.ts with reusable configs in helpers/compile/configs.ts.

Component map

graph TD
    USER[User code]
    CLI[packages/cli — `prisma` binary]
    INIT[Init / Format / Generate / Studio / Validate]
    MIGRATE[packages/migrate — db / migrate subcommands]
    SE_BIN[Schema Engine binary]
    INTERNALS[packages/internals — shared CLI utilities]
    CONFIG[packages/config — prisma.config.ts loader]

    GEN_TS[client-generator-ts — `prisma-client`]
    GEN_JS[client-generator-js — `prisma-client-js`]
    GEN_REGISTRY[client-generator-registry]

    CLIENT[packages/client — runtime + getPrismaClient]
    CER[client-engine-runtime — query interpreter, txn manager]
    ENGINES[packages/engines — engine downloads]
    ADAPTERS[adapter-pg, adapter-neon, adapter-libsql, adapter-d1, ...]
    DAU[driver-adapter-utils]

    USER -->|invokes| CLI
    CLI --> INIT
    CLI --> MIGRATE
    MIGRATE -->|spawns| SE_BIN
    CLI --> INTERNALS
    CLI --> CONFIG
    CLI -->|invokes| GEN_TS
    CLI -->|invokes| GEN_JS
    GEN_TS --> GEN_REGISTRY
    GEN_JS --> GEN_REGISTRY
    GEN_TS -->|imports types from| CLIENT
    GEN_JS -->|imports types from| CLIENT

    USER -->|imports generated| CLIENT
    CLIENT --> CER
    CER --> ADAPTERS
    ADAPTERS --> DAU
    CLIENT --> ENGINES

Query execution flow (Prisma 7)

The most important runtime path is "user code calls prisma.user.findMany() and gets rows back". With Prisma 7 this no longer goes through a native query engine binary; everything happens in Node.js with a Wasm query compiler:

sequenceDiagram
    participant App as User code
    participant Client as PrismaClient (packages/client)
    participant Engine as ClientEngine
    participant QC as Query compiler (Wasm)
    participant Exec as LocalExecutor / RemoteExecutor
    participant Interp as QueryInterpreter (client-engine-runtime)
    participant Adapter as Driver adapter (adapter-*)
    participant DB as Database

    App->>Client: prisma.user.findMany({...})
    Client->>Engine: request(jsonProtocol)
    Engine->>QC: compile to query plan
    QC-->>Engine: query plan
    Engine->>Exec: execute(plan)
    Exec->>Interp: run(plan)
    Interp->>Adapter: queryRaw / executeRaw
    Adapter->>DB: SQL
    DB-->>Adapter: rows
    Adapter-->>Interp: typed result rows
    Interp-->>Exec: shaped JSON
    Exec-->>Engine: response
    Engine-->>Client: response
    Client-->>App: typed objects

ClientEngine lives in packages/client/src/runtime/core/engines/client/ClientEngine.ts. The interpreter that walks query plans lives in packages/client-engine-runtime/src/interpreter/query-interpreter.ts. The driver adapter contract is defined in packages/driver-adapter-utils/src/types.ts.

There is no longer a separate "query engine" process — that name belongs to a previous era and should not appear in new docs or code (see Glossary).

Migration flow (Schema Engine)

Migrate is the one place Prisma still shells out to a native Rust binary:

sequenceDiagram
    participant CLI as prisma migrate dev
    participant Migrate as packages/migrate
    participant SE_RPC as SchemaEngineCLI / SchemaEngineWasm
    participant Bin as Schema Engine binary
    participant DB as Database

    CLI->>Migrate: invoke MigrateDev
    Migrate->>SE_RPC: spawn / load engine
    SE_RPC->>Bin: stdio JSON-RPC
    Bin->>DB: introspection / migrations SQL
    DB-->>Bin: results
    Bin-->>SE_RPC: rpc responses
    SE_RPC-->>Migrate: typed results
    Migrate-->>CLI: terminal output

There are two engine transports in packages/migrate/src/: SchemaEngineCLI.ts (subprocess + stdio JSON-RPC) and SchemaEngineWasm.ts (in-process Wasm). They both implement the contract defined in SchemaEngine.ts.

Build and tooling pipeline

graph LR
    PNPM[pnpm install]
    TURBO[turbo build]
    ESBUILD[helpers/compile/build.ts]
    DTS[helpers/compile/plugins/tsc/]
    ENGINE_DL[packages/engines postinstall]

    PNPM --> ENGINE_DL
    PNPM --> TURBO
    TURBO --> ESBUILD
    ESBUILD --> DTS
    ESBUILD --> Bundle[CJS + ESM bundles]
    DTS --> Types[*.d.ts]

The build is esbuild-based, not tsc. Type declarations are emitted by a TypeScript compiler step but bundling happens in helpers/compile/build.ts. Most packages opt into bundledConfig which produces dual CJS/ESM bundles plus type declarations.

Languages and lines of code

The TypeScript-vs-everything-else breakdown of source files in this repository:

xychart-beta horizontal
    title "Source files by language"
    x-axis [TypeScript, Prisma schema, JSON, JavaScript, YAML, Markdown]
    y-axis "Files" 0 --> 2800
    bar [2701, 509, 414, 95, 33, 170]

TypeScript dominates. The .prisma count is high because every test fixture gets its own schema. There is no Rust here — Rust lives in prisma/prisma-engines.