@jarenjs/db 0.75.0 → 0.83.3

package/src/algebra.js

@@ -335,7 +335,23 @@ export function planOrder(plan) {
   if (plan === null || plan === undefined) return null;
   if (plan.alg === 'entity-select' || plan.alg === 'entity-join') {
     if (plan.aggregate !== null) return null;
-    return effectiveOrder(plan.order, { bindings: plan.bindings.map((b) => b.name) });
+    const bindings = plan.bindings;
+    const ties = bindings.flatMap((binding) => binding.keys === undefined
+      ? [identityTerm(binding.name)] : binding.keys.map((column) => ({
+        source: 'column', binding: binding.name, column, path: null,
+        desc: false, nullsFirst: true, tieBreaker: true,
+      })));
+    if (plan.group) {
+      const group = plan.group;
+      const terms = group.order === 'first-seen' ? [] : group.order.map((term) => ({
+        source: 'group', binding: bindings[0].name,
+        column: term.aggregate === undefined ? group.keys[term.index].as : `a${term.aggregate}`,
+        path: null, desc: term.desc, nullsFirst: term.nullsFirst, tieBreaker: false,
+      }));
+      return [...terms, ...ties.map((term) => ({ ...term, source: 'group',
+        column: term.column, tieBreaker: group.order !== 'first-seen' }))];
+    }
+    return [...(plan.order ?? []).map((term) => declaredTerm(term, term.binding)), ...ties];
   }
   if (plan.aggregate !== null || plan.rank !== null) return null;
   if (plan.bucket !== null) {

package/src/backup.js

@@ -20,13 +20,13 @@
  * platform reports progress (`rate` pages per step): the platform
  * itself takes no signal, so the signal is checked in the progress
  * callback and a throw there is what stops the pump. There is no
- * progress event with a zero remainder — the platform's completion
- * signal is the resolved copy, which answers the page total — so
- * progress events are handed on verbatim and completion is the promise.
+ * guaranteed terminal progress event — the platform's completion signal
+ * is the resolved copy, which answers the page total. Cancellation is
+ * checked again before publication, including after a terminal event.
  *
  * This module imports no runtime builtin: the copy, the rename and the
- * removal are the driver's primitives (`connection.backup`), present on
- * the Node binding and declared absent elsewhere.
+ * removal are the driver's primitives (`connection.backup`), supplied by
+ * Node online backup and Bun serialized snapshots.
  */
 
 import { DbRuntimeError, wrapDriverError } from './errors.js';
@@ -139,7 +139,8 @@ export function createBackup({ connection, readOnly, gated, checkpoint, random,
         };
         let copying;
         try {
-          copying = files.copy(tmpPath, rate === undefined ? { progress } : { rate, progress });
+          const copy = () => files.copy(tmpPath, rate === undefined ? { progress } : { rate, progress });
+          copying = files.snapshot === true ? gated(copy, 'a snapshot backup') : copy();
         }
         catch (error) {
           return discard(aborted ?? failed(error));
@@ -153,7 +154,11 @@ export function createBackup({ connection, readOnly, gated, checkpoint, random,
           attempt(() => files.rename(tmpPath, targetPath), failed),
           () => Object.freeze({ path: targetPath, pages: Number(pages), checkpoint: checkpointed ?? null }));
         return toPromise(copying)
-          .then((pages) => toPromise(publish(pages)))
+          .then((pages) => {
+            if (signal?.aborted === true) { aborted = cancelled(signal); throw aborted; }
+            callable(options, 'the temporary file was removed and the target path was not written');
+            return toPromise(publish(pages));
+          })
           .catch((error) => discard(aborted ?? failed(error)));
       });
     },

package/src/cursor.js

@@ -345,6 +345,12 @@ export function admitSyncCursor(cursor, admit) {
 /** The page size a page takes when none is given. */
 export const PAGE_LIMIT_DEFAULT = 100;
 
+/** Classify the cursor's byte, row and work refusals at structural adapter boundaries.
+ * @param {any} error @returns {boolean} */
+export function isCursorBudgetError(error) {
+  return ['JD2073', 'JD2074', 'JD2076'].includes(error?.code);
+}
+
 /**
  * Drain a cursor into ONE page: at most `limit` items, at most `maxBytes`
  * serialised bytes (`null` for no byte bound), stopping at an item
@@ -357,9 +363,13 @@ export const PAGE_LIMIT_DEFAULT = 100;
  * An item that does not fit beside earlier ones ends the page before
  * it: `hasMore` is true and the continuation is the last delivered
  * item's, so the next page starts at the item that did not fit.
- * `hasMore` is otherwise decided by one peek past `limit`.
+ * `hasMore` is otherwise decided by one peek past `limit`. With
+ * `lookahead: false`, a full page reports `hasMore: null` and `work`
+ * records each consumed root and its serialized payload bytes, including
+ * the root that stopped the page at its byte boundary. Failures preserve
+ * those counters on the error; pages using the default keep their shape.
  * @param {any} cursor - a `QueryCursor`
- * @param {{ limit: number, maxBytes: number | null, after?: any,
+ * @param {{ limit: number, maxBytes: number | null, after?: any, lookahead?: boolean,
  *   sizeOf: (item: any) => number, continuationOf: (item: any) => any }} options
  * @returns {any} value-or-promise, matching the cursor
  */
@@ -368,10 +378,13 @@ export function drainPage(cursor, options) {
   const after = options.after ?? null;
   const items = [];
   let bytes = 0;
+  const measured = options.lookahead === false;
+  const work = { rows: 0, bytes: 0 };
   let last = after;
   let hasMore = false;
   const finish = () => chain(cursor.return(), () => ({
     items, continuation: items.length > 0 ? last : (hasMore ? after : null), hasMore,
+    ...(measured ? { work: { ...work } } : {}),
   }));
   const consume = (pulled) => {
     if (items.length >= limit) {
@@ -380,7 +393,8 @@ export function drainPage(cursor, options) {
     }
     if (pulled.done === true) return finish();
     const item = pulled.value;
-    const size = maxBytes === null ? 0 : sizeOf(item);
+    const size = maxBytes === null && !measured ? 0 : sizeOf(item);
+    if (measured) { work.rows++; work.bytes += size; }
     if (maxBytes !== null && bytes + size > maxBytes) {
       if (items.length === 0) {
         return chain(cursor.return(), () => {
@@ -393,6 +407,10 @@ export function drainPage(cursor, options) {
     items.push(item);
     bytes += size;
     last = continuationOf(item);
+    if (options.lookahead === false && items.length === limit) {
+      hasMore = null;
+      return finish();
+    }
     return null;
   };
   const step = () => {
@@ -403,7 +421,12 @@ export function drainPage(cursor, options) {
       if (result !== null) return result;
     }
   };
-  return settling(step, () => cursor.return());
+  return settling(step, () => cursor.return(), (error) => {
+    // A refused boundary row was still consumed. Preserve that evidence
+    // through the owning error so a bounded caller cannot report zero work.
+    if (measured && error !== null && typeof error === 'object') error.work = { ...work };
+    return error;
+  });
 }
 
 /** The shared refusal for an indivisible item, including a replicated transaction.

package/src/dag-job.js

@@ -52,7 +52,7 @@ const fingerprint = (value) => hashContent(canonicalizeJson(value ?? null));
  *   concurrency?: number, pollInterval?: number, leaseMs?: number,
  *   owner?: string, renew?: boolean, onOutcome?: (event: any) => void,
  *   backoffBase?: number, backoffCap?: number,
- *   stopGraceMs?: number }} options
+ *   stopGraceMs?: number, effectSafety?: (job: any, context: any) => any }} options
  * @returns {{ start: () => any, stop: (options?: any) => Promise<any>, stats: () => any }}
  */
 export function createDagJobRunner(store, options) {
@@ -215,6 +215,7 @@ export function createDagJobRunner(store, options) {
     owner: options.owner,
     renew: options.renew,
     onOutcome: options.onOutcome,
+    effectSafety: options.effectSafety,
     backoffBase: options.backoffBase,
     backoffCap: options.backoffCap,
     // the runner's declared default for `stop()` with no override; an

package/src/ddl.js

@@ -14,6 +14,7 @@
  * silently indexing the wrong thing.
  */
 
+import { explainMapping } from './model.js';
 import { analyzeQuery } from '@jarenjs/json/query';
 import { DbCompileError } from './errors.js';
 import { chain } from './driver.js';
@@ -902,6 +903,9 @@ export function verifyShape(connection, plan, collection, docPath) {
  *   columnNames: Set<string> }}
  */
 export function planEntity(name, entityMapping, entities, dialect) {
+  if (entityMapping.document === false) return { table: entityMapping.table,
+    physical: { ...entityMapping, triggers: dialect.invariantTriggers?.(entityMapping, entities, dialect) ?? [] }, createSql: [], expected: { columns: [], indexes: [] },
+    columnNames: new Set(entityMapping.columns.map((c) => c.physical)) };
   const storageType = (storage) => dialect.typeFor(storage, 'generated');
   const keyType = (entityName) => {
     const target = entities.entities[entityName];
@@ -1037,3 +1041,12 @@ export function planJoinTable(tableName, join, entities, dialect) {
     },
   };
 }
+
+/** Plan explicit database-enforced persistence rules; never applies them.
+ * @param {any} model @param {{ dialect: any }} options @returns {any[]} */
+export function planInvariants(model, options) {
+  const mapping = explainMapping(model);
+  const dialect = options.dialect;
+  if (typeof dialect.invariantTriggers !== 'function') throw new DbCompileError('JD0005', 'this dialect cannot lower database invariants');
+  return Object.values(mapping.entities).flatMap((entity) => dialect.invariantTriggers(entity, mapping, dialect));
+}

package/src/dialect.js

@@ -185,6 +185,11 @@ function normalizeCapabilities(declared) {
  *   memberPathOf?: (expression: string) => (JsonPathSegment[] | null),
  *   expressionOf?: (expression: string, byName: Record<string, string>) => (any | null),
  *   readGenerated?: (rows: any[]) => { name: string, expression: string }[],
+ *   physicalRead?: (codec: string, sql: string) => string,
+ *   mutationRowGuard?: (count: string, limit: number) => string,
+ *   codepoint?: (value: string) => string,
+ *   physicalTypeMatches?: (codec: string, type: string) => boolean,
+ *   invariantTriggers?: (mapping: any, all: any, dialect: any) => any[],
  *   readChecks?: (rows: any[]) => { name: string, column?: string, values?: any[] }[],
  *   introspect: { version: () => string, compileOptions: () => string,
  *     pragma: (name: string) => string,
@@ -642,6 +647,11 @@ export function createDialect(spec) {
      */
     readGenerated: spec.readGenerated,
     readChecks: spec.readChecks,
+    physicalRead: spec.physicalRead,
+    mutationRowGuard: spec.mutationRowGuard,
+    codepoint: spec.codepoint,
+    physicalTypeMatches: spec.physicalTypeMatches,
+    invariantTriggers: spec.invariantTriggers,
     explainQuery: spec.explainQuery,
     /** The plan narrative, one line per row the engine answered. */
     explainLines: spec.explainLines,

package/src/dialects/check-read.js

@@ -3,7 +3,7 @@
 
 /** Tokenize catalog SQL without treating quoted text or comments as syntax.
  * @param {string} sql @returns {{ kind: string, value: string }[]} */
-function tokensOf(sql) {
+export function sqlTokens(sql) {
   const tokens = [];
   for (let i = 0; i < sql.length;) {
     const c = sql[i];
@@ -120,7 +120,7 @@ function enumOf(tokens) {
 export function sqliteChecks(rows) {
   const checks = [];
   for (const row of rows) {
-    const tokens = tokensOf(String(row.sql ?? ''));
+    const tokens = sqlTokens(String(row.sql ?? ''));
     // A column's inherited collation changes IN equality even when the
     // CHECK itself names no collation. Refuse conservatively per table.
     const collated = tokens.some((token, i) => token.kind === 'word'
@@ -147,5 +147,5 @@ export function sqliteChecks(rows) {
  * @param {any[]} rows @returns {any[]} neutral constraints */
 export function postgresChecks(rows) {
   return rows.map((row) => ({ name: String(row.name),
-    ...(row.unsafe_collation ? null : enumOf(tokensOf(String(row.expression ?? '')))) }));
+    ...(row.unsafe_collation ? null : enumOf(sqlTokens(String(row.expression ?? '')))) }));
 }

package/src/dialects/invariant-sql.js

@@ -0,0 +1,117 @@
+//@ts-check
+/** SQLite trigger lowering for bounded query predicates over old/new columns. */
+import { DbCompileError } from '../errors.js';
+
+/** @param {any} mapping @param {any} all @param {any} dialect @returns {any[]} */
+export function sqliteInvariantTriggers(mapping, all, dialect) {
+  const q = dialect.quoteIdentifier;
+  const sl = dialect.stringLiteral;
+  const fail = (why) => { throw new DbCompileError('JD0005', `database invariant: ${why}`); };
+  const rules = mapping.invariants ?? [];
+  const columns = mapping.columns;
+  let domains = new Set();
+  const scalar = (value, op) => {
+    if (typeof value === 'string' && value.startsWith('$.')) {
+      if (value === '$.op') return sl(op);
+      const match = /^\$\.(old|new)\.([A-Za-z_][A-Za-z0-9_]*)$/.exec(value);
+      if (!match) return fail(`unsupported record path '${value}'`);
+      const column = columns.find((c) => c.name === match[2]);
+      if (!column || column.null === 'absent' || !['text', 'integer', 'number', 'boolean', 'date', 'datetime'].includes(column.codec)) return fail(`'${match[2]}' needs a scalar column codec`);
+      if ((op === 'insert' && match[1] === 'old') || (op === 'delete' && match[1] === 'new')) return fail('a property of an unavailable record is absent, not SQL NULL');
+      const ref = `${match[1].toUpperCase()}.${q(column.physical)}`;
+      const type = `typeof(${ref})`;
+      let valid = ['integer', 'number', 'boolean'].includes(column.codec)
+        ? column.codec === 'number' ? `${type} IN ('integer', 'real') AND ${ref} BETWEEN -9007199254740991 AND 9007199254740991`
+          : `${type} = 'integer' AND ${column.codec === 'boolean' ? `${ref} IN (0, 1)` : `${ref} BETWEEN -9007199254740991 AND 9007199254740991`}`
+        : `${type} = 'text'`;
+      if (column.null === 'null') valid = `${ref} IS NULL OR (${valid})`;
+      domains.add(`(${valid})`);
+      return `(${ref} COLLATE BINARY)`;
+    }
+    if (value === null) return 'NULL';
+    if (typeof value === 'string') return sl(value);
+    if (typeof value === 'boolean') return value ? '1' : '0';
+    if (typeof value === 'number' && Number.isFinite(value) && (!Number.isInteger(value) || Number.isSafeInteger(value))) return String(value);
+    if (value && typeof value === 'object' && Object.keys(value).length === 1 && Object.hasOwn(value, '$const')) {
+      const literal = value.$const;
+      return typeof literal === 'string' ? sl(literal) : scalar(literal, op);
+    }
+    return fail('only scalar literals and old/new property paths can be lowered');
+  };
+  const typeOf = (value) => {
+    if (typeof value === 'string' && value.startsWith('$.')) {
+      if (value === '$.op') return 'string';
+      const name = value.slice(value.indexOf('.', 2) + 1);
+      const column = columns.find((c) => c.name === name);
+      return column?.codec === 'boolean' ? 'boolean'
+        : ['integer', 'number'].includes(column?.codec) ? 'number' : 'string';
+    }
+    if (value && typeof value === 'object' && Object.hasOwn(value, '$const')) return value.$const === null ? 'null' : typeof value.$const;
+    return value === null ? 'null' : typeof value;
+  };
+  const predicate = (node, op) => {
+    if (typeof node === 'boolean') return node ? '1' : '0';
+    if (!node || typeof node !== 'object' || Array.isArray(node) || Object.keys(node).length !== 1) return fail('predicate must be a bounded query expression');
+    const [key, args] = Object.entries(node)[0];
+    if (key === '$and' || key === '$or') {
+      if (!Array.isArray(args) || !args.length) return fail('logical predicates require operands');
+      return `(${args.map((a) => predicate(a, op)).join(key === '$and' ? ' AND ' : ' OR ')})`;
+    }
+    if (key === '$not') return `(NOT (${predicate(args, op)}))`;
+    const operators = { $eq: 'IS', $ne: 'IS NOT', $lt: '<', $le: '<=', $gt: '>', $ge: '>=' };
+    if (!operators[key] || !Array.isArray(args) || args.length !== 2) return fail(`unsupported predicate '${key}'`);
+    const left = scalar(args[0], op), right = scalar(args[1], op);
+    const lt = typeOf(args[0]), rt = typeOf(args[1]);
+    if (lt !== rt && lt !== 'null' && rt !== 'null') return key === '$ne' ? '1' : '0';
+    const compare = `(${left} ${operators[key]} ${right})`;
+    return key === '$eq' || key === '$ne' ? compare : `COALESCE(${compare}, 0)`;
+  };
+  const changed = columns.filter((c) => c.name !== mapping.version && !c.generated)
+    .map((c) => `OLD.${q(c.physical)} IS NOT NEW.${q(c.physical)}`).join(' OR ') || '0';
+  const out = [];
+  const groups = new Map();
+  const add = (op, stage, rule, when, body) => {
+    const key = `${op}_${stage}`;
+    if (!groups.has(key)) groups.set(key, { op, stage, rules: [], bodies: [] });
+    const group = groups.get(key);
+    group.rules.push(rule); group.bodies.push(`${body}${when ? ` WHERE ${when}` : ''};`);
+  };
+  for (const rule of rules) {
+    if (rule.enforcement !== 'database') continue;
+    if (mapping.document !== false || mapping.kind === 'view') fail('database rules require a writable explicit column layout');
+    for (const op of rule.on) {
+      domains = new Set();
+      const assertion = predicate(rule.assert, op);
+      if (rule.audit !== undefined) {
+        const target = all.entities[rule.audit.entity];
+        if (!target || target.document !== false || target.kind === 'view') fail('audit target must be a mapped application table');
+        if (target === mapping || (target.invariants ?? []).some((r) => r.audit)) fail('recursive or chained audit effects are refused');
+        const names = [], values = [];
+        for (const [member, expression] of Object.entries(rule.audit.values)) {
+          const column = target.columns.find((c) => c.name === member);
+          if (!column || column.generated || !['text', 'integer', 'number', 'boolean'].includes(column.codec)) fail(`audit member '${member}' needs a writable scalar codec`);
+          const expected = column.codec === 'text' ? 'string' : column.codec === 'boolean' ? 'boolean' : 'number';
+          const actual = typeOf(expression);
+          if (actual !== expected && actual !== 'null') fail(`audit member '${member}' needs a matching scalar type`);
+          const value = scalar(expression, op);
+          if (column.null === 'reject') domains.add(`(${value} IS NOT NULL)`);
+          names.push(q(column.physical)); values.push(value);
+        }
+        if (!names.length) fail('audit values cannot be empty');
+        add(op, 'AFTER', rule.name, op === 'update' ? `(${changed})` : '',
+          `INSERT INTO ${q(target.table)} (${names.join(', ')}) SELECT ${values.join(', ')}`);
+      }
+      const when = `${op === 'update' ? `(${changed}) AND ` : ''}(${[...domains, assertion].join(' AND ')}) IS NOT TRUE`;
+      add(op, 'BEFORE', rule.name, when, `SELECT RAISE(ABORT, ${sl(`jaren invariant:${rule.name}`)})`);
+    }
+  }
+  for (const op of ['insert', 'update', 'delete']) {
+    const checks = groups.get(`${op}_BEFORE`);
+    if (!checks) continue;
+    const bodies = [...checks.bodies, ...(groups.get(`${op}_AFTER`)?.bodies ?? [])];
+    const name = `_jaren_rule_${mapping.table.length}_${mapping.table}_${op}`;
+    out.push({ type: 'trigger', name, owner: mapping.table, rule: checks.rules.join(','),
+      sql: `CREATE TRIGGER ${q(name)} AFTER ${op.toUpperCase()} ON ${q(mapping.table)} BEGIN ${bodies.join(' ')} END` });
+  }
+  return out;
+}

package/src/dialects/postgres.js

@@ -563,8 +563,11 @@ export function postgresDialect(options = undefined) {
       // fact the shape check reads beside the name and the type
       columns: (table) =>
         'SELECT a.attname AS name, format_type(a.atttypid, a.atttypmod) AS type, '
-        + "CASE WHEN a.attgenerated <> '' THEN 1 ELSE 0 END AS hidden "
+        + "CASE WHEN a.attgenerated <> '' THEN 1 ELSE 0 END AS hidden, "
+        + 'CASE WHEN a.attnotnull THEN 1 ELSE 0 END AS not_null, '
+        + 'pg_get_expr(d.adbin, d.adrelid) AS default_value '
         + 'FROM pg_attribute a JOIN pg_class c ON c.oid = a.attrelid '
+        + 'LEFT JOIN pg_attrdef d ON d.adrelid = a.attrelid AND d.adnum = a.attnum '
         + 'JOIN pg_namespace n ON n.oid = c.relnamespace '
         + `WHERE c.relname = ${stringLiteral(table)} AND ${inNamespace} `
         + 'AND a.attnum > 0 AND NOT a.attisdropped ORDER BY a.attnum',
@@ -597,6 +600,15 @@ export function postgresDialect(options = undefined) {
         + 'JOIN pg_namespace n ON n.oid = c.relnamespace '
         + `WHERE c.relkind IN ('r', 'p', 'v', 'm') AND ${inNamespace} `
         + 'ORDER BY type, c.relname',
+      objects: () =>
+        "SELECT 'trigger' AS type, t.tgname AS name, c.relname AS owner, "
+        + 'pg_get_triggerdef(t.oid) AS sql FROM pg_trigger t '
+        + 'JOIN pg_class c ON c.oid = t.tgrelid JOIN pg_namespace n ON n.oid = c.relnamespace '
+        + `WHERE NOT t.tgisinternal AND ${inNamespace} UNION ALL `
+        + "SELECT 'index', ci.relname, c.relname, pg_get_indexdef(i.indexrelid) "
+        + 'FROM pg_index i JOIN pg_class c ON c.oid = i.indrelid '
+        + 'JOIN pg_class ci ON ci.oid = i.indexrelid JOIN pg_namespace n ON n.oid = c.relnamespace '
+        + `WHERE ${inNamespace} ORDER BY type, name`,
       generated: (table) =>
         'SELECT a.attname AS name, pg_get_expr(d.adbin, d.adrelid) AS expression '
         + 'FROM pg_attrdef d '
@@ -620,7 +632,7 @@ export function postgresDialect(options = undefined) {
           + "WHEN 'n' THEN 'SET NULL' WHEN 'd' THEN 'SET DEFAULT' ELSE 'NO ACTION' END";
         return 'SELECT tt.relname AS target, sa.attname AS source_column, '
           + `ta.attname AS target_column, ${action('c.confdeltype')} AS on_delete, `
-          + `${action('c.confupdtype')} AS on_update, k.ord - 1 AS seq `
+          + `${action('c.confupdtype')} AS on_update, c.conname AS id, k.ord - 1 AS seq `
           + 'FROM pg_constraint c JOIN pg_class ct ON ct.oid = c.conrelid '
           + 'JOIN pg_namespace n ON n.oid = ct.relnamespace '
           + 'JOIN pg_class tt ON tt.oid = c.confrelid '

package/src/dialects/sqlite.js

@@ -11,6 +11,7 @@
 import { createDialect } from '../dialect.js';
 import { rtreeDdl } from './rtree-ddl.js';
 import { readExpression } from './expression-read.js';
+import { sqliteInvariantTriggers } from './invariant-sql.js';
 import { sqliteChecks } from './check-read.js';
 
 /** @param {string} s */
@@ -428,6 +429,17 @@ export const sqliteDialect = createDialect({
       : `PRAGMA integrity_check(${pragmaValue(limit)})`),
     optimize: () => 'PRAGMA optimize',
   },
+  invariantTriggers: sqliteInvariantTriggers,
+  // The invalid path is evaluated only on overflow and carries a distinct
+  // marker through SQLite's error boundary, before any source row is written.
+  codepoint: (value) => `(${value} COLLATE BINARY)`,
+  mutationRowGuard: (count, limit) => `CASE WHEN ${count} > ${limit} `
+    + "THEN json_extract('{}', 'jaren-mutation-row-bound') ELSE 1 END",
+  physicalRead: (codec, sql) => codec === 'bigint' ? `CAST(${sql} AS TEXT)`
+    : codec === 'blob-hex' ? `CASE WHEN ${sql} IS NULL THEN NULL ELSE hex(${sql}) END` : sql,
+  physicalTypeMatches: (codec, type) => (codec === 'blob-hex' ? /BLOB/
+    : ['integer', 'bigint', 'boolean', 'epoch-ms'].includes(codec) ? /INT/
+      : codec === 'number' ? /REAL|FLOA|DOUB/ : /TEXT|CHAR|CLOB/).test(type),
   introspect: {
     version: () => 'SELECT sqlite_version() AS version',
     // the read-back of one configuration pragma: `PRAGMA name` answers
@@ -438,7 +450,8 @@ export const sqliteDialect = createDialect({
     tableExists: () =>
       "SELECT name FROM sqlite_schema WHERE type = 'table' AND name = ?",
     columns: (table) =>
-      `SELECT name, type, hidden FROM pragma_table_xinfo(${stringLiteral(table)})`,
+      `SELECT name, type, hidden, pk, "notnull" AS not_null, dflt_value AS default_value `
+      + `FROM pragma_table_xinfo(${stringLiteral(table)}) ORDER BY cid`,
     indexes: (table) =>
       `SELECT name, "unique" AS uniq, origin, partial FROM pragma_index_list(${stringLiteral(table)})`,
     indexColumns: (index) =>
@@ -447,7 +460,7 @@ export const sqliteDialect = createDialect({
     dataVersion: () => 'SELECT data_version AS v FROM pragma_data_version',
     foreignKeyList: (table) =>
       `SELECT "table" AS target, "from" AS source_column, "to" AS target_column, `
-      + `on_delete, on_update, seq FROM pragma_foreign_key_list(${stringLiteral(table)}) `
+      + `on_delete, on_update, id, seq, match FROM pragma_foreign_key_list(${stringLiteral(table)}) `
       + 'ORDER BY id, seq',
     // Every schema object one table owns, with the CREATE text SQLite
     // stored verbatim. That text is where the physical facts no pragma
@@ -475,6 +488,9 @@ export const sqliteDialect = createDialect({
     schemaDump: () =>
       "SELECT type, name, tbl_name AS owner, sql FROM sqlite_schema "
       + "WHERE sql IS NOT NULL ORDER BY type, name",
+    objects: () =>
+      'SELECT type, name, tbl_name AS owner, sql FROM sqlite_schema '
+      + "WHERE name NOT LIKE 'sqlite_%' ORDER BY type, name",
   },
   readChecks: sqliteChecks,
 });

package/src/driver.js

@@ -822,6 +822,7 @@ export function finishConnection(raw, dialect, synchronous, capabilities, queueT
     // closed exactly as a statement is
     backup: capabilities.backup === true
       ? Object.freeze({
+        snapshot: raw.backup.snapshot === true,
         copy: (path, options) => { requireOpen(); return raw.backup.copy(path, options); },
         rename: (from, to) => { requireOpen(); return raw.backup.rename(from, to); },
         remove: (path) => { requireOpen(); return raw.backup.remove(path); },

package/src/drivers/bun.js

@@ -27,7 +27,7 @@ import { PRAGMA_NAMES } from '../pragmas.js';
  * with its shape) into a probed connection. Exported so the adapter is
  * exercisable without the builtin.
  * @param {any} db - A Bun `Database`-shaped database
- * @param {{ queueTimeout?: number }} [options]
+ * @param {{ queueTimeout?: number, backup?: any }} [options]
  * @returns {any} a Connection, or a promise of one
  */
 export function adaptBunDatabase(db, options) {
@@ -38,6 +38,7 @@ export function adaptBunDatabase(db, options) {
   const statements = new Set();
   const collected = new FinalizationRegistry((ref) => statements.delete(ref));
   const raw = {
+    ...(options?.backup ? { backup: options.backup } : {}),
     /** @param {string} sql */
     exec: (sql) => db.run(sql),
     /** @param {string} sql */
@@ -91,6 +92,7 @@ export function adaptBunDatabase(db, options) {
     synchronous: true,
     queueTimeout: options?.queueTimeout,
     declared: {
+      backup: options?.backup !== undefined,
       sessions: false,
       userFunctions: false,
       deterministicIndexableFunctions: false,
@@ -112,9 +114,25 @@ export function adaptBunDatabase(db, options) {
  * @returns {any}
  */
 export function fromBunModule(mod, path, options) {
-  return adaptBunDatabase(options?.readOnly === true
-    ? new mod.Database(path, { readonly: true })
-    : new mod.Database(path), options);
+  const db = options?.readOnly === true ? new mod.Database(path, { readonly: true }) : new mod.Database(path);
+  const backup = typeof db.serialize !== 'function' ? undefined : {
+    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;
+    },
+    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 })),
+  };
+  return adaptBunDatabase(db, { ...options, ...(backup ? { backup } : {}) });
 }
 
 /**