uql-orm 0.86.0 → 0.87.0

package/dist/migrate/ddl/tableDdl.js

@@ -47,9 +47,11 @@ export class TableDdl {
         if (this.dialect.alterColumnStrategy !== 'separate-clauses') {
             return [`ALTER TABLE ${target} ${this.dialect.alterColumnSyntax} ${definition};`];
         }
-        const alter = `ALTER TABLE ${target} ALTER COLUMN ${this.dialect.escapeId(column.name)}`;
+        const name = this.dialect.escapeId(column.name);
+        const alter = `ALTER TABLE ${target} ALTER COLUMN ${name}`;
         return [
-            (!from || from.type !== column.type) && `${alter} TYPE ${column.type};`,
+            // Cast, since the engine converts only between types it deems compatible: text to integer needs saying.
+            (!from || from.type !== column.type) && `${alter} TYPE ${column.type} USING ${name}::${column.type};`,
             (!from || from.nullable !== column.nullable) && `${alter} ${column.nullable ? 'DROP NOT NULL' : 'SET NOT NULL'};`,
             (!from || !sameDefault(column.defaultValue, from.defaultValue, this.dialect)) &&
                 (column.defaultValue === undefined ? `${alter} DROP DEFAULT;` : `${alter} SET${this.defaultClause(column)};`),

package/dist/migrate/introspection/baseSqlIntrospector.d.ts

@@ -1,7 +1,7 @@
 import type { AbstractSqlDialect } from '../../dialect/index.js';
 import type { IndexFacet } from '../../schema/indexDifferences.js';
 import { SchemaAST } from '../../schema/schemaAST.js';
-import type { TableSchema } from '../../type/migration.js';
+import type { ColumnRenames, TableSchema } from '../../type/migration.js';
 /**
  * Base class for SQL introspectors with shared AST building logic.
  */
@@ -22,7 +22,9 @@ export declare abstract class BaseSqlIntrospector {
      * rather than raised: the point of naming them is to read a database other things are still
      * changing, where scanning every table is both wasted work and a relation that can vanish mid-scan.
      */
-    introspect(tables?: readonly string[]): Promise<SchemaAST>;
+    introspect(tables?: readonly string[], renames?: ColumnRenames): Promise<SchemaAST>;
+    /** `table` with each column `renames` names under its new name, wherever the table names it. */
+    private renamed;
     abstract getTableNames(): Promise<string[]>;
     abstract getTableSchema(tableName: string): Promise<TableSchema | undefined>;
     /**

package/dist/migrate/introspection/baseSqlIntrospector.js

@@ -1,7 +1,7 @@
 import { canonicalColumnType } from '../../schema/canonicalType.js';
 import { createTableNode, keyOfColumns, SchemaAST } from '../../schema/schemaAST.js';
 import { escapeSqlId } from '../../util/index.js';
-import { derivedForeignKeyName } from '../../util/sql.util.js';
+import { derivedForeignKeyName, qualifyName } from '../../util/sql.util.js';
 /**
  * Base class for SQL introspectors with shared AST building logic.
  */
@@ -27,17 +27,39 @@ export class BaseSqlIntrospector {
      * rather than raised: the point of naming them is to read a database other things are still
      * changing, where scanning every table is both wasted work and a relation that can vanish mid-scan.
      */
-    async introspect(tables) {
+    async introspect(tables, renames) {
         const tableNames = tables ?? (await this.getTableNames());
         const tableSchemas = [];
         for (const tableName of tableNames) {
             const schema = await this.getTableSchema(tableName);
             if (schema) {
-                tableSchemas.push(schema);
+                tableSchemas.push(renames ? this.renamed(schema, renames) : schema);
             }
         }
         return this.buildAST(tableSchemas);
     }
+    /** `table` with each column `renames` names under its new name, wherever the table names it. */
+    renamed(table, renames) {
+        const nameIn = (tableName) => (column) => renames.get(qualifyName(tableName, this.schema))?.find((rename) => rename.from === column)?.to ?? column;
+        const own = nameIn(table.name);
+        return {
+            ...table,
+            columns: table.columns.map((column) => ({ ...column, name: own(column.name) })),
+            primaryKey: table.primaryKey && { ...table.primaryKey, columns: table.primaryKey.columns.map(own) },
+            indexes: table.indexes?.map((index) => ({
+                ...index,
+                entries: index.entries.map((entry) => (entry.expression ? entry : { ...entry, column: own(entry.column) })),
+            })),
+            foreignKeys: table.foreignKeys?.map((foreignKey) => ({
+                ...foreignKey,
+                columns: foreignKey.columns.map(own),
+                references: {
+                    ...foreignKey.references,
+                    columns: foreignKey.references.columns.map(nameIn(foreignKey.references.table)),
+                },
+            })),
+        };
+    }
     /**
      * Build SchemaAST from table schemas.
      */

package/dist/migrate/migrator.d.ts

@@ -86,14 +86,25 @@ export declare class Migrator {
      * it. Read off the catalogue rather than recorded by uql, and exactly right for restoring one.
      */
     private revertedTriggers;
+    /**
+     * 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.
+     */
+    private noteChanges;
+    /** The tables the database holds that no entity names, each paired with a new one it is identical to. */
+    private renamedTables;
     /** The entities whose tables are among `created`. */
     private createdEntities;
     /** The table `entity` maps to, as a diff names it. */
     private tableOf;
     /**
-     * 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.
      */
-    getDiffs(): Promise<SchemaDiff[]>;
+    getDiffs(options?: {
+        renames?: boolean;
+    }): Promise<SchemaDiff[]>;
     /**
      * 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.

package/dist/migrate/migrator.js

@@ -3,6 +3,7 @@ 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';
@@ -183,8 +184,9 @@ 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 });
         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 +236,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)
+            .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 +272,36 @@ 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}')\`.`);
+        }
+    }
+    /** 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 +312,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 +338,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);
             }
         }
@@ -388,8 +432,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'),
@@ -554,3 +598,7 @@ 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 = [] }) {
+    return renamedColumns.flatMap(({ from, to }) => generator.generateOperation({ type: 'renameColumn', tableName, oldName: from, newName: to }));
+}

package/dist/migrate/schemaChange.js

@@ -33,5 +33,6 @@ 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 })),
     };
 }

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';
 /**
@@ -106,8 +106,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 +119,8 @@ 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;
+    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. */

package/dist/migrate/schemaGenerator.js

@@ -270,10 +270,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 +298,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 +322,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;
@@ -363,8 +360,11 @@ export class SqlSchemaGenerator {
                 ...indexes.toAlter.map(({ from, to }) => ({ from: indexNodeToSchema(from), to: indexNodeToSchema(to) })),
             ]),
             foreignKeys: nonEmpty(foreignKeys),
+            renamedColumns: nonEmpty(renamedColumns ?? []),
         };
-        return alter.primaryKey || alter.columns || alter.indexes || alter.foreignKeys ? alter : undefined;
+        return alter.primaryKey || alter.columns || alter.indexes || alter.foreignKeys || alter.renamedColumns
+            ? alter
+            : undefined;
     }
     diffOptions() {
         return {
@@ -513,7 +513,7 @@ export class SqlSchemaGenerator {
     }
     generateAlterColumnSql(tableName, columnName, column) {
         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);

package/dist/schema/matchByKey.d.ts

@@ -8,3 +8,12 @@ export declare function matchByKey<S, T>(source: Iterable<S>, target: Iterable<T
     dropped: T[];
     matched: (readonly [S, T])[];
 };
+/**
+ * What {@link matchByKey} left unpaired, paired where `same` finds exactly one counterpart on each side:
+ * an item two others could be is ambiguous, so it stays created or dropped.
+ */
+export declare function pairUnique<S, T>(created: readonly S[], dropped: readonly T[], same: (source: S, target: T) => boolean): {
+    created: S[];
+    dropped: T[];
+    matched: (readonly [S, T & ({} | null)])[];
+};

package/dist/schema/matchByKey.js

@@ -16,3 +16,21 @@ export function matchByKey(source, target, key) {
     }
     return { created, dropped: [...unpaired.values()].flat(), matched };
 }
+/**
+ * What {@link matchByKey} left unpaired, paired where `same` finds exactly one counterpart on each side:
+ * an item two others could be is ambiguous, so it stays created or dropped.
+ */
+export function pairUnique(created, dropped, same) {
+    const matched = created.flatMap((source) => {
+        const [target, ...others] = dropped.filter((candidate) => same(source, candidate));
+        return target !== undefined && !others.length && created.filter((other) => same(other, target)).length === 1
+            ? [[source, target]]
+            : [];
+    });
+    const paired = new Set(matched.flat());
+    return {
+        created: created.filter((item) => !paired.has(item)),
+        dropped: dropped.filter((item) => !paired.has(item)),
+        matched,
+    };
+}

package/dist/schema/schemaASTDiffer.d.ts

@@ -1,3 +1,4 @@
+import type { ColumnRenames, Rename } from '../type/migration.js';
 import type { SchemaAST } from './schemaAST.js';
 import type { CanonicalType } from './types.js';
 import type { ColumnDiff, ForeignKeyAction, IndexDiff, RelationshipDiff, RelationshipNode, SchemaDiffResult, TableDiff, TableNode } from './types.js';
@@ -28,6 +29,18 @@ export declare function diffTable(source: TableNode, target: TableNode, options?
     readonly columnDiffs: ColumnDiff[];
     readonly indexDiffs: IndexDiff[];
 }) | undefined;
+/**
+ * The columns renamed in the tables both sides name, by qualified table:
+ * a new column identical to exactly one the entity no longer names, and to no other. The dropped side is
+ * always the entity's own table, so a wrong guess renames, keeping the data, and never drops it.
+ */
+export declare function columnRenames(desired: SchemaAST, actual: SchemaAST, options?: DiffOptions): ColumnRenames;
+/**
+ * Tables the database holds that a new one is identical to but for its name, each only where it is the one
+ * match on both sides. Suggested, never applied: the database's side is a table no entity names, which may
+ * be another application's rather than one this schema renamed.
+ */
+export declare function tableRenameCandidates(desired: SchemaAST, actual: SchemaAST, options?: DiffOptions): Rename[];
 /** The differences between two lists of foreign keys, matched by their columns and never by the name the engine gave them. */
 export declare function diffRelationshipNodes(source: readonly RelationshipNode[], target: readonly RelationshipNode[], opts?: DiffOptions): RelationshipDiff[];
 /** A relationship's `ON DELETE` and `ON UPDATE`, an unstated one read as the action the database applies. */

package/dist/schema/schemaASTDiffer.js

@@ -1,6 +1,7 @@
+import { qualifyName } from '../util/sql.util.js';
 import { areTypesEqual, isBreakingTypeChange } from './canonicalType.js';
 import { describeIndexDifferences, pairIndexes } from './indexDifferences.js';
-import { matchByKey } from './matchByKey.js';
+import { matchByKey, pairUnique } from './matchByKey.js';
 import { DEFAULT_FOREIGN_KEY_ACTION } from './types.js';
 /**
  * Default diff options.
@@ -23,9 +24,7 @@ function relationEnds(relation) {
 /** The differences between the expected schema (the entities) and the actual one (the database). */
 export function diffSchemas(source, target, options = {}) {
     const opts = { ...DEFAULT_OPTIONS, ...options };
-    const normalizeName = nameNormalizer(opts);
-    const included = (tables) => [...tables].filter((table) => !opts.excludeTables.includes(table.name));
-    const { created: tablesToCreate, dropped: tablesToDrop, matched, } = matchByKey(included(source.tables.values()), included(target.tables.values()), (table) => normalizeName(table.name));
+    const { created: tablesToCreate, dropped: tablesToDrop, matched } = matchTables(source, target, opts);
     const tablesToAlter = matched
         .map(([sourceTable, targetTable]) => diffTable(sourceTable, targetTable, opts))
         .filter((tableDiff) => tableDiff !== undefined);
@@ -104,6 +103,38 @@ function diffTableColumns(source, target, opts) {
             .filter((diff) => diff !== undefined),
     ];
 }
+/**
+ * The columns renamed in the tables both sides name, by qualified table:
+ * a new column identical to exactly one the entity no longer names, and to no other. The dropped side is
+ * always the entity's own table, so a wrong guess renames, keeping the data, and never drops it.
+ */
+export function columnRenames(desired, actual, options = {}) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const normalizeName = nameNormalizer(opts);
+    return new Map(matchTables(desired, actual, opts).matched.flatMap(([expected, current]) => {
+        const { created, dropped } = matchByKey(expected.columns.values(), current.columns.values(), (column) => normalizeName(column.name));
+        const { matched } = pairUnique(created, dropped, (to, from) => !diffColumn(expected.name, to, from, opts));
+        const table = qualifyName(current.name, current.schema);
+        return matched.length ? [[table, matched.map(([to, from]) => ({ from: from.name, to: to.name }))]] : [];
+    }));
+}
+/**
+ * Tables the database holds that a new one is identical to but for its name, each only where it is the one
+ * match on both sides. Suggested, never applied: the database's side is a table no entity names, which may
+ * be another application's rather than one this schema renamed.
+ */
+export function tableRenameCandidates(desired, actual, options = {}) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const { created, dropped } = matchTables(desired, actual, opts);
+    const same = (to, from) => to.schema === from.schema && !diffTable(to, from, { ...opts, compareIndexes: false });
+    return pairUnique(created, dropped, same).matched.map(([to, from]) => ({ from: from.name, to: to.name }));
+}
+/** The two sides' tables paired by name, those `excludeTables` names left out of both. */
+function matchTables(desired, actual, opts) {
+    const normalizeName = nameNormalizer(opts);
+    const included = (tables) => [...tables].filter((table) => !opts.excludeTables.includes(table.name));
+    return matchByKey(included(desired.tables.values()), included(actual.tables.values()), (table) => normalizeName(table.name));
+}
 /** Compare indexes between two tables, paired by {@link pairIndexes}, in what the target's reader reports. */
 function diffTableIndexes(source, target, opts) {
     const { created, dropped, matched } = pairIndexes(source.indexes, target.indexes, nameNormalizer(opts));

package/dist/type/migration.d.ts

@@ -1,6 +1,7 @@
 import type { AnyMigrationOperation } from '../migrate/builder/types.js';
 import type { IndexFacet } from '../schema/indexDifferences.js';
 import type { SchemaAST } from '../schema/schemaAST.js';
+import type { DiffOptions } from '../schema/schemaASTDiffer.js';
 import type { ColumnNode, ForeignKeyAction, IndexType, TableNode } from '../schema/types.js';
 import type { EntityMeta, EntityWhereMeta, FieldOptions, IndexColumnSchema, IndexedVectorField, LoggingOptions, Querier, SqlQuerier, Type, VectorIndexOptions } from './index.js';
 /**
@@ -173,6 +174,17 @@ export interface ForeignKeySchema {
  * change is undone by swapping its ends. No engine alters an index, a key or a foreign key in place, so
  * an alter of one is its drop and its add, which safe mode holds back together.
  */
+/** A column's change, and whether it can lose what the column holds: a drop, or a retype that narrows it. */
+export type ColumnChange = Change<ColumnSchema> & {
+    readonly isBreaking?: boolean;
+};
+/** A name changed, `from` the database's `to` the entity's. */
+export type Rename = {
+    readonly from: string;
+    readonly to: string;
+};
+/** Renamed columns by qualified table name. */
+export type ColumnRenames = ReadonlyMap<string, readonly Rename[]>;
 export interface Change<T> {
     readonly from?: T;
     readonly to?: T;
@@ -199,9 +211,11 @@ export interface SchemaDiff {
     readonly schema?: string;
     readonly type: 'create' | 'alter' | 'drop';
     readonly primaryKey?: Change<PrimaryKeySchema>;
-    readonly columns?: readonly Change<ColumnSchema>[];
+    readonly columns?: readonly ColumnChange[];
     readonly indexes?: readonly Change<IndexSchema>[];
     readonly foreignKeys?: readonly Change<ForeignKeySchema>[];
+    /** Columns renamed in place, `from` the database's name `to` the entity's, which the other changes already use. */
+    readonly renamedColumns?: readonly Rename[];
 }
 /**
  * What every sync entry point takes: `safe` keeps it additive, `drop` lets it remove a column, and
@@ -288,10 +302,13 @@ export interface SchemaGenerator {
     /**
      * An entity's differences from its table. `desiredAst`, from {@link buildAST}, has to span every entity
      * a foreign key here points at, or those keys read as matching.
+     * `renamedColumns` are columns `currentTable` already holds under their new names.
      */
-    diffSchema(entity: Type<object>, currentTable: TableNode | undefined, desiredAst?: SchemaAST): SchemaDiff | undefined;
+    diffSchema(entity: Type<object>, currentTable: TableNode | undefined, desiredAst?: SchemaAST, renamedColumns?: readonly Rename[]): SchemaDiff | undefined;
     /** The entities as one AST, built once per run for every {@link diffSchema}. Absent on MongoDB, which diffs only indexes. */
     buildAST?(entities: readonly Type<object>[]): SchemaAST;
+    /** How this engine's diff compares types and defaults. Absent where {@link buildAST} is. */
+    diffOptions?(): DiffOptions;
     /**
      * The table's key: {@link resolveTableAlias} behind {@link resolveSchema}, which is how a
      * `SchemaAST` stores it and how a diff finds it again.
@@ -326,8 +343,11 @@ export interface SchemaIntrospector {
      * the database side never reports it, and no migration can close the gap.
      */
     readonly indexFacets: ReadonlySet<IndexFacet>;
-    /** The whole database, or just the tables named. Names nothing matches are left out. */
-    introspect(tables?: readonly string[]): Promise<SchemaAST>;
+    /**
+     * The whole database, or just the tables named. Names nothing matches are left out. `renames` reads
+     * each column under the name it is being renamed to, so a diff compares it as the column it becomes.
+     */
+    introspect(tables?: readonly string[], renames?: ColumnRenames): Promise<SchemaAST>;
     /**
      * Get all table names in the database
      */

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "JSON-native TypeScript ORM for Bun, Browsers, Edge, Deno, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.86.0",
+  "version": "0.87.0",
   "type": "module",
   "engines": {
     "node": ">=24"

package/skills/uql-orm/SKILL.md

@@ -154,7 +154,7 @@ transaction. A querier from `pool.getQuerier()` is yours to release: bind it wit
 ## Migrations
 
 `npx uql-migrate` reads `uql.config.ts`. `sync` creates what the entities imply (development only);
-`generate:entities` writes the diff as a migration file to review; `up` applies migrations; `generate:from-db`
+`generate:entities` writes the diff as a migration file to review, renaming a column its field was renamed from and printing `renameTable` for a table that may have been; `up` applies migrations; `generate:from-db`
 writes entity classes from an existing database; `drift:check` fails when the database no longer matches.
 Triggers are part of the diff: uql installs its own under `_uql_`-prefixed names and never touches another.