Driver Adapters

Driver adapters bridge the gap between Rust-compiled query plans and database-specific TypeScript drivers. They enable Prisma to run in any JavaScript environment with appropriate database connectivity.

Overview

The driver adapter system allows the Query Compiler to target different databases and environments:

PostgreSQL: pg, @neondatabase/serverless, @prisma/adapter-pg
MySQL: mysql2, @planetscale/database, @prisma/adapter-mysql
SQLite: better-sqlite3, @libsql/client, Cloudflare D1
SQL Server: tedious, @prisma/adapter-mssql

Architecture

Rust Side
TypeScript Side

The Rust side provides WASM bindings and connection info abstraction:

use quaint::connector::ConnectionInfo;
use query_compiler::compile;

pub fn compile(
    query_schema: &QuerySchema,
    query: Operation,
    connection_info: &ConnectionInfo,
) -> Result<Expression, CompileError>

Connection info tells the compiler which SQL dialect to generate without requiring actual database access.

The TypeScript side executes the plan using driver adapters:

interface SqlDriverAdapter {
  queryRaw(params: Query): Promise<Result<ResultSet>>
  executeRaw(params: Query): Promise<Result<number>>
  startTransaction(): Promise<Result<SqlDriverTransaction>>
}

The interpreter walks the expression tree and calls adapter methods as needed.

Driver Adapter Manager

The DriverAdaptersManager interface standardizes driver setup:

export interface DriverAdaptersManager {
  /**
   * Access the Driver Adapter factory
   */
  factory: () => SqlDriverAdapterFactory

  /**
   * Creates a queryable instance from the Driver Adapter factory,
   * attempting a connection to the database.
   */
  connect: () => Promise<SqlDriverAdapter>

  /**
   * Closes the connection to the database and cleans up any used resources.
   */
  teardown: () => Promise<void>

  /**
   * Returns the connector used by the Manager.
   */
  connector: () => Env['CONNECTOR']
}

From libs/driver-adapters/executor/src/driver-adapters-manager/index.ts

Example: PostgreSQL Adapter

Here’s how the pg adapter is implemented:

import { PrismaPg } from '@prisma/adapter-pg'
import type {
  SqlMigrationAwareDriverAdapterFactory,
  SqlDriverAdapter,
} from '@prisma/driver-adapter-utils'
import { postgresSchemaName, postgresOptions } from '../utils.js'
import type { DriverAdaptersManager } from './index.js'

export class PgManager implements DriverAdaptersManager {
  #factory: SqlMigrationAwareDriverAdapterFactory
  #adapter?: SqlDriverAdapter

  private constructor(
    private env: EnvForAdapter<'pg'>,
    { url }: SetupDriverAdaptersInput,
  ) {
    const schemaName = postgresSchemaName(url)
    this.#factory = new PrismaPg(postgresOptions(url), {
      schema: schemaName,
    })
  }

  static async setup(env: EnvForAdapter<'pg'>, input: SetupDriverAdaptersInput) {
    return new PgManager(env, input)
  }

  factory() {
    return this.#factory
  }

  async connect() {
    return (this.#adapter ??= await this.#factory.connect())
  }

  async teardown() {
    await this.#adapter?.dispose()
  }

  connector(): Env['CONNECTOR'] {
    // could be 'postgresql' or 'cockroachdb'
    return this.env.CONNECTOR
  }
}

From libs/driver-adapters/executor/src/driver-adapters-manager/pg.ts

Supported Adapters

PostgreSQL

@prisma/adapter-pg (node-postgres)
@prisma/adapter-neon (Neon serverless)
@prisma/adapter-pg-worker (Cloudflare Workers)

MySQL

@prisma/adapter-mysql (mysql2)
@prisma/adapter-planetscale (PlanetScale serverless)
@prisma/adapter-mariadb

SQLite

@prisma/adapter-better-sqlite3
@prisma/adapter-libsql (Turso)
@prisma/adapter-d1 (Cloudflare D1)

SQL Server

@prisma/adapter-mssql (tedious)

Building the Driver Adapters Kit

The driver adapters are built separately from the query compiler:

Ensure Prisma repository is available

The build process requires the main Prisma repository for adapter packages:

make ensure-prisma-present

This clones prisma/prisma to ../prisma if not already present.

Install dependencies

make install-driver-adapters-kit-deps

Runs pnpm i in the driver adapters directory.

Build for Query Compiler

make build-driver-adapters-kit-qc

This runs pnpm build:qc which builds only the packages needed for query compiler tests.

From the Makefile:

install-driver-adapters-kit-deps: build-driver-adapters
	cd libs/driver-adapters && pnpm i

build-driver-adapters-kit-qc: install-driver-adapters-kit-deps
	cd libs/driver-adapters && pnpm build:qc

build-driver-adapters: ensure-prisma-present
	@echo "Building driver adapters..."
	@cd ../prisma && pnpm i
	@echo "Driver adapters build completed.";

Testing with Driver Adapters

The connector test kit can run against any driver adapter:

PostgreSQL + pg
SQLite + libsql
MySQL + PlanetScale
SQL Server

make dev-pg-qc
cargo test -p query-engine-tests

This:

Starts PostgreSQL via Docker
Builds query-compiler-wasm
Builds driver adapters kit
Sets up test config for pg adapter

make dev-libsql-qc
cargo test -p query-engine-tests -- --test-threads 1

Tests run single-threaded for SQLite to avoid database locking issues.

make dev-planetscale-qc
cargo test -p query-engine-tests -- --test-threads 1

make dev-mssql-qc
cargo test -p query-engine-tests

Connection Info Types

The WASM compiler needs to know the provider without having a real connection:

export type AdapterProvider =
  | 'postgresql'
  | 'mysql'
  | 'sqlite'
  | 'sqlserver'
  | 'cockroachdb'

export interface JsConnectionInfo {
  supports_relation_joins: boolean
  // Additional provider-specific options
}

In the WASM constructor:

pub struct QueryCompilerParams {
    datamodel: String,
    provider: AdapterProvider,
    connection_info: JsConnectionInfo,
}

#[wasm_bindgen(constructor)]
pub fn new(params: QueryCompilerParams) -> Result<QueryCompiler, JsError> {
    let schema = Arc::new(psl::parse_without_validation(
        datamodel.into(),
        CONNECTOR_REGISTRY,
        &NoExtensionTypes,
    ));
    
    Ok(Self {
        schema,
        connection_info: ConnectionInfo::External(
            connection_info.into_external_connection_info(provider)
        ),
        protocol: EngineProtocol::Json,
    })
}

From query-compiler-wasm/src/compiler.rs

Expression Execution Flow

When the TypeScript interpreter executes a plan:

Relation Join Strategies

Driver adapters support different relation loading strategies:

Query Strategy
Join Strategy

Load relations in separate queries (application-level joins):

PRISMA_RELATION_LOAD_STRATEGY=query make dev-pg-qc

Generates a Join expression in the plan.

Use SQL JOINs when the database supports it:

PRISMA_RELATION_LOAD_STRATEGY=join make dev-pg-qc

Generates SQL with JOIN clauses.

Migration Script Support

Some adapters (like Cloudflare D1) support migration scripts:

export type SetupDriverAdaptersInput = {
  url: string
  
  /**
   * The `prisma migrate diff --script` output to apply migrations.
   * This is a temporary workaround only used by Cloudflare D1.
   */
  migrationScript?: string
}

Benchmarking

Benchmark driver adapter performance:

make bench-pg-js

This:

Sets up a PostgreSQL instance via Docker
Runs JavaScript benchmarks comparing adapter performance

Next Steps

Query Planning

Learn how queries are planned and optimized

WASM Build

Build the WebAssembly module

Overview

Core Components

Query Compiler

Schema Engine

Prisma Schema Language

Development

Overview

Architecture

Driver Adapter Manager

Example: PostgreSQL Adapter

Supported Adapters

PostgreSQL

MySQL

SQLite

SQL Server

Building the Driver Adapters Kit

Testing with Driver Adapters

Connection Info Types

Expression Execution Flow

Relation Join Strategies

Migration Script Support

Benchmarking

Next Steps

Query Planning

WASM Build

​Overview

​Architecture

​Driver Adapter Manager

​Example: PostgreSQL Adapter

​Supported Adapters

PostgreSQL

MySQL

SQLite

SQL Server

​Building the Driver Adapters Kit

​Testing with Driver Adapters

​Connection Info Types

​Expression Execution Flow

​Relation Join Strategies

​Migration Script Support

​Benchmarking

​Next Steps

Query Planning

WASM Build

Overview

Architecture

Driver Adapter Manager

Example: PostgreSQL Adapter

Supported Adapters

Building the Driver Adapters Kit

Testing with Driver Adapters

Connection Info Types

Expression Execution Flow

Relation Join Strategies

Migration Script Support

Benchmarking

Next Steps