@prisma-next/driver-sqlite 0.0.1

package/README.md

@@ -0,0 +1,121 @@
+# @prisma-next/driver-sqlite
+
+SQLite driver for Prisma Next.
+
+## Package Classification
+
+- **Domain**: targets
+- **Layer**: drivers
+- **Plane**: multi-plane (migration, runtime)
+
+## Overview
+
+The SQLite driver provides transport and connection management for SQLite databases using Node.js built-in `node:sqlite` module (`DatabaseSync`). It implements the `SqlDriver` interface for executing SQL statements, explaining queries, and managing connections.
+
+In Prisma Next, "driver" refers to the Prisma Next interface (not the underlying `node:sqlite` API). Drivers own connection management and transport, but contain no dialect-specific logic. All dialect behavior lives in adapters. Instantiation is separate from connection; `create()` returns an unbound driver, `connect(binding)` binds at the boundary ([ADR 159](../../../../docs/architecture%20docs/adrs/ADR%20159%20-%20Driver%20Terminology%20and%20Lifecycle.md)).
+
+This package spans multiple planes:
+- **Migration plane** (`src/exports/control.ts`): Control plane entry point for driver descriptors
+- **Runtime plane** (`src/exports/runtime.ts`): Runtime entry point for driver implementation
+
+## Purpose
+
+Provide SQLite transport and connection management. Execute SQL statements and manage connections without dialect-specific logic.
+
+## Responsibilities
+
+- **Connection Management**: Acquire and release database connections via `node:sqlite` `DatabaseSync`
+- **Statement Execution**: Execute SQL statements with positional `?` parameters
+- **Query Explanation**: Execute `EXPLAIN QUERY PLAN` queries for query analysis
+- **Persistent Connection**: Top-level `execute()`/`query()`/`explain()` reuse a persistent connection opened at `connect()` time
+- **Scoped Connections**: `acquireConnection()` opens fresh `DatabaseSync` handles for isolated scopes (transactions)
+- **Transaction Support**: `BEGIN`/`COMMIT`/`ROLLBACK` via `SqliteTransactionImpl`
+- **PRAGMA Configuration**: Enables `PRAGMA foreign_keys = ON` and `PRAGMA busy_timeout = 5000` on every opened connection
+- **Error Normalization**: Maps SQLite extended error codes to SQL state codes (23505 unique, 23503 FK, 23502 NOT NULL) and distinguishes transient (BUSY/LOCKED) from permanent errors
+
+**Non-goals:**
+- Dialect-specific SQL lowering (adapters)
+- Query compilation (sql-query)
+- Runtime execution orchestration (sql-runtime)
+
+## Architecture
+
+```mermaid
+flowchart TD
+    subgraph "Runtime"
+        RT[Runtime]
+        ADAPTER[Adapter]
+    end
+
+    subgraph "SQLite Driver"
+        DRIVER[Driver]
+        CONN[Persistent Connection]
+        SCOPED[Scoped Connection]
+    end
+
+    subgraph "SQLite"
+        DB[(SQLite File / :memory:)]
+    end
+
+    RT --> ADAPTER
+    ADAPTER --> DRIVER
+    DRIVER --> CONN
+    DRIVER --> SCOPED
+    CONN --> DB
+    SCOPED --> DB
+    DB --> DRIVER
+    DRIVER --> RT
+```
+
+## Components
+
+### Driver (`sqlite-driver.ts`)
+- `SqliteBoundDriver`: main driver implementation wrapping `DatabaseSync`
+- `SqliteConnectionImpl`: connection wrapper with `execute()`, `query()`, `explain()`, `beginTransaction()`
+- `SqliteTransactionImpl`: transaction wrapper adding `commit()` and `rollback()`
+- `createBoundDriverFromBinding()`: factory that creates and immediately connects a driver
+
+### Error Normalization (`normalize-error.ts`)
+- Maps SQLite extended `errcode` to structured `SqlQueryError` / `SqlConnectionError`
+- Handles constraint types individually (UNIQUE, FK, NOT NULL, CHECK)
+
+## Dependencies
+
+- **`@prisma-next/sql-relational-core`**: SQL contract types (`SqlDriver`, `SqlConnection`, `SqlTransaction`)
+- **`@prisma-next/framework-components`**: Descriptor types (`RuntimeDriverDescriptor`, `ControlDriverDescriptor`)
+- **`@prisma-next/errors`**: Structured error factories
+
+## Related Subsystems
+
+- **[Adapters & Targets](../../../../docs/architecture%20docs/subsystems/5.%20Adapters%20&%20Targets.md)**: Driver specification
+
+## Related ADRs
+
+- [ADR 159 -- Driver Terminology and Lifecycle](../../../../docs/architecture%20docs/adrs/ADR%20159%20-%20Driver%20Terminology%20and%20Lifecycle.md)
+- [ADR 005 -- Thin Core Fat Targets](../../../../docs/architecture%20docs/adrs/ADR%20005%20-%20Thin%20Core%20Fat%20Targets.md)
+- [ADR 016 -- Adapter SPI for Lowering](../../../../docs/architecture%20docs/adrs/ADR%20016%20-%20Adapter%20SPI%20for%20Lowering.md)
+
+## Usage
+
+Use the descriptor + connect lifecycle:
+
+```typescript
+import sqliteDriver from '@prisma-next/driver-sqlite/runtime';
+
+const driver = sqliteDriver.create();
+await driver.connect({ kind: 'path', path: ':memory:' });
+// driver is now bound; use acquireConnection, query, execute, etc.
+```
+
+Binding:
+- `{ kind: 'path', path: ':memory:' }`: In-memory database
+- `{ kind: 'path', path: './data.db' }`: File-based database
+
+## Exports
+
+- `./runtime`: Runtime entry point for driver implementation
+  - Default: `sqliteRuntimeDriverDescriptor` -- use `create()` for unbound driver, then `connect(binding)`
+  - Types: `SqliteBinding`, `SqliteRuntimeDriver`
+- `./control`: Control plane entry point for driver descriptors
+  - Default: `ControlDriverDescriptor` for use in CLI config
+  - `SqliteControlDriver` class for direct control-plane usage

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@prisma-next/driver-sqlite",
+  "version": "0.0.1",
+  "type": "module",
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --project tsconfig.json --noEmit",
+    "lint": "biome check . --error-on-warnings",
+    "lint:fix": "biome check --write .",
+    "lint:fix:unsafe": "biome check --write --unsafe .",
+    "clean": "rm -rf dist dist-tsc dist-tsc-prod coverage .tmp-output"
+  },
+  "dependencies": {
+    "@prisma-next/contract": "workspace:*",
+    "@prisma-next/errors": "workspace:*",
+    "@prisma-next/framework-components": "workspace:*",
+    "@prisma-next/sql-contract": "workspace:*",
+    "@prisma-next/sql-errors": "workspace:*",
+    "@prisma-next/sql-operations": "workspace:*",
+    "@prisma-next/sql-relational-core": "workspace:*",
+    "@prisma-next/utils": "workspace:*"
+  },
+  "devDependencies": {
+    "@prisma-next/test-utils": "workspace:*",
+    "@prisma-next/tsconfig": "workspace:*",
+    "@prisma-next/tsdown": "workspace:*",
+    "tsdown": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    "./control": "./dist/control.mjs",
+    "./runtime": "./dist/runtime.mjs",
+    "./package.json": "./package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/prisma/prisma-next.git",
+    "directory": "packages/3-targets/7-drivers/sqlite"
+  }
+}

package/src/core/control-driver.ts

@@ -0,0 +1,54 @@
+import type { SQLInputValue } from 'node:sqlite';
+import { DatabaseSync } from 'node:sqlite';
+import { errorRuntime } from '@prisma-next/errors/execution';
+import type {
+  ControlDriverDescriptor,
+  ControlDriverInstance,
+} from '@prisma-next/framework-components/control';
+import { normalizeSqliteError } from '../normalize-error';
+import { sqliteDriverDescriptorMeta } from './descriptor-meta';
+
+export class SqliteControlDriver implements ControlDriverInstance<'sql', 'sqlite'> {
+  readonly familyId = 'sql' as const;
+  readonly targetId = 'sqlite' as const;
+
+  constructor(private readonly db: DatabaseSync) {}
+
+  async query<Row = Record<string, unknown>>(
+    sql: string,
+    params?: readonly unknown[],
+  ): Promise<{ readonly rows: Row[] }> {
+    try {
+      const stmt = this.db.prepare(sql);
+      const rows = stmt.all(...((params ?? []) as SQLInputValue[])) as Row[];
+      return { rows };
+    } catch (error) {
+      throw normalizeSqliteError(error);
+    }
+  }
+
+  async close(): Promise<void> {
+    this.db.close();
+  }
+}
+
+const sqliteDriverDescriptor: ControlDriverDescriptor<'sql', 'sqlite', SqliteControlDriver> = {
+  ...sqliteDriverDescriptorMeta,
+  async create(pathOrMemory: string): Promise<SqliteControlDriver> {
+    try {
+      const db = new DatabaseSync(pathOrMemory);
+      db.exec('PRAGMA foreign_keys = ON');
+      return new SqliteControlDriver(db);
+    } catch (error) {
+      throw errorRuntime('Database connection failed', {
+        why: error instanceof Error ? error.message : String(error),
+        fix: 'Verify the database file path exists and is accessible',
+        meta: {
+          path: pathOrMemory,
+        },
+      });
+    }
+  },
+};
+
+export default sqliteDriverDescriptor;

package/src/core/descriptor-meta.ts

@@ -0,0 +1,8 @@
+export const sqliteDriverDescriptorMeta = {
+  kind: 'driver',
+  familyId: 'sql',
+  targetId: 'sqlite',
+  id: 'sqlite',
+  version: '0.0.1',
+  capabilities: {},
+} as const;

package/src/core/runtime-driver.ts

@@ -0,0 +1,19 @@
+import type { RuntimeDriverDescriptor } from '@prisma-next/framework-components/execution';
+import { SqliteDriver, type SqliteRuntimeDriver } from '../sqlite-driver';
+import { sqliteDriverDescriptorMeta } from './descriptor-meta';
+
+export type { SqliteRuntimeDriver } from '../sqlite-driver';
+
+const sqliteRuntimeDriverDescriptor: RuntimeDriverDescriptor<
+  'sql',
+  'sqlite',
+  void,
+  SqliteRuntimeDriver
+> = {
+  ...sqliteDriverDescriptorMeta,
+  create(): SqliteRuntimeDriver {
+    return new SqliteDriver();
+  },
+};
+
+export default sqliteRuntimeDriverDescriptor;

package/src/exports/control.ts

@@ -0,0 +1 @@
+export { default, SqliteControlDriver } from '../core/control-driver';

package/src/exports/runtime.ts

@@ -0,0 +1,3 @@
+export type { SqliteRuntimeDriver } from '../core/runtime-driver';
+export { default } from '../core/runtime-driver';
+export type { SqliteBinding } from '../sqlite-driver';

package/src/normalize-error.ts

@@ -0,0 +1,105 @@
+import { SqlConnectionError, SqlQueryError } from '@prisma-next/sql-errors';
+
+interface SqliteError extends Error {
+  readonly code?: string;
+  readonly errcode?: number;
+  readonly errstr?: string;
+}
+
+// SQLite extended error code ranges (base code * 256 + extended)
+// Base code 19 = SQLITE_CONSTRAINT
+const SQLITE_CONSTRAINT_BASE = 19;
+const SQLITE_CONSTRAINT_UNIQUE = 2067; // 19 + 8*256
+const SQLITE_CONSTRAINT_PRIMARYKEY = 1555; // 19 + 6*256
+const SQLITE_CONSTRAINT_FOREIGNKEY = 787; // 19 + 3*256
+const SQLITE_CONSTRAINT_NOTNULL = 1299; // 19 + 5*256
+const SQLITE_CONSTRAINT_CHECK = 275; // 19 + 1*256
+
+// Base code 5 = SQLITE_BUSY
+const SQLITE_BUSY = 5;
+// Base code 6 = SQLITE_LOCKED
+const SQLITE_LOCKED = 6;
+
+function isConstraintError(errcode: number): boolean {
+  return (errcode & 0xff) === SQLITE_CONSTRAINT_BASE;
+}
+
+function isBusyOrLocked(errcode: number): boolean {
+  const base = errcode & 0xff;
+  return base === SQLITE_BUSY || base === SQLITE_LOCKED;
+}
+
+export function isSqliteError(error: unknown): error is SqliteError {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  return (error as SqliteError).code === 'ERR_SQLITE_ERROR';
+}
+
+function constraintNameFromMessage(message: string): string | undefined {
+  // SQLite constraint messages follow patterns like:
+  // "UNIQUE constraint failed: table.column"
+  // "FOREIGN KEY constraint failed"
+  // "NOT NULL constraint failed: table.column"
+  const match = /constraint failed: (.+)/.exec(message);
+  return match?.[1];
+}
+
+function mapErrCodeToSqlState(errcode: number): string {
+  switch (errcode) {
+    case SQLITE_CONSTRAINT_UNIQUE:
+    case SQLITE_CONSTRAINT_PRIMARYKEY:
+      return '23505'; // unique_violation
+    case SQLITE_CONSTRAINT_FOREIGNKEY:
+      return '23503'; // foreign_key_violation
+    case SQLITE_CONSTRAINT_NOTNULL:
+      return '23502'; // not_null_violation
+    case SQLITE_CONSTRAINT_CHECK:
+      return '23514'; // check_violation
+    default:
+      if (isConstraintError(errcode)) {
+        return '23000'; // integrity_constraint_violation
+      }
+      return 'HY000'; // general error
+  }
+}
+
+export function normalizeSqliteError(error: unknown): SqlQueryError | SqlConnectionError | Error {
+  if (!(error instanceof Error)) {
+    return new Error(String(error));
+  }
+
+  if (isSqliteError(error)) {
+    const sqliteErr = error as SqliteError;
+    const errcode = sqliteErr.errcode ?? 0;
+
+    if (isBusyOrLocked(errcode)) {
+      return new SqlConnectionError(error.message, {
+        cause: error,
+        transient: true,
+      });
+    }
+
+    const sqlState = mapErrCodeToSqlState(errcode);
+    const constraint = constraintNameFromMessage(error.message);
+
+    return new SqlQueryError(error.message, {
+      cause: error,
+      sqlState,
+      ...(constraint !== undefined ? { constraint } : {}),
+    });
+  }
+
+  // Connection-related Node.js errors
+  if (
+    error.message.includes('database is locked') ||
+    error.message.includes('unable to open database')
+  ) {
+    return new SqlConnectionError(error.message, {
+      cause: error,
+      transient: false,
+    });
+  }
+
+  return error;
+}

package/src/sqlite-driver.ts

@@ -0,0 +1,276 @@
+import type { SQLInputValue } from 'node:sqlite';
+import { DatabaseSync } from 'node:sqlite';
+import type { RuntimeDriverInstance } from '@prisma-next/framework-components/execution';
+import type {
+  SqlConnection,
+  SqlDriver,
+  SqlDriverState,
+  SqlExecuteRequest,
+  SqlExplainResult,
+  SqlQueryResult,
+  SqlTransaction,
+} from '@prisma-next/sql-relational-core/ast';
+import { normalizeSqliteError } from './normalize-error';
+
+export type SqliteBinding = { readonly kind: 'path'; readonly path: string };
+
+export type SqliteRuntimeDriver = RuntimeDriverInstance<'sql', 'sqlite'> & SqlDriver<SqliteBinding>;
+
+interface DriverRuntimeError extends Error {
+  readonly code:
+    | 'DRIVER.NOT_CONNECTED'
+    | 'DRIVER.ALREADY_CONNECTED'
+    | 'DRIVER.EXPLAIN_NOT_SUPPORTED';
+  readonly category: 'RUNTIME';
+  readonly severity: 'error';
+  readonly details?: Record<string, unknown>;
+}
+
+function driverError(
+  code: DriverRuntimeError['code'],
+  message: string,
+  details?: Record<string, unknown>,
+): DriverRuntimeError {
+  const error = new Error(message) as DriverRuntimeError;
+  Object.defineProperty(error, 'name', {
+    value: 'RuntimeError',
+    configurable: true,
+  });
+  return Object.assign(error, {
+    code,
+    category: 'RUNTIME' as const,
+    severity: 'error' as const,
+    message,
+    details,
+  });
+}
+
+const NOT_CONNECTED_MESSAGE =
+  'SQLite driver not connected. Call connect(binding) before acquireConnection or execute.';
+const ALREADY_CONNECTED_MESSAGE =
+  'SQLite driver already connected. Call close() before reconnecting with a new binding.';
+
+function toSqliteParams(params: readonly unknown[] | undefined): SQLInputValue[] {
+  return (params ?? []) as SQLInputValue[];
+}
+
+function openConnection(path: string): DatabaseSync {
+  try {
+    const db = new DatabaseSync(path);
+    db.exec('PRAGMA foreign_keys = ON');
+    db.exec('PRAGMA busy_timeout = 5000');
+    return db;
+  } catch (error) {
+    throw normalizeSqliteError(error);
+  }
+}
+
+class SqliteConnectionImpl implements SqlConnection {
+  readonly #db: DatabaseSync;
+
+  constructor(db: DatabaseSync) {
+    this.#db = db;
+  }
+
+  async *execute<Row = Record<string, unknown>>(request: SqlExecuteRequest): AsyncIterable<Row> {
+    try {
+      const stmt = this.#db.prepare(request.sql);
+      for (const row of stmt.iterate(...toSqliteParams(request.params))) {
+        yield row as Row;
+      }
+    } catch (error) {
+      throw normalizeSqliteError(error);
+    }
+  }
+
+  async explain(request: SqlExecuteRequest): Promise<SqlExplainResult> {
+    try {
+      const stmt = this.#db.prepare(`EXPLAIN QUERY PLAN ${request.sql}`);
+      const rows = stmt.all(...toSqliteParams(request.params)) as ReadonlyArray<
+        Record<string, unknown>
+      >;
+      return { rows };
+    } catch (error) {
+      throw normalizeSqliteError(error);
+    }
+  }
+
+  async query<Row = Record<string, unknown>>(
+    sql: string,
+    params?: readonly unknown[],
+  ): Promise<SqlQueryResult<Row>> {
+    try {
+      const stmt = this.#db.prepare(sql);
+      const rows = stmt.all(...toSqliteParams(params)) as Row[];
+      return { rows };
+    } catch (error) {
+      throw normalizeSqliteError(error);
+    }
+  }
+
+  async beginTransaction(): Promise<SqlTransaction> {
+    try {
+      this.#db.exec('BEGIN');
+      return new SqliteTransactionImpl(this.#db);
+    } catch (error) {
+      throw normalizeSqliteError(error);
+    }
+  }
+
+  async release(): Promise<void> {
+    try {
+      this.#db.close();
+    } catch (error) {
+      throw normalizeSqliteError(error);
+    }
+  }
+}
+
+class SqliteTransactionImpl implements SqlTransaction {
+  readonly #db: DatabaseSync;
+
+  constructor(db: DatabaseSync) {
+    this.#db = db;
+  }
+
+  async *execute<Row = Record<string, unknown>>(request: SqlExecuteRequest): AsyncIterable<Row> {
+    try {
+      const stmt = this.#db.prepare(request.sql);
+      for (const row of stmt.iterate(...toSqliteParams(request.params))) {
+        yield row as Row;
+      }
+    } catch (error) {
+      throw normalizeSqliteError(error);
+    }
+  }
+
+  async explain(request: SqlExecuteRequest): Promise<SqlExplainResult> {
+    try {
+      const stmt = this.#db.prepare(`EXPLAIN QUERY PLAN ${request.sql}`);
+      const rows = stmt.all(...toSqliteParams(request.params)) as ReadonlyArray<
+        Record<string, unknown>
+      >;
+      return { rows };
+    } catch (error) {
+      throw normalizeSqliteError(error);
+    }
+  }
+
+  async query<Row = Record<string, unknown>>(
+    sql: string,
+    params?: readonly unknown[],
+  ): Promise<SqlQueryResult<Row>> {
+    try {
+      const stmt = this.#db.prepare(sql);
+      const rows = stmt.all(...toSqliteParams(params)) as Row[];
+      return { rows };
+    } catch (error) {
+      throw normalizeSqliteError(error);
+    }
+  }
+
+  async commit(): Promise<void> {
+    try {
+      this.#db.exec('COMMIT');
+    } catch (error) {
+      throw normalizeSqliteError(error);
+    }
+  }
+
+  async rollback(): Promise<void> {
+    try {
+      this.#db.exec('ROLLBACK');
+    } catch (error) {
+      throw normalizeSqliteError(error);
+    }
+  }
+}
+
+interface ConnectedState {
+  readonly kind: 'connected';
+  readonly path: string;
+  readonly conn: SqliteConnectionImpl;
+}
+
+type DriverState = { readonly kind: 'unbound' } | ConnectedState | { readonly kind: 'closed' };
+
+export class SqliteDriver implements SqliteRuntimeDriver {
+  readonly familyId = 'sql' as const;
+  readonly targetId = 'sqlite' as const;
+
+  #state: DriverState;
+
+  constructor(initialState?: ConnectedState) {
+    this.#state = initialState ?? { kind: 'unbound' };
+  }
+
+  #requireConnected(): ConnectedState {
+    if (this.#state.kind !== 'connected') {
+      throw driverError('DRIVER.NOT_CONNECTED', NOT_CONNECTED_MESSAGE);
+    }
+    return this.#state;
+  }
+
+  get state(): SqlDriverState {
+    return this.#state.kind;
+  }
+
+  async connect(binding: SqliteBinding): Promise<void> {
+    if (this.#state.kind === 'connected') {
+      throw driverError('DRIVER.ALREADY_CONNECTED', ALREADY_CONNECTED_MESSAGE, {
+        bindingKind: binding.kind,
+      });
+    }
+    this.#state = {
+      kind: 'connected',
+      path: binding.path,
+      conn: new SqliteConnectionImpl(openConnection(binding.path)),
+    };
+  }
+
+  async acquireConnection(): Promise<SqliteConnectionImpl> {
+    const { path } = this.#requireConnected();
+    return new SqliteConnectionImpl(openConnection(path));
+  }
+
+  async close(): Promise<void> {
+    if (this.#state.kind !== 'connected') return;
+    const { conn } = this.#state;
+    this.#state = { kind: 'closed' };
+    await conn.release();
+  }
+
+  execute<Row = Record<string, unknown>>(request: SqlExecuteRequest): AsyncIterable<Row> {
+    if (this.#state.kind !== 'connected') {
+      return {
+        [Symbol.asyncIterator]() {
+          return {
+            async next() {
+              throw driverError('DRIVER.NOT_CONNECTED', NOT_CONNECTED_MESSAGE);
+            },
+          };
+        },
+      };
+    }
+    return this.#state.conn.execute<Row>(request);
+  }
+
+  async explain(request: SqlExecuteRequest): Promise<SqlExplainResult> {
+    return this.#requireConnected().conn.explain(request);
+  }
+
+  async query<Row = Record<string, unknown>>(
+    sql: string,
+    params?: readonly unknown[],
+  ): Promise<SqlQueryResult<Row>> {
+    return this.#requireConnected().conn.query<Row>(sql, params);
+  }
+}
+
+export function createBoundDriverFromBinding(binding: SqliteBinding): SqliteDriver {
+  return new SqliteDriver({
+    kind: 'connected',
+    path: binding.path,
+    conn: new SqliteConnectionImpl(openConnection(binding.path)),
+  });
+}