@weft-js/db 0.0.0-stage → 0.1.0

package/src/kysely.ts

@@ -0,0 +1,86 @@
+// A list source over Kysely. The types say nothing here: `table` and `columns` are strings, so Kysely's `dynamic`-free
+// builder gets them from the spec, never from a request.
+
+import type { ExpressionBuilder, Kysely, SelectQueryBuilder } from 'kysely'
+import { likeOf, pageOf, plan, rowOf, storedId, written, type DbAdapter, type ListParams, type ListSource, type SourceSpec } from '@weft-js/start/list'
+import { StartError } from '@weft-js/start/data'
+import { driver } from './driver'
+
+const { sql } = await driver('@weft-js/db/kysely', 'kysely', () => import('kysely'))
+
+/** A source's allowlist, its table, and whether the engine can `returning`. */
+export interface KyselySpec extends SourceSpec {
+  table: string
+  /** MySQL has no `returning`. Default true. */
+  returning?: boolean
+}
+
+type Tables = Record<string, Record<string, unknown>>
+type Eb = ExpressionBuilder<Tables, string>
+
+/** A `ListSource` over one table of any `Kysely<DB>`. */
+export function kyselySource<Row = Record<string, unknown>, DB = unknown>(handle: Kysely<DB>, spec: KyselySpec): ListSource<Row> {
+  const db = handle as unknown as Kysely<Tables>
+  const { table, returning = true } = spec
+  const columns = Object.values(spec.columns)
+  const reading = rowOf<Row>(spec)
+  const idColumn = storedId(spec)
+  const byId = async (id: unknown) => {
+    const r = await db.selectFrom(table).select(columns).where(idColumn, '=', id).executeTakeFirst()
+    return r ? reading(r) : null
+  }
+  return {
+    async list(p: ListParams) {
+      const q = plan(spec, p)
+      const filtered = <O>(from: SelectQueryBuilder<Tables, string, O>) => {
+        let b = from
+        for (const w of q.where) {
+          const some = w.values.filter(v => v !== null)
+          b = b.where((eb: Eb) => eb.or([...(some.length ? [eb(w.column, 'in', some)] : []), ...(w.values.includes(null) ? [eb(w.column, 'is', null)] : [])]))
+        }
+        if (q.search) {
+          const like = likeOf(q.search.text)
+          b = b.where((eb: Eb) => eb.or(q.search!.columns.map(c => sql<boolean>`lower(${sql.ref(c)}) like ${like} escape '!'`)))
+        }
+        return b
+      }
+      let b = filtered(db.selectFrom(table).select(columns))
+      const dir = q.sort?.dir === 'desc' ? 'desc' : 'asc', cmp = dir === 'desc' ? '<' : '>'
+      if (p.after) {
+        const [value, id] = p.after
+        b = b.where((eb: Eb) => (q.sort ? eb.or([eb(q.sort.column, cmp, value), eb.and([eb(q.sort.column, '=', value), eb(idColumn, cmp, id)])]) : eb(idColumn, '>', id)))
+      }
+      b = q.sort ? b.orderBy(q.sort.column, dir).orderBy(idColumn, dir) : b.orderBy(idColumn, 'asc')
+      const cursor = p.mode === 'cursor'
+      const rows = (await b.limit(cursor ? p.limit + 1 : p.limit).offset(p.offset).execute()).map(reading)
+      const total = cursor ? undefined : Number((await filtered(db.selectFrom(table).select(sql<unknown>`count(*)`.as('n'))).executeTakeFirstOrThrow()).n)
+      return pageOf(rows, p, { sort: q.sort?.field, id: q.id.field }, total)
+    },
+    get: byId,
+    async create(data) {
+      const row = written(spec, data, true)
+      const id = row[idColumn]
+      if (returning) return reading(await db.insertInto(table).values(row).returning(columns).executeTakeFirstOrThrow())
+      if (id === undefined) throw new StartError('Q002', '`create` needs the id: MySQL can\'t return a row', 'generate it before the insert')
+      await db.insertInto(table).values(row).execute()
+      return (await byId(id))!
+    },
+    async update(id, patch) {
+      const row = written(spec, patch)
+      if (!Object.keys(row).length) return byId(id)
+      if (returning) {
+        const r = await db.updateTable(table).set(row).where(idColumn, '=', id).returning(columns).executeTakeFirst()
+        return r ? reading(r) : null
+      }
+      if (!(await byId(id))) return null
+      await db.updateTable(table).set(row).where(idColumn, '=', id).execute()
+      return byId(id)
+    },
+    async remove(id) {
+      return (await db.deleteFrom(table).where(idColumn, '=', id).executeTakeFirst()).numDeletedRows > 0n
+    },
+  }
+}
+
+/** `db.adapter@1` over a table of a Kysely instance. */
+export const adapter: DbAdapter<Kysely<unknown>> = { name: 'kysely', source: (t, spec) => kyselySource(t, spec as KyselySpec) }

package/src/mongo.ts

@@ -0,0 +1,182 @@
+// A list source over a MongoDB collection, and writes from anywhere as tag pokes. Every filter is `$eq`/`$in` on a
+// checked scalar and a search is an escaped `$regex`, so a request has no way to name an operator. Takes
+// whatever has the driver's collection methods, so `mongodb` is the app's dependency.
+
+import { pageOf, plan, rowOf, storedId, written, type DbAdapter, type ListParams, type ListSource, type SourceSpec } from '@weft-js/start/list'
+import { hub } from '@weft-js/start/hub'
+import type { Source } from '@weft-js/start/changes'
+
+/** What a change stream hands over, as far as anything here reads it. */
+export interface MongoEvent extends MongoChange { ns?: { coll?: string }; fullDocument?: { tags?: string[] } }
+
+/** The driver's change stream. */
+export type MongoStream = AsyncIterable<MongoEvent> & { close?(): Promise<unknown> }
+
+/** The methods of the driver's `Collection` a source calls. */
+export interface MongoCollection {
+  collectionName?: string
+  find(filter: object, options?: object): { toArray(): Promise<object[]> }
+  countDocuments(filter: object): Promise<number>
+  findOne(filter: object, options?: object): Promise<object | null>
+  insertOne(doc: object): Promise<unknown>
+  findOneAndUpdate(filter: object, update: object, options: object): Promise<object | null>
+  deleteOne(filter: object): Promise<{ deletedCount?: number }>
+  watch(pipeline?: object[], options?: object): MongoStream
+}
+
+const regex = (text: string) => ({ $regex: text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), $options: 'i' })
+
+/** A `ListSource` over one collection. */
+export function mongoSource<Row = Record<string, unknown>>(collection: MongoCollection, spec: SourceSpec): ListSource<Row> {
+  const stored = Object.values(spec.columns)
+  const idColumn = storedId(spec)
+  const projection = Object.fromEntries([...stored.map(c => [c, 1]), ...(stored.includes('_id') ? [] : [['_id', 0]])])
+  const reading = rowOf<Row>(spec)
+  return {
+    async list(p: ListParams) {
+      const q = plan(spec, p)
+      const and: object[] = q.where.map(w => ({ [w.column]: w.values.length === 1 ? { $eq: w.values[0] } : { $in: w.values } }))
+      if (q.search) and.push({ $or: q.search.columns.map(c => ({ [c]: regex(q.search!.text) })) })
+      const filter = and.length ? { $and: and } : {}
+      const dir = q.sort?.dir === 'desc' ? -1 : 1, cmp = dir < 0 ? '$lt' : '$gt'
+      const keyset = p.after && (q.sort
+        ? { $or: [{ [q.sort.column]: { [cmp]: p.after[0] } }, { [q.sort.column]: { $eq: p.after[0] }, [idColumn]: { [cmp]: p.after[1] } }] }
+        : { [idColumn]: { $gt: p.after[1] } })
+      const sort = q.sort ? { [q.sort.column]: dir, [idColumn]: dir } : { [idColumn]: 1 }
+      const cursor = p.mode === 'cursor'
+      const rows = (await collection.find(keyset ? { $and: [...and, keyset] } : filter, { projection, sort, skip: p.offset, limit: cursor ? p.limit + 1 : p.limit }).toArray()).map(reading)
+      return pageOf(rows, p, { sort: q.sort?.field, id: q.id.field }, cursor ? undefined : await collection.countDocuments(filter))
+    },
+    get: async id => { const r = await collection.findOne({ [idColumn]: { $eq: id } }, { projection }); return r ? reading(r) : null },
+    async create(data) {
+      const doc = written(spec, data, true)
+      await collection.insertOne({ ...doc })
+      return reading(doc)
+    },
+    async update(id, patch) {
+      const r = await collection.findOneAndUpdate({ [idColumn]: { $eq: id } }, { $set: written(spec, patch) }, { projection, returnDocument: 'after' })
+      return r ? reading(r) : null
+    },
+    remove: async id => ((await collection.deleteOne({ [idColumn]: { $eq: id } })).deletedCount ?? 0) > 0,
+  }
+}
+
+/** `db.adapter@1` over a Mongo collection. */
+export const adapter: DbAdapter<MongoCollection> = { name: 'mongo', source: (t, spec) => mongoSource(t, spec) }
+
+/** The methods of the driver's `Db` the change feed calls. */
+export interface MongoDb {
+  command(doc: object): Promise<{ setName?: string; msg?: string }>
+  watch(pipeline?: object[], options?: object): MongoStream
+  collection(name: string): { insertOne(doc: object): Promise<unknown> }
+  createCollection?(name: string, options?: object): Promise<unknown>
+}
+
+const BARRIER = '__weft_barrier'
+const said = (e: unknown) => (e as { message?: string } | null)?.message ?? String(e)
+
+/**
+ * `realtime({ changes: mongoChanges(db, ['todos']) })`: one change stream, ids only, read by every instance. A mutation's
+ * barrier is a capped collection's insert, so the oplog puts it after the writes it covers. After a lost stream every
+ * collection is poked: the resume token is not kept, because a poke is cheaper than a stale page.
+ */
+export function mongoChanges(db: MongoDb, collections: string[], options: { retry?: number; external?: boolean } = {}): Source {
+  const retry = options.retry ?? 1000
+  return {
+    name: 'mongodb',
+    tables: collections,
+    hold: 120, // a stream hands over a batch at a time
+    external: options.external,
+    async probe() {
+      try {
+        const hello = await db.command({ hello: 1 })
+        if (hello.setName || hello.msg === 'isdbgrid') return { mode: 'feed', via: 'mongo-change-stream' }
+        return { mode: 'off', via: 'none', why: 'a standalone mongod has no oplog, so no change streams', fix: 'run it as a replica set: a single member is enough (`mongod --replSet rs0`, then `rs.initiate()`)' }
+      } catch (e) {
+        return { mode: 'off', via: 'none', why: `MongoDB didn't answer: ${said(e)}`, fix: 'check the connection string' }
+      }
+    },
+    async start(sink, how) {
+      if (how.mode === 'off') return () => {}
+      await db.createCollection?.(BARRIER, { capped: true, size: 1 << 20 }).catch(() => {})
+      let stream: MongoStream | undefined, stopped = false, timer: ReturnType<typeof setTimeout> | undefined, again = false
+      const pipeline = [{ $match: { 'ns.coll': { $in: [...collections, BARRIER] } } }, { $project: { operationType: 1, documentKey: 1, 'ns.coll': 1, 'fullDocument.tags': 1 } }]
+      const run = async () => {
+        if (stopped) return
+        try {
+          stream = db.watch(pipeline)
+          if (again) sink.lost()
+          sink.up()
+          again = true
+          for await (const c of stream) {
+            if (c.ns?.coll === BARRIER) { if (c.fullDocument?.tags) sink.settled(c.fullDocument.tags); continue }
+            if (!['insert', 'update', 'replace', 'delete'].includes(c.operationType) || !c.ns?.coll) continue
+            sink.changes([{ table: c.ns.coll, ...(c.documentKey?._id !== undefined && { id: String(c.documentKey._id) }) }])
+          }
+        } catch (e) {
+          if (!stopped) sink.down(`change stream: ${said(e)}`)
+        }
+        if (!stopped) timer = setTimeout(() => void run(), retry)
+      }
+      void run()
+      return async () => {
+        stopped = true
+        clearTimeout(timer)
+        await stream?.close?.()
+      }
+    },
+    settle: async tags => void (await db.collection(BARRIER).insertOne({ tags })),
+  }
+}
+
+/** The fields of a change-stream event that say what happened to which row. */
+export interface MongoChange { operationType: string; documentKey?: { _id?: string | number | { toString(): string } } }
+
+/** The tags of one change: the collection's, and the row's. Never the row itself. */
+export function changeTags(change: MongoChange, tag: string): string[] {
+  if (!['insert', 'update', 'replace', 'delete'].includes(change.operationType)) return []
+  const id = change.documentKey?._id
+  return id === undefined ? [tag] : [tag, `${tag}:${String(id)}`]
+}
+
+/** How `watchMongo` turns a stream into pokes. */
+export interface WatchOptions {
+  /** Default the collection's name. */
+  tag?: string
+  /** Where the tags go. Default the realtime hub, as `invalidate` would. */
+  poke?: (tags: string[]) => unknown
+  /** Ms between attempts after the stream fails. Default 1000. */
+  retry?: number
+}
+
+/**
+ * Writes from cron, a shell or another service reach `.live` queries, as tags. Needs a replica set. After a lost stream
+ * the whole collection's tag is poked, because what happened meanwhile is unknown. Returns the way to stop.
+ */
+export function watchMongo(collection: MongoCollection, options: WatchOptions = {}): () => Promise<void> {
+  const tag = options.tag ?? collection.collectionName
+  if (!tag) throw new Error('`watchMongo` needs a `tag`')
+  const poke = options.poke ?? ((tags: string[]) => hub().poke(tags))
+  const retry = options.retry ?? 1000
+  let stream: MongoStream | undefined, stopped = false, timer: ReturnType<typeof setTimeout> | undefined
+  const run = async (again: boolean) => {
+    if (stopped) return
+    try {
+      stream = collection.watch([{ $project: { operationType: 1, documentKey: 1 } }])
+      if (again) await poke([tag])
+      for await (const change of stream) {
+        const tags = changeTags(change, tag)
+        if (tags.length) await poke(tags)
+      }
+    } catch {
+      // A closed stream ends here too; the loop below decides.
+    }
+    if (!stopped) timer = setTimeout(() => void run(true), retry)
+  }
+  void run(false)
+  return async () => {
+    stopped = true
+    clearTimeout(timer)
+    await stream?.close?.()
+  }
+}

package/src/native/auth.ts

@@ -0,0 +1,45 @@
+// Better Auth on Native (research 34 §5): Better Auth speaks Kysely, so this is a Kysely dialect over Native's own
+// connection. One connection on every engine and runtime, with no second driver and no ORM in the app's code.
+
+import type { Dialect } from 'kysely'
+import { driver } from '../driver'
+import type { NativeDb } from './index'
+
+const { MysqlAdapter, MysqlIntrospector, MysqlQueryCompiler, PostgresAdapter, PostgresIntrospector, PostgresQueryCompiler, SqliteAdapter, SqliteIntrospector, SqliteQueryCompiler } = await driver('@weft-js/db/plugin-native/auth', 'kysely', () => import('kysely'))
+
+const PARTS = {
+  sqlite: { adapter: SqliteAdapter, compiler: SqliteQueryCompiler, introspector: SqliteIntrospector, type: 'sqlite' },
+  postgresql: { adapter: PostgresAdapter, compiler: PostgresQueryCompiler, introspector: PostgresIntrospector, type: 'postgres' },
+  mysql: { adapter: MysqlAdapter, compiler: MysqlQueryCompiler, introspector: MysqlIntrospector, type: 'mysql' },
+} as const
+
+/** Better Auth's `database` option on a Native client. It runs without transactions, which Better Auth treats as optional. */
+export function nativeAuth(db: NativeDb) {
+  const { adapter, compiler, introspector, type } = PARTS[db.$weft.dialect]
+  const connection = {
+    async executeQuery({ sql, parameters }: { sql: string; parameters: readonly unknown[] }) {
+      const out = await db.query(sql, [...parameters]) as unknown
+      // mysql2 answers a write with a header, not rows.
+      if (Array.isArray(out)) return { rows: out }
+      return { rows: [], numAffectedRows: BigInt((out as { affectedRows?: number }).affectedRows ?? 0) }
+    },
+    streamQuery(): never {
+      throw new Error('Native has no streaming queries')
+    },
+  }
+  const dialect = {
+    createAdapter: () => new adapter(),
+    createDriver: () => ({
+      init: async () => {},
+      destroy: async () => {},
+      acquireConnection: () => Promise.resolve(connection),
+      releaseConnection: async () => {},
+      beginTransaction: async () => {},
+      commitTransaction: async () => {},
+      rollbackTransaction: async () => {},
+    }),
+    createIntrospector: (kysely: ConstructorParameters<typeof SqliteIntrospector>[0]) => new introspector(kysely),
+    createQueryCompiler: () => new compiler(),
+  } as unknown as Dialect
+  return { dialect, type, transaction: false }
+}

package/src/native/bun-sqlite.d.ts

@@ -0,0 +1,9 @@
+// Bun's built-in driver has no types on Node, where this package is checked: only what `open` calls.
+declare module 'bun:sqlite' {
+  /** One open database file. */
+  export class Database {
+    constructor(path: string, options: { create: boolean })
+    prepare(text: string): { all(...params: unknown[]): Record<string, unknown>[] }
+    run(text: string): unknown
+  }
+}

package/src/native/index.ts

@@ -0,0 +1,71 @@
+// The no-ORM client (research 34 §4): one `sql` tag over any driver. Values always go to the driver as parameters, so
+// a template can't build SQL from a value. An engine file supplies the driver; `createNative` takes your own the same way.
+
+import { gate, register, touch, type DbHandle, type Migration } from '@weft-js/start/db/core'
+
+/** One row, by column name. */
+export type Row = Record<string, unknown>
+
+/** What an engine supplies: statements, files of them, a transaction and a lock. */
+export interface Driver<D = unknown> {
+  dialect: DbHandle['dialect']
+  /** The client underneath, for anything `sql` doesn't cover. */
+  raw: D
+  /** Run one statement with bound values, and return its rows as objects. */
+  query(text: string, params: unknown[]): Promise<Row[]>
+  /** Run a whole file of statements. */
+  exec(text: string): Promise<void>
+  /** Run `fn` on one connection, committed when it resolves. */
+  transaction<T>(fn: (driver: Pick<Driver, 'query'>) => Promise<T>): Promise<T>
+  /** Hold off other instances while migrations run. */
+  locked<T>(fn: () => Promise<T>): Promise<T>
+}
+
+/** The template tag: its values always go to the driver as parameters. */
+export type Sql = (strings: TemplateStringsArray, ...values: unknown[]) => Promise<Row[]>
+
+/** The client an app holds, as `ctx.db`. */
+export interface NativeDb<D = unknown> {
+  sql: Sql
+  /** One statement you built, with its values bound. For a tool that writes SQL; in app code use `sql`. */
+  query: Driver['query']
+  driver: D
+  transaction<T>(fn: (tx: { sql: Sql }) => Promise<T>): Promise<T>
+  $weft: DbHandle
+}
+
+const placeholder = (dialect: DbHandle['dialect'], i: number) => (dialect === 'postgresql' ? `$${i + 1}` : '?')
+
+const tag = (handle: DbHandle, query: Driver['query']): Sql => (strings, ...values) => {
+  const text = strings.reduce((out, part, i) => out + placeholder(handle.dialect, i - 1) + part)
+  touch(handle, text)
+  return query(text, values)
+}
+
+/** A client over any `Driver`, with its migrations behind the same gate as every statement. */
+export function createNative<D>(driver: Driver<D>, { migrate = true }: { migrate?: boolean | undefined } = {}): NativeDb<D> {
+  const handle: DbHandle = {
+    dialect: driver.dialect,
+    exempt: new Set(),
+    migrate: (list: Migration[]) => driver.locked(async () => {
+      await driver.exec('create table if not exists __weft_migrations (tag varchar(255) primary key)')
+      const done = new Set((await driver.query('select tag from __weft_migrations', [])).map(r => r.tag))
+      for (const m of list) {
+        if (done.has(m.tag)) continue
+        // A file with only comments is a migration still being written; some engines refuse an empty query.
+        if (m.sql.replace(/--.*$/gm, '').trim()) await driver.exec(m.sql)
+        await driver.query(`insert into __weft_migrations (tag) values (${placeholder(driver.dialect, 0)})`, [m.tag])
+      }
+    }),
+  }
+  const ready = gate(handle, migrate)
+  const query: Driver['query'] = async (text, params) => (await ready(), driver.query(text, params))
+  const db = {
+    sql: tag(handle, query),
+    query,
+    driver: driver.raw,
+    transaction: async <T>(fn: (tx: { sql: Sql }) => Promise<T>) => (await ready(), driver.transaction(tx => fn({ sql: tag(handle, tx.query) }))),
+  }
+  return register(db, handle)
+}
+

package/src/native/mysql.ts

@@ -0,0 +1,57 @@
+// MySQL with no ORM: mysql2's pool, which connects on the first statement, so a build needs no database. Files run on
+// one connection with multiple statements on; everything else has it off.
+
+import { driver } from '../driver'
+import { createNative, type Driver, type Row } from './index'
+
+const { createConnection, createPool } = await driver('@weft-js/db/plugin-native/mysql', 'mysql2', () => import('mysql2/promise'))
+
+const LOCK = 'weft_migrations'
+type ExecuteValues = Parameters<Awaited<ReturnType<typeof createConnection>>['execute']>[1]
+
+/** A client on a mysql2 pool. */
+export function createDb({ url, migrate, max = 10 }: { url: string; migrate?: boolean; max?: number }) {
+  const uri = url || 'mysql://localhost/build'
+  // No `maxIdle` below the limit: that starts mysql2's reaper, a timer that keeps a finished `weft build` alive forever.
+  const pool = createPool({ uri, connectionLimit: max })
+  const rows = async (run: Promise<[unknown, unknown]>) => (await run)[0] as Row[]
+  const engine: Driver<typeof pool> = {
+    dialect: 'mysql',
+    raw: pool,
+    query: (text, params) => rows(pool.execute(text, params as ExecuteValues)),
+    async exec(text) {
+      const c = await createConnection({ uri, multipleStatements: true })
+      try {
+        await c.query(text)
+      } finally {
+        await c.end()
+      }
+    },
+    async transaction(fn) {
+      const c = await pool.getConnection()
+      try {
+        await c.beginTransaction()
+        const out = await fn({ query: (text, params) => rows(c.execute(text, params as ExecuteValues)) })
+        await c.commit()
+        return out
+      } catch (e) {
+        await c.rollback()
+        throw e
+      } finally {
+        c.release()
+      }
+    },
+    async locked(fn) {
+      const c = await pool.getConnection()
+      try {
+        const [got] = await c.query('select get_lock(?, 60) as got', [LOCK]) as unknown as [{ got: unknown }[]]
+        if (Number(got[0]?.got) !== 1) throw new Error('another instance held the migration lock for 60s')
+        return await fn()
+      } finally {
+        await c.query('select release_lock(?)', [LOCK]).catch(() => {})
+        c.release()
+      }
+    },
+  }
+  return createNative(engine, { migrate })
+}

package/src/native/postgres.ts

@@ -0,0 +1,26 @@
+// Postgres with no ORM: postgres.js, which connects on the first statement, so a build needs no database.
+
+import { driver } from '../driver'
+import { createNative, type Driver, type Row } from './index'
+
+const { default: postgres } = await driver('@weft-js/db/plugin-native/postgres', 'postgres', () => import('postgres'))
+
+const LOCK = 7_301_987
+
+/** A client on a postgres.js connection pool. */
+export function createDb({ url, migrate, max = 10 }: { url: string; migrate?: boolean; max?: number }) {
+  const client = postgres(url || 'postgres://localhost/build', { max, idle_timeout: 20, onnotice: () => {} })
+  const on = (c: { unsafe: typeof client.unsafe }) => (text: string, params: unknown[]) => c.unsafe(text, params as Parameters<typeof client.unsafe>[1]) as unknown as Promise<Row[]>
+  const engine: Driver<typeof client> = {
+    dialect: 'postgresql',
+    raw: client,
+    query: on(client),
+    exec: async text => void (await client.unsafe(text)),
+    transaction: fn => client.begin(tx => fn({ query: on(tx) })),
+    locked: fn => client.begin(async tx => {
+      await tx.unsafe(`select pg_advisory_xact_lock(${LOCK})`)
+      return fn()
+    }),
+  }
+  return createNative(engine, { migrate })
+}

package/src/native/sqlite.ts

@@ -0,0 +1,74 @@
+// SQLite with no ORM: Node's and Deno's `node:sqlite`, or Bun's `bun:sqlite`. One connection, opened on the first
+// statement. A transaction's body is async, so it holds a gate: statements outside it wait.
+
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
+import type { SQLInputValue } from 'node:sqlite'
+import { createNative, type Driver, type Row } from './index'
+
+interface Conn {
+  all(text: string, params: unknown[]): Row[]
+  exec(text: string): void
+}
+
+async function open(path: string): Promise<Conn> {
+  if (path !== ':memory:') mkdirSync(dirname(path), { recursive: true })
+  let conn: Conn
+  if ('Bun' in globalThis) {
+    const { Database } = await import('bun:sqlite')
+    const db = new Database(path, { create: true })
+    conn = { all: (text, params) => db.prepare(text).all(...params), exec: text => void db.run(text) }
+  } else {
+    const { DatabaseSync } = await import('node:sqlite')
+    const db = new DatabaseSync(path)
+    // `node:sqlite` on Deno refuses a boolean, which SQLite stores as 0 or 1 anyway.
+    conn = { all: (text, params) => db.prepare(text).all(...(params.map(v => (typeof v === 'boolean' ? Number(v) : v)) as SQLInputValue[])), exec: text => db.exec(text) }
+  }
+  if (path !== ':memory:') conn.exec('pragma journal_mode = wal')
+  conn.exec('pragma foreign_keys = on; pragma busy_timeout = 5000')
+  return conn
+}
+
+/** A client on one SQLite file, or `:memory:`. */
+export function createDb({ url = 'file:.data/app.db', migrate }: { url?: string; migrate?: boolean } = {}) {
+  const path = url.replace(/^file:/, '')
+  let conn: Promise<Conn> | undefined
+  const connect = () => (conn ??= open(path))
+  const inside = new AsyncLocalStorage<boolean>()
+  let gate: Promise<unknown> = Promise.resolve()
+  const query = async (text: string, params: unknown[]) => {
+    const c = await connect()
+    if (!inside.getStore()) await gate
+    return c.all(text, params)
+  }
+  const driver: Driver<() => Promise<Conn>> = {
+    dialect: 'sqlite',
+    raw: connect,
+    query,
+    exec: async text => (await connect()).exec(text),
+    async transaction(fn) {
+      if (inside.getStore()) return fn({ query })
+      const c = await connect()
+      const before = gate
+      let release!: () => void
+      gate = new Promise<void>(ok => { release = ok })
+      await before
+      try {
+        c.exec('begin')
+        try {
+          const out = await inside.run(true, () => fn({ query }))
+          c.exec('commit')
+          return out
+        } catch (e) {
+          c.exec('rollback')
+          throw e
+        }
+      } finally {
+        release()
+      }
+    },
+    locked: fn => fn(),
+  }
+  return createNative(driver, { migrate })
+}

package/src/prisma-client.ts

@@ -0,0 +1,51 @@
+// Prisma on weft's seam (research 34 §4): `withWeft(client, dialect)` returns the same client with the handle the server
+// migrates and Q011 reads. Migrations are `prisma/migrations`, applied here because `prisma migrate deploy` isn't in a
+// production bundle. Interactive transactions keep the lock and the statements on one connection. It stays Prisma's own
+// client, so weft can't hold a statement: the server runs the gate per request instead, and a failed run doesn't fail it.
+
+import { gate, register, touch, type DbHandle, type Migration } from '@weft-js/start/db/core'
+import { runtime } from '@weft-js/start/data'
+
+type Dialect = DbHandle['dialect']
+interface Tx {
+  $executeRawUnsafe(sql: string, ...values: unknown[]): Promise<number>
+  $queryRawUnsafe<T>(sql: string, ...values: unknown[]): Promise<T>
+}
+interface Client extends Tx {
+  $on?(event: 'query', fn: (e: { query: string }) => void): void
+  $transaction<T>(fn: (tx: Tx) => Promise<T>, options: { maxWait: number; timeout: number }): Promise<T>
+}
+
+const LOCK = 7_301_988
+const statements = (sql: string) => sql.split(/;[ \t]*(?:\r?\n|$)/).map(s => s.replace(/^(\s*--.*\n)+/, '').trim()).filter(Boolean)
+
+/** The same client, with `$weft`: the handle the server migrates and Q011 reads. */
+export function withWeft<C extends object>(client: C, dialect: Dialect, { migrate = true }: { migrate?: boolean | undefined } = {}): C & { $weft: DbHandle } {
+  const c = client as unknown as Client
+  const handle: DbHandle = {
+    dialect,
+    exempt: new Set(),
+    migrate: (list: Migration[]) => c.$transaction(async tx => {
+      if (dialect === 'postgresql') await tx.$queryRawUnsafe(`select pg_advisory_xact_lock(${LOCK})::text`)
+      if (dialect === 'mysql') {
+        const got = await tx.$queryRawUnsafe<{ got: unknown }[]>(`select get_lock('weft_migrations', 60) as got`)
+        if (Number(got[0]?.got) !== 1) throw new Error('another instance held the migration lock for 60s')
+      }
+      try {
+        await tx.$executeRawUnsafe('create table if not exists __weft_migrations (tag varchar(255) primary key)')
+        const done = new Set((await tx.$queryRawUnsafe<{ tag: string }[]>('select tag from __weft_migrations')).map(r => r.tag))
+        for (const m of list) {
+          if (done.has(m.tag)) continue
+          for (const s of statements(m.sql)) await tx.$executeRawUnsafe(s)
+          await tx.$executeRawUnsafe(`insert into __weft_migrations (tag) values (${dialect === 'postgresql' ? '$1' : '?'})`, m.tag)
+        }
+      } finally {
+        // MySQL's lock belongs to the connection, not the transaction: a failed run would keep it in the pool.
+        if (dialect === 'mysql') await tx.$queryRawUnsafe(`select release_lock('weft_migrations')`).catch(() => {})
+      }
+    }, { maxWait: 60_000, timeout: 120_000 }),
+  }
+  c.$on?.('query', e => touch(handle, e.query))
+  ;(runtime.dbs ??= new Set()).add(gate(handle, migrate))
+  return register(client, handle)
+}