@objectstack/driver-sql 10.0.0 → 10.2.0

package/dist/index.d.mts

@@ -1,7 +1,115 @@
 import { AutonumberToken, SchemaMode, QueryAST, DriverOptions } from '@objectstack/spec/data';
 import { IDataDriver } from '@objectstack/spec/contracts';
+import { SchemaDiffEntry } from '@objectstack/spec/shared';
 import knex, { Knex } from 'knex';
 
+/**
+ * Managed-datasource schema drift (issue #2186).
+ *
+ * The driver's `initObjects` sync is *additive-only*: it creates missing
+ * tables and adds missing columns, but never alters or drops existing ones.
+ * So a non-additive metadata change (relax `required`, change a type/length,
+ * drop or rename a field) silently diverges from an existing database — the
+ * served metadata says one thing and the physical column enforces another.
+ *
+ * This module is the single source of truth for *detecting* that divergence
+ * (metadata is authoritative on a `managed` datasource) and for *categorising*
+ * each divergence by how dangerous it is to reconcile:
+ *
+ *   - `safe`         — loosening that cannot lose data and cannot fail:
+ *                      relax NOT NULL → NULL, widen a varchar. Applied
+ *                      automatically by dev auto-reconcile (P2).
+ *   - `needs_confirm`— a change a human should eyeball but that does not
+ *                      destroy data (e.g. a non-narrowing type change).
+ *   - `destructive`  — drops or tightenings that can lose data or fail:
+ *                      drop an orphaned column, narrow a varchar, add a
+ *                      NOT NULL constraint over possibly-null data. Only
+ *                      applied by `os migrate apply --allow-destructive`.
+ *
+ * The detector reuses {@link SchemaDiffEntry} (the same shape the external /
+ * federated validator emits, ADR-0015 §5.2) so CLI / Studio / audit can render
+ * managed and external drift uniformly.
+ */
+
+type SqlDialectName = 'sqlite' | 'postgres' | 'mysql' | 'unknown';
+type DriftCategory = 'safe' | 'needs_confirm' | 'destructive';
+/** A reconcilable schema operation, machine-readable for the reconciler. */
+type DriftOp = {
+    type: 'relax_not_null';
+    table: string;
+    column: string;
+} | {
+    type: 'tighten_not_null';
+    table: string;
+    column: string;
+} | {
+    type: 'widen_varchar';
+    table: string;
+    column: string;
+    to: number;
+    from?: number;
+} | {
+    type: 'narrow_varchar';
+    table: string;
+    column: string;
+    to: number;
+    from?: number;
+} | {
+    type: 'drop_column';
+    table: string;
+    column: string;
+};
+/**
+ * A managed-schema drift finding: a {@link SchemaDiffEntry} enriched with the
+ * owning table, a reconcile {@link DriftOp}, and a {@link DriftCategory}.
+ */
+interface ManagedDriftEntry extends SchemaDiffEntry {
+    table: string;
+    category: DriftCategory;
+    op: DriftOp;
+    /** Human one-liner with an actionable hint. */
+    message: string;
+}
+/** Columns the driver creates unconditionally — never metadata fields. */
+declare const BUILTIN_COLUMNS: Set<string>;
+/** Minimal shape of an introspected physical column (see SqlDriver.introspectColumns). */
+interface PhysicalColumn {
+    name: string;
+    type: string;
+    nullable: boolean;
+    maxLength?: number;
+}
+/** Minimal shape of a metadata field definition. */
+interface FieldDef {
+    type?: string;
+    required?: boolean;
+    multiple?: boolean;
+    maxLength?: number;
+}
+/**
+ * Does this metadata field materialise a physical column? Mirrors
+ * `SqlDriver.createColumn` exactly: `formula` is virtual (computed, no column);
+ * everything else — including `multiple` (a JSON column) — gets one.
+ */
+declare function fieldHasColumn(field: FieldDef): boolean;
+/**
+ * Diff one table's metadata fields against its physical columns and return the
+ * set of *drift* findings. Metadata is authoritative.
+ *
+ * Note: a metadata field with no physical column is NOT reported — the
+ * additive sync (`ALTER TABLE ADD COLUMN`) already covers added fields, so by
+ * the time this runs every expected column exists. We only surface the
+ * non-additive divergences the additive sync can never fix.
+ */
+declare function diffManagedTable(args: {
+    table: string;
+    fields: Record<string, FieldDef>;
+    columns: PhysicalColumn[];
+    dialect: SqlDialectName;
+}): ManagedDriftEntry[];
+/** Stable de-dup / sort key for a drift entry. */
+declare function driftKey(d: ManagedDriftEntry): string;
+
 /**
  * SQL Driver for ObjectStack
  *
@@ -44,6 +152,14 @@ interface IntrospectedSchema {
  */
 type SqlDriverConfig = Knex.Config & {
     schemaMode?: SchemaMode;
+    /**
+     * Dev-only schema auto-reconcile (issue #2186). When `'safe'`, `initObjects`
+     * automatically applies *non-destructive* alters (relax NOT NULL, widen
+     * varchar) so an existing database self-heals after a metadata change
+     * loosens a constraint. `'off'` (default) only warns. Never applies
+     * destructive DDL, and is force-disabled when `NODE_ENV==='production'`.
+     */
+    autoMigrate?: 'off' | 'safe';
 };
 /**
  * SQL Driver for ObjectStack.
@@ -171,6 +287,7 @@ declare class SqlDriver implements IDataDriver {
      */
     protected logger: {
         warn: (msg: string, meta?: any) => void;
+        info?: (msg: string, meta?: any) => void;
     };
     /** Whether the underlying database is a SQLite variant (sqlite3 or better-sqlite3). */
     protected get isSqlite(): boolean;
@@ -212,6 +329,20 @@ declare class SqlDriver implements IDataDriver {
      * `'managed'` so existing callers are unaffected.
      */
     protected readonly schemaMode: SchemaMode;
+    /**
+     * Dev-only auto-reconcile policy (issue #2186). See {@link SqlDriverConfig.autoMigrate}.
+     */
+    protected readonly autoMigrate: 'off' | 'safe';
+    /**
+     * Metadata field defs for every table this driver manages, captured during
+     * `initObjects` (tableName → fields). The source of truth that
+     * {@link detectManagedDrift} diffs the physical schema against.
+     */
+    protected managedObjectFields: Map<string, Record<string, any>>;
+    /** Declared indexes per managed table (tableName → indexes[]), captured in `initObjects`. Used to recreate indexes after a SQLite table rebuild. */
+    protected managedObjectIndexes: Map<string, any[]>;
+    /** De-dup set for boot-time drift warnings (keyed by {@link driftKey}). */
+    protected driftWarned: Set<string>;
     constructor(config: SqlDriverConfig);
     /**
      * DDL gate (ADR-0015 §5.1). Single choke-point asserting that
@@ -376,6 +507,61 @@ declare class SqlDriver implements IDataDriver {
         name: string;
         fields?: Record<string, any>;
     }>): Promise<void>;
+    /** Canonical dialect name for the drift differ. */
+    protected get dialectName(): SqlDialectName;
+    /** True only when running under `NODE_ENV=production` — auto-DDL is force-disabled there. */
+    protected isProductionEnv(): boolean;
+    /** Diff one table's metadata fields against its physical columns. */
+    protected detectTableDrift(tableName: string, fields: Record<string, any>): Promise<ManagedDriftEntry[]>;
+    /**
+     * Detect every managed-schema divergence between metadata and the physical
+     * database. Metadata is the source of truth. Returns one entry per drift,
+     * sorted by table then column. Used by `os migrate` (P3) and tests.
+     *
+     * @param objects optional explicit object list; defaults to whatever
+     *   `initObjects` last synced (captured in {@link managedObjectFields}).
+     */
+    detectManagedDrift(objects?: Array<{
+        name: string;
+        fields?: Record<string, any>;
+    }>): Promise<ManagedDriftEntry[]>;
+    /**
+     * Boot-time per-table drift handling (P1 + P2): detect divergence, in dev
+     * auto-reconcile the *safe* (loosening) subset when `autoMigrate==='safe'`,
+     * then WARN once per remaining divergence with an actionable hint.
+     */
+    protected reconcileAndWarnDrift(tableName: string, fields: Record<string, any>): Promise<void>;
+    /**
+     * Apply a set of drift entries to the physical schema. Destructive entries
+     * are skipped unless `allowDestructive` is set. Postgres/MySQL alter columns
+     * in place; SQLite (which cannot alter constraints in place) rebuilds each
+     * affected table (copy → swap) applying only the requested edits.
+     *
+     * @returns the entries actually applied and those skipped (e.g. destructive
+     *   without `allowDestructive`, or unsupported on the dialect).
+     */
+    applyMigrationEntries(entries: ManagedDriftEntry[], opts?: {
+        allowDestructive?: boolean;
+    }): Promise<{
+        applied: ManagedDriftEntry[];
+        skipped: ManagedDriftEntry[];
+    }>;
+    /** Apply a single drift op in place (Postgres / MySQL). Returns false if unsupported. */
+    protected applyDriftOpInPlace(op: DriftOp): Promise<boolean>;
+    /**
+     * Rebuild a SQLite table applying a set of column edits (relax/tighten NOT
+     * NULL, drop column), preserving all other columns and their data. Follows
+     * the official SQLite procedure: create patched table → copy → drop → rename.
+     * varchar widen/narrow are no-ops on SQLite (dynamic typing) and ignored.
+     *
+     * Unique field-level constraints and declared indexes are recreated from
+     * metadata afterwards (the source of truth). DB-level foreign keys declared
+     * by `lookup` fields are not re-added (ObjectStack enforces relationships at
+     * the application layer, not via SQLite FK constraints).
+     */
+    protected rebuildSqliteTablePatched(table: string, ents: ManagedDriftEntry[]): Promise<void>;
+    /** Map an introspected SQLite column to a knex builder for the rebuilt table. */
+    protected buildRebuiltColumn(t: Knex.CreateTableBuilder, c: IntrospectedColumn): any;
     /**
      * Build a deterministic index name for a declared index so repeated
      * `initObjects` runs converge on the same identifier (and can detect an
@@ -579,4 +765,4 @@ declare const _default: {
     onEnable: (context: any) => Promise<void>;
 };
 
-export { type IntrospectedColumn, type IntrospectedForeignKey, type IntrospectedSchema, type IntrospectedTable, SqlDriver, type SqlDriverConfig, _default as default };
+export { BUILTIN_COLUMNS, type DriftCategory, type FieldDef as DriftFieldDef, type DriftOp, type IntrospectedColumn, type IntrospectedForeignKey, type IntrospectedSchema, type IntrospectedTable, type ManagedDriftEntry, type PhysicalColumn, type SqlDialectName, SqlDriver, type SqlDriverConfig, _default as default, diffManagedTable, driftKey, fieldHasColumn };

package/dist/index.d.ts

@@ -1,7 +1,115 @@
 import { AutonumberToken, SchemaMode, QueryAST, DriverOptions } from '@objectstack/spec/data';
 import { IDataDriver } from '@objectstack/spec/contracts';
+import { SchemaDiffEntry } from '@objectstack/spec/shared';
 import knex, { Knex } from 'knex';
 
+/**
+ * Managed-datasource schema drift (issue #2186).
+ *
+ * The driver's `initObjects` sync is *additive-only*: it creates missing
+ * tables and adds missing columns, but never alters or drops existing ones.
+ * So a non-additive metadata change (relax `required`, change a type/length,
+ * drop or rename a field) silently diverges from an existing database — the
+ * served metadata says one thing and the physical column enforces another.
+ *
+ * This module is the single source of truth for *detecting* that divergence
+ * (metadata is authoritative on a `managed` datasource) and for *categorising*
+ * each divergence by how dangerous it is to reconcile:
+ *
+ *   - `safe`         — loosening that cannot lose data and cannot fail:
+ *                      relax NOT NULL → NULL, widen a varchar. Applied
+ *                      automatically by dev auto-reconcile (P2).
+ *   - `needs_confirm`— a change a human should eyeball but that does not
+ *                      destroy data (e.g. a non-narrowing type change).
+ *   - `destructive`  — drops or tightenings that can lose data or fail:
+ *                      drop an orphaned column, narrow a varchar, add a
+ *                      NOT NULL constraint over possibly-null data. Only
+ *                      applied by `os migrate apply --allow-destructive`.
+ *
+ * The detector reuses {@link SchemaDiffEntry} (the same shape the external /
+ * federated validator emits, ADR-0015 §5.2) so CLI / Studio / audit can render
+ * managed and external drift uniformly.
+ */
+
+type SqlDialectName = 'sqlite' | 'postgres' | 'mysql' | 'unknown';
+type DriftCategory = 'safe' | 'needs_confirm' | 'destructive';
+/** A reconcilable schema operation, machine-readable for the reconciler. */
+type DriftOp = {
+    type: 'relax_not_null';
+    table: string;
+    column: string;
+} | {
+    type: 'tighten_not_null';
+    table: string;
+    column: string;
+} | {
+    type: 'widen_varchar';
+    table: string;
+    column: string;
+    to: number;
+    from?: number;
+} | {
+    type: 'narrow_varchar';
+    table: string;
+    column: string;
+    to: number;
+    from?: number;
+} | {
+    type: 'drop_column';
+    table: string;
+    column: string;
+};
+/**
+ * A managed-schema drift finding: a {@link SchemaDiffEntry} enriched with the
+ * owning table, a reconcile {@link DriftOp}, and a {@link DriftCategory}.
+ */
+interface ManagedDriftEntry extends SchemaDiffEntry {
+    table: string;
+    category: DriftCategory;
+    op: DriftOp;
+    /** Human one-liner with an actionable hint. */
+    message: string;
+}
+/** Columns the driver creates unconditionally — never metadata fields. */
+declare const BUILTIN_COLUMNS: Set<string>;
+/** Minimal shape of an introspected physical column (see SqlDriver.introspectColumns). */
+interface PhysicalColumn {
+    name: string;
+    type: string;
+    nullable: boolean;
+    maxLength?: number;
+}
+/** Minimal shape of a metadata field definition. */
+interface FieldDef {
+    type?: string;
+    required?: boolean;
+    multiple?: boolean;
+    maxLength?: number;
+}
+/**
+ * Does this metadata field materialise a physical column? Mirrors
+ * `SqlDriver.createColumn` exactly: `formula` is virtual (computed, no column);
+ * everything else — including `multiple` (a JSON column) — gets one.
+ */
+declare function fieldHasColumn(field: FieldDef): boolean;
+/**
+ * Diff one table's metadata fields against its physical columns and return the
+ * set of *drift* findings. Metadata is authoritative.
+ *
+ * Note: a metadata field with no physical column is NOT reported — the
+ * additive sync (`ALTER TABLE ADD COLUMN`) already covers added fields, so by
+ * the time this runs every expected column exists. We only surface the
+ * non-additive divergences the additive sync can never fix.
+ */
+declare function diffManagedTable(args: {
+    table: string;
+    fields: Record<string, FieldDef>;
+    columns: PhysicalColumn[];
+    dialect: SqlDialectName;
+}): ManagedDriftEntry[];
+/** Stable de-dup / sort key for a drift entry. */
+declare function driftKey(d: ManagedDriftEntry): string;
+
 /**
  * SQL Driver for ObjectStack
  *
@@ -44,6 +152,14 @@ interface IntrospectedSchema {
  */
 type SqlDriverConfig = Knex.Config & {
     schemaMode?: SchemaMode;
+    /**
+     * Dev-only schema auto-reconcile (issue #2186). When `'safe'`, `initObjects`
+     * automatically applies *non-destructive* alters (relax NOT NULL, widen
+     * varchar) so an existing database self-heals after a metadata change
+     * loosens a constraint. `'off'` (default) only warns. Never applies
+     * destructive DDL, and is force-disabled when `NODE_ENV==='production'`.
+     */
+    autoMigrate?: 'off' | 'safe';
 };
 /**
  * SQL Driver for ObjectStack.
@@ -171,6 +287,7 @@ declare class SqlDriver implements IDataDriver {
      */
     protected logger: {
         warn: (msg: string, meta?: any) => void;
+        info?: (msg: string, meta?: any) => void;
     };
     /** Whether the underlying database is a SQLite variant (sqlite3 or better-sqlite3). */
     protected get isSqlite(): boolean;
@@ -212,6 +329,20 @@ declare class SqlDriver implements IDataDriver {
      * `'managed'` so existing callers are unaffected.
      */
     protected readonly schemaMode: SchemaMode;
+    /**
+     * Dev-only auto-reconcile policy (issue #2186). See {@link SqlDriverConfig.autoMigrate}.
+     */
+    protected readonly autoMigrate: 'off' | 'safe';
+    /**
+     * Metadata field defs for every table this driver manages, captured during
+     * `initObjects` (tableName → fields). The source of truth that
+     * {@link detectManagedDrift} diffs the physical schema against.
+     */
+    protected managedObjectFields: Map<string, Record<string, any>>;
+    /** Declared indexes per managed table (tableName → indexes[]), captured in `initObjects`. Used to recreate indexes after a SQLite table rebuild. */
+    protected managedObjectIndexes: Map<string, any[]>;
+    /** De-dup set for boot-time drift warnings (keyed by {@link driftKey}). */
+    protected driftWarned: Set<string>;
     constructor(config: SqlDriverConfig);
     /**
      * DDL gate (ADR-0015 §5.1). Single choke-point asserting that
@@ -376,6 +507,61 @@ declare class SqlDriver implements IDataDriver {
         name: string;
         fields?: Record<string, any>;
     }>): Promise<void>;
+    /** Canonical dialect name for the drift differ. */
+    protected get dialectName(): SqlDialectName;
+    /** True only when running under `NODE_ENV=production` — auto-DDL is force-disabled there. */
+    protected isProductionEnv(): boolean;
+    /** Diff one table's metadata fields against its physical columns. */
+    protected detectTableDrift(tableName: string, fields: Record<string, any>): Promise<ManagedDriftEntry[]>;
+    /**
+     * Detect every managed-schema divergence between metadata and the physical
+     * database. Metadata is the source of truth. Returns one entry per drift,
+     * sorted by table then column. Used by `os migrate` (P3) and tests.
+     *
+     * @param objects optional explicit object list; defaults to whatever
+     *   `initObjects` last synced (captured in {@link managedObjectFields}).
+     */
+    detectManagedDrift(objects?: Array<{
+        name: string;
+        fields?: Record<string, any>;
+    }>): Promise<ManagedDriftEntry[]>;
+    /**
+     * Boot-time per-table drift handling (P1 + P2): detect divergence, in dev
+     * auto-reconcile the *safe* (loosening) subset when `autoMigrate==='safe'`,
+     * then WARN once per remaining divergence with an actionable hint.
+     */
+    protected reconcileAndWarnDrift(tableName: string, fields: Record<string, any>): Promise<void>;
+    /**
+     * Apply a set of drift entries to the physical schema. Destructive entries
+     * are skipped unless `allowDestructive` is set. Postgres/MySQL alter columns
+     * in place; SQLite (which cannot alter constraints in place) rebuilds each
+     * affected table (copy → swap) applying only the requested edits.
+     *
+     * @returns the entries actually applied and those skipped (e.g. destructive
+     *   without `allowDestructive`, or unsupported on the dialect).
+     */
+    applyMigrationEntries(entries: ManagedDriftEntry[], opts?: {
+        allowDestructive?: boolean;
+    }): Promise<{
+        applied: ManagedDriftEntry[];
+        skipped: ManagedDriftEntry[];
+    }>;
+    /** Apply a single drift op in place (Postgres / MySQL). Returns false if unsupported. */
+    protected applyDriftOpInPlace(op: DriftOp): Promise<boolean>;
+    /**
+     * Rebuild a SQLite table applying a set of column edits (relax/tighten NOT
+     * NULL, drop column), preserving all other columns and their data. Follows
+     * the official SQLite procedure: create patched table → copy → drop → rename.
+     * varchar widen/narrow are no-ops on SQLite (dynamic typing) and ignored.
+     *
+     * Unique field-level constraints and declared indexes are recreated from
+     * metadata afterwards (the source of truth). DB-level foreign keys declared
+     * by `lookup` fields are not re-added (ObjectStack enforces relationships at
+     * the application layer, not via SQLite FK constraints).
+     */
+    protected rebuildSqliteTablePatched(table: string, ents: ManagedDriftEntry[]): Promise<void>;
+    /** Map an introspected SQLite column to a knex builder for the rebuilt table. */
+    protected buildRebuiltColumn(t: Knex.CreateTableBuilder, c: IntrospectedColumn): any;
     /**
      * Build a deterministic index name for a declared index so repeated
      * `initObjects` runs converge on the same identifier (and can detect an
@@ -579,4 +765,4 @@ declare const _default: {
     onEnable: (context: any) => Promise<void>;
 };
 
-export { type IntrospectedColumn, type IntrospectedForeignKey, type IntrospectedSchema, type IntrospectedTable, SqlDriver, type SqlDriverConfig, _default as default };
+export { BUILTIN_COLUMNS, type DriftCategory, type FieldDef as DriftFieldDef, type DriftOp, type IntrospectedColumn, type IntrospectedForeignKey, type IntrospectedSchema, type IntrospectedTable, type ManagedDriftEntry, type PhysicalColumn, type SqlDialectName, SqlDriver, type SqlDriverConfig, _default as default, diffManagedTable, driftKey, fieldHasColumn };