feat(sqlite): add SQLite target (milestones 1–3)

[SevInf]

closes TML-2167

Intent

Add SQLite as the second concrete target in Prisma Next, validating the multi-target adapter architecture. Four new packages (driver, adapter, target, extension) follow the Postgres 4-tier pattern. All dialect differences are handled through adapters, capabilities, and codecs — no target-name conditionals anywhere in shared code. This covers milestones 1–3 of the project plan: driver + codecs, AST→SQL lowering, and end-to-end integration through sql-builder-new and ORM.

Change map

• Implementation:
  • packages/3-targets/7-drivers/sqlite/ — node:sqlite driver
  • packages/3-targets/6-adapters/sqlite/ — AST→SQL lowering, codecs
  • packages/3-targets/3-targets/sqlite/ — target descriptor
  • packages/3-extensions/sqlite/ — sqlite() factory + integration tests
  • packages/2-sql/4-lanes/relational-core/src/ast/adapter-types.ts — readMarkerStatement() on AdapterProfile
  • packages/2-sql/5-runtime/src/sql-family-adapter.ts — delegates marker reader to profile
• Tests (evidence):
  • packages/3-targets/7-drivers/sqlite/test/ — 24 driver tests
  • packages/3-targets/6-adapters/sqlite/test/ — 68 adapter/codec tests
  • packages/3-extensions/sqlite/test/integration/ — 31 integration tests (sql-builder + ORM)

The story

1. Driver and codec foundation — A node:sqlite DatabaseSync driver wraps synchronous APIs in the async SqlDriver interface, with foreign keys enabled by default. Eight codecs handle SQLite's type system (TEXT, INTEGER, REAL, BLOB, plus semantic codecs for boolean→0/1, datetime→ISO8601, JSON→TEXT, bigint→INTEGER).

2. AST→SQL lowering — The SQLite adapter lowers the shared AnyQueryAst to valid SQLite SQL: ? positional params instead of $1, CAST() instead of ::type, json_object()/json_group_array() instead of Postgres JSON functions, and ON CONFLICT upsert support. Golden tests lock every AST node type.

3. Target-aware marker reader — The runtime's contract verification previously hardcoded Postgres SQL (prisma_contract.marker with $1). Marker reading is moved to AdapterProfile so each target provides its own SQL. This is the only cross-cutting change to shared framework code.

4. Extension + integration tests — The sqlite() factory composes driver, adapter, and target into a lazy client with sql, schema, orm surfaces. Integration tests exercise the full stack against real :memory: databases, with expectTypeOf assertions proving that codec output types flow correctly through the contract type system.

5. Codec type preservation — Column type descriptors and codec definitions are fixed to preserve literal codecId types through the TypeScript type system, enabling Db<Contract> to resolve row types to concrete JS types (e.g. boolean, Date, JsonValue) rather than unknown.

Behavior changes & evidence

Adds SQLite driver wrapping node:sqlite DatabaseSync

Provides connect(), execute() (async iterable), query(), close(), transaction support, and PRAGMA foreign_keys = ON on connect.

• Implementation:
  • packages/3-targets/7-drivers/sqlite/src/sqlite-driver.ts
  • packages/3-targets/7-drivers/sqlite/src/exports/runtime.ts
  • packages/3-targets/7-drivers/sqlite/src/normalize-error.ts
• Tests:
  • packages/3-targets/7-drivers/sqlite/test/sqlite-driver.test.ts — 13 tests
  • packages/3-targets/7-drivers/sqlite/test/runtime-driver.test.ts — 7 tests
  • packages/3-targets/7-drivers/sqlite/test/control-driver.test.ts — 4 tests

Adds SQLite adapter that lowers AnyQueryAst to SQLite SQL

SELECT, INSERT (with ON CONFLICT), UPDATE, DELETE, RETURNING, JOINs, subqueries, JSON aggregation, parameterized queries with ? placeholders, CAST() syntax.

• Implementation:
  • packages/3-targets/6-adapters/sqlite/src/core/adapter.ts — 546 lines, full lowering
  • packages/3-targets/6-adapters/sqlite/src/core/codecs.ts — 8 codecs with traits
  • packages/3-targets/6-adapters/sqlite/src/core/sql-utils.ts — identifier quoting
• Tests:
  • packages/3-targets/6-adapters/sqlite/test/adapter.test.ts — 34 golden SQL tests
  • packages/3-targets/6-adapters/sqlite/test/codecs.test.ts — 34 codec round-trip tests

Moves marker reader from hardcoded Postgres SQL to AdapterProfile

Before: SqlFamilyAdapter hardcoded readContractMarker() which produced SELECT ... FROM prisma_contract.marker WHERE id = $1. This failed on SQLite (no schema support, wrong placeholder syntax).

After: AdapterProfile.readMarkerStatement() lets each adapter provide target-specific marker SQL. SqlFamilyAdapter delegates to the adapter profile. Postgres uses prisma_contract.marker with $1; SQLite uses prisma_contract_marker with ?.

• Implementation:
  • packages/2-sql/4-lanes/relational-core/src/ast/adapter-types.ts — MarkerStatement interface + readMarkerStatement() on AdapterProfile
  • packages/2-sql/5-runtime/src/sql-family-adapter.ts — delegates to profile
  • packages/2-sql/5-runtime/src/sql-runtime.ts — passes adapter.profile
  • packages/3-targets/6-adapters/postgres/src/core/adapter.ts — Postgres marker SQL
  • packages/3-targets/6-adapters/sqlite/src/core/adapter.ts — SQLite marker SQL
• Tests:
  • packages/2-sql/5-runtime/test/sql-family-adapter.test.ts — delegation test

Adds sqlite() factory with lazy client composition

Mirrors postgres(): accepts contract/contractJson + path, creates execution stack, returns SqliteClient with sql, schema, orm, context, connect(), runtime().

• Implementation:
  • packages/3-extensions/sqlite/src/runtime/sqlite.ts — 237 lines
  • packages/3-extensions/sqlite/src/runtime/binding.ts — binding resolution
• Tests:
  • packages/3-extensions/sqlite/test/integration/sql-builder.test.ts — 14 tests (SELECT, INSERT, UPDATE, DELETE with RETURNING, codec round-trips, capability gating)
  • packages/3-extensions/sqlite/test/integration/orm.test.ts — 17 tests (findMany, findFirst, create, createAll, update, updateAll, delete, deleteAll, includeMany, upsert, typed rows)

Fixes codec type preservation so Db<Contract> resolves row types

Two root causes made all sql-builder row fields resolve to unknown:

1. Column type descriptors (e.g. integerColumn) had explicit : ColumnTypeDescriptor annotation, widening codecId from literal 'sqlite/integer@1' to string.
2. Codec definitions used incorrect explicit generic params (codec<Id, number, number> where number mapped to TTraits not TWire), breaking type inference.

Both are fixed by removing explicit annotations and letting TypeScript infer literals from as const and typed encode/decode signatures.

• Implementation:
  • packages/3-targets/6-adapters/sqlite/src/exports/column-types.ts — removed : ColumnTypeDescriptor annotations
  • packages/3-targets/6-adapters/sqlite/src/core/codecs.ts — removed explicit generic params, added typed encode/decode
• Tests:
  • packages/3-extensions/sqlite/test/integration/sql-builder.test.ts — expectTypeOf assertions verify { id: number; name: string }, { active: boolean }, { created_at: Date }, { metadata: JsonValue | null }
  • packages/3-extensions/sqlite/test/integration/orm.test.ts — expectTypeOf assertions on ORM row types

Capability gating verified at type level and runtime

lateralJoin and distinctOn are unavailable for SQLite contracts — verified by @ts-expect-error (type gate) and expect(...).toThrow() (runtime gate with specific error message).

• Tests:
  • packages/3-extensions/sqlite/test/integration/sql-builder.test.ts — "capability gating" describe block

Compatibility / migration / risk

• AdapterProfile breaking change: All AdapterProfile implementations must now provide readMarkerStatement(). Updated for Postgres adapter and all test stubs.
• Codec type narrowing: Removing : ColumnTypeDescriptor from column type exports narrows the inferred type. This is a type-level improvement (more precise), not a runtime change.

Follow-ups / open questions

• ORM codec decoding: The ORM does not populate projectionTypes on its query plans, so codec decoding (e.g. INTEGER 0/1 → boolean) does not apply to ORM read results. Pre-existing cross-target limitation.
• ORM selectIncludeStrategy bug: Reads capabilities['lateral'] at top level but capabilities are nested under sql.*. Lateral/correlated strategies unreachable for any target. Pre-existing.
• ilike not feature-gated: The ORM exposes ilike() on text fields for SQLite, but the adapter silently maps it to LIKE. Should be properly gated in a follow-up.
• Milestone 4 (contract authoring, migrations, introspection) and Milestone 5 (E2E) not yet started.

Non-goals / intentionally out of scope

• sql-lane (legacy) and kysely-lane SQLite support
• SQLite migration planner/runner (Milestone 4)
• FTS5, WAL mode, ATTACH DATABASE support

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: 5c305e3a-013f-4778-a479-7abaee72a52b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch worktree/sqlite

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}