@jarenjs/db 0.86.0 → 0.89.0

package/src/table-migration.js

@@ -3,20 +3,56 @@
 import { hashContent } from '@jarenjs/core/string';
 import { canonicalizeJson } from '@jarenjs/json/canonical';
 import { DbCompileError } from './errors.js';
-import { defineTable, planTable } from './dialects/sqlite-schema.js';
+import { defineTable, planTable, schemaChangeSql } from './dialects/sqlite-schema.js';
 import { relationalEmitter, relationalIdentifier as q, sql } from './dialects/sqlite-relational.js';
 import { sqliteDialect as dialect, sqliteTableMigration } from './dialects/sqlite.js';
 import { sqlTokens } from './dialects/check-read.js';
+import { ENGINE_TABLES } from './engine-metadata.js';
+import { withForeignKeySettings } from './foreign-key-scope.js';
 
 const refuse = (message) => { throw new DbCompileError('JD0021', message); };
 const fingerprint = (v) => canonicalizeJson(v);
-const schema = (connection) => connection.prepare(sqliteTableMigration.schema()).all([]).map((v) => ({ ...v }));
+const schema = (connection) => connection.prepare(sqliteTableMigration.schema()).all([])
+  .filter((v) => !ENGINE_TABLES.has(v.name) && !ENGINE_TABLES.has(v.tbl_name)).map((v) => ({ ...v }));
 const createdSql = (text) => text.replace(/^CREATE (TABLE|(?:UNIQUE )?INDEX|TRIGGER) IF NOT EXISTS /i, 'CREATE $1 ');
 const owned = (objects, table) => objects.filter((o) => o.tbl_name === table).map((o) => [o.type, o.name, o.sql]).sort((a, b) => (a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0));
 const sync = (connection) => {
   if (connection.dialect.name !== 'sqlite' || !connection.synchronous || connection.mustQueue) refuse('table migration requires an available synchronous SQLite connection');
 };
 
+/** Connection settings that govern the meaning of an additive/drop/rename plan. */
+function schemaSettings(connection) {
+  return ['foreign_keys', 'legacy_alter_table', 'schema_version'].map((name) =>
+    connection.prepare(dialect.introspect.pragma(name)).get([])[name]);
+}
+
+/** Review one native main-schema change without changing the database.
+ * Plans describe one source snapshot; callers own durable migration receipts.
+ * @param {any} connection @param {any} operation */
+export function planSchemaChange(connection, operation) {
+  sync(connection);
+  const text = schemaChangeSql(operation);
+  const body = { version: 1, operation: structuredClone(operation), sql: text,
+    source: schema(connection), settings: schemaSettings(connection) };
+  return { ...body, checksum: fingerprint({ ...body, operation: text }) };
+}
+
+/** Apply a reviewed native change atomically, refusing schema/settings drift.
+ * Replan after any schema change; only explicit drop ifExists handles absence.
+ * @param {any} connection @param {ReturnType<typeof planSchemaChange>} plan */
+export function applySchemaChange(connection, plan) {
+  sync(connection);
+  const { checksum, ...body } = plan;
+  if (body.version !== 1 || checksum !== fingerprint({ ...body, operation: plan.sql }) || plan.sql !== schemaChangeSql(plan.operation)) refuse('schema change checksum or statement differs');
+  return connection.transaction(() => {
+    const before = schema(connection);
+    if (fingerprint(before) !== fingerprint(plan.source) || fingerprint(schemaSettings(connection)) !== fingerprint(plan.settings))
+      refuse('source schema or connection settings changed after planning');
+    connection.exec(plan.sql);
+    return { changed: fingerprint(before) === fingerprint(schema(connection)) ? 0 : 1 };
+  }, undefined, 'immediate');
+}
+
 /** Inspect a live schema and generate a table plan without changing it.
  * Rebuilds require explicit opt-in. Unlisted indexes and triggers are preserved.
  * @param {any} connection @param {any} definition
@@ -71,7 +107,15 @@ export function planTableMigration(connection, definition, options) {
   // Preserve hidden rowids too, including text/composite-key rowid tables.
   const tableInfo = existing ? connection.prepare(sqliteTableMigration.tableList()).all([]).find((t) => t.schema === 'main' && t.name === target.name) : null;
   if (rebuild && !!tableInfo.wr !== !!target.withoutRowid) refuse('rebuild cannot change rowid ownership');
-  if (rebuild && !tableInfo.wr && !(oldKey.length === 1 && oldColumns.find((c) => c.name === oldKey[0]).type.toUpperCase() === 'INTEGER')) {
+  // INTEGER PRIMARY KEY DESC has a separate primary-key index and a hidden
+  // rowid. The declared type alone cannot establish rowid ownership.
+  const sourceAlias = rebuild && !tableInfo.wr && oldKey.length === 1
+    && oldColumns.find((c) => c.name === oldKey[0]).type.toUpperCase() === 'INTEGER'
+    && !connection.prepare(dialect.introspect.indexes(target.name)).all([]).some((index) => index.origin === 'pk');
+  const targetAlias = !target.withoutRowid && target.primaryKey?.length === 1
+    && target.columns.find((c) => c.name.toLowerCase() === target.primaryKey[0].toLowerCase()).type === 'INTEGER';
+  if (rebuild && sourceAlias !== !!targetAlias) refuse('rebuild cannot change rowid ownership');
+  if (rebuild && !tableInfo.wr && !sourceAlias) {
     const rowid = ['rowid', '_rowid_', 'oid'].find((name) => !oldColumns.some((c) => c.name.toLowerCase() === name)
       && !target.columns.some((c) => c.name.toLowerCase() === name));
     if (!rowid) refuse('the source shadows every rowid alias');
@@ -124,7 +168,7 @@ export function applyTableMigration(connection, plan) {
     if (connection.prepare(dialect.pragma.foreignKeyCheck()).get([])) refuse('migration violates foreign-key references');
     if (fingerprint(owned(schema(connection), plan.table)) !== fingerprint(owned(plan.after, plan.table))) refuse('migrated schema differs from the reviewed target');
     return { changed: plan.statements.length + plan.finish.length };
-  }, { mode: 'immediate' });
+  }, undefined, 'immediate');
   return plan.rebuild ? withForeignKeysSuspended(connection, run) : run();
 }
 
@@ -135,13 +179,7 @@ export function withForeignKeysSuspended(connection, fn) {
   sync(connection);
   if (typeof fn !== 'function' || Object.prototype.toString.call(fn) === '[object AsyncFunction]')
     refuse('a physical migration scope requires a synchronous callback');
-  const foreignKeys = connection.prepare(dialect.introspect.pragma('foreign_keys')).get([]).foreign_keys;
-  const legacy = connection.prepare(dialect.introspect.pragma('legacy_alter_table')).get([]).legacy_alter_table;
-  try {
-    connection.exec(dialect.pragma.foreignKeys(false));
-    if (connection.prepare(dialect.introspect.pragma('foreign_keys')).get([]).foreign_keys !== 0) refuse('foreign_keys cannot change inside a transaction; establish the outer migration scope first');
-    connection.exec(dialect.pragma.set('legacy_alter_table', 'ON'));
-    return connection.transaction(() => {
+  return withForeignKeySettings(connection, () => connection.transaction(() => {
       const result = fn();
       if (result != null && typeof result.then === 'function') {
         Promise.resolve(result).catch(() => {});
@@ -149,10 +187,5 @@ export function withForeignKeysSuspended(connection, fn) {
       }
       if (connection.prepare(dialect.pragma.foreignKeyCheck()).get([])) refuse('migration violates foreign-key references');
       return result;
-    }, { mode: 'immediate' });
-  }
-  finally {
-    connection.exec(dialect.pragma.set('legacy_alter_table', legacy ? 'ON' : 'OFF'));
-    connection.exec(dialect.pragma.foreignKeys(!!foreignKeys));
-  }
+  }, undefined, 'immediate'));
 }

package/types/index.d.ts

@@ -1169,6 +1169,10 @@ export interface Dialect {
 export interface Driver {
   readonly name: string;
   readonly dialect: Dialect;
+  /** Optional storage identity for shadow isolation. Equal non-null values
+   * identify the same database; private memory databases return null. Native
+   * SQLite bindings use filesystem device/inode identity. */
+  databaseIdentity?(connection: unknown): string | null | Promise<string | null>;
   /** Open a connection (value-or-promise) at `path` (`':memory:'` for
    * none) with the driver's own options. */
   open(path: string, options?: unknown): unknown;
@@ -1259,6 +1263,37 @@ export interface MigrationTarget {
   path?: string;
   /** `PRAGMA busy_timeout` for the run's connection, ms (default 5000). */
   busyTimeout?: number;
+  connection?: never;
+}
+
+/** A caller-owned connection, never closed or reopened by migration entry points. */
+export interface BorrowedMigrationTarget {
+  connection: unknown;
+  driver?: never;
+  path?: never;
+  busyTimeout?: never;
+}
+
+/** One physical catalog object. Some dialects cannot supply declaration text. */
+export interface SchemaObject {
+  readonly type: 'table' | 'view' | 'index' | 'trigger';
+  readonly name: string;
+  readonly owner: string;
+  readonly sql: string | null;
+}
+
+export interface SchemaInventory {
+  readonly tables: readonly unknown[];
+  readonly views: readonly string[];
+  readonly objects: readonly SchemaObject[];
+}
+
+/** Complete reviewed SQLite objects in an explicitly owned scope.
+ * Every object must carry SQL text; missing declaration text refuses at runtime. */
+export interface PhysicalMigrationTarget {
+  readonly objects: readonly SchemaObject[];
+  /** Defaults to the object owners; an absent named table records an intended drop. */
+  readonly tables?: readonly string[];
 }
 
 /** One progress event: the migration and collection a data step is
@@ -1302,7 +1337,7 @@ export declare function introspectModel(connection: unknown, options?: {
  * model cannot declare. */
 export declare function readSchema(connection: unknown, options?: {
   tables?: readonly string[];
-}): unknown;
+}): SchemaInventory | Promise<SchemaInventory>;
 
 export interface AssertionBounds {
   maxRows?: number | null;
@@ -1328,6 +1363,10 @@ export interface MigrateOptions {
   dryRun?: boolean;
   batchSize?: number;
   shadow?: boolean;
+  /** Complete owned target; also checked when there are no pending steps. */
+  physicalTarget?: PhysicalMigrationTarget;
+  /** Initialize the disposable shadow with the actual historical schema and rows. */
+  shadowFixture?: (connection: unknown) => unknown;
   /** Where the shadow replay runs (default `':memory:'`). */
   shadowPath?: string;
   /** The host's declared index-expression functions, by name — the same
@@ -1337,7 +1376,7 @@ export interface MigrateOptions {
    * A file engine's shadow is another file; a SERVER engine's is another
    * schema, and only the host can name one — the baseline shape the
    * replay creates would otherwise collide with the real store's. */
-  shadowDriver?: unknown;
+  shadowDriver?: Driver;
   /** Called once per batch a data step walks (transform, derive, or a
    * per-document assertion). */
   onProgress?: (progress: MigrationProgress) => void;
@@ -1381,7 +1420,33 @@ export declare function classifyAssertion(query: unknown, options?: { expect?: s
 
 export declare function migrate(
   target: MigrationTarget, migrations: readonly unknown[], options: MigrateOptions,
-): Promise<unknown>;
+): Promise<MigrationResult>;
+/** Borrowed synchronous work stays synchronous when shadow replay is disabled;
+ * async connections or hooks retain their promise boundary. */
+export declare function migrate(
+  target: BorrowedMigrationTarget, migrations: readonly unknown[], options: MigrateOptions,
+): MigrationResult | Promise<MigrationResult>;
+
+export interface AppliedMigrationReport {
+  applied: string[];
+  skipped: string[];
+  shape: string;
+}
+export interface UpToDateMigrationReport {
+  applied: [];
+  skipped: string[];
+  upToDate: true;
+}
+export interface DryRunMigrationReport {
+  dryRun: true;
+  pending: string[];
+  statements: string[];
+  /** Current rows by transform collection; null when its mapped relation does
+   * not exist yet. These are not predictions after pending SQL runs. */
+  counts: Record<string, number | null>;
+  shadowValidated: boolean;
+}
+export type MigrationResult = AppliedMigrationReport | UpToDateMigrationReport | DryRunMigrationReport;
 /** Whether an assertion step is a per-document predicate (a FLWOR over
  * `$[*]` whose body reads only its binding), which the runner evaluates
  * per batch; anything else reads the collection whole. */
@@ -1396,20 +1461,33 @@ export interface MigrationStatusReport {
   drift: string | null;
   upToDate: boolean;
 }
+export interface MigrationStatusOptions {
+  model?: unknown;
+  physicalTarget?: PhysicalMigrationTarget;
+  /** Reference driver required by borrowed model-only comparison. */
+  shadowDriver?: Driver;
+  registerFunctions?: (connection: unknown) => unknown;
+  signal?: AbortSignal;
+  deadline?: number;
+  runtime?: Partial<Runtime>;
+}
 /** Report a database's migration state without touching it: the
  * history table is probed, never created. `model` enables the drift
  * comparison once the chain is fully applied. */
 export declare function migrationStatus(
   target: MigrationTarget,
   migrations: readonly unknown[],
-  options?: { model?: unknown;
-    registerFunctions?: (connection: unknown) => unknown;
-    signal?: AbortSignal; deadline?: number; runtime?: Partial<Runtime> },
+  options?: MigrationStatusOptions,
 ): Promise<MigrationStatusReport>;
+export declare function migrationStatus(
+  target: BorrowedMigrationTarget,
+  migrations: readonly unknown[],
+  options?: MigrationStatusOptions,
+): MigrationStatusReport | Promise<MigrationStatusReport>;
 /** Create a model's whole physical shape on a connection. */
 export declare function createModelShape(connection: unknown, model: unknown): unknown;
-/** The declared schema, normalized for shape-equality comparison. */
-export declare function schemaShapeOf(connection: unknown):
+/** The declared schema, preserving physical column order unless explicitly relaxed. */
+export declare function schemaShapeOf(connection: unknown, options?: DeclaredSqlOptions):
   Promise<Array<{ type: string; name: string; owner: string; sql: string }>>
   | Array<{ type: string; name: string; owner: string; sql: string }>;
 /** Null when the database's shape equals a fresh build of the model. */
@@ -1473,7 +1551,7 @@ export interface DocumentMigrationOptions {
  * source is rewindable, so the steps run exactly as a Store runs them —
  * every step over the whole collection, in step order — which is what
  * makes the answer, and the refusal, identical to the Store's. A step
- * that needs tables (`ddl`, `sql`, `rebuild`, `derive`) is refused
+ * that needs tables (`ddl`, `sql`, `rebuild`, `derive`, `table`) is refused
  * (`JD0023`) before the first document is read. */
 export declare function migrateDocuments(
   collections: Record<string, readonly unknown[]>,
@@ -1522,8 +1600,13 @@ export declare function stepFailure(
 
 export declare function planCollection(name: string, collection: unknown, dialect: Dialect): unknown;
 export declare function compileIndexPath(expression: string, docPath: string): unknown;
+/** Conservative declaration comparison policy. Index, trigger and constraint order is always preserved. */
+export interface DeclaredSqlOptions {
+  /** Preserve physical order by default; ignore only safe managed named-column order. */
+  columnOrder?: 'preserve' | 'ignore';
+}
 export declare function normalizeDeclaredSql(sql: string): string;
-export declare function comparableDeclaredSql(sql: string): string;
+export declare function comparableDeclaredSql(sql: string, options?: DeclaredSqlOptions): string;
 /** The comparison kind a declared schema type implies — what a column
  * over that member holds, and how its expression must read it. */
 export declare function columnKindFor(
@@ -2041,8 +2124,25 @@ export interface TrustedSyncSql {
 export declare function planInvariants(model: unknown, options: { dialect: Dialect }): {
   type: 'trigger'; name: string; owner: string; rule: string; sql: string;
 }[];
-export declare function planPhysicalMigration(connection: unknown, fromModel: unknown, toModel: unknown,
-  options: { id: string; steps: readonly unknown[]; dispositions: Readonly<Record<string, 'preserve' | 'replace' | 'drop'>>;
-    assertions?: readonly { sql: string; params?: readonly unknown[]; expected: readonly unknown[] }[] }): unknown;
+/** A reviewed preservation document. The supplied steps retain their types;
+ * untyped saved steps remain unknown until the caller validates them. */
+export interface PhysicalMigrationDocument<Steps extends readonly unknown[] = readonly unknown[]> {
+  readonly $migration: '0.1';
+  readonly id: string;
+  readonly from: string;
+  readonly to: string;
+  readonly steps: Steps;
+  readonly physical: {
+    readonly source: readonly SchemaObject[];
+    readonly dispositions: Readonly<Record<string, 'preserve' | 'replace' | 'drop'>>;
+    readonly assertions: readonly { readonly sql: string; readonly params?: readonly unknown[]; readonly expected: readonly unknown[] }[];
+    readonly target?: PhysicalMigrationTarget;
+  };
+}
+/** Planning retains a synchronous connection's value boundary. */
+export declare function planPhysicalMigration<const Steps extends readonly unknown[]>(connection: unknown, fromModel: unknown, toModel: unknown,
+  options: { id: string; steps: Steps; dispositions: Readonly<Record<string, 'preserve' | 'replace' | 'drop'>>;
+    assertions?: readonly { sql: string; params?: readonly unknown[]; expected: readonly unknown[] }[];
+    physicalTarget?: PhysicalMigrationTarget }): PhysicalMigrationDocument<Steps> | Promise<PhysicalMigrationDocument<Steps>>;
 
-export { sql, relational, planRelational, defineTable, planTable, planTableMigration, applyTableMigration, withForeignKeysSuspended } from './relational.js';
+export { sql, relational, planRelational, defineTable, planTable, planTableMigration, applyTableMigration, withForeignKeysSuspended, planSchemaChange, applySchemaChange } from './relational.js';

package/types/relational.d.ts

@@ -4,7 +4,7 @@ export type SqlInput = SqlValue | SqlExpression;
 export type SqlOperator = '=' | '<>' | '<' | '<=' | '>' | '>=' | 'IS' | 'IS NOT'
   | '+' | '-' | '*' | '/' | '%' | '||' | 'AND' | 'OR' | 'LIKE' | 'NOT LIKE' | 'GLOB';
 export type SqlFunction = 'coalesce' | 'nullif' | 'trim' | 'ltrim' | 'rtrim' | 'lower' | 'upper'
-  | 'length' | 'abs' | 'round' | 'typeof' | 'json_extract' | 'json_valid'
+  | 'length' | 'abs' | 'round' | 'typeof' | 'json_extract' | 'json_valid' | 'json_type'
   | 'count' | 'sum' | 'total' | 'avg' | 'min' | 'max'
   | 'date' | 'time' | 'datetime' | 'julianday' | 'unixepoch' | 'strftime';
 export type SqlType = 'INTEGER' | 'REAL' | 'TEXT' | 'BLOB' | 'NUMERIC';
@@ -78,8 +78,13 @@ export interface TableColumn {
   readonly default?: SqlInput; readonly collation?: SqlCollation;
   readonly identity?: 'rowid' | 'autoincrement'; readonly check?: SqlInput;
   readonly generated?: SqlInput; readonly stored?: boolean;
+  readonly references?: ColumnReference;
 }
 export type ForeignKeyAction = 'cascade' | 'restrict' | 'no action' | 'set null' | 'set default';
+export interface ColumnReference {
+  readonly table: string; readonly columns: readonly [string];
+  readonly onDelete?: ForeignKeyAction; readonly onUpdate?: ForeignKeyAction; readonly deferred?: boolean;
+}
 export type TableConstraint = { readonly name?: string } & (
   { readonly kind: 'unique'; readonly columns: readonly string[] }
   | { readonly kind: 'check'; readonly expression: SqlInput }
@@ -111,4 +116,17 @@ export interface TableMigrationPlan {
 export declare function planTableMigration(connection: unknown, definition: TableDefinition, options: TableMigrationOptions): TableMigrationPlan;
 export declare function applyTableMigration(connection: unknown, plan: TableMigrationPlan): { changed: number };
 export declare function withForeignKeysSuspended<T>(connection: unknown, fn: () => T): T;
+export type SchemaChange =
+  | { readonly op: 'addColumn'; readonly table: string; readonly column: TableColumn }
+  | { readonly op: 'dropIndex'; readonly name: string; readonly ifExists?: boolean }
+  | { readonly op: 'renameTable'; readonly table: string; readonly to: string }
+  | { readonly op: 'dropTable'; readonly table: string; readonly ifExists?: boolean };
+export interface SchemaChangePlan {
+  readonly version: 1; readonly operation: SchemaChange; readonly sql: string;
+  readonly source: readonly unknown[]; readonly settings: readonly number[]; readonly checksum: string;
+}
+/** Main-schema snapshot; does not execute SQL or infer replay/disposition policy. */
+export declare function planSchemaChange(connection: unknown, operation: SchemaChange): SchemaChangePlan;
+/** Refuses stale source/settings under an immediate transaction. */
+export declare function applySchemaChange(connection: unknown, plan: SchemaChangePlan): { changed: number };
 export { sqliteDialect } from './index.js';