@jarenjs/db 0.84.3 → 0.85.0

package/src/dialects/sqlite-relational.js

@@ -0,0 +1,314 @@
+//@ts-check
+/** Explicit SQLite expressions and statements on an existing connection.
+ * Values retain SQLite's NULL, numeric, collation and byte semantics. */
+import { DbCompileError } from '../errors.js';
+import { sqliteDialect } from './sqlite.js';
+import { chain } from '../driver.js';
+import { createSyncCursor, rowClassOf } from '../cursor.js';
+
+/** @typedef {{ sql: string, params: any[], access: 'read'|'write' }} RelationalPlan */
+const fail = (message) => { throw new DbCompileError('JD0038', message); };
+const own = (o, key) => Object.hasOwn(o, key);
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const check = (value, members, label) => {
+  if (!object(value)) fail(`${label} must be an object`);
+  for (const key of Object.keys(value)) if (!members.includes(key)) fail(`unknown ${label} member '${key}'`);
+};
+/** Quote one identifier; a dot is part of the name, never SQL syntax.
+ * @param {string} name @returns {string} */
+export function relationalIdentifier(name) {
+  if (typeof name !== 'string' || !name || name.includes('\0')) fail('a SQL identifier must be nonempty and contain no NUL');
+  return sqliteDialect.quoteIdentifier(name);
+}
+const q = relationalIdentifier;
+const binary = new Set(['=', '<>', '<', '<=', '>', '>=', 'IS', 'IS NOT', '+', '-', '*', '/', '%', '||', 'AND', 'OR', 'LIKE', 'NOT LIKE', 'GLOB']);
+const functions = new Set(['coalesce', 'nullif', 'trim', 'ltrim', 'rtrim', 'lower', 'upper', 'length', 'abs', 'round', 'typeof', 'json_extract', 'json_valid', 'count', 'sum', 'total', 'avg', 'min', 'max', 'date', 'time', 'datetime', 'julianday', 'unixepoch', 'strftime']);
+const types = new Set(['INTEGER', 'REAL', 'TEXT', 'BLOB', 'NUMERIC']);
+const collations = new Set(['BINARY', 'NOCASE', 'RTRIM']);
+const node = (kind, spec) => ({ $sql: kind, ...spec });
+
+/** Typed structural authoring for SQLite's own expression semantics. */
+export const sql = Object.freeze({
+  /** @param {string} name @param {string} [table] */
+  column: (name, table) => node('column', { name, ...(table === undefined ? {} : { table }) }),
+  /** @param {string|number|bigint|Uint8Array|null} value */
+  value: (value) => node('value', { value }),
+  /** @param {string} name */
+  param: (name) => node('param', { name }),
+  /** @param {'='|'<>'|'<'|'<='|'>'|'>='|'IS'|'IS NOT'|'+'|'-'|'*'|'/'|'%'|'||'|'AND'|'OR'|'LIKE'|'NOT LIKE'|'GLOB'} op @param {any} left @param {any} right */
+  binary: (op, left, right) => node('binary', { op, left, right }),
+  /** @param {any} value */
+  not: (value) => node('not', { value }),
+  /** @param {any} value @param {any[]|object} values @param {boolean} [negate] */
+  in: (value, values, negate = false) => node('in', { value, values, negate }),
+  /** @param {string} name @param {any[]} args @param {{distinct?:boolean}} [options] */
+  call: (name, args, options = {}) => node('call', { name, args, ...options }),
+  /** @param {any} value @param {'INTEGER'|'REAL'|'TEXT'|'BLOB'|'NUMERIC'} type */
+  cast: (value, type) => node('cast', { value, type }),
+  /** @param {any} value @param {'BINARY'|'NOCASE'|'RTRIM'} collation */
+  collate: (value, collation) => node('collate', { value, collation }),
+  /** @param {{when:any,then:any}[]} branches @param {any} [otherwise] */
+  case: (branches, otherwise = null) => node('case', { branches, otherwise }),
+  /** @param {any} query */
+  scalar: (query) => node('scalar', { query }),
+  /** @param {any} query */
+  exists: (query) => node('exists', { query }),
+});
+
+/** Compile expressions once, sharing parameter ordering with nested statements.
+ * Inline mode is for schema expressions, where SQLite disallows placeholders.
+ * @param {{externals?:Record<string,any>, inline?:boolean}} [options] */
+export function relationalEmitter(options = {}) {
+  const params = [];
+  const literal = (value) => {
+    if (!(value === null || typeof value === 'string' || typeof value === 'bigint'
+      || (typeof value === 'number' && Number.isFinite(value)) || value instanceof Uint8Array))
+      return fail('SQL values are null, strings, finite numbers, integers or bytes');
+    if (!options.inline) { params.push(value); return '?'; }
+    if (value === null) return 'NULL';
+    if (typeof value === 'string') {
+      if (value.includes('\0')) fail('NUL text defaults require a data operation');
+      return sqliteDialect.stringLiteral(value);
+    }
+    if (value instanceof Uint8Array) return fail('binary schema defaults are not supported');
+    return String(value);
+  };
+  const expr = (value, depth = 0) => {
+    if (depth > 64) return fail('SQL expression nesting exceeds 64');
+    if (!object(value) || value instanceof Uint8Array) return literal(value);
+    const next = (child) => expr(child, depth + 1);
+    switch (value.$sql) {
+      case 'column':
+        check(value, ['$sql', 'name', 'table'], 'column');
+        return (value.table === undefined ? '' : `${q(value.table)}.`) + q(value.name);
+      case 'value': check(value, ['$sql', 'value'], 'value'); return literal(value.value);
+      case 'param':
+        check(value, ['$sql', 'name'], 'parameter');
+        if (options.inline || !own(options.externals ?? {}, value.name)) return fail(`missing or unavailable SQL parameter '${value.name}'`);
+        return literal(options.externals[value.name]);
+      case 'binary':
+        check(value, ['$sql', 'op', 'left', 'right'], 'binary expression');
+        if (!binary.has(value.op)) return fail('unsupported SQL operator');
+        return `(${next(value.left)} ${value.op} ${next(value.right)})`;
+      case 'not': check(value, ['$sql', 'value'], 'not'); return `(NOT ${next(value.value)})`;
+      case 'in': {
+        check(value, ['$sql', 'value', 'values', 'negate'], 'in');
+        if (value.negate !== undefined && typeof value.negate !== 'boolean') fail('IN negate must be boolean');
+        const left = next(value.value);
+        const right = Array.isArray(value.values) ? value.values.map(next).join(', ') : select(value.values, depth + 1);
+        return `(${left} ${value.negate ? 'NOT IN' : 'IN'} (${right}))`;
+      }
+      case 'call': {
+        check(value, ['$sql', 'name', 'args', 'distinct'], 'function');
+        if (!functions.has(value.name) || !Array.isArray(value.args)) return fail('unsupported SQL function');
+        if (value.distinct !== undefined && typeof value.distinct !== 'boolean') fail('DISTINCT must be boolean');
+        if (value.distinct && value.args.length !== 1) fail('DISTINCT functions require one argument');
+        if (!value.args.length && value.name !== 'count') fail('SQL function requires arguments');
+        return `${value.name.toUpperCase()}(${value.distinct ? 'DISTINCT ' : ''}${value.args.length ? value.args.map(next).join(', ') : '*'})`;
+      }
+      case 'cast':
+        check(value, ['$sql', 'value', 'type'], 'cast');
+        if (!types.has(value.type)) return fail('unsupported SQLite cast type');
+        return `CAST(${next(value.value)} AS ${value.type})`;
+      case 'collate':
+        check(value, ['$sql', 'value', 'collation'], 'collation');
+        if (!collations.has(value.collation)) return fail('unsupported SQLite collation');
+        return `(${next(value.value)} COLLATE ${value.collation})`;
+      case 'case':
+        check(value, ['$sql', 'branches', 'otherwise'], 'case');
+        if (!Array.isArray(value.branches) || !value.branches.length) return fail('CASE requires branches');
+        return `(CASE ${value.branches.map((b) => {
+          check(b, ['when', 'then'], 'case branch');
+          return `WHEN ${next(b.when)} THEN ${next(b.then)}`;
+        }).join(' ')} ELSE ${next(value.otherwise ?? null)} END)`;
+      case 'scalar': case 'exists':
+        check(value, ['$sql', 'query'], 'subquery');
+        return `${value.$sql === 'exists' ? 'EXISTS ' : ''}(${select(value.query, depth + 1)})`;
+      default: return fail('SQL expressions require a supported $sql node');
+    }
+  };
+  const order = (term, depth) => {
+    check(term, ['by', 'direction', 'nulls'], 'order');
+    if (term.direction !== undefined && !['asc', 'desc'].includes(term.direction)) fail('order direction is asc or desc');
+    if (term.nulls !== undefined && !['first', 'last'].includes(term.nulls)) fail('null order is first or last');
+    return expr(term.by, depth) + (term.direction ? ` ${term.direction.toUpperCase()}` : '')
+      + (term.nulls ? ` NULLS ${term.nulls.toUpperCase()}` : '');
+  };
+  const source = (s, depth) => {
+    if (typeof s === 'string') return q(s);
+    check(s, ['table', 'query', 'as'], 'source');
+    if (own(s, 'table') === own(s, 'query')) return fail('a source names one table or subquery');
+    return (own(s, 'table') ? q(s.table) : `(${select(s.query, depth + 1)})`)
+      + (s.as === undefined ? '' : ` AS ${q(s.as)}`);
+  };
+  const projection = (columns, depth) => {
+    if (columns === undefined || columns === '*') return '*';
+    if (!object(columns) || !Object.keys(columns).length) return fail('columns must be a nonempty projection or *');
+    return Object.entries(columns).map(([name, value]) => `${expr(value, depth)} AS ${q(name)}`).join(', ');
+  };
+  const window = (value, name) => {
+    if (!Number.isSafeInteger(value) || value < 0) fail(`${name} must be a nonnegative safe integer`);
+    return value;
+  };
+  const select = (spec, depth = 0) => {
+    if (depth > 64) return fail('SQL query nesting exceeds 64');
+    check(spec, ['from', 'columns', 'where', 'joins', 'groupBy', 'having', 'orderBy', 'limit', 'offset', 'distinct', 'union', 'all'], 'select');
+    let out;
+    if (spec.union !== undefined) {
+      if (!Array.isArray(spec.union) || spec.union.length < 2) return fail('UNION requires at least two queries');
+      if (Object.keys(spec).some((key) => !['union', 'all', 'orderBy', 'limit', 'offset'].includes(key))) fail('UNION cannot also declare a selection');
+      if (spec.all !== undefined && typeof spec.all !== 'boolean') fail('UNION all must be boolean');
+      out = spec.union.map((part) => `SELECT * FROM (${select(part, depth + 1)})`).join(spec.all ? ' UNION ALL ' : ' UNION ');
+    }
+    else {
+      if (spec.all !== undefined) fail('all requires UNION');
+      if (spec.distinct !== undefined && typeof spec.distinct !== 'boolean') fail('distinct must be boolean');
+      out = `SELECT ${spec.distinct ? 'DISTINCT ' : ''}${projection(spec.columns, depth)}`;
+      if (spec.from !== undefined) out += ` FROM ${source(spec.from, depth)}`;
+      if (spec.joins !== undefined) {
+        if (spec.from === undefined || !Array.isArray(spec.joins)) fail('joins require a FROM source and a list');
+        for (const join of spec.joins) {
+          check(join, ['source', 'type', 'on'], 'join');
+          const type = join.type ?? 'inner';
+          if (!['inner', 'left', 'cross'].includes(type)) fail('unsupported join type');
+          if (type === 'cross' ? own(join, 'on') : !own(join, 'on')) fail('inner/left joins require ON; cross joins have no ON');
+          out += ` ${type.toUpperCase()} JOIN ${source(join.source, depth)}`;
+          if (type !== 'cross') out += ` ON ${expr(join.on, depth)}`;
+        }
+      }
+      if (own(spec, 'where')) out += ` WHERE ${expr(spec.where, depth)}`;
+      if (spec.groupBy !== undefined) {
+        if (!Array.isArray(spec.groupBy) || !spec.groupBy.length) fail('groupBy must be nonempty');
+        out += ` GROUP BY ${spec.groupBy.map((v) => expr(v, depth)).join(', ')}`;
+      }
+      if (own(spec, 'having')) out += ` HAVING ${expr(spec.having, depth)}`;
+    }
+    if (spec.orderBy !== undefined) {
+      if (!Array.isArray(spec.orderBy) || !spec.orderBy.length) fail('orderBy must be nonempty');
+      out += ` ORDER BY ${spec.orderBy.map((term) => order(term, depth)).join(', ')}`;
+    }
+    if (spec.limit !== undefined) out += ` LIMIT ${window(spec.limit, 'limit')}`;
+    if (spec.offset !== undefined) out += `${spec.limit === undefined ? ' LIMIT -1' : ''} OFFSET ${window(spec.offset, 'offset')}`;
+    return out;
+  };
+  const mutation = (spec) => {
+    check(spec, ['op', 'table', 'set', 'where', 'values', 'source', 'columns', 'conflict', 'ignore', 'returning', 'reporting'], 'mutation');
+    const table = q(spec.table);
+    let out;
+    if (spec.op === 'update' || spec.op === 'delete') {
+      if (!own(spec, 'where')) fail('update/delete require an explicit where (use 1 for all rows)');
+      for (const key of ['values', 'source', 'columns', 'conflict', 'ignore']) if (own(spec, key)) fail(`${key} requires insert`);
+      if (spec.op === 'delete' && (own(spec, 'set') || own(spec, 'reporting'))) fail('delete has no assignments or reporting policy');
+      if (spec.reporting !== undefined && !['matched', 'changed'].includes(spec.reporting)) fail('reporting is matched or changed');
+      if (spec.op === 'update') {
+        if (!object(spec.set) || !Object.keys(spec.set).length) fail('update requires assignments');
+        out = `UPDATE ${table} SET ${Object.entries(spec.set).map(([name, v]) => `${q(name)} = ${expr(v)}`).join(', ')}`;
+      }
+      else out = `DELETE FROM ${table}`;
+      out += ` WHERE ${expr(spec.where)}`;
+      if (spec.reporting === 'changed') out += ` AND (${Object.entries(spec.set).map(([name, v]) =>
+        `${q(name)} COLLATE BINARY IS NOT ${expr(v)}`).join(' OR ')})`;
+    }
+    else if (spec.op === 'insert') {
+      for (const key of ['set', 'where', 'reporting']) if (own(spec, key)) fail(`${key} is not an insert member`);
+      if (spec.ignore !== undefined && typeof spec.ignore !== 'boolean') fail('ignore must be boolean');
+      if (own(spec, 'values') === own(spec, 'source')) fail('insert requires values or a source query');
+      let names;
+      let input;
+      if (own(spec, 'source')) {
+        names = spec.columns;
+        if (!Array.isArray(names) || !names.length || new Set(names).size !== names.length) fail('insert-select requires distinct target columns');
+        input = `SELECT * FROM (${select(spec.source)}) WHERE 1`;
+      }
+      else {
+        if (own(spec, 'columns')) fail('literal inserts take column names from values');
+        if (!object(spec.values)) fail('insert values must be an object');
+        names = Object.keys(spec.values);
+        input = names.length ? `VALUES (${names.map((name) => expr(spec.values[name])).join(', ')})` : 'DEFAULT VALUES';
+      }
+      out = `INSERT${spec.ignore ? ' OR IGNORE' : ''} INTO ${table}`
+        + (names.length ? ` (${names.map(q).join(', ')})` : '') + ` ${input}`;
+      if (spec.conflict !== undefined) {
+        if (!names.length) fail('DEFAULT VALUES cannot carry an upsert clause');
+        const conflict = spec.conflict;
+        check(conflict, ['target', 'where', 'action', 'set', 'updateWhere'], 'conflict');
+        if (!['nothing', 'update'].includes(conflict.action)) fail('conflict action is nothing or update');
+        out += ' ON CONFLICT';
+        if (conflict.target !== undefined) {
+          if (!Array.isArray(conflict.target) || !conflict.target.length) fail('conflict target must be nonempty');
+          // Conflict predicates and index expressions must be literal
+          // schema expressions, otherwise SQLite cannot match the index.
+          const schema = relationalEmitter({ inline: true });
+          out += ` (${conflict.target.map((term) => typeof term === 'string' ? q(term) : schema.expr(term)).join(', ')})`;
+          if (own(conflict, 'where')) out += ` WHERE ${schema.expr(conflict.where)}`;
+        }
+        else if (own(conflict, 'where')) fail('a conflict predicate requires a target');
+        if (conflict.action === 'nothing') {
+          if (own(conflict, 'set') || own(conflict, 'updateWhere')) fail('DO NOTHING has no update assignments');
+          out += ' DO NOTHING';
+        }
+        else {
+          if (!object(conflict.set) || !Object.keys(conflict.set).length) fail('conflict update requires assignments');
+          out += ` DO UPDATE SET ${Object.entries(conflict.set).map(([name, v]) => `${q(name)} = ${expr(v)}`).join(', ')}`;
+          if (own(conflict, 'updateWhere')) out += ` WHERE ${expr(conflict.updateWhere)}`;
+        }
+      }
+    }
+    else return fail('mutation op is insert, update or delete');
+    if (spec.returning !== undefined) out += ` RETURNING ${projection(spec.returning, 0)}`;
+    return out;
+  };
+  return { expr, select, mutation, order, params };
+}
+
+/** Produce reviewable, bound SQLite SQL from structural data.
+ * @param {any} document @param {{externals?:Record<string,any>}} [options]
+ * @returns {RelationalPlan} */
+export function planRelational(document, options) {
+  const emitter = relationalEmitter(options);
+  const writing = object(document) && own(document, 'op');
+  return { sql: writing ? emitter.mutation(document) : emitter.select(document),
+    params: emitter.params, access: writing ? 'write' : 'read' };
+}
+
+/** Native SQLite operations without a model store. Raw text and Uint8Array
+ * values travel directly through the driver, including synchronous cursors.
+ * @param {any} connection */
+export function relational(connection) {
+  if (connection.dialect.name !== 'sqlite' || !connection.synchronous) fail('relational operations require a synchronous SQLite connection');
+  const read = (document, options) => {
+    if (connection.mustQueue) fail('synchronous reads cannot enter another transaction');
+    const plan = planRelational(document, options);
+    if (plan.access !== 'read') fail('a read method requires a select document');
+    return plan;
+  };
+  return Object.freeze({
+    plan: planRelational,
+    all(document, options = undefined) {
+      const plan = read(document, options);
+      return chain(connection.prepare(plan.sql, { readOnly: true }), (s) => s.all(plan.params));
+    },
+    get(document, options = undefined) {
+      const plan = read(document, options);
+      return chain(connection.prepare(plan.sql, { readOnly: true }), (s) => s.get(plan.params));
+    },
+    iterate(document, options = undefined) {
+      const plan = read(document, options);
+      return createSyncCursor({ ...rowClassOf(connection),
+        open: () => {
+          if (connection.mustQueue) fail('synchronous iteration cannot enter another transaction');
+          return connection.prepare(plan.sql, { readOnly: true, ephemeral: true }).iterate(plan.params);
+        },
+        items: (row) => [row],
+      });
+    },
+    execute(document, options = undefined) {
+      if (connection.mustQueue) fail('synchronous mutation cannot wait for another transaction');
+      const plan = planRelational(document, options);
+      if (plan.access !== 'write') fail('execute requires a mutation document');
+      return connection.transaction(() => chain(connection.prepare(plan.sql), (s) =>
+        document.returning !== undefined ? chain(s.all(plan.params), (rows) => ({ affected: rows.length, rows }))
+          : chain(s.run(plan.params), (result) => ({ affected: Number(result.changes), lastInsertRowid: result.lastInsertRowid }))));
+    },
+  });
+}

package/src/dialects/sqlite-schema.js

@@ -0,0 +1,142 @@
+//@ts-check
+/** Column-first SQLite schema programs. No SQL strings are accepted as expressions. */
+import { DbCompileError } from '../errors.js';
+import { relationalEmitter, relationalIdentifier as q } from './sqlite-relational.js';
+
+const fail = (message) => { throw new DbCompileError('JD0005', message); };
+const check = (v, keys, label) => {
+  if (!v || typeof v !== 'object' || Array.isArray(v)) fail(`${label} must be an object`);
+  for (const key of Object.keys(v)) if (!keys.includes(key)) fail(`unknown ${label} member '${key}'`);
+};
+const list = (values, label) => {
+  if (!Array.isArray(values) || !values.length || new Set(values).size !== values.length) fail(`${label} must be a nonempty distinct list`);
+  return values.map(q).join(', ');
+};
+const action = (value) => {
+  if (!['cascade', 'restrict', 'no action', 'set null', 'set default'].includes(value)) fail('unsupported foreign-key action');
+  return value.toUpperCase();
+};
+
+/** Validate a structural table definition and retain its explicit column order.
+ * @param {any} definition @returns {any} */
+export function defineTable(definition) {
+  planTable(definition);
+  return structuredClone(definition);
+}
+
+/** Render table, indexes and triggers as independently reviewable statements.
+ * @param {any} definition @returns {{table:string,createSql:string[],expected:any}} */
+export function planTable(definition) {
+  check(definition, ['name', 'columns', 'primaryKey', 'constraints', 'indexes', 'triggers', 'strict', 'withoutRowid'], 'table');
+  const table = q(definition.name);
+  if (!Array.isArray(definition.columns) || !definition.columns.length) fail('table columns must be nonempty');
+  for (const key of ['strict', 'withoutRowid']) if (definition[key] !== undefined && typeof definition[key] !== 'boolean') fail(`${key} must be boolean`);
+  for (const key of ['constraints', 'indexes', 'triggers']) if (definition[key] !== undefined && !Array.isArray(definition[key])) fail(`${key} must be a list`);
+  const emitter = relationalEmitter({ inline: true });
+  const names = new Set();
+  let inlineKey = false;
+  const columns = definition.columns.map((column) => {
+    check(column, ['name', 'type', 'nullable', 'default', 'collation', 'identity', 'check', 'generated', 'stored'], 'column definition');
+    const name = q(column.name);
+    if (names.has(column.name.toLowerCase())) fail('physical column names must be distinct');
+    names.add(column.name.toLowerCase());
+    if (!['INTEGER', 'REAL', 'TEXT', 'BLOB', 'NUMERIC', 'ANY'].includes(column.type)) fail('unsupported SQLite column type');
+    if (definition.strict && column.type === 'NUMERIC') fail('STRICT tables do not support NUMERIC');
+    if (column.nullable !== undefined && typeof column.nullable !== 'boolean') fail('nullable must be boolean');
+    if (column.stored !== undefined && (typeof column.stored !== 'boolean' || column.generated === undefined)) fail('stored requires a generated expression');
+    let out = `${name} ${column.type}`;
+    if (column.identity !== undefined) {
+      if (!['rowid', 'autoincrement'].includes(column.identity) || column.type !== 'INTEGER'
+        || definition.withoutRowid || definition.primaryKey?.length !== 1
+        || definition.primaryKey[0] !== column.name || column.generated !== undefined) fail('identity requires a single INTEGER rowid primary key');
+      inlineKey = true;
+      out += ` PRIMARY KEY${column.identity === 'autoincrement' ? ' AUTOINCREMENT' : ''}`;
+    }
+    if (column.nullable === false) out += ' NOT NULL';
+    if (column.collation !== undefined) {
+      if (!['BINARY', 'NOCASE', 'RTRIM'].includes(column.collation)) fail('unsupported column collation');
+      out += ` COLLATE ${column.collation}`;
+    }
+    if (Object.hasOwn(column, 'default')) out += ` DEFAULT (${emitter.expr(column.default)})`;
+    if (column.check !== undefined) out += ` CHECK (${emitter.expr(column.check)})`;
+    if (column.generated !== undefined) {
+      if (Object.hasOwn(column, 'default')) fail('a generated column cannot have a default');
+      out += ` GENERATED ALWAYS AS (${emitter.expr(column.generated)}) ${column.stored ? 'STORED' : 'VIRTUAL'}`;
+    }
+    return out;
+  });
+  const members = (values) => {
+    const text = list(values, 'constraint columns');
+    if (values.some((name) => !names.has(name.toLowerCase()))) fail('constraint names an undeclared column');
+    return text;
+  };
+  if (definition.primaryKey !== undefined && !inlineKey) columns.push(`PRIMARY KEY (${members(definition.primaryKey)})`);
+  if (definition.withoutRowid && !definition.primaryKey?.length) fail('WITHOUT ROWID requires a primary key');
+  for (const constraint of definition.constraints ?? []) {
+    check(constraint, ['kind', 'name', 'columns', 'expression', 'table', 'references', 'onDelete', 'onUpdate', 'deferred'], 'constraint');
+    const prefix = constraint.name === undefined ? '' : `CONSTRAINT ${q(constraint.name)} `;
+    if (constraint.kind === 'unique') columns.push(`${prefix}UNIQUE (${members(constraint.columns)})`);
+    else if (constraint.kind === 'check') columns.push(`${prefix}CHECK (${emitter.expr(constraint.expression)})`);
+    else if (constraint.kind === 'foreignKey') {
+      if (constraint.columns?.length !== constraint.references?.length) fail('foreign-key columns must have equal arity');
+      if (constraint.deferred !== undefined && typeof constraint.deferred !== 'boolean') fail('deferred must be boolean');
+      columns.push(`${prefix}FOREIGN KEY (${members(constraint.columns)}) REFERENCES ${q(constraint.table)} (${list(constraint.references, 'references')})`
+        + (constraint.onDelete === undefined ? '' : ` ON DELETE ${action(constraint.onDelete)}`)
+        + (constraint.onUpdate === undefined ? '' : ` ON UPDATE ${action(constraint.onUpdate)}`)
+        + (constraint.deferred ? ' DEFERRABLE INITIALLY DEFERRED' : ''));
+    }
+    else fail('constraint kind is unique, check or foreignKey');
+    const keys = constraint.kind === 'unique' ? ['kind', 'name', 'columns']
+      : constraint.kind === 'check' ? ['kind', 'name', 'expression']
+        : ['kind', 'name', 'columns', 'table', 'references', 'onDelete', 'onUpdate', 'deferred'];
+    check(constraint, keys, `${constraint.kind} constraint`);
+  }
+  const createSql = [`CREATE TABLE IF NOT EXISTS ${table} (${columns.join(', ')})`
+    + (definition.withoutRowid ? ' WITHOUT ROWID' : '')
+    + (definition.strict ? `${definition.withoutRowid ? ',' : ''} STRICT` : '')];
+  const objects = new Set([definition.name.toLowerCase()]);
+  const objectName = (name) => {
+    const out = q(name);
+    if (objects.has(name.toLowerCase())) fail('schema object names must be distinct');
+    objects.add(name.toLowerCase()); return out;
+  };
+  for (const index of definition.indexes ?? []) {
+    check(index, ['name', 'terms', 'unique', 'where'], 'index');
+    if (!Array.isArray(index.terms) || !index.terms.length) fail('index terms must be nonempty');
+    if (index.unique !== undefined && typeof index.unique !== 'boolean') fail('index unique must be boolean');
+    if (index.terms.some((term) => term?.nulls !== undefined)) fail('SQLite index terms cannot declare NULLS FIRST/LAST');
+    createSql.push(`CREATE ${index.unique ? 'UNIQUE ' : ''}INDEX IF NOT EXISTS ${objectName(index.name)} ON ${table} `
+      + `(${index.terms.map((term) => emitter.order(term, 0)).join(', ')})`
+      + (index.where === undefined ? '' : ` WHERE ${emitter.expr(index.where)}`));
+  }
+  for (const trigger of definition.triggers ?? []) {
+    check(trigger, ['name', 'timing', 'event', 'of', 'when', 'steps'], 'trigger');
+    if (!['before', 'after'].includes(trigger.timing) || !['insert', 'update', 'delete'].includes(trigger.event)) fail('unsupported trigger timing or event');
+    if (trigger.of !== undefined && trigger.event !== 'update') fail('UPDATE OF requires an update trigger');
+    if (!Array.isArray(trigger.steps) || !trigger.steps.length) fail('trigger steps must be nonempty');
+    const steps = trigger.steps.map((step) => {
+      if (!step || typeof step !== 'object' || Array.isArray(step)) fail('a trigger step must be a mutation or raise object');
+      if (Object.hasOwn(step, 'raise')) {
+        check(step, ['raise'], 'raise step');
+        check(step.raise, ['action', 'message'], 'raise');
+        if (!['abort', 'fail', 'rollback', 'ignore'].includes(step.raise.action)) fail('unsupported trigger RAISE action');
+        if (step.raise.action === 'ignore') {
+          if (step.raise.message !== undefined) fail('RAISE IGNORE has no message');
+          return 'SELECT RAISE(IGNORE)';
+        }
+        if (typeof step.raise.message !== 'string') fail('RAISE requires a string message');
+        return `SELECT RAISE(${step.raise.action.toUpperCase()}, ${emitter.expr(step.raise.message)})`;
+      }
+      if (step.returning !== undefined) fail('triggers cannot use RETURNING');
+      return emitter.mutation(step);
+    });
+    createSql.push(`CREATE TRIGGER IF NOT EXISTS ${objectName(trigger.name)} ${trigger.timing.toUpperCase()} ${trigger.event.toUpperCase()}`
+      + (trigger.of === undefined ? '' : ` OF ${members(trigger.of)}`) + ` ON ${table}`
+      + (trigger.when === undefined ? '' : ` WHEN ${emitter.expr(trigger.when)}`)
+      + ` BEGIN ${steps.join('; ')}; END`);
+  }
+  return { table: definition.name, createSql, expected: {
+    columns: definition.columns.map((c) => ({ name: c.name, type: c.type, generated: c.generated !== undefined })),
+    indexes: (definition.indexes ?? []).map((i) => ({ name: i.name, unique: i.unique === true, terms: i.terms })),
+  } };
+}

package/src/dialects/sqlite.js

@@ -494,3 +494,20 @@ export const sqliteDialect = createDialect({
   },
   readChecks: sqliteChecks,
 });
+
+/** SQLite schema inspection and identity preservation statements. */
+export const sqliteTableMigration = Object.freeze({
+    schema: () => "SELECT type,name,tbl_name,sql FROM sqlite_schema WHERE sql IS NOT NULL AND substr(name,1,7) <> 'sqlite_' ORDER BY type,name",
+    tableList: () => 'PRAGMA table_list',
+    sequenceExists: () => "SELECT 1 AS present FROM sqlite_schema WHERE name='sqlite_sequence'",
+    sequence: () => 'SELECT CAST(seq AS TEXT) AS seq FROM sqlite_sequence WHERE name=?',
+    raiseSequence: () => 'UPDATE sqlite_sequence SET seq=MAX(seq,CAST(? AS INTEGER)) WHERE name=?',
+    seedSequence: () => 'INSERT INTO sqlite_sequence(name,seq) SELECT ?,CAST(? AS INTEGER) WHERE NOT EXISTS(SELECT 1 FROM sqlite_sequence WHERE name=?)',
+});
+
+/** Infer the storage declaration for a physical codec.
+ * @param {string} codec @returns {string} */
+export function sqlitePhysicalColumnType(codec) {
+  return ['integer', 'bigint', 'boolean', 'epoch-ms'].includes(codec)
+    ? 'INTEGER' : codec === 'number' ? 'REAL' : codec === 'blob-hex' ? 'BLOB' : 'TEXT';
+}

package/src/drivers/bun.js

@@ -21,6 +21,8 @@
 import { lazyOpen, openConnection } from '../driver.js';
 import { sqliteDialect } from '../dialects/sqlite.js';
 import { PRAGMA_NAMES } from '../pragmas.js';
+import { writeSqliteSnapshot } from './snapshot.js';
+export { snapshotDatabase } from './snapshot.js';
 
 /**
  * Adapt an already-constructed `bun:sqlite` `Database` (or any object
@@ -37,6 +39,7 @@ export function adaptBunDatabase(db, options) {
   /** @type {Set<WeakRef<any>>} */
   const statements = new Set();
   const collected = new FinalizationRegistry((ref) => statements.delete(ref));
+  let changesStatement;
   const raw = {
     ...(options?.backup ? { backup: options.backup } : {}),
     /** @param {string} sql */
@@ -50,7 +53,13 @@ export function adaptBunDatabase(db, options) {
         collected.register(statement, ref, ref);
       }
       return {
-        run: (params = []) => statement.run(...params),
+        run: (params = []) => {
+          const result = statement.run(...params);
+          // Bun's result can include trigger side effects. The driver
+          // contract counts the data statement's own affected rows.
+          changesStatement ??= db.prepare('SELECT changes() AS changes');
+          return { ...result, changes: changesStatement.get().changes };
+        },
         // the driver contract says a missing row reads UNDEFINED;
         // bun:sqlite answers null — normalize at the seam, or every
         // create-or-verify and absence check misfires
@@ -60,12 +69,21 @@ export function adaptBunDatabase(db, options) {
         // driver-level wrapper composes one over `all` when it does not,
         // and `iterate` stays absent here so that fallback is reached
         ...(typeof statement.iterate === 'function'
-          ? { iterate: (params = []) => statement.iterate(...params) }
+          ? { *iterate(params = []) {
+            // Bun's iterator.return() does not reset the native statement.
+            // Give each cursor its own statement and finalize on every exit;
+            // cached queries and concurrent cursors remain independently usable.
+            const cursorStatement = db.prepare(sql);
+            try { yield* cursorStatement.iterate(...params); }
+            finally { cursorStatement.finalize?.(); }
+          } }
           : undefined),
       };
     },
     close: () => {
       const errors = [];
+      try { changesStatement?.finalize?.(); }
+      catch (error) { errors.push(error); }
       for (const ref of statements) {
         collected.unregister(ref);
         try {
@@ -115,20 +133,13 @@ export function adaptBunDatabase(db, options) {
  */
 export function fromBunModule(mod, path, options) {
   const db = options?.readOnly === true ? new mod.Database(path, { readonly: true }) : new mod.Database(path);
-  const backup = typeof db.serialize !== 'function' ? undefined : {
+  const backup = {
     snapshot: true,
-    copy: async (target, copyOptions) => {
-      const bytes = db.serialize();
-      const pageSize = ((bytes[16] << 8) | bytes[17]) || 65536;
-      const pages = bytes.length / (pageSize === 1 ? 65536 : pageSize);
-      copyOptions?.progress?.({ totalPages: pages, remainingPages: pages });
-      const fs = await import('node:fs/promises');
-      const file = await fs.open(target, 'wx');
-      try { await file.writeFile(bytes); await file.sync(); }
-      finally { await file.close(); }
-      copyOptions?.progress?.({ totalPages: pages, remainingPages: 0 });
-      return pages;
-    },
+    copy: (target, copyOptions) => writeSqliteSnapshot(target, () => {
+      const statement = db.prepare('VACUUM INTO ?');
+      try { return statement.run(target); }
+      finally { statement.finalize?.(); }
+    }, copyOptions),
     rename: (from, to) => import('node:fs/promises').then((fs) => fs.rename(from, to)),
     remove: (target) => import('node:fs/promises').then((fs) => fs.rm(target, { force: true })),
   };

package/src/drivers/node.js

@@ -120,6 +120,8 @@ export function nodeDriver() {
   });
 }
 
+export { snapshotDatabase } from './snapshot.js';
+
 export {
   readDocuments, readJsonDocuments, readJsonlDocuments, readCollectionBundle,
   openAtomicTarget, openStreamTarget, openNullTarget,

package/src/drivers/snapshot.js

@@ -0,0 +1,49 @@
+//@ts-check
+/** Disk-backed SQLite snapshots shared by the Node and Bun bindings. */
+import { DbCompileError } from '../errors.js';
+
+/** Reserve a new destination and fill it through SQLite, never a JS image.
+ * @param {string} target @param {() => any} write
+ * @param {{progress?:Function}} [options] @returns {Promise<number>} */
+export async function writeSqliteSnapshot(target, write, options) {
+  if (typeof target !== 'string' || !target || target.includes('\0')) throw new TypeError('snapshot target must be a nonempty path');
+  const fs = await import('node:fs/promises');
+  const file = await fs.open(target, 'wx');
+  let complete = false;
+  try {
+    await write();
+    await file.sync();
+    const header = new Uint8Array(100);
+    const reader = await fs.open(target, 'r');
+    try { await reader.read(header, 0, header.length, 0); }
+    finally { await reader.close(); }
+    const encoded = (header[16] << 8) | header[17];
+    const pageSize = encoded === 1 ? 65536 : encoded;
+    const size = (await file.stat()).size;
+    const pages = size / pageSize;
+    options?.progress?.({ totalPages: pages, remainingPages: 0 });
+    complete = true;
+    return pages;
+  }
+  finally {
+    await file.close();
+    if (!complete) await fs.rm(target, { force: true });
+  }
+}
+
+/** Create a consistent, bounded-memory snapshot on a new path, including
+ * committed WAL data. Does not open a model store or replace a target.
+ * SQLite's page caches bound working memory; no serialize/hex image is built.
+ * @param {any} connection @param {string} target
+ * @returns {Promise<{path:string,pages:number}>} */
+export async function snapshotDatabase(connection, target) {
+  if (connection.dialect.name !== 'sqlite' || !connection.synchronous)
+    throw new DbCompileError('JD0038', 'snapshotDatabase requires a synchronous SQLite connection');
+  const write = () => connection.prepare('VACUUM INTO ?').run([target]);
+  // Acquire ownership before asynchronous filesystem work. Acquiring it
+  // afterwards would queue behind an outer transaction awaiting this call.
+  const snapshot = () => writeSqliteSnapshot(target, write);
+  const pages = await (typeof connection.exclusively === 'function'
+    ? connection.exclusively(snapshot, 'a database snapshot') : snapshot());
+  return { path: target, pages };
+}