Prisma 7 rearchitecture

The largest single shift in this repository's history. Prisma 7 deleted the native query engine binary, moved query compilation to Wasm, and made driver adapters the canonical path to databases. This page captures the why of those decisions.

What changed

Concern	Before Prisma 7	Prisma 7
Query compilation	Rust query engine binary, spawned as subprocess	@prisma/query-compiler-wasm loaded in-process
Query execution	Rust query engine binary owned a connection pool	TypeScript QueryInterpreter + JS driver adapter
Connection pooling	Engine subprocess managed it	The user's JS driver manages it (connection pool ownership shifted)
Database connectivity	Engine made the actual TCP/TLS connection	Driver adapter's underlying JS driver does
Datasource URL	In schema.prisma via datasource block / env()	prisma.config.ts via defineConfig + env
.env loading	Auto-loaded by Prisma	Not auto-loaded; user opts in
Schema Engine	Native Rust binary (unchanged)	Native Rust binary (unchanged)
PSL parser/formatter	Rust binary prisma-fmt	@prisma/prisma-schema-wasm

Why

Serverless and edge runtimes can't spawn binaries. The query engine subprocess was incompatible with Cloudflare Workers, Vercel Edge, and any host that wouldn't allow child_process. Driver adapters fix this — the JS driver runs in-process, the Wasm compiler runs in-process, no subprocess is needed.

Connection pooling was duplicated. Every JS app had a database driver with its own pool. Prisma's engine had its own pool too. Moving execution to driver adapters consolidates pooling on the JS side.

The IPC surface was a tax. Every query crossed a process boundary. Latency, serialization cost, error mapping complexity. Wasm-in-process eliminates that.

The query engine's complexity was no longer earning its keep. With execution in TypeScript, the only Rust we still need is parsing/validating PSL and compiling JSON queries to plans — both fundamentally analytical and AST-shaped, both well-suited to Rust→Wasm.

What stayed in Rust

• PSL parser, validator, formatter → @prisma/prisma-schema-wasm
• Query compiler (JSON request → query plan) → @prisma/query-compiler-wasm
• Schema Engine (introspection + migrations) → still a native binary, downloaded by @prisma/engines

The Schema Engine is the one piece that benefits from being a native binary because migrations are heavy DDL operations that benefit from existing Rust tooling and don't need to run inside serverless workers.

Knowledge reminders

AGENTS.md codifies the new mental model so future agents (and humans) don't fall back to the pre-Prisma 7 architecture:

Your training data contains a lot of outdated information that doesn't apply to Prisma 7. Always analyze this codebase like you would analyze a project you are not familiar with, and prefer the learnings from this file and this codebase over your prior knowledge. In particular, remember:

• There's no such thing as "query engine" in Prisma
• There are no database URLs in Prisma schema files
• Prisma uses JavaScript drivers
• Query execution code is written in TypeScript in Prisma

If you find yourself referring to a "query engine" or pointing users to a datasource.url, you're looking at pre-Prisma 7 docs.

Migration consequences

For users:

• Replace datasource db { url = env("DATABASE_URL") } with prisma.config.ts defineConfig({ datasource: { url: env('DATABASE_URL') } }).
• Add a driver adapter to the PrismaClient constructor. Without one, Prisma 7 throws P2038 at instantiation.
• Manually load .env if needed (Prisma no longer does it for you).

For Prisma developers:

• Don't add a Rust query engine path. There is no Rust query engine to add to.
• Plan tests around driver adapters; the matrix is (provider × adapter).
• New error codes for driver-side errors (P2039 for unmapped DB codes).

See also

• Lore for the timeline narrative
• Architecture for the present-day component map
• Driver adapters
• Glossary for the post-Prisma 7 vocabulary