uql-orm 0.79.0 → 0.81.0

package/dist/migrate/migrator.js

@@ -3,10 +3,12 @@ import { basename, extname, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { getEntities, getMeta } from '../entity/index.js';
 import { SchemaAST } from '../schema/index.js';
+import { hasTriggers } from '../util/field.util.js';
 import { LoggerWrapper } from '../util/index.js';
 import { buildMigrationModule } from './codegen/migrationFile.js';
 import { introspectorFor } from './introspection/registry.js';
 import { migrationBuilderFor, migrationTargetFor } from './migrationTarget.js';
+import { dropped, nonEmpty, reverseDiff, sides } from './schemaChange.js';
 /**
  * Main class for managing database migrations
  */
@@ -181,17 +183,17 @@ export class Migrator {
     async generateFromEntities(name) {
         const generator = await this.getSchemaGenerator();
         const { created, altered } = await this.pendingChanges();
-        const up = [
-            ...this.createSchema(generator, created),
-            ...altered.flatMap((diff) => generator.generateAlterTable(diff)),
-        ];
+        const plan = this.alterPlan(generator, altered, await this.installedTriggers(created));
+        const up = [...this.createSchema(generator, created), ...plan.up];
         if (up.length === 0) {
             this.logger.logInfo('No schema changes detected.');
             return '';
         }
         // Diff by diff in reverse, each rolled back in the order its generator wrote it.
         const down = [
-            ...altered.toReversed().flatMap((diff) => generator.generateAlterTableDown(diff)),
+            ...plan.down(),
+            // A table's drop takes its triggers along, but not the function the Postgres family keeps each body in.
+            ...this.createdEntities(created).flatMap((entity) => generator.generateTriggersDown(entity)),
             ...created.toReversed().map((tableName) => generator.generateDropTable(tableName, { ifExists: true })),
         ];
         const { emit } = this.target.source;
@@ -203,6 +205,74 @@ export class Migrator {
         this.logger.logInfo(`Created migration from entities: ${filePath}`);
         return filePath;
     }
+    /**
+     * Each entity on a table this plan does not create - a new one carries its triggers in its `CREATE` -
+     * beside the triggers uql has installed there, read once per schema. Kept only where either side has
+     * any: one declaring none on a table holding none has nothing to reconcile.
+     */
+    async installedTriggers(created, entities = this.entities) {
+        const { dialect } = this.pool;
+        const fresh = new Set(created);
+        // Tables this plan creates are left out: their `CREATE` carries their triggers, and asking the
+        // catalogue about a table that is not there yet fails outright on some engines.
+        const wanted = entities.filter((entity) => !fresh.has(this.tableOf(entity)));
+        const state = [];
+        for (const entity of wanted) {
+            const meta = getMeta(entity);
+            const installed = await this.schemaIntrospectorFor(dialect.resolveSchema(meta)).ownedTriggers(dialect.resolveTableAlias(meta));
+            // An installed trigger alone keeps it: an entity that stopped declaring one has it to drop.
+            if (installed.size || hasTriggers(meta)) {
+                state.push({ entity, installed });
+            }
+        }
+        return state;
+    }
+    /**
+     * The alters, with the triggers reconciled around them. Postgres refuses to retype or drop a column a
+     * trigger names, so every trigger on a table whose columns change comes off before the alters and what
+     * its entity declares goes back on after. `down` is lazy: SQLite cannot express every alter's inverse.
+     */
+    alterPlan(generator, altered, state) {
+        const changing = new Set(altered.filter((diff) => sides(diff.columns, 'from').length).map((diff) => diff.tableName));
+        const cleared = state.filter(({ entity }) => changing.has(this.tableOf(entity)));
+        const after = state.map((it) => (cleared.includes(it) ? { entity: it.entity, installed: new Map() } : it));
+        return {
+            up: [
+                ...cleared.flatMap(({ entity, installed }) => generator.generateTriggerDrops(entity, [...installed.keys()])),
+                ...altered.flatMap((diff) => generator.generateAlterTable(diff)),
+                ...this.reconcileTriggers(generator, after),
+            ],
+            down: () => [
+                ...this.revertedTriggers(generator, after),
+                ...altered.toReversed().flatMap((diff) => generator.generateAlterTable(reverseDiff(diff))),
+                ...cleared.flatMap(({ installed }) => [...installed.values()].flat().map((sql) => `${sql};`)),
+            ],
+        };
+    }
+    /**
+     * Each entity's triggers taken from what the catalogue holds to what it declares. Against the catalogue
+     * rather than a diff, because a trigger hangs off a table whose columns may be unchanged: a body edited
+     * on a settled table appears in no diff at all.
+     */
+    reconcileTriggers(generator, state) {
+        return state.flatMap(({ entity, installed }) => generator.generateTriggers(entity, installed));
+    }
+    /**
+     * The inverse: what the reconcile created dropped, and what it dropped restored as the engine reprints
+     * it. Read off the catalogue rather than recorded by uql, and exactly right for restoring one.
+     */
+    revertedTriggers(generator, state) {
+        return state.flatMap(({ entity, installed }) => generator.generateTriggersDown(entity, installed));
+    }
+    /** The entities whose tables are among `created`. */
+    createdEntities(created) {
+        const fresh = new Set(created);
+        return this.entities.filter((entity) => fresh.has(this.tableOf(entity)));
+    }
+    /** The table `entity` maps to, as a diff names it. */
+    tableOf(entity) {
+        return this.pool.dialect.resolveTableName(getMeta(entity));
+    }
     /**
      * Get all schema differences between entities and database
      */
@@ -269,14 +339,16 @@ export class Migrator {
         }
         // With the tables it references, which its foreign keys resolve against.
         const ast = await this.introspectEntities([entity, ...referencedEntities(meta)]);
-        return this.alterFromEntity(generator, entity, ast.getTable(tableName), options);
+        // The table is already there, so its triggers are reconciled rather than carried by a `CREATE`.
+        const altered = this.alterFromEntity(generator, entity, ast.getTable(tableName), options);
+        return this.alterPlan(generator, altered, await this.installedTriggers([], [entity])).up;
     }
-    /** The same for one entity against the table it already has, and nothing where the two agree. */
+    /** The diff for one entity against the table it already has, and none where the two agree. */
     alterFromEntity(generator, entity, table, options) {
         // Spanning the set for the reason `planEntity` spells out: a foreign key needs the table it
         // points at, which a sync of one entity outside the configured list would not otherwise have.
         const diff = generator.diffSchema(entity, table, generator.buildAST?.(this.entitiesWith(entity)));
-        return diff?.type === 'alter' ? generator.generateAlterTable(this.filterDiff(diff, options)) : [];
+        return diff?.type === 'alter' ? [this.filterDiff(diff, options)] : [];
     }
     /** The configured entities, with `entity` among them however the migrator was built. */
     entitiesWith(entity) {
@@ -300,9 +372,10 @@ export class Migrator {
             return this.planEntity(generator, options.entity, options);
         }
         const { created, altered } = await this.pendingChanges();
+        const filtered = altered.map((diff) => this.filterDiff(diff, options));
         return [
             ...this.createSchema(generator, created),
-            ...altered.flatMap((diff) => generator.generateAlterTable(this.filterDiff(diff, options))),
+            ...this.alterPlan(generator, filtered, await this.installedTriggers(created)).up,
         ];
     }
     /** The new tables, created together so a foreign key between them, cyclic included, resolves. Empty in, empty out. */
@@ -321,45 +394,40 @@ export class Migrator {
             altered: diffs.filter((diff) => diff.type === 'alter'),
         };
     }
+    /**
+     * Safe mode only adds: a change with a `from` drops or rebuilds what the table holds, so it is held,
+     * and so is a key whole, which rebuilds an index over every row and fails where a column holds a null.
+     * Without `drop`, a column's drop is held too.
+     */
     filterDiff(diff, options) {
-        const filteredDiff = { ...diff };
-        if (options.safe !== false) {
-            // In safe mode, we only allow additions (creating tables/columns)
-            // We block drops and alterations to prevent accidental data loss
-            if (filteredDiff.columnsToDrop?.length) {
-                this.logger.logSkippedMigration(`[AutoSync] Skipped dropping ${filteredDiff.columnsToDrop.length} columns in table '${diff.tableName}': ${filteredDiff.columnsToDrop.join(', ')} (safe mode active)`);
-                delete filteredDiff.columnsToDrop;
+        const safe = options.safe !== false;
+        const skip = (what, names, fix) => {
+            if (names.length) {
+                this.logger.logSkippedMigration(`[AutoSync] Skipped ${names.length} ${what} in table '${diff.tableName}': ${names.join(', ')} (${fix}).`);
             }
-            if (filteredDiff.columnsToAlter?.length) {
-                this.logger.logSkippedMigration(`[AutoSync] Skipped altering ${filteredDiff.columnsToAlter.length} columns in table '${diff.tableName}': ${filteredDiff.columnsToAlter.map((c) => c.to.name).join(', ')} (safe mode active). Use a migration or { safe: false } to apply.`);
-                delete filteredDiff.columnsToAlter;
-            }
-            if (filteredDiff.primaryKey) {
-                // Rewriting a key drops a constraint and rebuilds an index over the whole table, and fails
-                // outright where the new columns are null on rows that already exist. Firmly not additive.
-                this.logger.logSkippedMigration(`[AutoSync] Skipped changing the primary key of '${diff.tableName}' from (${filteredDiff.primaryKey.from.join(', ')}) to (${filteredDiff.primaryKey.to.join(', ')}) (safe mode active). Use a migration or { safe: false } to apply.`);
-                delete filteredDiff.primaryKey;
-            }
-            if (filteredDiff.foreignKeysToAlter?.length) {
-                // Altering one is dropping it and adding it back, so letting the add through while the drop
-                // is held would emit `ADD CONSTRAINT` for a constraint the table still has.
-                this.logger.logSkippedMigration(`[AutoSync] Skipped altering ${filteredDiff.foreignKeysToAlter.length} foreign keys in table '${diff.tableName}': ${filteredDiff.foreignKeysToAlter.map((fk) => fk.to.name).join(', ')} (safe mode active). Use a migration or { safe: false } to apply.`);
-                delete filteredDiff.foreignKeysToAlter;
-            }
-            if (filteredDiff.indexesToDrop?.length) {
-                // An index recreated under its old name is a drop and an add, held back together.
-                const dropped = new Set(filteredDiff.indexesToDrop.map((index) => index.name));
-                this.logger.logSkippedMigration(`[AutoSync] Skipped dropping ${dropped.size} indexes in table '${diff.tableName}': ${[...dropped].join(', ')} (safe mode active). Use a migration or { safe: false } to apply.`);
-                filteredDiff.indexesToAdd = filteredDiff.indexesToAdd?.filter((index) => !dropped.has(index.name));
-                delete filteredDiff.indexesToDrop;
+        };
+        const safeFix = 'safe mode active. Use a migration or { safe: false } to apply';
+        const additive = (what, changes, nameOf) => {
+            if (!safe) {
+                return changes;
             }
-            delete filteredDiff.foreignKeysToDrop;
+            skip(`${what} changes`, sides(changes, 'from').map(nameOf), safeFix);
+            return nonEmpty((changes ?? []).filter((change) => change.from === undefined));
+        };
+        const columns = additive('column', diff.columns, (column) => column.name);
+        if (safe && diff.primaryKey) {
+            skip('primary key changes', [diff.tableName], safeFix);
         }
-        if (!options.drop && filteredDiff.columnsToDrop?.length) {
-            this.logger.logSkippedMigration(`[AutoSync] Skipped dropping ${filteredDiff.columnsToDrop.length} columns in table '${diff.tableName}' (drop: false). Use { drop: true } to apply.`);
-            delete filteredDiff.columnsToDrop;
+        if (!options.drop) {
+            skip('column drops', dropped(columns).map((column) => column.name), 'drop: false. Use { drop: true } to apply');
         }
-        return filteredDiff;
+        return {
+            ...diff,
+            primaryKey: safe ? undefined : diff.primaryKey,
+            columns: options.drop ? columns : nonEmpty((columns ?? []).filter((change) => change.to !== undefined)),
+            indexes: additive('index', diff.indexes, (index) => index.name),
+            foreignKeys: additive('foreign key', diff.foreignKeys, (foreignKey) => foreignKey.name ?? foreignKey.columns.join(', ')),
+        };
     }
     /** Runs the statements a generator wrote, in one transaction where the engine takes DDL in one. */
     async executeSyncStatements(statements, options) {

package/dist/migrate/schemaChange.d.ts

@@ -0,0 +1,18 @@
+import type { Change, SchemaDiff } from '../type/index.js';
+/** Each change's end on `side`, where it has one: what a drop half removes (`from`), or an add half creates (`to`). */
+export declare function sides<T>(changes: readonly Change<T>[] | undefined, side: 'from' | 'to'): T[];
+/** What the changes add: each `to` with no `from`. */
+export declare function added<T>(changes?: readonly Change<T>[]): T[];
+/** What the changes drop: each `from` with no `to`. */
+export declare function dropped<T>(changes?: readonly Change<T>[]): T[];
+/** The changes that alter an object in place, which only a column can. */
+export declare function alterations<T>(changes?: readonly Change<T>[]): {
+    readonly from: T;
+    readonly to: T;
+}[];
+/** `items`, or nothing where it has none, so an empty change list is left off a diff. */
+export declare function nonEmpty<T>(items: readonly T[]): readonly T[] | undefined;
+/** `change` undone: an add becomes a drop, a drop an add, and an alter runs the other way. */
+export declare function swap<T>({ from, to }: Change<T>): Change<T>;
+/** `diff` undone: every change swapped, which is what a migration's `down` runs. */
+export declare function reverseDiff(diff: SchemaDiff): SchemaDiff;

package/dist/migrate/schemaChange.js

@@ -0,0 +1,37 @@
+/** Each change's end on `side`, where it has one: what a drop half removes (`from`), or an add half creates (`to`). */
+export function sides(changes, side) {
+    return (changes ?? []).flatMap((change) => {
+        const end = change[side];
+        return end === undefined ? [] : [end];
+    });
+}
+/** What the changes add: each `to` with no `from`. */
+export function added(changes = []) {
+    return changes.flatMap(({ from, to }) => (from === undefined && to !== undefined ? [to] : []));
+}
+/** What the changes drop: each `from` with no `to`. */
+export function dropped(changes = []) {
+    return changes.flatMap(({ from, to }) => (to === undefined && from !== undefined ? [from] : []));
+}
+/** The changes that alter an object in place, which only a column can. */
+export function alterations(changes = []) {
+    return changes.flatMap(({ from, to }) => (from === undefined || to === undefined ? [] : [{ from, to }]));
+}
+/** `items`, or nothing where it has none, so an empty change list is left off a diff. */
+export function nonEmpty(items) {
+    return items.length ? items : undefined;
+}
+/** `change` undone: an add becomes a drop, a drop an add, and an alter runs the other way. */
+export function swap({ from, to }) {
+    return { from: to, to: from };
+}
+/** `diff` undone: every change swapped, which is what a migration's `down` runs. */
+export function reverseDiff(diff) {
+    return {
+        ...diff,
+        primaryKey: diff.primaryKey && swap(diff.primaryKey),
+        columns: diff.columns?.map(swap),
+        indexes: diff.indexes?.map(swap),
+        foreignKeys: diff.foreignKeys?.map(swap),
+    };
+}

package/dist/migrate/schemaGenerator.d.ts

@@ -3,7 +3,7 @@ import type { SchemaAST } from '../schema/schemaAST.js';
 import { type BuildSchemaASTOptions } from '../schema/schemaASTBuilder.js';
 import { type DiffOptions } from '../schema/schemaASTDiffer.js';
 import type { CanonicalType, ColumnNode, ForeignKeyAction, IndexNode, TableNode } from '../schema/types.js';
-import type { ColumnSchema, CreateSchemaOptions, DialectFeatures, DropSchemaOptions, EntityMeta, EntityWhereMeta, FieldMeta, FieldOptions, ForeignKeySchema, IndexSchema, NamingStrategy, SchemaDiff, SchemaGenerator, Type } from '../type/index.js';
+import type { ColumnSchema, CreateSchemaOptions, DialectFeatures, DropSchemaOptions, EntityMeta, InstalledTriggers, EntityWhereMeta, FieldMeta, FieldOptions, ForeignKeySchema, IndexSchema, NamingStrategy, SchemaDiff, SchemaGenerator, Type } from '../type/index.js';
 import type { AnyMigrationOperation, FullColumnDefinition, IndexDefinition, TableDefinition } from './builder/types.js';
 import { type IndexDdl, type TableDdl } from './ddl/index.js';
 /**
@@ -43,6 +43,17 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
      * cyclic. SQLite keeps them inline: it cannot add one later, and resolves a forward reference lazily.
      */
     generateCreateSchema(entities: readonly Type<object>[], options?: CreateSchemaOptions): string[];
+    /**
+     * The installed triggers on `entity`'s table it does not declare, and the declared ones not installed,
+     * compared by name alone: a name carries a hash of the trigger's SQL, so an edited one is a new name.
+     * Every trigger counts - the ones it authored, and one per event each stamp names.
+     */
+    private triggerChanges;
+    generateTriggers(entity: Type<object>, installed?: InstalledTriggers): string[];
+    generateTriggersDown(entity: Type<object>, installed?: InstalledTriggers): string[];
+    /** `dropped` taken off `entity`'s table and `created` put on, which is a reconcile read either way. */
+    private swapTriggers;
+    generateTriggerDrops(entity: Type<object>, names: readonly string[]): string[];
     /**
      * One statement per distinct schema the tables being created live in, in first-seen order. Only
      * the tables actually being created, so a narrowed `only` does not declare namespaces it is not
@@ -57,18 +68,19 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
      */
     private orderedTables;
     generateDropTable(tableName: string, options?: DropSchemaOptions): string;
+    /**
+     * The statements taking a table through `diff`, in the one order both directions need: whatever holds
+     * something down goes before it and comes back after it. A foreign key holds its columns and the key it
+     * points at, so it goes first and comes back last; the key holds its columns; and some engines drop an
+     * index along with its column, which would leave nothing to name. An alter is its drop, then its add.
+     */
     generateAlterTable(diff: SchemaDiff): string[];
     /** `ADD CONSTRAINT` for each of `foreignKeys`. */
     private addForeignKeyStatements;
-    /** `DROP CONSTRAINT` for each of `constraintNames`, the mirror of {@link addForeignKeyStatements}. */
-    private dropForeignKeyStatements;
-    /** The `ALTER COLUMN` restating each of `columns`. */
-    private alterColumnStatements;
     /** An index added to a table that may already have rows: its `CREATE`, then what the engine needs after. */
     private addIndexStatements;
-    /** `DROP INDEX` for each of `indexes`, the mirror of {@link addIndexStatements}. */
-    private dropIndexStatements;
-    generateAlterTableDown(diff: SchemaDiff): string[];
+    /** A column added to a table that exists, and its comment where the engine keeps one apart. */
+    private addColumnStatements;
     generateCreateIndex(tableName: string, index: IndexSchema, options?: {
         ifNotExists?: boolean;
     }): string;
@@ -85,8 +97,8 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
     /**
      * The one place a column definition is spelled, so the `ColumnSchema` and `ColumnNode` paths cannot
      * drift. A key column states `NOT NULL` rather than leave it to the key: SQLite lets a key column hold
-     * NULL otherwise, and SQL Server adds no key over a nullable column. `UNIQUE` is left to the key. An
-     * enum's `CHECK` comes last, the only place MariaDB takes it.
+     * NULL otherwise, and SQL Server adds no key over a nullable column. Never `UNIQUE`: a unique column is
+     * a unique index, which the table creates beside it. An enum's `CHECK` comes last, the only place MariaDB takes it.
      */
     private renderColumn;
     /**
@@ -113,10 +125,8 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
     protected diffOptions(): DiffOptions;
     /** Spread, not copied field by field, so a field the node gains cannot go missing here. */
     private columnNodeToSchema;
-    /**
-     * Compare two default values for equality
-     */
-    protected isDefaultValueEqual(current: unknown, desired: unknown): boolean;
+    /** Whether a column's stored default is the one the entity declares, as this engine reprints it. */
+    readonly defaultsEqual: (desired: unknown, current: unknown) => boolean;
     generateCreateTableFromNode(table: TableNode, options?: {
         ifNotExists?: boolean;
     }): string[];
@@ -175,4 +185,4 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
  * The entities as an AST, named by `generator`'s resolvers rather than a naming strategy, which would
  * also rename an explicit `@Entity({ name })` and so compare each table under another name.
  */
-export declare function buildEntityAST(generator: Pick<SchemaGenerator, 'resolveTableAlias' | 'resolveSchema' | 'resolveColumnName' | 'compileDdl' | 'compileIndexPredicate'>, entities: readonly Type<object>[], options?: Pick<BuildSchemaASTOptions, 'defaultForeignKeyAction' | 'textScoreIndexes'>): SchemaAST;
+export declare function buildEntityAST(generator: Pick<SchemaGenerator, 'resolveTableAlias' | 'resolveSchema' | 'resolveColumnName' | 'compileDdl' | 'compileIndexPredicate'>, entities: readonly Type<object>[], options?: Pick<BuildSchemaASTOptions, 'defaultForeignKeyAction' | 'textScoreIndexes' | 'vectorIndexRequiresNotNull'>): SchemaAST;