uql-orm 0.86.0 → 0.88.0

package/dist/migrate/migrator.js

@@ -3,13 +3,15 @@ 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 { columnRenames, tableRenameCandidates } from '../schema/schemaASTDiffer.js';
 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
  */
@@ -183,8 +185,10 @@ export class Migrator {
      */
     async generateFromEntities(name) {
         const generator = await this.getSchemaGenerator();
-        const { created, altered } = await this.pendingChanges();
+        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];
         if (up.length === 0) {
             this.logger.logInfo('No schema changes detected.');
@@ -234,18 +238,23 @@ export class Migrator {
      * 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 changing = new Set(altered
+            .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));
         return {
             up: [
                 ...cleared.flatMap(({ entity, installed }) => generator.generateTriggerDrops(entity, [...installed.keys()])),
-                ...altered.flatMap((diff) => generator.generateAlterTable(diff)),
+                ...altered.flatMap((diff) => [...renameStatements(generator, diff), ...generator.generateAlterTable(diff)]),
                 ...this.reconcileTriggers(generator, after),
             ],
             down: () => [
                 ...this.revertedTriggers(generator, after),
-                ...altered.toReversed().flatMap((diff) => generator.generateAlterTable(reverseDiff(diff))),
+                ...altered.toReversed().flatMap((diff) => {
+                    const reversed = reverseDiff(diff);
+                    return [...generator.generateAlterTable(reversed), ...renameStatements(generator, reversed)];
+                }),
                 ...cleared.flatMap(({ installed }) => [...installed.values()].flat().map((sql) => `${sql};`)),
             ],
         };
@@ -265,6 +274,65 @@ export class Migrator {
     revertedTriggers(generator, state) {
         return state.flatMap(({ entity, installed }) => generator.generateTriggersDown(entity, installed));
     }
+    /**
+     * What a generated migration does that its reader must not miss: each column it drops or retypes, which
+     * can lose data, and each table it creates empty while the database holds one no entity names with the
+     * same columns, which may be the table renamed. That one is never renamed here: it may be another's.
+     */
+    async noteChanges(generator, created, altered) {
+        for (const { tableName, columns = [] } of altered) {
+            for (const { from, to } of columns.filter((change) => change.isBreaking)) {
+                this.logger.logWarn(to
+                    ? `Retypes "${tableName}"."${to.name}" from ${from?.type} to ${to.type}: a value that does not fit is lost or refused.`
+                    : `Drops "${tableName}"."${from?.name}", losing what it holds.`);
+            }
+        }
+        for (const { from, to } of await this.renamedTables(generator, created)) {
+            this.logger.logWarn(`Creates "${to}" empty, while "${from}", which no entity names, holds the same columns. If it was ` +
+                `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);
+        const diffOptions = generator.diffOptions?.();
+        if (!createdEntities.length || !generator.buildAST || !diffOptions) {
+            return [];
+        }
+        const owned = new Set(this.entities.map((entity) => this.tableOf(entity)));
+        const unowned = (await this.schemaIntrospector.getTableNames()).filter((table) => !owned.has(table));
+        const current = await this.schemaIntrospector.introspect(unowned);
+        return tableRenameCandidates(generator.buildAST(createdEntities), current, diffOptions);
+    }
     /** The entities whose tables are among `created`. */
     createdEntities(created) {
         const fresh = new Set(created);
@@ -275,18 +343,25 @@ export class Migrator {
         return this.pool.dialect.resolveTableName(getMeta(entity));
     }
     /**
-     * Get all schema differences between entities and database
+     * The differences between the entities and the database. With `renames`, a column identical to one the
+     * entity no longer names is renamed in place rather than dropped and added, as a generated migration wants.
      */
-    async getDiffs() {
+    async getDiffs(options = {}) {
         const generator = await this.getSchemaGenerator();
-        const ast = await this.introspectEntities(this.entities);
-        // Both sides built once: the database's above, the entities' here. Left to `diffSchema`, each
+        // Both sides built once: the database's here, the entities' below. Left to `diffSchema`, each
         // entity would rebuild the whole AST, which is quadratic in the number of entities. Absent on a
         // generator that compares no schema of its own - MongoDB, which reads only indexes.
         const desiredAst = generator.buildAST?.(this.entities);
+        let ast = await this.introspectEntities(this.entities);
+        const diffOptions = generator.diffOptions?.();
+        const renames = options.renames && desiredAst && diffOptions ? columnRenames(desiredAst, ast, diffOptions) : new Map();
+        if (renames.size) {
+            // Read again under the names the entities give them, so the rest compares as the columns they become.
+            ast = await this.introspectEntities(this.entities, renames);
+        }
         return this.entities.flatMap((entity) => {
-            const table = ast.getTable(generator.resolveTableName(getMeta(entity)));
-            const diff = generator.diffSchema(entity, table, desiredAst);
+            const tableName = generator.resolveTableName(getMeta(entity));
+            const diff = generator.diffSchema(entity, ast.getTable(tableName), desiredAst, renames.get(tableName));
             return diff ? [diff] : [];
         });
     }
@@ -294,13 +369,13 @@ export class Migrator {
      * The tables `entities` name, read a schema at a time so each is keyed as its entity spells it. Those
      * alone: nothing else is diffed, and another table can be dropped mid-scan by whatever else is running.
      */
-    async introspectEntities(entities) {
+    async introspectEntities(entities, renames) {
         const { dialect } = this.pool;
         const bySchema = Map.groupBy(new Set(entities), (entity) => dialect.resolveSchema(getMeta(entity)));
         const merged = new SchemaAST();
         for (const [schema, members] of bySchema) {
             const tables = members.map((entity) => dialect.resolveTableAlias(getMeta(entity)));
-            for (const table of (await this.schemaIntrospectorFor(schema).introspect(tables)).getTables()) {
+            for (const table of (await this.schemaIntrospectorFor(schema).introspect(tables, renames)).getTables()) {
                 merged.addTable(table);
             }
         }
@@ -342,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. */
@@ -374,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,
@@ -388,8 +465,8 @@ export class Migrator {
      * alter. What to emit for each stays with the caller: a sync narrows an alter to what it allows and
      * never asks for the rollback, which on SQLite cannot even be expressed (no `ALTER COLUMN`).
      */
-    async pendingChanges() {
-        const diffs = await this.getDiffs();
+    async pendingChanges(options = {}) {
+        const diffs = await this.getDiffs(options);
         return {
             created: diffs.filter((diff) => diff.type === 'create').map((diff) => diff.tableName),
             altered: diffs.filter((diff) => diff.type === 'alter'),
@@ -398,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}).`);
             }
         };
@@ -422,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) {
@@ -554,3 +639,9 @@ function referencedEntities(meta) {
     const relations = Object.values(meta.relations).flatMap((relation) => relation?.entity?.() ?? []);
     return [...fields, ...relations];
 }
+/** A diff's column renames, through the builder operation every SQL generator already renders. */
+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;
@@ -33,5 +59,7 @@ export function reverseDiff(diff) {
         columns: diff.columns?.map(swap),
         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

@@ -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, InstalledTriggers, 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, Rename, 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';
 /**
@@ -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. */
@@ -106,8 +111,6 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
      * one column of a composite key, which its table never makes serial.
      */
     getSqlType(field: FieldMeta): string;
-    /** The statements that alter `column` in place, as this dialect spells them. */
-    generateAlterColumnStatements(tableName: string, column: ColumnSchema, newDefinition: string): string[];
     /** The inline ` COMMENT '...'` a column declaration carries, where the engine takes one there. */
     generateColumnComment(comment: string): string;
     /** The `COMMENT ON` statements a table and its columns need, after the `CREATE TABLE`, where the engine uses them. */
@@ -121,8 +124,14 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
      * How the entity differs from the table the database reported, compared by {@link diffTable}, the one
      * drift detection runs, with types normalized as the engine stores them.
      */
-    diffSchema(entity: Type<object>, currentTable: TableNode | undefined, desiredAst?: SchemaAST): SchemaDiff | undefined;
-    protected diffOptions(): DiffOptions;
+    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;
     /** Whether a column's stored default is the one the entity declares, as this engine reprints it. */
@@ -174,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),
         ];
     }
@@ -270,10 +288,6 @@ export class SqlSchemaGenerator {
             ? this.serialType(canonical)
             : this.canonicalTypeToSql(canonical);
     }
-    /** The statements that alter `column` in place, as this dialect spells them. */
-    generateAlterColumnStatements(tableName, column, newDefinition) {
-        return this.tableDdl.alterColumn(tableName, column, newDefinition);
-    }
     /** The inline ` COMMENT '...'` a column declaration carries, where the engine takes one there. */
     generateColumnComment(comment) {
         return this.features.commentSyntax === 'inline' ? ` COMMENT ${this.dialect.escape(comment)}` : '';
@@ -302,7 +316,7 @@ export class SqlSchemaGenerator {
      * How the entity differs from the table the database reported, compared by {@link diffTable}, the one
      * drift detection runs, with types normalized as the engine stores them.
      */
-    diffSchema(entity, currentTable, desiredAst) {
+    diffSchema(entity, currentTable, desiredAst, renamedColumns) {
         const meta = getMeta(entity);
         const tableName = this.resolveTableName(meta);
         const schema = this.resolveSchema(meta);
@@ -326,11 +340,12 @@ export class SqlSchemaGenerator {
                 return { to: this.columnNodeToSchema(it.expected) };
             }
             if (it.type === 'drop') {
-                return { from: this.columnNodeToSchema(it.actual) };
+                return { from: this.columnNodeToSchema(it.actual), isBreaking: true };
             }
             return {
                 from: this.columnNodeToSchema(it.actual),
                 to: { ...this.columnNodeToSchema(it.expected), enum: undefined },
+                isBreaking: it.isBreaking,
             };
         });
         const keyDiff = tableDiff?.primaryKeyDiff;
@@ -342,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),
@@ -363,8 +374,40 @@ export class SqlSchemaGenerator {
                 ...indexes.toAlter.map(({ from, to }) => ({ from: indexNodeToSchema(from), to: indexNodeToSchema(to) })),
             ]),
             foreignKeys: nonEmpty(foreignKeys),
+            renamedColumns: nonEmpty(renamedColumns ?? []),
+        };
+        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),
+            },
         };
-        return alter.primaryKey || alter.columns || alter.indexes || alter.foreignKeys ? alter : undefined;
     }
     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,12 +552,12 @@ 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.generateAlterColumnStatements(tableName, { ...this.columnNodeToSchema(node), name: columnName }, this.generateColumnFromNode(node));
+        return this.tableDdl.alterColumn(tableName, { ...this.columnNodeToSchema(node), name: columnName }, this.generateColumnFromNode(node));
     }
     generateDropColumnSql(tableName, columnName) {
         return this.tableDdl.dropColumn(tableName, columnName);
@@ -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.');
     }
 }
 /**