@weft-js/start 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,10 @@
+// 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): { run(...params: unknown[]): unknown; values(...params: unknown[]): unknown[][] }
+    run(text: string): unknown
+    close(): void
+  }
+}

package/src/db/changes-mysql.ts

@@ -0,0 +1,86 @@
+// The change feed on MySQL. A trigger can't reach a client and the binlog needs replication rights, so triggers write a
+// log and this reads it on a timer: polling, and it says so. An AUTO_INCREMENT id is taken before commit, so a long
+// transaction can land behind the mark: each look re-reads a window behind it.
+
+import type { Pool } from 'mysql2/promise'
+import { LOG, MAX_IDS } from '../changes-sql.mjs'
+import type { Change, Probe, Sink } from '../changes'
+
+const BEHIND = 512
+const KEEP_HOURS = 1
+const PRUNE = 60_000
+
+interface Options { pool: Pool; tables: string[]; interval?: number }
+
+/** A bigint column: the driver's number, or its string once past 2^53. */
+type Seq = number | string
+const said = (e: unknown) => (e as Error | null)?.message ?? String(e)
+
+export function mysqlChanges({ pool, tables, interval = 500 }: Options) {
+  async function probe(): Promise<Probe> {
+    try {
+      const [rows] = await pool.query(`select event_object_table as t from information_schema.triggers where trigger_schema = database() and trigger_name like 'weft\\_changes\\_%\\_upd'`)
+      const have = (rows as { t: string }[]).map(r => r.t)
+      const missing = tables.filter(t => !have.includes(t))
+      if (!missing.length) return { mode: 'feed', via: 'mysql-log', why: `read every ${interval} ms: MySQL can't push` }
+      const [grants] = await pool.query('show grants').catch(() => [[]])
+      const may = (grants as Record<string, string>[]).some(g => /ALL PRIVILEGES|\bTRIGGER\b/.test(Object.values(g)[0] ?? ''))
+      return { mode: 'off', via: 'none', why: `no trigger on ${missing.map(t => `\`${t}\``).join(', ')}, and MySQL has no counter to fall back on`, fix: may ? 'run `weft db live`, then apply the migration' : 'run `weft db live`, and apply the migration as a user with the TRIGGER privilege' }
+    } catch (e) {
+      return { mode: 'off', via: 'none', why: `the database didn't answer: ${said(e)}`, fix: 'check `DATABASE_URL`' }
+    }
+  }
+
+  async function start(sink: Sink, how: Probe) {
+    if (how.mode === 'off') return () => {}
+    let stopped = false, timer: ReturnType<typeof setTimeout> | undefined, failed = false, pruned = Date.now()
+    const [[{ top }]] = (await pool.query(`select coalesce(max(seq), 0) as top from ${LOG}`)) as unknown as [[{ top: number | string }]]
+    let mark = Number(top)
+    // What's already there is old news, and needs no poke.
+    const [old] = (await pool.query(`select seq from ${LOG} where seq > ?`, [Math.max(0, mark - BEHIND)])) as unknown as [{ seq: Seq }[]]
+    const seen = new Set<number>(old.map(r => Number(r.seq)))
+    const look = async () => {
+      if (stopped) return
+      try {
+        const [rows] = (await pool.query(`select seq, tbl, pk from ${LOG} where seq > ? order by seq limit 5000`, [Math.max(0, mark - BEHIND)])) as unknown as [{ seq: Seq; tbl: string; pk: string | null }[]]
+        if (failed) {
+          failed = false
+          sink.lost()
+          sink.up()
+        }
+        const fresh = rows.filter(r => !seen.has(Number(r.seq)))
+        const byTable = new Map<string, Set<string> | null>()
+        for (const r of fresh) {
+          seen.add(Number(r.seq))
+          if (r.pk === null) byTable.set(r.tbl, null)
+          else if (byTable.get(r.tbl) !== null) {
+            const ids = byTable.get(r.tbl) ?? new Set()
+            ids.add(r.pk)
+            byTable.set(r.tbl, ids.size > MAX_IDS ? null : ids)
+          }
+          mark = Math.max(mark, Number(r.seq))
+        }
+        for (const s of seen) if (s <= mark - BEHIND) seen.delete(s)
+        const list: Change[] = []
+        for (const [table, ids] of byTable) ids ? list.push(...[...ids].map(id => ({ table, id }))) : list.push({ table })
+        if (list.length) sink.changes(list)
+        if (Date.now() - pruned > PRUNE) {
+          pruned = Date.now()
+          await pool.query(`delete from ${LOG} where at < now() - interval ${KEEP_HOURS} hour limit 10000`)
+        }
+      } catch (e) {
+        failed = true
+        sink.down(`MySQL watcher: ${said(e)}`)
+      }
+      timer = setTimeout(() => void look(), interval)
+      ;(timer as { unref?(): void }).unref?.()
+    }
+    await look()
+    return () => {
+      stopped = true
+      clearTimeout(timer)
+    }
+  }
+
+  return { probe, start }
+}

package/src/db/changes-postgres.ts

@@ -0,0 +1,159 @@
+// The change feed on Postgres: triggers NOTIFY, one dedicated connection LISTENs. The probe tries the real thing before it
+// claims anything, because a pooler in transaction mode accepts LISTEN and then delivers nothing.
+
+import postgres from 'postgres'
+import { CHANNEL } from '../changes-sql.mjs'
+import type { Probe, Sink } from '../changes'
+
+type Sql = ReturnType<typeof postgres>
+
+const SECRET = /\/\/[^@/]*@/
+const opts = { onnotice: () => {}, connect_timeout: 5 }
+const PROBE = 1500
+const HEARTBEAT = 5_000
+const MAX_BARRIER = 7_800
+
+interface Options { url: string; listenUrl?: string; client: Sql; tables: string[]; interval?: number; heartbeat?: number }
+
+export function postgresChanges({ url, listenUrl, client, tables, interval = 2000, heartbeat = HEARTBEAT }: Options) {
+  const direct = listenUrl ?? url
+  const late = heartbeat * 2
+
+  /** Sends a NOTIFY and waits to hear it on a listening connection: the only proof a pooler can't fake. */
+  async function hears(): Promise<boolean | string> {
+    const sql = postgres(direct, { ...opts, max: 1 })
+    const token = `?${crypto.randomUUID()}`
+    let heard!: () => void
+    const got = new Promise<void>(ok => { heard = ok })
+    try {
+      await sql.listen(CHANNEL, p => { if (p === token) heard() })
+      await client.notify(CHANNEL, token)
+      return await Promise.race([got.then(() => true), new Promise<boolean>(ok => { setTimeout(ok, PROBE, false) })])
+    } catch (e) {
+      return (e as Error | null)?.message ?? String(e)
+    } finally {
+      void sql.end({ timeout: 0 }).catch(() => {})
+    }
+  }
+
+  async function triggers(): Promise<string[]> {
+    const rows = await client`select c.relname from pg_trigger t join pg_class c on c.oid = t.tgrelid where t.tgname = 'weft_changes_upd' and c.relname = any(${tables})`
+    return rows.map(r => r.relname as string)
+  }
+
+  /** Whether this role may add them, for the error's fix. */
+  async function mayCreate(table: string): Promise<boolean> {
+    const [r] = await client`select has_table_privilege(current_user, ${table}, 'TRIGGER') as ok`.catch(() => [{ ok: false }])
+    return !!r?.ok
+  }
+
+  async function stats(): Promise<boolean> {
+    const [r] = await client`select current_setting('track_counts') = 'on' as ok`.catch(() => [{ ok: false }])
+    return !!r?.ok
+  }
+
+  const poll = async (why: string, fix: string): Promise<Probe> =>
+    (await stats())
+      ? { mode: 'poll', via: 'postgres-stats', why: `${why}. Reading table counters every ${interval / 1000} s: writes show up late, and by table only`, fix }
+      : { mode: 'off', via: 'none', why: `${why}, and \`track_counts\` is off, so there is nothing to poll`, fix }
+
+  async function probe(): Promise<Probe> {
+    let have: string[]
+    try {
+      have = await triggers()
+    } catch (e) {
+      return { mode: 'off', via: 'none', why: `the database didn't answer: ${((e as Error | null)?.message ?? String(e)).replace(SECRET, '//…@')}`, fix: 'check `DATABASE_URL`' }
+    }
+    const missing = tables.filter(t => !have.includes(t))
+    if (missing.length) {
+      const allowed = await mayCreate(missing[0]!)
+      return poll(`no trigger on ${missing.map(t => `\`${t}\``).join(', ')}`, allowed ? 'run `weft db live`, then apply the migration' : `run \`weft db live\`, and apply the migration as a role that may create triggers: this one has no TRIGGER on \`${missing[0]}\``)
+    }
+    const ok = await hears()
+    if (ok === true) return { mode: 'feed', via: 'postgres-notify' }
+    const pooler = /:6432\b|-pooler\.|pooler\./.test(direct)
+    const why = typeof ok === 'string' ? `LISTEN failed: ${ok.replace(SECRET, '//…@')}` : `a NOTIFY never reached a LISTEN on this connection${pooler ? ', which looks like a pooler' : ''}: a pooler in transaction mode does that`
+    return poll(why, 'give `dbChanges` a direct connection: `{ listenUrl }`')
+  }
+
+  /** A self-addressed NOTIFY proves the listener is alive: a half-open TCP connection looks fine until then. */
+  async function listen(sink: Sink) {
+    let sql: Sql | undefined, started = false, stopped = false, seen = Date.now(), timer: ReturnType<typeof setTimeout> | undefined
+    const token = `?${crypto.randomUUID()}`
+    const heard = (payload: string) => {
+      seen = Date.now()
+      if (payload[0] === '?') return
+      const m = JSON.parse(payload)
+      if (m.b) return sink.settled(m.b)
+      sink.changes(m.i ? m.i.map((id: string) => ({ table: m.t, id })) : [{ table: m.t }])
+    }
+    const connect = async () => {
+      const mine = (sql = postgres(direct, { ...opts, max: 1, idle_timeout: 0 }))
+      await mine.listen(CHANNEL, heard, () => {
+        seen = Date.now()
+        if (started) sink.lost() // what committed while it was gone is unknown
+        started = true
+        sink.up()
+      })
+    }
+    const check = async () => {
+      if (stopped) return
+      if (Date.now() - seen > late) {
+        sink.down('the database listener is not receiving')
+        const old = sql
+        sql = undefined
+        void old?.end({ timeout: 0 }).catch(() => {})
+        await connect().catch(() => {}) // the next check tries again
+      }
+      await client.notify(CHANNEL, token).catch(() => sink.down('the database is not answering'))
+      if (stopped) return
+      timer = setTimeout(() => void check(), heartbeat)
+      ;(timer as { unref?(): void }).unref?.()
+    }
+    await connect().catch(e => sink.down(`the database listener can't connect: ${String(e?.message ?? e).replace(SECRET, '//…@')}`))
+    timer = setTimeout(() => void check(), heartbeat)
+    ;(timer as { unref?(): void }).unref?.()
+    return async () => {
+      stopped = true
+      clearTimeout(timer)
+      await sql?.end({ timeout: 0 }).catch(() => {})
+    }
+  }
+
+  /** `postgres-stats`: counters that only ever grow, per table, by the second. Nothing to install. */
+  function counters(sink: Sink) {
+    const seen = new Map<string, string>()
+    let stopped = false, timer: ReturnType<typeof setTimeout> | undefined
+    const look = async () => {
+      if (stopped) return
+      try {
+        const rows = await client`select relname, n_tup_ins + n_tup_upd + n_tup_del + n_mod_since_analyze as n from pg_stat_user_tables where relname = any(${tables})`
+        sink.up()
+        const changed = rows.filter(r => {
+          const was = seen.get(r.relname)
+          seen.set(r.relname, String(r.n))
+          return was !== undefined && was !== String(r.n)
+        })
+        if (changed.length) sink.changes(changed.map(r => ({ table: r.relname as string })))
+      } catch {
+        sink.down('the database is not answering')
+      }
+      timer = setTimeout(() => void look(), interval)
+      ;(timer as { unref?(): void }).unref?.()
+    }
+    return look().then(() => () => {
+      stopped = true
+      clearTimeout(timer)
+    })
+  }
+
+  return {
+    probe,
+    start: (sink: Sink, how: Probe) => (how.via === 'postgres-notify' ? listen(sink) : how.mode === 'poll' ? counters(sink) : Promise.resolve(() => {})),
+    /** After the mutation committed, so it arrives after that commit's changes, and before the poke it stands for. */
+    async settle(tags: string[]) {
+      const text = JSON.stringify({ b: tags })
+      await client.notify(CHANNEL, text.length < MAX_BARRIER ? text : JSON.stringify({ b: [...new Set(tags.map(t => t.split(':')[0]))] }))
+    },
+  }
+}

package/src/db/changes-sqlite.ts

@@ -0,0 +1,116 @@
+// The change feed on SQLite. There is no notify across processes, so this is polling, of the cheapest thing there is:
+// `PRAGMA data_version` on a second connection moves when any connection commits, and costs no file read. Only then is
+// the triggers' log read. Same host only: WAL's shared memory doesn't cross a network file system.
+
+import { execFileSync } from 'node:child_process'
+import { existsSync, statfsSync } from 'node:fs'
+import { LOG, MAX_IDS } from '../changes-sql.mjs'
+import type { Change, Probe, Sink } from '../changes'
+import type { Method } from './sqlite'
+
+interface Conn {
+  query(sql: string, params: unknown[], method: Method): unknown
+  exec(sql: string): void
+  close?(): void
+}
+
+// statfs(2) magic numbers: https://man7.org/linux/man-pages/man2/statfs.2.html
+const NETWORK = new Set([0x6969 /* nfs */, 0x517b /* smb */, 0xfe534d42 /* smb2 */, 0xff534d42 /* cifs */, 0x65735546 /* fuse */, 0x5346414f /* afs */, 0xc36400 /* ceph */, 0x47504653 /* gpfs */])
+
+/** Whether a file is on a network file system. `exec` and `statfs` are the test's way in. */
+export function onNetwork(path: string, { platform = process.platform, statfs = statfsSync, df = (p: string) => execFileSync('df', ['-P', p], { encoding: 'utf8' }) } = {}): boolean {
+  try {
+    if (platform === 'linux') return NETWORK.has(statfs(path).type)
+    const device = df(path).trim().split('\n').at(-1)!.split(/\s+/)[0] ?? ''
+    return device.startsWith('//') || /^[^/]+:\//.test(device)
+  } catch {
+    return false
+  }
+}
+
+interface Options { path: string; open: (path: string) => Promise<Conn>; tables: string[]; interval?: number }
+
+export function sqliteChanges({ path, open, tables, interval = 100 }: Options) {
+  const log = (c: Conn) => (c.query(`select count(*) from sqlite_master where name = '${LOG}'`, [], 'values') as number[][])[0]![0]! > 0
+  const triggers = (c: Conn) => (c.query(`select tbl_name from sqlite_master where type = 'trigger' and name like 'weft\\_changes\\_%\\_upd' escape '\\'`, [], 'values') as string[][]).map(r => r[0])
+  let tick: (() => void) | undefined, out: Sink | undefined
+
+  async function probe(): Promise<Probe> {
+    if (path === ':memory:') return { mode: 'off', via: 'none', why: 'an in-memory database has no other writers, and no second connection could see it', fix: 'use a file to have writes from other processes reach `.live`' }
+    if (onNetwork(existsSync(path) ? path : '.')) return { mode: 'off', via: 'none', why: `\`${path}\` is on a network file system: \`data_version\` and WAL don't work across hosts`, fix: 'put the database on a local disk, or move to Postgres' }
+    const c = await open(path)
+    try {
+      const have = log(c) ? triggers(c) : []
+      const missing = tables.filter(t => !have.includes(t))
+      if (missing.length) return { mode: 'poll', via: 'sqlite-data-version', why: `no trigger on ${missing.map(t => `\`${t}\``).join(', ')}: any commit pokes every table, unrelated ones included`, fix: 'run `weft db live`' }
+      return { mode: 'feed', via: 'sqlite-data-version' }
+    } finally {
+      c.close?.()
+    }
+  }
+
+  async function start(sink: Sink, how: Probe) {
+    if (how.mode === 'off') return () => {}
+    const c = await open(path)
+    const version = () => (c.query('pragma data_version', [], 'values') as number[][])[0]![0]!
+    const usable = how.mode === 'feed'
+    const newest = () => (c.query(`select coalesce(max(seq), 0) from ${LOG}`, [], 'values') as number[][])[0]![0]!
+    let seq = usable ? newest() : 0
+    let at = version()
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const read = () => {
+      const rows = c.query(`select seq, tbl, pk from ${LOG} where seq > ? order by seq`, [seq], 'values') as [number, string, string | null][]
+      if (!rows.length) return
+      if (rows[0]![0] > seq + 1) sink.lost() // the log moved past us
+      const byTable = new Map<string, Set<string> | null>()
+      for (const [, table, id] of rows) {
+        if (id === null) byTable.set(table, null)
+        else if (byTable.get(table) !== null) {
+          const ids = byTable.get(table) ?? new Set()
+          ids.add(id)
+          byTable.set(table, ids.size > MAX_IDS ? null : ids)
+        }
+      }
+      seq = rows.at(-1)![0]
+      const list: Change[] = []
+      for (const [table, ids] of byTable) ids ? list.push(...[...ids].map(id => ({ table, id }))) : list.push({ table })
+      sink.changes(list)
+    }
+    const look = () => {
+      try {
+        const now = version()
+        if (now === at) return
+        at = now
+        if (usable) read()
+        else sink.changes(tables.map(table => ({ table })))
+        sink.up()
+      } catch (e) {
+        sink.down(`SQLite watcher: ${(e as Error | null)?.message ?? String(e)}`)
+      }
+    }
+    tick = look
+    out = sink
+    const every = () => {
+      look()
+      timer = setTimeout(every, interval)
+      ;(timer as { unref?(): void }).unref?.()
+    }
+    every()
+    return () => {
+      tick = out = undefined
+      clearTimeout(timer)
+      c.close?.()
+    }
+  }
+
+  return {
+    probe,
+    start,
+    /** In this process, so the barrier needs no trip: read what's committed now, and let the hub drop what the poke covers. */
+    settle(tags: string[]) {
+      tick?.()
+      out?.settled(tags)
+      return Promise.resolve()
+    },
+  }
+}

package/src/db/core.ts

@@ -0,0 +1,63 @@
+// What every data layer shares (research 28 §2, 34 §4): the gate that applies the server's migrations before a database's
+// first statement, and the touched-tables record behind Q011. A provider is any client with a `$weft` handle made through
+// `register`. No driver imports, so `@weft-js/start/db/sqlite` doesn't load Postgres, or the other way round.
+
+import { currentScope, runtime, StartError } from '../data'
+import type { Probe, Sink } from '../changes'
+
+/** One migration file: its name and the SQL. */
+export interface Migration { tag: string; sql: string }
+
+/** What every Weft database carries on `$weft`, whichever driver is under it. */
+export interface DbHandle {
+  dialect: 'sqlite' | 'postgresql' | 'mysql'
+  /** Apply what's new in `list`, in order. */
+  migrate(list: Migration[]): Promise<void>
+  /** Tables Q011 doesn't report (Better Auth's). */
+  exempt: Set<string>
+  /** `dbChanges`'s source: loaded on the first use, so a database with no live tables loads none of it. */
+  changes?(tables: string[], options: { listenUrl?: string; interval?: number }): Promise<{ probe(): Promise<Probe>; start(sink: Sink, how: Probe): Promise<() => unknown>; settle?(tags: string[]): Promise<void> }>
+}
+
+/** Attach weft's handle to a client. */
+export const register = <D extends object>(db: D, handle: DbHandle): D & { $weft: DbHandle } => Object.assign(db, { $weft: handle })
+
+/** The database can't be used: its connection, or a migration it needs. The client sees this; the server log gets the cause. */
+export const unavailable = (cause: unknown) =>
+  new StartError('Q016', 'the database is unavailable, or a migration failed', 'start it and check `DATABASE_URL`; the server log has the driver\'s error', { status: 503, cause })
+
+/**
+ * What a provider awaits before each statement, or its connection call: resolved once the list the server's first request
+ * set (`runtime.migrations`) is applied, so a request that touches no database never needs one. Concurrent callers share
+ * one run; a failed run is retried by the next caller, so a database that comes back needs no restart. Before a request
+ * (`weft build`, scripts) and with `migrate: false` there's nothing to wait for.
+ */
+export function gate(handle: DbHandle, migrate: boolean) {
+  let applied: unknown
+  let run: Promise<void> = Promise.resolve()
+  return (): Promise<void> | undefined => {
+    const m = runtime.migrations
+    if (!migrate || !m) return undefined
+    if (m !== applied) {
+      applied = m
+      run = run.catch(() => {}).then(() => handle.migrate(m.list)).catch(e => {
+        if (applied === m) applied = undefined
+        m.report(e)
+        throw unavailable(e)
+      })
+    }
+    return run
+  }
+}
+
+/** Dev: record a statement's tables in the running function's frame. Identifiers may be quoted, as Drizzle's always are. */
+export function touch(handle: DbHandle, sql: string) {
+  const t = currentScope()?.touched
+  if (!t) return
+  const target = /^\s*(?:insert\s+into|update|delete\s+from)\s+(?:["`]?\w+["`]?\.)?["`]?([\w$]+)/i.exec(sql)?.[1]
+  if (target && !handle.exempt.has(target)) t.write.add(target)
+  for (const m of sql.matchAll(/\b(?:from|join)\s+(?:["`]?\w+["`]?\.)?["`]?([\w$]+)/gi)) if (m[1] !== target && !handle.exempt.has(m[1]!)) t.read.add(m[1]!)
+}
+
+/** A migration file's statements (drizzle-kit separates them with this marker). */
+export const statements = (sql: string) => sql.split('--> statement-breakpoint').map(s => s.trim()).filter(Boolean)

package/src/db/index.ts

@@ -0,0 +1,27 @@
+// `@weft-js/start/db`: what doesn't depend on the driver (research 28 §2). `schemasOf(schema).todos.insert` is a Zod
+// schema per table, so a table is its own validator: `input: schemas.todos.insert.pick({ title: true })`.
+
+import { getTableName, isTable, type Table } from 'drizzle-orm'
+import { createInsertSchema, createSelectSchema, createUpdateSchema, type BuildSchema } from 'drizzle-zod'
+
+export type { DbHandle, Migration } from './core'
+
+type TablesOf<S> = { [K in keyof S as S[K] extends Table ? K : never]: S[K] }
+type Select<T extends Table> = BuildSchema<'select', T['_']['columns'], undefined, undefined>
+type Insert<T extends Table> = BuildSchema<'insert', T['_']['columns'], undefined, undefined>
+type Update<T extends Table> = BuildSchema<'update', T['_']['columns'], undefined, undefined>
+/** The select and insert types of each table in a schema. */
+export type Schemas<S> = { [K in keyof TablesOf<S>]: TablesOf<S>[K] extends infer T extends Table ? { select: Select<T>; insert: Insert<T>; update: Update<T> } : never }
+
+/** `refine`: per table, per column, what drizzle-zod takes: `{ todos: { title: s => s.trim().min(1) } }`. */
+export function schemasOf<S extends Record<string, unknown>>(schema: S, refine: { [K in keyof TablesOf<S>]?: Record<string, (s: never) => unknown> } = {}): Schemas<S> {
+  const out: Record<string, unknown> = {}
+  for (const [k, t] of Object.entries(schema)) {
+    if (!isTable(t)) continue
+    const r = (refine as Record<string, never>)[k]
+    out[k] = { select: createSelectSchema(t, r), insert: createInsertSchema(t, r), update: createUpdateSchema(t, r) }
+  }
+  return out as Schemas<S>
+}
+
+export { getTableName }

package/src/db/mysql.ts

@@ -0,0 +1,67 @@
+// MySQL for `@weft-js/start` (research 34 §4): Drizzle on mysql2, pure JS. The pool connects on the first statement, so
+// `weft build` and a page with no queries need no database. MySQL commits around DDL, so a failed migration can't roll back; a named lock keeps
+// instances starting together from applying a file twice.
+
+import { drizzle, type MySql2Database } from 'drizzle-orm/mysql2'
+import { createPool } from 'mysql2/promise'
+import { StartError } from '../data'
+import { gate, register, statements, touch, type DbHandle, type Migration } from './core'
+
+/** `createDb` on MySQL: the schema, the URL, and whether to migrate on first use. */
+export interface MysqlOptions<S extends Record<string, unknown>> {
+  schema: S
+  /** `mysql://user:pass@host:3306/db`. */
+  url: string
+  /** Apply `drizzle/` before the first statement a request runs (default true). */
+  migrate?: boolean
+  /** Pool size (default 10). */
+  max?: number
+}
+
+/** Drizzle on mysql2, with `$weft` for the framework's own needs. */
+export type MysqlDb<S extends Record<string, unknown>> = MySql2Database<S> & { $weft: DbHandle }
+
+const LOCK = 'weft_migrations'
+
+/** A pooled Drizzle client on MySQL, with this app's migrations and write tracking. */
+export function createDb<S extends Record<string, unknown>>({ schema, url, migrate = true, max = 10 }: MysqlOptions<S>): MysqlDb<S> {
+  if (!url && process.env.WEFT_BUILD) url = 'mysql://localhost/build' // a build loads this module and never connects
+  if (!url?.startsWith('mysql://'))
+    throw new StartError('Q013', `\`@weft-js/start/db/mysql\` needs a \`mysql://\` URL, not \`${(url ?? '').replace(/\/\/.*@/, '//…@')}\``, 'set `DATABASE_URL`, or `createDb` from `@weft-js/start/db/sqlite`')
+  // No `maxIdle` below the limit: that starts mysql2's reaper, a timer that keeps a finished `weft build` alive forever.
+  const pool = createPool({ uri: url, connectionLimit: max })
+  const handle: DbHandle = {
+    dialect: 'mysql',
+    exempt: new Set(),
+    async migrate(list: Migration[]) {
+      const c = await pool.getConnection()
+      try {
+        await c.query('select get_lock(?, 60)', [LOCK])
+        await c.query('create table if not exists __weft_migrations (tag varchar(255) primary key, at timestamp not null default current_timestamp)')
+        const [rows] = await c.query('select tag from __weft_migrations')
+        const done = new Set((rows as { tag: string }[]).map(r => r.tag))
+        for (const m of list) {
+          if (done.has(m.tag)) continue
+          for (const s of statements(m.sql)) await c.query(s)
+          await c.query('insert into __weft_migrations (tag) values (?)', [m.tag])
+        }
+      } finally {
+        await c.query('select release_lock(?)', [LOCK]).catch(() => {})
+        c.release()
+      }
+    },
+    changes: (tables, o) => import('./changes-mysql').then(m => m.mysqlChanges({ ...o, pool, tables })),
+  }
+  const ready = gate(handle, migrate)
+  // All Drizzle sends goes through these three, so holding them holds it; `handle.migrate` keeps the plain pool.
+  const held = new Proxy(pool, {
+    get(t, key) {
+      const v = Reflect.get(t, key)
+      if (typeof v !== 'function') return v
+      if (key !== 'query' && key !== 'execute' && key !== 'getConnection') return v.bind(t)
+      return async (...a: unknown[]) => (await ready(), v.apply(t, a))
+    },
+  })
+  const db = drizzle(held, { schema, mode: 'default', logger: { logQuery: sql => touch(handle, sql) } })
+  return register(db, handle)
+}

package/src/db/postgres.ts

@@ -0,0 +1,65 @@
+// Postgres for `@weft-js/start` (research 28 §2): Drizzle on postgres.js, pure JS on Node, Bun and Deno. The client
+// connects on the first statement, so `weft build` and a page with no queries need no database. Migrations hold an
+// advisory lock, so instances starting together apply each file once.
+
+import postgres from 'postgres'
+import { drizzle, type PostgresJsDatabase } from 'drizzle-orm/postgres-js'
+import { StartError } from '../data'
+import { gate, register, statements, touch, type DbHandle, type Migration } from './core'
+
+/** `createDb` on Postgres: the schema, the URL, and whether to migrate on first use. */
+export interface PostgresOptions<S extends Record<string, unknown>> {
+  schema: S
+  /** `postgres://user:pass@host:5432/db`. */
+  url: string
+  /** Apply `drizzle/` before the first statement a request runs (default true). */
+  migrate?: boolean
+  /** Pool size (default 10). */
+  max?: number
+}
+
+/** Drizzle on postgres.js, with `$weft` for the framework's own needs. */
+export type PostgresDb<S extends Record<string, unknown>> = PostgresJsDatabase<S> & { $weft: DbHandle }
+
+const LOCK = 7_301_986
+
+/** A pooled Drizzle client on Postgres, with this app's migrations and write tracking. */
+export function createDb<S extends Record<string, unknown>>({ schema, url, migrate = true, max = 10 }: PostgresOptions<S>): PostgresDb<S> {
+  if (!url && process.env.WEFT_BUILD) url = 'postgres://localhost/build' // a build loads this module and never connects
+  if (!/^postgres(ql)?:\/\//.test(url ?? ''))
+    throw new StartError('Q013', `\`@weft-js/start/db/postgres\` needs a \`postgres://\` URL, not \`${(url ?? '').replace(/\/\/.*@/, '//…@')}\``, 'set `DATABASE_URL`, or `createDb` from `@weft-js/start/db/sqlite` for a file')
+  // Idle connections close, so a stopped server can exit.
+  const client = postgres(url, { max, idle_timeout: 20, onnotice: () => {} })
+  const handle: DbHandle = {
+    dialect: 'postgresql',
+    exempt: new Set(),
+    async migrate(list: Migration[]) {
+      await client.begin(async tx => {
+        await tx.unsafe(`select pg_advisory_xact_lock(${LOCK})`)
+        await tx.unsafe('create table if not exists __weft_migrations (tag text primary key, at timestamptz not null default now())')
+        const done = new Set((await tx.unsafe('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.unsafe(s)
+          await tx.unsafe('insert into __weft_migrations (tag) values ($1)', [m.tag])
+        }
+      })
+    },
+    changes: (tables, o) => import('./changes-postgres').then(m => m.postgresChanges({ ...o, url, client, tables })),
+  }
+  const ready = gate(handle, migrate)
+  // All Drizzle sends goes through `unsafe` and `begin`, so holding those holds it; `handle.migrate` keeps the plain client.
+  const held = new Proxy(client, {
+    get(t, key) {
+      if (key === 'begin') return async (...a: Parameters<typeof t.begin>) => (await ready(), t.begin(...a))
+      if (key !== 'unsafe') return Reflect.get(t, key)
+      return (...a: Parameters<typeof t.unsafe>) => {
+        const after = <T>(send: () => PromiseLike<T>) => Promise.resolve(ready()).then(send)
+        // oxlint-disable-next-line unicorn/no-thenable -- postgres.js's query is a lazy thenable, and Drizzle awaits it as one
+        return { values: () => after(() => t.unsafe(...a).values()), then: <A, B>(ok: (rows: unknown) => A, no: (e: unknown) => B) => after(() => t.unsafe(...a)).then(ok, no) }
+      }
+    },
+  })
+  const db = drizzle(held, { schema, logger: { logQuery: sql => touch(handle, sql) } })
+  return register(db, handle)
+}