Driver adapters

How Prisma 7 talks to databases. This page is the cross-package narrative; the contract details are in driver-adapter-utils and the per-adapter packages in Driver adapters.

What a driver adapter is

A small TypeScript package that:

1. Wraps an existing JS database driver (pg, mysql2, mssql, @neondatabase/serverless, @libsql/client, etc.)
2. Implements the SqlDriverAdapter contract from @prisma/driver-adapter-utils
3. Maps DB-specific errors to a normalized MappedError shape

Users construct an adapter and pass it to new PrismaClient({ adapter }). There is no longer a Rust query engine subprocess; queries go through the adapter directly.

Why driver adapters

Prisma 7 deleted the native query engine binary. The query engine used to:

• Maintain its own connection pool
• Translate Prisma queries into SQL
• Speak to the database

The first two responsibilities were duplicated by every JS app's existing database driver. Driver adapters move those responsibilities back to the JS driver and keep only plan compilation in Prisma (now done by Wasm). That makes Prisma:

• Compatible with serverless platforms that don't allow spawning binaries (Cloudflare Workers, Vercel Edge)
• Compatible with custom drivers (Neon HTTP, PlanetScale HTTP)
• Lighter-weight overall (no engine subprocess, no IPC overhead)

End-to-end flow

sequenceDiagram
    participant App as User app
    participant Client as PrismaClient
    participant Engine as ClientEngine
    participant Compiler as @prisma/query-compiler-wasm
    participant Exec as LocalExecutor
    participant Interp as QueryInterpreter
    participant Adapter as e.g. PrismaPg
    participant Driver as pg
    participant DB as Postgres

    App->>Client: prisma.user.findMany({...})
    Client->>Engine: request(json)
    Engine->>Compiler: compile to plan
    Compiler-->>Engine: query plan
    Engine->>Exec: execute(plan)
    Exec->>Interp: run(plan, adapter)
    Interp->>Adapter: queryRaw({sql, args})
    Adapter->>Driver: client.query(text, values)
    Driver->>DB: SQL
    DB-->>Driver: rows
    Driver-->>Adapter: result
    Adapter-->>Interp: typed rows
    Interp-->>Exec: shaped JSON
    Exec-->>Engine: response
    Engine-->>Client: response
    Client-->>App: User[]

Contract surface

Defined in packages/driver-adapter-utils/src/types.ts:

Type	What it is
SqlQueryable	The minimum interface: provider, executeRaw, queryRaw. Both adapters and Transaction extend it
SqlDriverAdapter extends SqlQueryable	Adds transactionContext() (returns a TransactionContext for starting transactions) and dispose()
SqlDriverAdapterFactory	A factory: connect(config) returns a SqlDriverAdapter
SqlMigrationAwareDriverAdapterFactory	A factory that Migrate can use to introspect/modify schema
Transaction extends SqlQueryable	Adds commit(), rollback(), createSavepoint(name), rollbackToSavepoint(name), releaseSavepoint?(name)
MappedError	Normalized error: { kind, originalCode?, originalMessage?, ... }
Provider	'mysql' | 'postgres' | 'sqlite' | 'sqlserver'

The nine adapters

Package	Drivers / target	Provider
@prisma/adapter-pg	pg	postgres + cockroachdb
@prisma/adapter-neon	@neondatabase/serverless	postgres
@prisma/adapter-libsql	@libsql/client	sqlite
@prisma/adapter-better-sqlite3	better-sqlite3	sqlite
@prisma/adapter-d1	Cloudflare D1	sqlite
@prisma/adapter-planetscale	@planetscale/database	mysql
@prisma/adapter-mariadb	mariadb	mysql
@prisma/adapter-mssql	mssql (tedious)	sqlserver
@prisma/adapter-ppg	Prisma Postgres Serverless (HTTP)	postgres

CI test flavors map 1:1 to adapters: js_pg, js_neon, js_libsql, js_planetscale, js_d1, js_better_sqlite3, js_mssql, js_mariadb, js_pg_cockroachdb. Functional tests in packages/client/tests/functional/ run against each flavor.

Error mapping pipeline

graph LR
    DBError[Driver throws raw error] --> Convert[adapter's convertDriverError<br/>e.g., adapter-pg/src/errors.ts]
    Convert --> Mapped[MappedError kind]
    Mapped --> Reroute{kind?}
    Reroute -->|known cross-DB kind| Mapped2Code[getErrorCode in user-facing-error.ts]
    Reroute -->|unknown DB code| P2039[P2039 fallback]
    Mapped2Code --> Pxxxx[P2002 / P2003 / etc.]
    Pxxxx --> KnownErr[PrismaClientKnownRequestError]
    P2039 --> KnownErr

The adapter maps DB-specific codes to MappedError kinds. rethrowAsUserFacing in client-engine-runtime/src/user-facing-error.ts turns them into Prisma's P2xxx codes. Unknown codes fall through to P2039 (with format Database error. Code: <originalCode>. Message: <originalMessage>) so they remain debuggable instead of becoming HTTP 500s through Accelerate.

Raw queries ($queryRaw, $executeRaw) take a different path through rethrowAsUserFacingRawError, which always returns P2010.

Where things live

• Contract → packages/driver-adapter-utils/src/types.ts
• Per-adapter implementation → packages/adapter-*/src/<name>.ts + errors.ts
• Consumer that talks through the adapter → packages/client-engine-runtime/src/interpreter/query-interpreter.ts
• User-visible constructor option → packages/client/src/runtime/getPrismaClient.ts (adapter field)
• Error code translation → packages/client-engine-runtime/src/user-facing-error.ts

Adding a new adapter

Step-by-step:

1. Copy packages/adapter-pg/ to packages/adapter-<name>/ and rename.
2. Replace the underlying driver in the implementation.
3. Implement convertDriverError in errors.ts for the database's error codes.
4. If the adapter requires Migrate compatibility, implement SqlMigrationAwareDriverAdapterFactory.
5. Implement savepoint methods on Transaction (per-database SQL — see @prisma/client-engine-runtime).
6. Register the package in pnpm-workspace.yaml (auto-discovered via packages/*).
7. Add the package to the driver-adapter-unit-tests job in .github/workflows/test-template.yml.
8. Add a CI flavor (js_<name>) to the functional test matrix.
9. Add documentation in this wiki under Driver adapters package page and link from there.

See also

• Driver adapters package page for per-adapter detail
• driver-adapter-utils for the contract
• Transactions for the savepoint flow
• Query execution for how plans flow through adapters