Prisma Driver Adapter Implementation

# Prisma SQL Driver Adapter Implementation

Use this guide with the exact `@prisma/driver-adapter-utils` version installed by the target Prisma release. Driver adapters are a protocol boundary: type-compatible code can still corrupt values, leak connections, or break transactions.

## When to Apply

- Implementing `SqlDriverAdapterFactory`, `SqlMigrationAwareDriverAdapterFactory`, `SqlDriverAdapter`, or `Transaction` - Adding nested-transaction/savepoint support - Mapping driver values, column metadata, bind arguments, or database errors - Debugging `P2039`, transaction leaks, shadow-database failures, or adapter-specific query behavior

## Contract snapshot

```typescript interface SqlDriverAdapterFactory extends AdapterInfo { connect(): Promise<SqlDriverAdapter> }

interface SqlMigrationAwareDriverAdapterFactory extends SqlDriverAdapterFactory { connectToShadowDb(): Promise<SqlDriverAdapter> }

interface SqlDriverAdapter extends AdapterInfo { queryRaw(query: SqlQuery): Promise<SqlResultSet> executeRaw(query: SqlQuery): Promise<number> executeScript(script: string): Promise<void> startTransaction(isolationLevel?: IsolationLevel): Promise<Transaction> getConnectionInfo?(): ConnectionInfo dispose(): Promise<void> }

interface Transaction extends AdapterInfo { readonly options: { usePhantomQuery: boolean } queryRaw(query: SqlQuery): Promise<SqlResultSet> executeRaw(query: SqlQuery): Promise<number> commit(): Promise<void> rollback(): Promise<void> createSavepoint?(name: string): Promise<void> rollbackToSavepoint?(name: string): Promise<void> releaseSavepoint?(name: string): Promise<void> } ```

`IsolationLevel` currently includes `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READ`, `SNAPSHOT`, and `SERIALIZABLE`; validate what the concrete database supports.

## Priority rules

| Priority | Rule | Impact | |----------|------|--------| | CRITICAL | One dedicated connection per transaction | Prevents interleaving and leaks | | CRITICAL | `commit`/`rollback` are lifecycle cleanup hooks | Prevents duplicate COMMIT/ROLLBACK | | CRITICAL | Savepoints live on `Transaction`, not adapter-global depth | Makes nested scopes connection-local | | CRITICAL | Preserve original database error code/message | Enables useful `P2039` fallback | | HIGH | Map arguments and result metadata exactly | Prevents silent value corruption | | HIGH | Shadow databases are isolated and always cleaned up | Makes Migrate safe | | HIGH | Dispose only resources the adapter owns | Prevents shutting down caller-owned pools |

## Query implementation

`SqlQuery` contains `sql`, `args`, and parallel `argTypes`. Map each argument using both value and `ArgType`; do not discard type/arity information. Execute in the driver's array/tuple row mode so column order is stable.

```typescript class ExampleQueryable { readonly provider = 'postgres' as const readonly adapterName = '@acme/adapter-example'

constructor(protected readonly connection: DriverConnection) {}

async queryRaw(query: SqlQuery): Promise<SqlResultSet> { try { const result = await this.connection.query({ text: query.sql, values: query.args.map((value, index) => mapArg(value, query.argTypes[index]), ), rowMode: 'array', })

return { columnNames: result.fields.map((field) => field.name), columnTypes: result.fields.map(mapColumnType), rows: result.rows, } } catch (error) { throwAdapterError(error) } }

async executeRaw(query: SqlQuery): Promise<number> { try { const result = await this.connection.execute( query.sql, query.args.map((value, index) => mapArg(value, query.argTypes[index])), ) return result.rowsAffected ?? 0 } catch (error) { throwAdapterError(error) } } } ```

### Result mapping

Return `columnNames`, `columnTypes`, and `rows` with identical lengths/order. Map driver metadata to `ColumnTypeEnum` deliberately:

- signed integer widths to `Int32`/`Int64`; preserve 64-bit values without JS number truncation - decimal/numeric to `Numeric` using the representation expected by Prisma - binary to `Uint8Array`/`Bytes` - date-only, time-only, and timestamp to `Date`, `Time`, and `DateTime` - UUID, JSON, enum, arrays, and provider-specific unknown values to their explicit types - unsupported native types to `DriverAdapterError({ kind: 'UnsupportedNativeDataType', type })`

Test `null`, empty arrays, array element types, big integers, decimals, byte arrays, JSON, dates, and user-defined/unknown native types.

### Script execution

`executeScript` must execute a migration script as the provider expects. Prefer the driver's native multi-statement/script facility or a real SQL parser. Naively splitting on `;` breaks functions, triggers, quoted strings, and dialect-specific blocks.

## Transaction protocol

`startTransaction` must acquire one dedicated connection, start the database tran