prisma/prisma

query-plan-executor

Active contributors: jacek-prisma, Oleksii Orlenko

Purpose

@prisma/query-plan-executor is a standalone HTTP service that executes Prisma query plans server-side. It is the engine behind Prisma Accelerate (Data Proxy): when a Prisma Client uses RemoteExecutor (because the user configured accelerateUrl), the compiled query plan is sent to this service, which runs it against a connection pool and returns the response.

It exists as its own deployable so that Accelerate can horizontally scale and pool connections, while end-user clients stay thin and adapter-agnostic.

How it fits

graph LR
    subgraph Client side
        UserApp[User app]
        PC[PrismaClient]
        RE[RemoteExecutor]
    end
    UserApp --> PC
    PC --> RE
    RE -->|HTTPS POST plan| Accelerate[(Prisma Accelerate)]
    Accelerate --> QPE[query-plan-executor process]
    QPE --> Pool[Connection pool]
    Pool --> DB[(Database)]
    DB --> Pool
    Pool --> QPE
    QPE -->|HTTPS response| Accelerate
    Accelerate --> RE
    RE --> PC
    PC --> UserApp

Inside query-plan-executor, the work is done by exactly the same QueryInterpreter and TransactionManager from @prisma/client-engine-runtime. That's the whole point of having extracted those types into their own package: server-side and client-side execution use the same code.

Directory layout

packages/query-plan-executor/
├── src/
│   ├── ...           # HTTP server, plan dispatch, connection pool
│   └── __tests__/
├── helpers/
└── package.json

Wire format

Requests come in as json-protocol payloads (see packages/client-engine-runtime/src/json-protocol.ts) — the same format LocalExecutor and RemoteExecutor produce. The response is shaped JSON that the client unpacks identically to local execution.

Error handling

Errors from this service propagate back to the client. Of particular note:

Database errors that the adapter can't classify (postgres/mysql/sqlite/mssql with unrecognized codes) are returned as HTTP 400 with P2039 rather than HTTP 500. This is intentional: Accelerate strips HTTP 500s. From AGENTS.md:

P2039 is used for non-raw queries so the message doesn't claim a regular Prisma operation was a raw query. … This keeps the DB error surface as PrismaClientKnownRequestError locally and as an HTTP 400 from the query plan executor (instead of HTTP 500, which Accelerate strips), so that schema-drift-style failures (stale migrations, stale generated client, etc.) remain debuggable.
Raw queries continue to use P2010 via rethrowAsUserFacingRawError.

Integration points

Consumes @prisma/client-engine-runtime for QueryInterpreter, TransactionManager, and the user-facing error mapper
Consumes @prisma/driver-adapter-utils for the adapter contract
Used by Prisma Accelerate — Accelerate's edge proxy forwards plans to instances of this service

Entry points for modification

Add a new endpoint: src/
Change pooling behavior: src/ (connection pool helpers)
Add a new error case: see @prisma/client-engine-runtime's error mapping section