Client

Active contributors: jacek-prisma, Oleksii Orlenko, Søren Bramer Schmidt

Purpose

packages/client is the Prisma Client runtime — the type-safe query builder users import as @prisma/client. It contains the PrismaClient class, the ClientEngine orchestrator, the request/response handling pipeline, the extension system, and the runtime that generated clients import from.

The actual generated client is emitted by client-generator-ts or client-generator-js at user-project build time, but every emitted client is a thin wrapper that imports the heavy lifting from this package's runtime/ directory.

Directory layout

packages/client/
├── src/
│   ├── runtime/                        # The runtime that generated clients import
│   │   ├── getPrismaClient.ts          # Factory for the PrismaClient class (~37KB)
│   │   ├── RequestHandler.ts           # Maps request → engine call → response shape
│   │   ├── DataLoader.ts               # Per-request batching for relation loads
│   │   ├── core/
│   │   │   ├── engines/
│   │   │   │   ├── client/             # ClientEngine (Prisma 7)
│   │   │   │   │   └── ClientEngine.ts
│   │   │   │   └── common/Engine.ts    # Engine contract
│   │   │   ├── extensions/             # PrismaClient extensions API
│   │   │   ├── compositeProxy/         # Proxy plumbing for extensions
│   │   │   ├── errors/                 # Runtime error types
│   │   │   ├── errorRendering/         # Validation error formatting
│   │   │   ├── jsonProtocol/           # JSON wire format
│   │   │   ├── model/                  # applyModel / applyFluent / etc.
│   │   │   ├── public/                 # Public-API utilities (Decimal, etc.)
│   │   │   ├── raw-query/              # $queryRaw / $executeRaw plumbing
│   │   │   ├── request/                # request lifecycle helpers
│   │   │   ├── tracing/                # OpenTelemetry hooks
│   │   │   ├── transaction/            # Interactive and batch transactions
│   │   │   └── types/                  # Internal type plumbing
│   │   └── utils/                      # Misc runtime utilities
│   ├── generation/                     # Code-generation utilities (legacy, transitional)
│   ├── utils/                          # Build-time utilities
│   └── __tests__/                      # Unit + integration + benchmarks
├── tests/
│   ├── functional/                     # Functional matrix tests
│   └── e2e/                            # End-to-end tests with real generated clients
├── fixtures/                           # Schema fixtures
├── helpers/build.ts                    # esbuild glue
├── default.js / index.js / edge.js     # Public entry shims
├── sql.js / extension.js               # Auxiliary entry points
└── package.json

The package publishes multiple entry points (default, index, edge, sql, extension) — each shim re-exports a different runtime configuration (e.g., edge runtime trimmed for Cloudflare Workers).

Key abstractions

Symbol	File	What it does
getPrismaClient(config)	packages/client/src/runtime/getPrismaClient.ts	Factory that returns the PrismaClient class tailored to a generated client's config
ClientEngine	packages/client/src/runtime/core/engines/client/ClientEngine.ts	Orchestrates request → query plan → execution. Replaces the old query engine for Prisma 7
Engine interface	packages/client/src/runtime/core/engines/common/Engine.ts	The contract ClientEngine and any future engine implementations satisfy
RequestHandler	packages/client/src/runtime/RequestHandler.ts	Translates user-method calls (prisma.user.findMany(...)) into engine requests, then unpacks the response
DataLoader	packages/client/src/runtime/DataLoader.ts	Batches sibling relation loads to avoid N+1 round trips
PrismaClientOptions type	packages/client/src/runtime/getPrismaClient.ts	Constructor options the user passes to new PrismaClient({ ... })
validatePrismaClientOptions	packages/client/src/runtime/utils/validatePrismaClientOptions.ts	Validation entry for the constructor options object
applyFluent	packages/client/src/runtime/core/model/applyFluent.ts	Implements the fluent API (prisma.user.findFirst({...}).posts())

How a query reaches the database

The runtime path is documented in Architecture. Inside this package, the trip is:

sequenceDiagram
    participant User as User code
    participant Proxy as PrismaClient (compositeProxy)
    participant RH as RequestHandler
    participant Engine as ClientEngine
    participant Exec as LocalExecutor / RemoteExecutor

    User->>Proxy: prisma.user.findMany({...})
    Proxy->>RH: handleRequest(action, args, dataPath)
    RH->>Engine: request(jsonProtocol)
    Engine->>Exec: execute(plan, params)
    Exec-->>Engine: response
    Engine-->>RH: response
    RH-->>Proxy: shaped JSON
    Proxy-->>User: typed objects

Two executor implementations live alongside ClientEngine:

• LocalExecutor — uses a driver adapter to talk directly to the database via QueryInterpreter from client-engine-runtime.
• RemoteExecutor — sends the query plan to Prisma Accelerate (Data Proxy) over HTTP. Used when accelerateUrl is configured.

The ExecutePlanParams interface in packages/client/src/runtime/core/engines/client/Executor.ts is the contract both executors satisfy.

Constructor options

PrismaClient constructor options are validated in packages/client/src/runtime/utils/validatePrismaClientOptions.ts. The current set:

Option	Notes
errorFormat	pretty / colorless / minimal
adapter	A SqlDriverAdapterFactory from a @prisma/adapter-* package
accelerateUrl	URL for Prisma Accelerate; switches to RemoteExecutor
log	Log levels and emit modes
transactionOptions	Defaults for interactive transactions (maxWait, timeout, isolationLevel)
omit	Per-model field omission
comments	List of SQL Commenter plugins (see SQL Commenter)
__internal	Reserved escape hatch used by Prisma's own tooling

Adding an option requires changes in five places per AGENTS.md:

1. Runtime types: PrismaClientOptions in getPrismaClient.ts
2. Validation: validatePrismaClientOptions.ts (knownProperties array + validators object)
3. Engine config: EngineConfig interface in core/engines/common/Engine.ts
4. Generated types in both generators: client-generator-js/src/TSClient/PrismaClient.ts buildClientOptions method, and client-generator-ts/src/TSClient/file-generators/PrismaNamespaceFile.ts buildClientOptions function
5. Use @prisma/ts-builders to emit the TypeScript declarations in the generators

Extensions

Prisma Client extensions ($extends) let users add or override methods on models, results, and the client itself. Implementation lives in packages/client/src/runtime/core/extensions/ and the proxy machinery in packages/client/src/runtime/core/compositeProxy/.

A subtle bug in Prisma 7's path: in extension context resolution, dataPath should be interpreted as selector/field pairs (select|include, then relation field), not by stripping select/include segments by raw string. Stripping by raw value drops relations literally named select or include. Track this in applyFluent.ts and RequestHandler.ts.

Sub-pages

• Runtime: ClientEngine and execution — deeper dive into ClientEngine, executors, and the runtime path
• Tests — how the package tests itself (functional matrix, e2e, unit)

See also

• client-engine-runtime — the query interpreter and transaction manager that ClientEngine calls into
• Driver adapters and driver-adapter-utils — the adapter surface
• Query execution — feature-page summary of the end-to-end flow
• SQL Commenter plugins