prisma/prisma

Driver adapters

Active contributors: jacek-prisma, Oleksii Orlenko

Purpose

Driver adapters are how Prisma 7 talks to databases. Each packages/adapter-* package wraps an existing JS database driver (pg, mysql2, mssql, @neondatabase/serverless, @libsql/client, etc.) and exposes the SqlDriverAdapter contract from @prisma/driver-adapter-utils. Users pass an adapter instance to new PrismaClient({ adapter }) and Prisma Client speaks to the database through that adapter.

This page is the lens for all nine adapters. The contract itself is small — most of the per-adapter work is error mapping and savepoint dialect.

The adapters

Package	Driver wrapped	Provider	CI flavor
`@prisma/adapter-pg`	`pg`	postgres	`js_pg`
`@prisma/adapter-pg` (CockroachDB mode)	`pg`	postgres	`js_pg_cockroachdb`
`@prisma/adapter-neon`	`@neondatabase/serverless`	postgres	`js_neon`
`@prisma/adapter-libsql`	`@libsql/client`	sqlite	`js_libsql`
`@prisma/adapter-better-sqlite3`	`better-sqlite3`	sqlite	`js_better_sqlite3`
`@prisma/adapter-d1`	Cloudflare D1	sqlite	`js_d1`
`@prisma/adapter-planetscale`	`@planetscale/database`	mysql	`js_planetscale`
`@prisma/adapter-mariadb`	`mariadb`	mysql	`js_mariadb`
`@prisma/adapter-mssql`	`mssql` (`tedious`)	sqlserver	`js_mssql`
`@prisma/adapter-ppg`	Prisma Postgres Serverless (HTTP)	postgres	(covered by Accelerate)

Plus packages/bundled-js-drivers — a build helper package that re-exports specific bundled versions of the underlying drivers for use inside Prisma's own bundles.

The contract

All adapters implement interfaces from packages/driver-adapter-utils/src/types.ts:

SqlDriverAdapterFactory — connect(...) returns a SqlDriverAdapter
SqlDriverAdapter extends SqlQueryable — provider, executeRaw, queryRaw, transactionContext(), dispose()
SqlMigrationAwareDriverAdapterFactory — adapters that Migrate can use directly
Transaction — savepoint methods (createSavepoint, rollbackToSavepoint, optional releaseSavepoint), commit/rollback, plus SqlQueryable
SqlQuery — the query payload (SQL text + parameter values)
ConnectionInfo — adapter metadata exposed to the client

The Provider type is 'mysql' | 'postgres' | 'sqlite' | 'sqlserver'.

Error mapping per adapter

Every adapter has an errors.ts file that defines convertDriverError:

graph LR
    DBError[Driver throws DB-specific error] --> Convert[convertDriverError]
    Convert --> Mapped[MappedError kind]
    Mapped --> Rethrow[client-engine-runtime/user-facing-error.ts<br/>rethrowAsUserFacing]
    Rethrow --> Pxxxx[PrismaClientKnownRequestError P2xxx]

The known error kinds are listed in MappedError in driver-adapter-utils/src/types.ts. Categories:

Cross-database: GenericJs, UnsupportedNativeDataType, InvalidIsolationLevel, LengthMismatch
Constraints: UniqueConstraintViolation, NullConstraintViolation, ForeignKeyConstraintViolation
Connectivity: DatabaseNotReachable, DatabaseDoesNotExist, DatabaseAlreadyExists, DatabaseAccessDenied, ConnectionClosed, TlsConnectionError, AuthenticationFailed, TooManyConnections, SocketTimeout
Schema: TableDoesNotExist, ColumnNotFound, MissingFullTextSearchIndex
Transactions: TransactionWriteConflict, TransactionAlreadyClosed
Values: ValueOutOfRange, InvalidInputValue, InconsistentColumnData
Database-specific kinds as fallbacks: postgres, mysql, sqlite, mssql (with raw originalCode/originalMessage)

The fallback database-specific kinds are what rethrowAsUserFacing translates to P2039 when no specific mapping is found. Raw queries route through rethrowAsUserFacingRawError which always returns P2010.

To add a new error mapping:

Add the kind to MappedError in packages/driver-adapter-utils/src/types.ts.
Map the database error code in each adapter's errors.ts.
Add Prisma code mapping in getErrorCode() and message in renderErrorMessage() in packages/client-engine-runtime/src/user-facing-error.ts.

Savepoints (per-provider dialect)

Nested transactions are implemented as savepoints. Each adapter owns its own SQL:

Provider	Create	Rollback to	Release
PostgreSQL	`SAVEPOINT <name>`	`ROLLBACK TO SAVEPOINT <name>`	`RELEASE SAVEPOINT <name>`
MySQL	`SAVEPOINT <name>`	`ROLLBACK TO <name>`	`RELEASE SAVEPOINT <name>`
SQLite	`SAVEPOINT <name>`	`ROLLBACK TO <name>`	`RELEASE <name>`
SQL Server	`SAVE TRANSACTION <name>`	`ROLLBACK TRANSACTION <name>`	(no release statement)

These are surfaced via async methods on Transaction (createSavepoint, rollbackToSavepoint, optional releaseSavepoint). TransactionManager in client-engine-runtime does not synthesize fallback SQL — adapters that don't implement these methods will fail at nested-transaction time, intentionally.

How Prisma Client picks an adapter

import { PrismaPg } from '@prisma/adapter-pg';
import { PrismaClient } from './generated/client';

const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL });
const prisma = new PrismaClient({ adapter });

The adapter factory is constructed once and passed to new PrismaClient. ClientEngine reads the adapter through EngineConfig and routes via LocalExecutor. Without an adapter, ClientEngine throws a P2038 PrismaClientInitializationError (packages/client/src/runtime/core/engines/client/ClientEngine.ts CLIENT_ENGINE_ERROR).

Layout pattern

Each adapter package looks the same:

packages/adapter-<name>/
├── src/
│   ├── index.ts          # Exports the public factory class (e.g., PrismaPg)
│   ├── <name>.ts         # The adapter implementation
│   ├── errors.ts         # convertDriverError (DB code → MappedError kind)
│   └── ...               # Helpers per-driver
├── helpers/
└── package.json

packages/adapter-pg is the canonical reference — when adding a new adapter, copy its layout.

CI

.github/workflows/test-template.yml has a dedicated driver-adapter-unit-tests job for the adapters. Functional tests run against actual databases (provided by docker/docker-compose.yml); each driver flavor (js_pg, js_neon, etc.) is tested in matrix.

Integration points

@prisma/driver-adapter-utils — the contract every adapter implements
@prisma/client-engine-runtime — the QueryInterpreter and TransactionManager consume a SqlQueryable
@prisma/client — PrismaClientOptions.adapter accepts a SqlDriverAdapterFactory
packages/migrate — Migrate consumes adapters via SqlMigrationAwareDriverAdapterFactory for some flows

Entry points for modification

Add a new error mapping to existing adapters: see the three-step procedure above
Add a new adapter: copy packages/adapter-pg, replace the underlying driver, implement errors.ts, register in CI's driver-adapter-unit-tests job, add a flavor to the functional test matrix
Change savepoint semantics: the adapter's Transaction implementation