uql-orm 0.87.0 → 0.89.0

package/dist/migrate/migrator.js

@@ -7,10 +7,11 @@ import { columnRenames, tableRenameCandidates } from '../schema/schemaASTDiffer.
 import { hasTriggers } from '../util/field.util.js';
 import { LoggerWrapper } from '../util/index.js';
 import { UqlUsageError } from '../util/uqlError.js';
+import { withSqlQuerierForMigrations } from './acquireQuerierForMigrations.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';
+import { dropped, lacksValue, newlyRequired, nonEmpty, reverseDiff, sides, withoutRebuild } from './schemaChange.js';
 /**
  * Main class for managing database migrations
  */
@@ -185,6 +186,7 @@ export class Migrator {
     async generateFromEntities(name) {
         const generator = await this.getSchemaGenerator();
         const { created, altered } = await this.pendingChanges({ renames: true });
+        await this.assertFillable(altered);
         const plan = this.alterPlan(generator, altered, await this.installedTriggers(created));
         await this.noteChanges(generator, created, altered);
         const up = [...this.createSchema(generator, created), ...plan.up];
@@ -237,7 +239,7 @@ export class Migrator {
      */
     alterPlan(generator, altered, state) {
         const changing = new Set(altered
-            .filter((diff) => sides(diff.columns, 'from').length || diff.renamedColumns?.length)
+            .filter((diff) => sides(diff.columns, 'from').length || diff.renamedColumns?.length || diff.rebuild)
             .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));
@@ -290,6 +292,35 @@ export class Migrator {
                 `renamed, replace its creation in this migration with \`renameTable('${from}', '${to}')\`.`);
         }
     }
+    /**
+     * Refuses, before anything runs, each column the changes require with no default while rows would hold
+     * none: every engine fails on one but MySQL, which fills in a zero. Counted, since an empty table is fine.
+     */
+    async assertFillable(altered) {
+        // A renamed column is identical but for its name, so the one counted is never renamed too.
+        const counts = altered.flatMap(({ tableName, columns }) => newlyRequired(columns)
+            .filter(({ to }) => lacksValue(to))
+            .map(({ from, to }) => ({ tableName, column: to.name, nullable: from })));
+        if (!counts.length) {
+            return;
+        }
+        const unfilled = await withSqlQuerierForMigrations(this.pool, 'Migrator', async (querier) => {
+            const escapeId = (name) => querier.dialect.escapeId(name);
+            const found = [];
+            for (const { tableName, column, nullable } of counts) {
+                const empty = nullable ? ` WHERE ${escapeId(column)} IS NULL` : '';
+                const [{ rows }] = await querier.all(`SELECT COUNT(*) AS ${escapeId('rows')} FROM ${escapeId(tableName)}${empty}`);
+                const count = Number(rows);
+                if (count) {
+                    found.push(`"${tableName}"."${column}" is required with no default, and ${count} ${count === 1 ? 'row holds' : 'rows hold'} none`);
+                }
+            }
+            return found;
+        });
+        if (unfilled.length) {
+            throw new UqlUsageError(`${unfilled.join('; ')}. Declare a default, or add the column nullable, fill it, then require it.`);
+        }
+    }
     /** The tables the database holds that no entity names, each paired with a new one it is identical to. */
     async renamedTables(generator, created) {
         const createdEntities = this.createdEntities(created);
@@ -386,6 +417,7 @@ export class Migrator {
         const ast = await this.introspectEntities([entity, ...referencedEntities(meta)]);
         // 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);
+        await this.assertFillable(altered);
         return this.alterPlan(generator, altered, await this.installedTriggers([], [entity])).up;
     }
     /** The diff for one entity against the table it already has, and none where the two agree. */
@@ -418,6 +450,7 @@ export class Migrator {
         }
         const { created, altered } = await this.pendingChanges();
         const filtered = altered.map((diff) => this.filterDiff(diff, options));
+        await this.assertFillable(filtered);
         return [
             ...this.createSchema(generator, created),
             ...this.alterPlan(generator, filtered, await this.installedTriggers(created)).up,
@@ -442,12 +475,15 @@ export class Migrator {
     /**
      * 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.
+     * Without `drop`, a column's drop is held too. A rebuilt table applies its diff whole, so holding any
+     * part of it holds the rebuild, and only what an `ALTER` adds goes ahead: a plain column, an index.
      */
     filterDiff(diff, options) {
         const safe = options.safe !== false;
+        let held = false;
         const skip = (what, names, fix) => {
             if (names.length) {
+                held = true;
                 this.logger.logSkippedMigration(`[AutoSync] Skipped ${names.length} ${what} in table '${diff.tableName}': ${names.join(', ')} (${fix}).`);
             }
         };
@@ -466,13 +502,18 @@ export class Migrator {
         if (!options.drop) {
             skip('column drops', dropped(columns).map((column) => column.name), 'drop: false. Use { drop: true } to apply');
         }
-        return {
+        const filtered = {
             ...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(', ')),
         };
+        if (!diff.rebuild || !held) {
+            return filtered;
+        }
+        skip('rebuild', [diff.tableName], 'it applies the whole diff, and part of it is held');
+        return withoutRebuild(filtered);
     }
     /** Runs the statements a generator wrote, in one transaction where the engine takes DDL in one. */
     async executeSyncStatements(statements, options) {
@@ -599,6 +640,8 @@ function referencedEntities(meta) {
     return [...fields, ...relations];
 }
 /** A diff's column renames, through the builder operation every SQL generator already renders. */
-function renameStatements(generator, { tableName, renamedColumns = [] }) {
-    return renamedColumns.flatMap(({ from, to }) => generator.generateOperation({ type: 'renameColumn', tableName, oldName: from, newName: to }));
+function renameStatements(generator, { tableName, renamedColumns = [], rebuild }) {
+    return rebuild
+        ? []
+        : renamedColumns.flatMap(({ from, to }) => generator.generateOperation({ type: 'renameColumn', tableName, oldName: from, newName: to }));
 }

package/dist/migrate/schemaChange.d.ts

@@ -1,4 +1,4 @@
-import type { Change, SchemaDiff } from '../type/index.js';
+import type { Change, ColumnSchema, 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`. */
@@ -10,6 +10,17 @@ export declare function alterations<T>(changes?: readonly Change<T>[]): {
     readonly from: T;
     readonly to: T;
 }[];
+/** Each column `changes` make required on the rows already there: added so, or no longer nullable. */
+export declare function newlyRequired(changes?: readonly Change<ColumnSchema>[]): {
+    readonly from?: ColumnSchema;
+    readonly to: ColumnSchema;
+}[];
+/** Whether a row already in the table would hold nothing in `column`: required, with no default, and not one the engine fills. */
+export declare function lacksValue(column: ColumnSchema): boolean;
+/** Whether `diff` holds anything an engine that rebuilds tables makes no other way, a key or a foreign key included. */
+export declare function needsRebuild(diff: SchemaDiff): boolean;
+/** `diff` less its rebuild and everything only a rebuild makes: what an `ALTER` can still apply alone. */
+export declare function withoutRebuild(diff: SchemaDiff): SchemaDiff;
 /** `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. */

package/dist/migrate/schemaChange.js

@@ -17,6 +17,32 @@ export function dropped(changes = []) {
 export function alterations(changes = []) {
     return changes.flatMap(({ from, to }) => (from === undefined || to === undefined ? [] : [{ from, to }]));
 }
+/** Each column `changes` make required on the rows already there: added so, or no longer nullable. */
+export function newlyRequired(changes = []) {
+    return changes.flatMap(({ from, to }) => (to && !to.nullable && (!from || from.nullable) ? [{ from, to }] : []));
+}
+/** Whether a row already in the table would hold nothing in `column`: required, with no default, and not one the engine fills. */
+export function lacksValue(column) {
+    return !column.nullable && column.defaultValue === undefined && !column.generatedAs && !column.isAutoIncrement;
+}
+/** Whether an engine that rebuilds tables makes `change` no other way: a column changed in place, or a stored generated one added. */
+function onlyRebuilt({ from, to }) {
+    return from === undefined ? Boolean(to?.generatedAs) : to !== undefined;
+}
+/** Whether `diff` holds anything an engine that rebuilds tables makes no other way, a key or a foreign key included. */
+export function needsRebuild(diff) {
+    return Boolean(diff.primaryKey || diff.foreignKeys || diff.columns?.some(onlyRebuilt));
+}
+/** `diff` less its rebuild and everything only a rebuild makes: what an `ALTER` can still apply alone. */
+export function withoutRebuild(diff) {
+    return {
+        ...diff,
+        primaryKey: undefined,
+        foreignKeys: undefined,
+        columns: nonEmpty((diff.columns ?? []).filter((change) => !onlyRebuilt(change))),
+        rebuild: undefined,
+    };
+}
 /** `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;
@@ -34,5 +60,6 @@ export function reverseDiff(diff) {
         indexes: diff.indexes?.map(swap),
         foreignKeys: diff.foreignKeys?.map(swap),
         renamedColumns: diff.renamedColumns?.map(({ from, to }) => ({ from: to, to: from })),
+        rebuild: diff.rebuild && { from: diff.rebuild.to, to: diff.rebuild.from },
     };
 }

package/dist/migrate/schemaGenerator.d.ts

@@ -75,6 +75,11 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
      * index along with its column, which would leave nothing to name. An alter is its drop, then its add.
      */
     generateAlterTable(diff: SchemaDiff): string[];
+    /**
+     * Each column the changes make required while declaring a default, and that default as SQL: the rows
+     * already there hold a null it has to replace, and it is the only value the entity says it may take.
+     */
+    private defaultFills;
     /** `ADD CONSTRAINT` for each of `foreignKeys`. */
     private addForeignKeyStatements;
     /** An index added to a table that may already have rows: its `CREATE`, then what the engine needs after. */
@@ -120,6 +125,12 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
      * drift detection runs, with types normalized as the engine stores them.
      */
     diffSchema(entity: Type<object>, currentTable: TableNode | undefined, desiredAst?: SchemaAST, renamedColumns?: readonly Rename[]): SchemaDiff | undefined;
+    /**
+     * Both ends of rebuilding `actual` as `desired`. The new table is the entity's, keeping what it cannot
+     * know of: the indexes and triggers uql did not make, and foreign keys to tables no entity names. The
+     * old one is the engine's own statements, so a rollback restores it exactly, checks included.
+     */
+    private rebuildOf;
     diffOptions(): DiffOptions;
     /** Spread, not copied field by field, so a field the node gains cannot go missing here. */
     private columnNodeToSchema;
@@ -172,12 +183,13 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
      * generator added it. MySQL takes no name.
      */
     generateDropPrimaryKeySql(tableName: string, constraintName?: string): string;
+    /** A stored generated column, which an engine that rebuilds tables takes only in a `CREATE TABLE`. */
+    private assertColumnAddable;
     /**
-     * A column an `ALTER` can carry. Only a generated one is ever refused, and only where the engine
-     * takes it in a `CREATE TABLE` but not afterwards.
+     * Refuses `what` where the engine makes it only by rebuilding the table, which a migration generated
+     * from the entities does and a lone statement of the builder cannot.
      */
-    private assertColumnAddable;
-    private assertPrimaryKeyAlterable;
+    private assertAlterable;
 }
 /**
  * The entities as an AST, named by `generator`'s resolvers rather than a naming strategy, which would

package/dist/migrate/schemaGenerator.js

@@ -6,14 +6,15 @@ import { diffRelationshipNodes, diffTable } from '../schema/schemaASTDiffer.js';
 import { isAutoIncrement, qualifyName } from '../util/index.js';
 import { derivedCheckName, derivedForeignKeyName, derivedPrimaryKeyName, isOwnedName } from '../util/sql.util.js';
 import { UqlUsageError } from '../util/uqlError.js';
-import { sameDefault } from './builder/expressions.js';
+import { formatDefaultValue, sameDefault } from './builder/expressions.js';
 import { splitSqlStatements } from './builder/splitSqlStatements.js';
 import { indexDdlFor, tableDdlFor } from './ddl/index.js';
 import { sizedType } from './ddl/tableDdl.js';
+import { rebuildTable } from './ddl/tableRebuild.js';
 import { columnForeignKey, columnIndex, fullColumnDefinitionToNode, renderIndexDefinition, tableDefinitionToNode, } from './generator/definitionToNode.js';
 import { indexNodeToSchema } from './generator/indexNodeToSchema.js';
 import { assertIndexPredicate } from './indexPredicate.js';
-import { added, alterations, dropped, nonEmpty, sides } from './schemaChange.js';
+import { added, alterations, dropped, needsRebuild, newlyRequired, nonEmpty, sides } from './schemaChange.js';
 import { dropTrigger, renderTrigger, stampTriggers } from './triggerSql.js';
 /**
  * Unified SQL schema generator.
@@ -92,7 +93,7 @@ export class SqlSchemaGenerator {
         const withForeignKeys = options.foreignKeys ?? true;
         // Inline only where a constraint cannot be added afterwards, which is what makes the cyclic case
         // work everywhere else.
-        const inline = withForeignKeys && !this.features.foreignKeyAlter;
+        const inline = withForeignKeys && this.features.rebuildsTables;
         // Namespaces first: a qualified `CREATE TABLE` fails against a schema nobody created, and the
         // schema is the one part of the layout a migration cannot infer from the table it is making.
         const statements = this.generateCreateSchemas(tables);
@@ -183,13 +184,21 @@ export class SqlSchemaGenerator {
      * index along with its column, which would leave nothing to name. An alter is its drop, then its add.
      */
     generateAlterTable(diff) {
-        const { tableName, schema, primaryKey } = diff;
-        const { columns } = diff;
+        const { tableName, schema, primaryKey, columns, rebuild } = diff;
+        const fills = this.defaultFills(columns);
+        if (rebuild) {
+            return rebuildTable(this.dialect, tableName, rebuild, { renames: diff.renamedColumns ?? [], fills });
+        }
+        const target = this.escapeId(tableName);
         return [
             ...sides(diff.foreignKeys, 'from').map((foreignKey) => this.generateDropForeignKeySql(tableName, constraintNameOf(tableName, foreignKey))),
             ...(primaryKey?.from ? [this.generateDropPrimaryKeySql(tableName, primaryKey.from.name)] : []),
             ...sides(diff.indexes, 'from').map((index) => this.generateDropIndex(tableName, index.name, schema)),
             ...added(columns).flatMap((column) => this.addColumnStatements(tableName, column, schema)),
+            ...[...fills].map(([column, value]) => {
+                const name = this.escapeId(column);
+                return `UPDATE ${target} SET ${name} = ${value} WHERE ${name} IS NULL;`;
+            }),
             ...alterations(columns).flatMap(({ from, to }) => this.tableDdl.alterColumn(tableName, to, this.generateColumnDefinitionFromSchema(to), from)),
             ...dropped(columns).flatMap((column) => this.tableDdl.dropColumn(tableName, column.name)),
             ...this.addIndexStatements(tableName, sides(diff.indexes, 'to')),
@@ -197,6 +206,15 @@ export class SqlSchemaGenerator {
             ...this.addForeignKeyStatements(tableName, sides(diff.foreignKeys, 'to')),
         ];
     }
+    /**
+     * Each column the changes make required while declaring a default, and that default as SQL: the rows
+     * already there hold a null it has to replace, and it is the only value the entity says it may take.
+     */
+    defaultFills(columns) {
+        return new Map(newlyRequired(columns)
+            .filter(({ from, to }) => from && to.defaultValue !== undefined)
+            .map(({ to }) => [to.name, formatDefaultValue(to.defaultValue, this.dialect, to.type)]));
+    }
     /** `ADD CONSTRAINT` for each of `foreignKeys`. */
     addForeignKeyStatements(tableName, foreignKeys) {
         return foreignKeys.map((foreignKey) => this.generateAddForeignKeySql(tableName, foreignKey));
@@ -212,7 +230,7 @@ export class SqlSchemaGenerator {
     addColumnStatements(tableName, column, schema) {
         this.assertColumnAddable(tableName, column);
         return [
-            this.tableDdl.addColumn(tableName, this.generateColumnDefinitionFromSchema(column)),
+            ...this.tableDdl.addColumnStatements(tableName, column, (it) => this.generateColumnDefinitionFromSchema(it)),
             ...this.generateColumnCommentStatement(tableName, column, schema),
         ];
     }
@@ -339,11 +357,7 @@ export class SqlSchemaGenerator {
                 name: derivedPrimaryKeyName(tableName, keyDiff.expected.columns),
             },
         };
-        // This table's own foreign keys. None where the engine cannot alter one (SQLite, short of rebuilding
-        // the table), since a difference nothing can apply would throw on every sync; `drift:check` names it.
-        const relationDiffs = this.features.foreignKeyAlter
-            ? diffRelationshipNodes(desired.outgoingRelations, currentTable.outgoingRelations, this.diffOptions())
-            : [];
+        const relationDiffs = diffRelationshipNodes(desired.outgoingRelations, currentTable.outgoingRelations, this.diffOptions());
         const foreignKeys = relationDiffs.map(({ actual, expected }) => ({
             from: actual && foreignKeyOf(actual),
             to: expected && foreignKeyOf(expected),
@@ -362,9 +376,38 @@ export class SqlSchemaGenerator {
             foreignKeys: nonEmpty(foreignKeys),
             renamedColumns: nonEmpty(renamedColumns ?? []),
         };
-        return alter.primaryKey || alter.columns || alter.indexes || alter.foreignKeys || alter.renamedColumns
-            ? alter
-            : undefined;
+        if (!(alter.primaryKey || alter.columns || alter.indexes || alter.foreignKeys || alter.renamedColumns)) {
+            return undefined;
+        }
+        return this.features.rebuildsTables && needsRebuild(alter)
+            ? { ...alter, rebuild: this.rebuildOf(desired, currentTable, indexes.kept, renamedColumns ?? []) }
+            : alter;
+    }
+    /**
+     * Both ends of rebuilding `actual` as `desired`. The new table is the entity's, keeping what it cannot
+     * know of: the indexes and triggers uql did not make, and foreign keys to tables no entity names. The
+     * old one is the engine's own statements, so a rollback restores it exactly, checks included.
+     */
+    rebuildOf(desired, actual, kept, renames) {
+        const definition = actual.definition ?? [];
+        const read = new Set(actual.indexes.map((index) => index.name));
+        const own = (entry) => entry.kind === 'trigger' && isOwnedName(entry.name);
+        const verbatim = (entries) => entries.map((entry) => `${entry.sql};`);
+        const stored = (table) => [...table.columns.values()].filter((column) => !column.generatedAs).map((column) => column.name);
+        return {
+            from: {
+                statements: verbatim(definition.filter((entry) => !own(entry))),
+                columns: stored(actual).map((name) => renames.find((rename) => rename.to === name)?.from ?? name),
+            },
+            to: {
+                statements: [
+                    ...this.generateCreateTableFromNode({ ...desired, externalForeignKeys: actual.externalForeignKeys }),
+                    ...kept.map((index) => this.generateCreateIndexFromNode(index)),
+                    ...verbatim(definition.filter((entry) => (entry.kind === 'index' && !read.has(entry.name)) || (entry.kind === 'trigger' && !own(entry)))),
+                ],
+                columns: stored(desired),
+            },
+        };
     }
     diffOptions() {
         return {
@@ -406,6 +449,9 @@ export class SqlSchemaGenerator {
             const refTable = this.dialect.escapeQualifiedId(rel.to.table.name, rel.to.table.schema);
             constraints.push(this.foreignKeyConstraint(table.name, foreignKeyOf(rel), refTable));
         }
+        for (const foreignKey of table.externalForeignKeys) {
+            constraints.push(this.foreignKeyConstraint(table.name, foreignKey, this.escapeId(foreignKey.references.table)));
+        }
         const target = this.dialect.escapeQualifiedId(table.name, table.schema);
         let createSql = `${this.tableDdl.createTable(target, !!options.ifNotExists)} (\n`;
         createSql += columns.map((col) => `  ${col}`).join(',\n');
@@ -497,9 +543,7 @@ export class SqlSchemaGenerator {
     }
     /** `ADD COLUMN`, plus the foreign key and index the column declares, as `CREATE TABLE` lifts them. */
     generateAddColumnSql(tableName, column) {
-        this.assertColumnAddable(tableName, column);
-        const colSql = this.generateColumnFromNode(fullColumnDefinitionToNode(column, tableName));
-        const statements = [this.tableDdl.addColumn(tableName, colSql)];
+        const statements = this.addColumnStatements(tableName, this.columnNodeToSchema(fullColumnDefinitionToNode(column, tableName)));
         const foreignKey = columnForeignKey(column);
         if (foreignKey) {
             statements.push(...this.addForeignKeyStatements(tableName, [foreignKey]));
@@ -508,10 +552,10 @@ export class SqlSchemaGenerator {
         if (index) {
             statements.push(this.generateCreateIndex(tableName, index));
         }
-        statements.push(...this.generateColumnCommentStatement(tableName, column));
         return statements;
     }
     generateAlterColumnSql(tableName, columnName, column) {
+        this.assertAlterable(`Altering the column "${columnName}" of "${tableName}"`);
         const node = fullColumnDefinitionToNode(column, tableName);
         return this.tableDdl.alterColumn(tableName, { ...this.columnNodeToSchema(node), name: columnName }, this.generateColumnFromNode(node));
     }
@@ -536,9 +580,7 @@ export class SqlSchemaGenerator {
             `ON UPDATE ${foreignKey.onUpdate ?? this.defaultForeignKeyAction}`);
     }
     generateAddForeignKeySql(tableName, foreignKey) {
-        if (!this.features.foreignKeyAlter) {
-            throw new UqlUsageError(`Dialect ${this.dialect} does not support adding foreign keys to existing tables`);
-        }
+        this.assertAlterable(`Adding a foreign key to "${tableName}"`);
         const constraint = this.foreignKeyConstraint(tableName, foreignKey, this.escapeId(foreignKey.references.table));
         return `ALTER TABLE ${this.escapeId(tableName)} ADD ${constraint};`;
     }
@@ -551,7 +593,7 @@ export class SqlSchemaGenerator {
      * rather than emitting DDL it will reject.
      */
     generateAddPrimaryKeySql(tableName, columns, name) {
-        this.assertPrimaryKeyAlterable(tableName);
+        this.assertAlterable(`Changing the primary key of "${tableName}"`);
         const constraintName = this.escapeId(name ?? derivedPrimaryKeyName(tableName, columns));
         const pkCols = columns.map((c) => this.escapeId(c)).join(', ');
         return `ALTER TABLE ${this.escapeId(tableName)} ADD CONSTRAINT ${constraintName} PRIMARY KEY (${pkCols});`;
@@ -561,7 +603,7 @@ export class SqlSchemaGenerator {
      * generator added it. MySQL takes no name.
      */
     generateDropPrimaryKeySql(tableName, constraintName) {
-        this.assertPrimaryKeyAlterable(tableName);
+        this.assertAlterable(`Changing the primary key of "${tableName}"`);
         const table = this.escapeId(tableName);
         if (this.dialect.dropPrimaryKeySyntax === 'DROP PRIMARY KEY') {
             return `ALTER TABLE ${table} DROP PRIMARY KEY;`;
@@ -572,24 +614,21 @@ export class SqlSchemaGenerator {
         }
         return `ALTER TABLE ${table} DROP CONSTRAINT ${this.escapeId(constraintName)};`;
     }
-    /**
-     * A column an `ALTER` can carry. Only a generated one is ever refused, and only where the engine
-     * takes it in a `CREATE TABLE` but not afterwards.
-     */
+    /** A stored generated column, which an engine that rebuilds tables takes only in a `CREATE TABLE`. */
     assertColumnAddable(tableName, column) {
-        if (!column.generatedAs || this.features.generatedColumnAdd) {
-            return;
+        if (column.generatedAs) {
+            this.assertAlterable(`Adding the stored column "${column.name}" to "${tableName}"`);
         }
-        throw new UqlUsageError(`${this.dialect}: Cannot add the computed column "${column.name}" to the existing table ` +
-            `"${tableName}" - this database only accepts one in a CREATE TABLE. Drop \`stored\` to have the ` +
-            'expression spliced into each statement instead, or recreate the table in a written migration.');
     }
-    assertPrimaryKeyAlterable(tableName) {
-        if (this.features.primaryKeyAlter) {
-            return;
+    /**
+     * Refuses `what` where the engine makes it only by rebuilding the table, which a migration generated
+     * from the entities does and a lone statement of the builder cannot.
+     */
+    assertAlterable(what) {
+        if (this.features.rebuildsTables) {
+            throw new UqlUsageError(`${this.dialect}: ${what} rebuilds the table, which a migration generated from the entities does ` +
+                '(`uql-migrate generate:entities`) and a hand-written one cannot.');
         }
-        throw new UqlUsageError(`${this.dialect}: Cannot change the primary key of "${tableName}" - this database has no ALTER ` +
-            'for it. Recreate the table in a written migration.');
     }
 }
 /**

package/dist/migrate/triggerSql.js

@@ -1,7 +1,9 @@
+import { TriggerWriteRaw } from '../type/index.js';
 import { stampEvents } from '../util/field.util.js';
 import { definedEntries } from '../util/object.util.js';
 import { raw, refs, rowRefs } from '../util/raw.js';
 import { ownedName } from '../util/sql.util.js';
+import { written } from '../util/triggerWrite.js';
 import { UqlUsageError } from '../util/uqlError.js';
 /**
  * One trigger for `dialect`, named for its table and label and ending in a hash of its own SQL. That hash
@@ -48,31 +50,35 @@ function triggerStatements(dialect, meta, trigger, name) {
     const features = dialect.features.triggers;
     const [timing, operation] = EVENT_PARTS[trigger.on];
     const before = timing === 'BEFORE';
-    const body = triggerBody(dialect, meta, trigger, before);
-    const id = triggerId(dialect, meta, name);
-    const table = dialect.escapedTableName(meta);
+    const { fires } = features;
+    const perStatement = fires === 'eachStatement';
     const names = rowNames(dialect);
     const rows = [rowRefs(meta.entity, names.$new), rowRefs(meta.entity, names.$old)];
-    const sql = dialect.compileDdl(body(...rows), meta.entity, { rows: rowsFrom(dialect, meta, operation) });
-    const guard = triggerGuard(dialect, meta, trigger, rows, names);
-    const inBody = features.guards !== 'clause';
-    const guarded = !guard || !inBody
-        ? sql
-        : features.guards === 'beginEnd'
-            ? `IF ${guard}\nBEGIN\n${sql}\nEND`
-            : `IF ${guard} THEN\n${sql}\nEND IF;`;
-    // The preamble opens the body, outside the guard: it settles how the batch reports itself rather than
-    // which rows are touched, so it runs even when the guard keeps the statements from running.
+    const filter = triggerFilter(dialect, meta, trigger, rows, names);
+    const body = triggerBody(dialect, meta, trigger, before)(...rows);
+    if (perStatement && filter && !(body instanceof TriggerWriteRaw)) {
+        throw new UqlUsageError(`${dialect.dialectName} fires a trigger once per statement, so 'of' and 'where' narrow only what ` +
+            `insertInto, updateTable or deleteFrom reads, and '${meta.entity.name}' has one running its own SQL. ` +
+            'Keep the body to those writes, or filter inserted and deleted in that SQL.');
+    }
+    const sql = dialect.compileDdl(body, meta.entity, {
+        rows: perStatement ? rowsFrom(dialect, meta, operation, names, filter) : undefined,
+    });
+    // A per-row engine keeps to the selected rows by a guard; a per-statement one narrowed what the body reads.
+    const guarded = filter && fires === 'eachRowIf' ? `IF ${filter} THEN\n${sql}\nEND IF;` : sql;
     const opened = features.preamble ? `${features.preamble}\n${guarded}` : guarded;
-    const of = features.guards === 'clause' && operation === 'UPDATE' && trigger.of?.length
+    const id = triggerId(dialect, meta, name);
+    const table = dialect.escapedTableName(meta);
+    const byWhen = fires === 'eachRowWhen';
+    const of = byWhen && operation === 'UPDATE' && trigger.of?.length
         ? ` OF ${trigger.of.map((key) => dialect.escapedColumnName(meta, key)).join(', ')}`
         : '';
-    const each = features.rows === 'set' ? '' : '\nFOR EACH ROW';
-    const clause = guard && !inBody ? `\nWHEN (${guard})` : '';
-    const when = `${timing} ${operation}${of}`;
+    const each = perStatement ? '' : '\nFOR EACH ROW';
+    const whenClause = filter && byWhen ? `\nWHEN (${filter})` : '';
+    const event = `${timing} ${operation}${of}`;
     const header = features.layout === 'tableFirst'
-        ? `CREATE TRIGGER ${id}\nON ${table} ${when}${each}${clause}\nAS`
-        : `CREATE TRIGGER ${id}\n${when} ON ${table}${each}${clause}`;
+        ? `CREATE TRIGGER ${id}\nON ${table} ${event}${each}${whenClause}\nAS`
+        : `CREATE TRIGGER ${id}\n${event} ON ${table}${each}${whenClause}`;
     if (features.body !== 'function') {
         return [`${header}\nBEGIN\n${opened}\nEND`];
     }
@@ -97,16 +103,10 @@ const EVENT_PARTS = {
  * PL/pgSQL, MariaDB MySQL's.
  */
 function triggerBody(dialect, meta, trigger, before) {
-    const features = dialect.features.triggers;
-    if (before && !features.before) {
+    if (before && !dialect.features.triggers.before) {
         throw new UqlUsageError(`${dialect.dialectName} has no BEFORE trigger, only AFTER and INSTEAD OF, so '${trigger.on}' cannot be ` +
             'rendered there. Use the matching after event, which sees the row already written.');
     }
-    if (trigger.where && features.rows === 'set') {
-        throw new UqlUsageError(`${dialect.dialectName} fires a trigger once per statement, over the rows it touched, so no condition ` +
-            `can read one row: '${meta.entity.name}' cannot state a trigger 'where' there. Guard inside the body ` +
-            'instead, where `inserted` and `deleted` can be read as tables.');
-    }
     const { run } = trigger;
     const body = typeof run === 'function' ? run : (run[dialect.dialectName] ?? run[dialect.dialectFamily]);
     if (!body) {
@@ -115,8 +115,11 @@ function triggerBody(dialect, meta, trigger, before) {
     }
     return body;
 }
-/** The one condition both guards reduce to: any watched column that moved, and whatever `where` asks. */
-function triggerGuard(dialect, meta, trigger, rows, names) {
+/**
+ * The rows a trigger fires for, as one condition on every engine: any watched column that moved, and
+ * whatever `where` asks. Empty where it names neither.
+ */
+function triggerFilter(dialect, meta, trigger, rows, names) {
     const moved = movedColumns(dialect, meta, trigger.of ?? [], names);
     return [
         ...(moved ? [moved] : []),
@@ -130,12 +133,12 @@ function plpgsqlFunction(id, block) {
 }
 /** What the engine calls the rows it hands a trigger: records on a row-based engine, tables on a set-based one. */
 function rowNames(dialect) {
-    return dialect.features.triggers.rows === 'set'
+    return dialect.features.triggers.fires === 'eachStatement'
         ? { $new: 'inserted', $old: 'deleted' }
         : { $new: 'NEW', $old: 'OLD' };
 }
 /**
- * The `where` guard as the terms an `AND` joins. A callback writes its own off the rows; a predicate
+ * The `where` filter as the terms an `AND` joins. A callback writes its own off the rows; a predicate
  * renders a term per row it names, spelled verbatim because `NEW` is a record the engine declares. Each
  * is an `operand` wherever another term sits beside it, bracketing itself if compound, as `$where` does.
  */
@@ -198,7 +201,7 @@ function stampBody(dialect, meta, key, value, newRow) {
     const stamped = dialect.compileDdl(value, entity);
     const differs = raw(({ ctx, escapedPrefix }) => ctx.append(dialect.neExpr(`${escapedPrefix}${dialect.escapedColumnName(meta, key)}`, stamped)));
     const where = { $and: [...keyed, differs] };
-    return raw(({ ctx, rows }) => dialect.triggerWrite(ctx, { kind: 'update', entity, set: { [key]: value }, where }, rows));
+    return written({ kind: 'update', entity, set: { [key]: value }, where });
 }
 /** A dollar quote the body does not contain, so no `$$` in it - a literal, a comment - ends the function early. */
 function dollarQuote(body) {
@@ -210,7 +213,7 @@ function dollarQuote(body) {
 }
 /**
  * Whether any watched column moved, null-safely, or `undefined` where none is watched: the two records
- * compared on a row-based engine, and on a set-based one the same question over a join of its two tables.
+ * compared on a row-based engine, the two tables' rows on a set-based one.
  */
 function movedColumns(dialect, meta, of, { $new: newName, $old: oldName }) {
     if (!of.length) {
@@ -220,26 +223,17 @@ function movedColumns(dialect, meta, of, { $new: newName, $old: oldName }) {
         const column = dialect.escapedColumnName(meta, key);
         return dialect.neExpr(`${oldName}.${column}`, `${newName}.${column}`);
     });
-    const moved = differs.length > 1 ? `(${differs.join(' OR ')})` : differs.join('');
-    const source = rowsFrom(dialect, meta, 'UPDATE');
-    return source ? `EXISTS (SELECT 1 ${source} WHERE ${moved})` : moved;
+    return differs.length > 1 ? `(${differs.join(' OR ')})` : differs.join('');
 }
 /**
- * Where a set-based engine's body reads the rows it fires for, as the `FROM` a statement names them in:
- * `inserted` on an insert, `deleted` on a delete, and on an update both, joined on the whole key. None on a
- * row-based engine, whose body reads `NEW` and `OLD` bare.
+ * What a set-based engine's writes read: `inserted` on an insert, `deleted` on a delete, and on an update
+ * both, joined on the whole key, narrowed by `filter` to the rows a per-row engine would fire for.
  */
-function rowsFrom(dialect, meta, operation) {
-    if (dialect.features.triggers.rows !== 'set') {
-        return undefined;
-    }
-    const { $new, $old } = rowNames(dialect);
-    if (operation !== 'UPDATE') {
-        return `FROM ${operation === 'INSERT' ? $new : $old}`;
-    }
+function rowsFrom(dialect, meta, operation, { $new, $old }, filter) {
     const keyed = meta.ids.map((id) => {
         const column = dialect.escapedColumnName(meta, id);
         return `${$new}.${column} = ${$old}.${column}`;
     });
-    return `FROM ${$new} JOIN ${$old} ON ${keyed.join(' AND ')}`;
+    const from = operation === 'UPDATE' ? `${$new} JOIN ${$old} ON ${keyed.join(' AND ')}` : operation === 'INSERT' ? $new : $old;
+    return { from, where: filter || undefined };
 }

package/dist/mongo/mongoDialect.js

@@ -19,9 +19,7 @@ export const mongoDialectFeatures = {
     indexIfNotExists: false,
     schemas: false, // the connection picks the database, and a collection name takes no dot
     dropTableCascade: false,
-    foreignKeyAlter: false,
-    primaryKeyAlter: false,
-    generatedColumnAdd: false,
+    rebuildsTables: false,
     commentSyntax: 'none',
     vectorIndexRequiresNotNull: false,
     vectorSupportsLength: false,