@jarenjs/db 0.86.0 → 0.89.0

package/src/ddl.js

@@ -21,6 +21,10 @@ import { chain } from './driver.js';
 import { BBOX_COMPONENTS, BBOX_INDEX_ORDER, derivedMappingFor } from './derive.js';
 import { expressionSql, expressionStem, expressionFunctions } from './expression.js';
 import { planTable } from './dialects/sqlite-schema.js';
+import { comparableDeclaredSql } from './schema-sql.js';
+export { normalizeDeclaredSql, comparableDeclaredSql } from './schema-sql.js';
+
+const MANAGED_SQL_OPTIONS = Object.freeze({ columnOrder: /** @type {const} */ ('ignore') });
 
 /** The fixed physical column names of the 0.1 mapping. */
 export const KEY_COLUMN = 'key';
@@ -620,88 +624,6 @@ export function planCollection(name, collection, dialect, options = undefined) {
   };
 }
 
-/**
- * Normalize a stored `CREATE` statement for comparison: collapse runs of
- * whitespace, drop whitespace around punctuation, and strip the
- * `IF NOT EXISTS` SQLite does not keep. What survives is every token that
- * carries meaning, so two statements compare equal exactly when they
- * declare the same physical object.
- * @param {string} sql
- * @returns {string}
- */
-export function normalizeDeclaredSql(sql) {
-  return String(sql)
-    .replace(/\s+/g, ' ')
-    .replace(/\s*([(),])\s*/g, '$1')
-    .replace(/\bIF NOT EXISTS\s+/i, '')
-    .trim();
-}
-
-/**
- * Split a comma-separated list at TOP-LEVEL commas only, so a
- * `CHECK(x IN (1,2))` or a multi-column constraint stays one item.
- * @param {string} body
- * @returns {string[]}
- */
-function splitTopLevel(body) {
-  /** @type {string[]} */
-  const parts = [];
-  let depth = 0;
-  let quote = '';
-  let start = 0;
-  for (let i = 0; i < body.length; i++) {
-    const c = body[i];
-    if (quote !== '') {
-      if (c === quote) quote = '';
-      continue;
-    }
-    if (c === '"' || c === "'") quote = c;
-    else if (c === '(') depth++;
-    else if (c === ')') depth--;
-    else if (c === ',' && depth === 0) {
-      parts.push(body.slice(start, i));
-      start = i + 1;
-    }
-  }
-  parts.push(body.slice(start));
-  return parts.map((part) => part.trim()).filter((part) => part !== '');
-}
-
-/**
- * A comparable form of one `CREATE` statement.
- *
- * For a TABLE the column definitions compare as a SET, because
- * `ALTER TABLE … ADD COLUMN` can only append — so a migrated table and a
- * freshly built one legitimately differ in column order, and this store
- * never reads a column positionally. Everything else is exact: each
- * column's full definition (type, `PRIMARY KEY`, `NOT NULL`, `DEFAULT`,
- * `CHECK`, `GENERATED … AS`, `REFERENCES … ON DELETE …`), the table
- * constraints, and the trailing table options (`STRICT`,
- * `WITHOUT ROWID`).
- *
- * For an INDEX the text compares whole, because an index IS its order —
- * `(a,b)` and `(b,a)` serve different lookups — as are its partial
- * predicate and each term's collation and direction.
- * @param {string} sql
- * @returns {string}
- */
-export function comparableDeclaredSql(sql) {
-  const normalized = normalizeDeclaredSql(sql);
-  const open = normalized.indexOf('(');
-  const close = normalized.lastIndexOf(')');
-  if (!/^CREATE\s+TABLE\b/i.test(normalized) || open < 0 || close < open)
-    return normalized;
-  const head = normalized.slice(0, open);
-  const options = normalized.slice(close + 1).trim();
-  const items = splitTopLevel(normalized.slice(open + 1, close));
-  // a column definition opens with the quoted column name; anything else
-  // (PRIMARY KEY(...), UNIQUE(...), CHECK(...), FOREIGN KEY(...)) is a
-  // table constraint, and those are unordered too
-  const columns = items.filter((item) => item.startsWith('"')).sort();
-  const constraints = items.filter((item) => !item.startsWith('"')).sort();
-  return `${head}(${[...columns, ...constraints].join(',')})${options}`;
-}
-
 /**
  * The declared-SQL half of verification: compare every schema object the
  * table owns against the statements the plan would have created.
@@ -738,7 +660,7 @@ function verifyDeclaredSql(connection, plan, disagree) {
   // comparison for free.
   const owned = new Set(plan.virtualTables?.map((virtual) => virtual.name) ?? []);
   for (const sql of plan.createSql) {
-    const comparable = comparableDeclaredSql(sql);
+    const comparable = comparableDeclaredSql(sql, MANAGED_SQL_OPTIONS);
     // the object's name is the first quoted identifier in the statement
     const name = /"((?:[^"]|"")*)"/.exec(comparable)?.[1]?.replace(/""/g, '"');
     if (name === undefined || owned.has(name)) continue;
@@ -756,8 +678,8 @@ function verifyDeclaredSql(connection, plan, disagree) {
           disagree(`the model declares the virtual table '${virtual.name}', `
             + 'which the database does not have');
         }
-        const have = comparableDeclaredSql(row.sql);
-        const wanted = comparableDeclaredSql(virtual.createSql);
+        const have = comparableDeclaredSql(row.sql, MANAGED_SQL_OPTIONS);
+        const wanted = comparableDeclaredSql(virtual.createSql, MANAGED_SQL_OPTIONS);
         if (have !== wanted) {
           disagree(`'${virtual.name}' is declared as\n  ${have}\nand the model declares\n  ${wanted}`);
         }
@@ -768,7 +690,7 @@ function verifyDeclaredSql(connection, plan, disagree) {
     (statement) => chain(statement.all([]), (rows) => {
       /** @type {Map<string, string>} */
       const actual = new Map();
-      for (const row of rows) actual.set(String(row.name), comparableDeclaredSql(row.sql));
+      for (const row of rows) actual.set(String(row.name), comparableDeclaredSql(row.sql, MANAGED_SQL_OPTIONS));
       for (const [name, wanted] of planned) {
         const have = actual.get(name);
         if (have === undefined)

package/src/dialects/sqlite-relational.js

@@ -22,7 +22,7 @@ export function relationalIdentifier(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 functions = new Set(['coalesce', 'nullif', 'trim', 'ltrim', 'rtrim', 'lower', 'upper', 'length', 'abs', 'round', 'typeof', 'json_extract', 'json_valid', 'json_type', '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 });
@@ -104,6 +104,7 @@ export function relationalEmitter(options = {}) {
         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');
+        if (value.name === 'json_type' && value.args.length > 2) fail('json_type requires one or two arguments');
         return `${value.name.toUpperCase()}(${value.distinct ? 'DISTINCT ' : ''}${value.args.length ? value.args.map(next).join(', ') : '*'})`;
       }
       case 'cast':

package/src/dialects/sqlite-schema.js

@@ -34,37 +34,13 @@ export function planTable(definition) {
   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);
+    const text = columnSql(column, definition, emitter);
     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;
+    return text;
   });
+  const inlineKey = definition.columns.some((column) => column.identity !== undefined);
   const members = (values) => {
     const text = list(values, 'constraint columns');
     if (values.some((name) => !names.has(name.toLowerCase()))) fail('constraint names an undeclared column');
@@ -79,11 +55,12 @@ export function planTable(definition) {
     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' : ''));
+      columns.push(`${prefix}FOREIGN KEY (${members(constraint.columns)}) ${referenceSql({
+        table: constraint.table, columns: constraint.references,
+        ...(constraint.onDelete === undefined ? {} : { onDelete: constraint.onDelete }),
+        ...(constraint.onUpdate === undefined ? {} : { onUpdate: constraint.onUpdate }),
+        ...(constraint.deferred === undefined ? {} : { deferred: constraint.deferred }),
+      })}`);
     }
     else fail('constraint kind is unique, check or foreignKey');
     const keys = constraint.kind === 'unique' ? ['kind', 'name', 'columns']
@@ -140,3 +117,76 @@ export function planTable(definition) {
     indexes: (definition.indexes ?? []).map((i) => ({ name: i.name, unique: i.unique === true, terms: i.terms })),
   } };
 }
+
+/** One REFERENCES clause shared by table constraints and column declarations. */
+function referenceSql(reference) {
+  check(reference, ['table', 'columns', 'onDelete', 'onUpdate', 'deferred'], 'reference');
+  if (reference.deferred !== undefined && typeof reference.deferred !== 'boolean') fail('deferred must be boolean');
+  return `REFERENCES ${q(reference.table)} (${list(reference.columns, 'references')})`
+    + (reference.onDelete === undefined ? '' : ` ON DELETE ${action(reference.onDelete)}`)
+    + (reference.onUpdate === undefined ? '' : ` ON UPDATE ${action(reference.onUpdate)}`)
+    + (reference.deferred ? ' DEFERRABLE INITIALLY DEFERRED' : '');
+}
+
+/** Render one typed column without reconstructing any surrounding schema. */
+function columnSql(column, context, emitter) {
+  check(column, ['name', 'type', 'nullable', 'default', 'collation', 'identity', 'check', 'generated', 'stored', 'references'], 'column definition');
+  const name = q(column.name);
+  if (!['INTEGER', 'REAL', 'TEXT', 'BLOB', 'NUMERIC', 'ANY'].includes(column.type)) fail('unsupported SQLite column type');
+  if (context.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');
+  const hasDefault = Object.hasOwn(column, 'default');
+  if (context.additive) {
+    if (column.identity !== undefined || column.stored === true) fail('ADD COLUMN cannot add an identity or STORED column');
+    const value = column.default?.$sql === 'value' ? column.default.value : column.default;
+    if (hasDefault && !(value === null || typeof value === 'string' || typeof value === 'bigint'
+      || (typeof value === 'number' && Number.isFinite(value)))) fail('ADD COLUMN requires a literal default');
+    if (column.generated === undefined && column.nullable === false && (!hasDefault || value === null)) fail('ADD COLUMN NOT NULL requires a non-null default');
+    if (column.references !== undefined && hasDefault && value !== null) fail('ADD COLUMN REFERENCES requires a NULL default');
+  }
+  let out = `${name} ${column.type}`;
+  if (column.identity !== undefined) {
+    if (!['rowid', 'autoincrement'].includes(column.identity) || column.type !== 'INTEGER'
+      || context.withoutRowid || context.primaryKey?.length !== 1
+      || context.primaryKey[0] !== column.name || column.generated !== undefined) fail('identity requires a single INTEGER rowid primary key');
+    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 (hasDefault) out += context.additive ? ` DEFAULT ${emitter.expr(column.default)}` : ` DEFAULT (${emitter.expr(column.default)})`;
+  if (column.check !== undefined) out += ` CHECK (${emitter.expr(column.check)})`;
+  if (column.generated !== undefined) {
+    if (hasDefault) fail('a generated column cannot have a default');
+    out += ` GENERATED ALWAYS AS (${emitter.expr(column.generated)}) ${column.stored ? 'STORED' : 'VIRTUAL'}`;
+  }
+  if (column.references !== undefined) {
+    if (column.references?.columns?.length !== 1) fail('a column reference requires one referenced column');
+    out += ` ${referenceSql(column.references)}`;
+  }
+  return out;
+}
+
+/** Render one explicit main-schema operation; validation never executes SQL.
+ * @param {any} operation @returns {string} */
+export function schemaChangeSql(operation) {
+  check(operation, ['op', 'table', 'column', 'name', 'to', 'ifExists'], 'schema change');
+  switch (operation.op) {
+    case 'addColumn':
+      check(operation, ['op', 'table', 'column'], 'addColumn');
+      return `ALTER TABLE "main".${q(operation.table)} ADD COLUMN ${columnSql(operation.column, { additive: true }, relationalEmitter({ inline: true }))}`;
+    case 'renameTable':
+      check(operation, ['op', 'table', 'to'], 'renameTable');
+      return `ALTER TABLE "main".${q(operation.table)} RENAME TO ${q(operation.to)}`;
+    case 'dropIndex': case 'dropTable': {
+      const index = operation.op === 'dropIndex';
+      check(operation, ['op', index ? 'name' : 'table', 'ifExists'], operation.op);
+      if (operation.ifExists !== undefined && typeof operation.ifExists !== 'boolean') fail('ifExists must be boolean');
+      return `DROP ${index ? 'INDEX' : 'TABLE'}${operation.ifExists ? ' IF EXISTS' : ''} "main".${q(index ? operation.name : operation.table)}`;
+    }
+    default: return fail('schema change is addColumn, dropIndex, renameTable or dropTable');
+  }
+}

package/src/dialects/sqlite.js

@@ -497,6 +497,7 @@ export const sqliteDialect = createDialect({
 
 /** SQLite schema inspection and identity preservation statements. */
 export const sqliteTableMigration = Object.freeze({
+    binaryCast: (sql) => `CAST(${sql} AS BLOB)`,
     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'",

package/src/document-steps.js

@@ -17,6 +17,7 @@
  */
 
 import { analyzeQuery, createQueryAccumulator } from '@jarenjs/json/query';
+import { setObjectMember } from '@jarenjs/core/object';
 import { DbCompileError, DbRuntimeError } from './errors.js';
 import { utf8Length } from './cursor.js';
 
@@ -31,13 +32,13 @@ export const DOCUMENT_STEP_KINDS = new Set(['jslt', 'query']);
 
 /**
  * The step kinds that act on a PHYSICAL database — rendered DDL, a
- * data statement spelled as SQL, the table-rebuild procedure, and the
+ * data statement spelled as SQL, guarded table plans, the table-rebuild procedure, and the
  * backfill that recomputes stored derived COLUMNS. A host without
  * tables cannot honour any of them, and silently skipping one would
  * leave a migration half-applied, so it refuses instead.
  * @type {ReadonlySet<string>}
  */
-export const PHYSICAL_STEP_KINDS = new Set(['ddl', 'sql', 'rebuild', 'derive']);
+export const PHYSICAL_STEP_KINDS = new Set(['ddl', 'sql', 'rebuild', 'derive', 'table']);
 
 /**
  * The refusal a failing step raises, spelled the one way — a reader
@@ -185,8 +186,12 @@ export function compileDocumentStep(step, index, context) {
         // a body that leaves it out keeps it, a body that rewrites it
         // is refused, as a collection's key is
         for (const key of keys) {
-          if (next[key] === undefined) next[key] = document[key];
-          else if (next[key] !== document[key]) {
+          const present = Object.hasOwn(document, key);
+          const previous = present ? document[key] : undefined;
+          if (!Object.hasOwn(next, key) || next[key] === undefined) {
+            if (present) setObjectMember(next, key, previous);
+          }
+          else if (next[key] !== previous) {
             fail(`the transform changed the key member '${key}' of row ${identity} — `
               + `key changes are not supported in ${MIGRATION_VERSION}`);
           }
@@ -271,7 +276,7 @@ export function compileDocumentStep(step, index, context) {
   };
 }
 
-const STEP_KINDS = new Set(['ddl', 'jslt', 'query', 'sql', 'rebuild', 'derive']);
+const STEP_KINDS = new Set([...DOCUMENT_STEP_KINDS, ...PHYSICAL_STEP_KINDS]);
 
 /**
  * Structural validation of one migration document, including the
@@ -304,6 +309,19 @@ export function checkMigrationDocument(migration) {
       throw new DbCompileError('JD0023',
         `migration '${migration.id}' step ${i} is a sql step without sql text`);
     }
+    if (step.kind === 'table' && (!step.plan || typeof step.plan !== 'object' || Array.isArray(step.plan) || step.plan.version !== 1
+      || ['id', 'table', 'checksum', 'temporary'].some((key) => typeof step.plan[key] !== 'string' || step.plan[key].length === 0)
+      || typeof step.plan.rebuild !== 'boolean'
+      || ['source', 'after'].some((key) => !Array.isArray(step.plan[key])
+        || step.plan[key].some((value) => !value || typeof value !== 'object' || Array.isArray(value)))
+      || ['unchanged', 'statements', 'finish'].some((key) => !Array.isArray(step.plan[key])
+        || step.plan[key].some((value) => typeof value !== 'string' || value.length === 0)))) {
+      throw new DbCompileError('JD0023', `migration '${migration.id}' step ${i} is a table step without its reviewed plan`);
+    }
+    if (['jslt', 'query'].includes(step.kind) && step.model !== undefined
+      && (!step.model || typeof step.model !== 'object' || step.model.$model !== '0.1')) {
+      throw new DbCompileError('JD0023', `migration '${migration.id}' step ${i} has an invalid current model`);
+    }
     if (step.kind === 'derive'
       && (typeof step.collection !== 'string' || !Array.isArray(step.columns)
         || step.columns.length === 0)) {

package/src/drivers/bun.js

@@ -20,8 +20,9 @@
 
 import { lazyOpen, openConnection } from '../driver.js';
 import { sqliteDialect } from '../dialects/sqlite.js';
-import { PRAGMA_NAMES } from '../pragmas.js';
+import { PRAGMAS, PRAGMA_NAMES } from '../pragmas.js';
 import { writeSqliteSnapshot } from './snapshot.js';
+import { nativeDatabaseIdentity } from './file-identity.js';
 export { snapshotDatabase } from './snapshot.js';
 
 /**
@@ -128,11 +129,19 @@ export function adaptBunDatabase(db, options) {
  * substitute module.
  * @param {any} mod - The `bun:sqlite` module (or a substitute)
  * @param {string} path
- * @param {{ readOnly?: boolean, queueTimeout?: number }} [options]
+ * @param {{ timeout?: number, readOnly?: boolean, queueTimeout?: number }} [options]
  * @returns {any}
  */
 export function fromBunModule(mod, path, options) {
+  const timeout = options?.timeout === undefined ? undefined
+    : PRAGMAS.busyTimeout.normalize(options.timeout, 'timeout');
   const db = options?.readOnly === true ? new mod.Database(path, { readonly: true }) : new mod.Database(path);
+  // Bun has no constructor timeout option. Configure newly owned handles
+  // before probing; adapting a caller-owned handle preserves its settings.
+  if (timeout !== undefined) {
+    try { db.run(sqliteDialect.pragma.set('busy_timeout', timeout)); }
+    catch (error) { db.close(); throw error; }
+  }
   const backup = {
     snapshot: true,
     copy: (target, copyOptions) => writeSqliteSnapshot(target, () => {
@@ -154,9 +163,10 @@ export function bunDriver() {
   return Object.freeze({
     name: 'bun-sqlite',
     dialect: sqliteDialect,
+    databaseIdentity: nativeDatabaseIdentity,
     /**
      * @param {string} path
-     * @param {{ readOnly?: boolean, queueTimeout?: number }} [options]
+     * @param {{ timeout?: number, readOnly?: boolean, queueTimeout?: number }} [options]
      * @returns {Promise<any>}
      */
     open: (path, options) => lazyOpen('bun:sqlite',

package/src/drivers/file-identity.js

@@ -0,0 +1,14 @@
+//@ts-check
+/** Native filesystem identity stays below the Node/Bun entry points. */
+import { chain } from '../driver.js';
+import { sqliteDatabasePath } from '../migration-target.js';
+
+/** Device/inode identity also catches hardlinks that SQLite filenames cannot.
+ * The filesystem is imported only when identifying an opened file; two private
+ * in-memory databases remain independent.
+ * @param {any} connection @returns {any} value-or-promise of string or null */
+export function nativeDatabaseIdentity(connection) {
+  return chain(sqliteDatabasePath(connection), (path) => path === null ? null
+    : import('node:fs/promises').then((fs) => fs.stat(path, { bigint: true }))
+      .then((stat) => `${stat.dev}:${stat.ino}`));
+}

package/src/drivers/node.js

@@ -9,6 +9,7 @@
 import { lazyOpen, openConnection } from '../driver.js';
 import { sqliteDialect } from '../dialects/sqlite.js';
 import { PRAGMA_NAMES } from '../pragmas.js';
+import { nativeDatabaseIdentity } from './file-identity.js';
 
 /**
  * Adapt an already-constructed `node:sqlite` `DatabaseSync` (or any
@@ -109,6 +110,7 @@ export function nodeDriver() {
   return Object.freeze({
     name: 'node-sqlite',
     dialect: sqliteDialect,
+    databaseIdentity: nativeDatabaseIdentity,
     /**
      * @param {string} path
      * @param {{ timeout?: number, readOnly?: boolean,

package/src/foreign-key-scope.js

@@ -0,0 +1,50 @@
+//@ts-check
+/** SQLite's connection settings belong outside the transaction they govern. */
+import { isThenable } from '@jarenjs/core/function';
+import { chain } from './driver.js';
+import { DbCompileError } from './errors.js';
+
+/** Suspend enforcement and legacy rewrites for a caller-owned transaction,
+ * restoring the exact original settings after success or failure. The caller
+ * still must run foreign_key_check before committing. Value-or-promise, so both
+ * synchronous table helpers and asynchronous migration drivers share one bracket.
+ * @param {any} connection @param {()=>any} fn @returns {any} */
+export function withForeignKeySettings(connection, fn) {
+  const dialect = connection.dialect;
+  const read = (name) => chain(connection.prepare(dialect.introspect.pragma(name)), (s) => chain(s.get([]), (row) => row[name]));
+  return chain(read('foreign_keys'), (foreignKeys) => chain(read('legacy_alter_table'), (legacy) => {
+    const restore = () => {
+      const errors = [];
+      const attempt = (sql) => {
+        try {
+          const result = connection.exec(sql);
+          return isThenable(result) ? result.then(() => undefined, (error) => { errors.push(error); }) : undefined;
+        }
+        catch (error) { errors.push(error); return undefined; }
+      };
+      // These settings are independent: a failed legacy restoration must
+      // not prevent the attempt to re-enable foreign-key enforcement.
+      return chain(attempt(dialect.pragma.set('legacy_alter_table', legacy ? 'ON' : 'OFF')),
+        () => chain(attempt(dialect.pragma.foreignKeys(!!foreignKeys)), () => errors));
+    };
+    const finish = (value) => chain(restore(), (errors) => {
+      if (errors.length === 1) throw errors[0];
+      if (errors.length > 1) throw new AggregateError(errors, 'migration connection settings could not be restored');
+      return value;
+    });
+    const fail = (error) => chain(restore(), (errors) => {
+      if (errors.length > 0) throw new AggregateError([error, ...errors],
+        'migration failed and its connection settings could not be restored', { cause: error });
+      throw error;
+    });
+    let result;
+    try {
+      result = chain(connection.exec(dialect.pragma.foreignKeys(false)), () => chain(read('foreign_keys'), (actual) => {
+        if (actual !== 0) throw new DbCompileError('JD0021', 'foreign_keys cannot change inside a transaction; establish the outer migration scope first');
+        return chain(connection.exec(dialect.pragma.set('legacy_alter_table', 'ON')), fn);
+      }));
+    }
+    catch (error) { return fail(error); }
+    return isThenable(result) ? result.then(finish, fail) : finish(result);
+  }));
+}

package/src/index.js

@@ -105,4 +105,4 @@ export { planInvariants } from './ddl.js';
 export { planPhysicalMigration } from './migrate.js';
 export { sql, planRelational, relational } from './dialects/sqlite-relational.js';
 export { defineTable, planTable } from './dialects/sqlite-schema.js';
-export { planTableMigration, applyTableMigration, withForeignKeysSuspended } from './table-migration.js';
+export { planTableMigration, applyTableMigration, withForeignKeysSuspended, planSchemaChange, applySchemaChange } from './table-migration.js';