uql-orm 0.65.1 → 0.67.0

package/dist/migrate/migrator.d.ts

@@ -46,13 +46,7 @@ export declare class Migrator {
         to?: string;
         step?: number;
     }): Promise<MigrationResult[]>;
-    /**
-     * Narrow a run list by `to`/`step` and execute it, stopping at the first failure.
-     *
-     * Both directions do exactly this and differ only in the list they start from: `up` takes the
-     * pending migrations, `down` the executed ones reversed. Keeping the selection in one place is what
-     * makes `--to` and `--step` mean the same thing whichever way you are going.
-     */
+    /** Runs the list narrowed by `to`/`step`, stopping at the first failure: `up` over the pending, `down` over the executed reversed. */
     private runInOrder;
     /**
      * Run a single migration, within a transaction where the dialect has one for it
@@ -73,29 +67,13 @@ export declare class Migrator {
      */
     getDiffs(): Promise<SchemaDiff[]>;
     /**
-     * One AST spanning every schema the entities claim, each table stamped with the schema it was read
-     * from. Read per schema rather than all at once, so a table comes back keyed exactly as the entity
-     * that wants it spells the key: `undefined` on both sides for the connection's default, a name on
-     * both sides otherwise. Ordinarily that is one schema and one pass, as before, and that pass keeps
-     * {@link schemaIntrospector} so a caller that replaced it still wins.
-     */
-    private introspectClaimedSchemas;
-    /**
-     * Applies the entity schema to the database: every registered entity, or the one `entity` names.
-     *
-     * The whole surface is this and {@link planSync}, which answers the same question without running
-     * it - `force` and a single entity included, so `--dry-run` means the same thing whatever else was
-     * asked for.
+     * 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.
      */
+    private introspectEntities;
+    /** Applies the entity schema: every entity, or the one `entity` names. {@link planSync} answers the same without running it. */
     sync(options?: SyncOptions): Promise<void>;
-    /**
-     * Every table dropped and recreated.
-     *
-     * Both directions span the whole entity set rather than looping an entity at a time. A per-entity
-     * AST cannot resolve a cross-entity foreign key, so the old create loop silently produced a schema
-     * with no referential integrity; and the old drop loop went in reverse *declaration* order, which
-     * says nothing about the relation graph and is rejected as soon as the constraints are really there.
-     */
+    /** Every table dropped and recreated, the whole entity set at once, so foreign keys resolve and drop in graph order. */
     private forceStatements;
     /**
      * The DDL for one entity: {@link planSync} narrowed to the table it names. A new table costs one
@@ -114,14 +92,7 @@ export declare class Migrator {
      * statements rather than a summary of a second, differently-computed diff.
      */
     planSync(options?: SyncOptions): Promise<string[]>;
-    /**
-     * New tables are emitted together, never one at a time: a single-entity AST has no other table for a
-     * relation to resolve against, so every cross-entity foreign key was dropped and generated schemas
-     * carried none. Spanning the graph is also what lets a cyclic relation (any `createdBy`
-     * back-reference) be created at all.
-     *
-     * Empty in, empty out, so a diff with no new tables does not build an AST for the whole graph.
-     */
+    /** The new tables, created together so a foreign key between them, cyclic included, resolves. Empty in, empty out. */
     private createSchema;
     /**
      * The pending diffs a sync or a generated migration acts on: the tables to create and the tables to
@@ -184,22 +155,7 @@ export interface BuilderMigrationDefinition<Q extends Querier = SqlQuerier> {
     down(builder: IMigrationBuilder, querier: Q): Promise<void>;
 }
 /**
- * Define a migration using the type-safe builder API.
- *
- * @example
- * ```ts
- * export default defineBuilderMigration({
- *   async up(m) {
- *     await m.createTable('users', (t) => {
- *       t.id();
- *       t.string('email', { length: 255 }).unique();
- *       t.timestamps();
- *     });
- *   },
- *   async down(m) {
- *     await m.dropTable('users');
- *   }
- * });
- * ```
+ * Defines a migration with the builder:
+ * `defineBuilderMigration({ up: (m) => m.createTable('users', (t) => t.id()), down: (m) => m.dropTable('users') })`.
  */
 export declare function defineBuilderMigration<Q extends Querier = SqlQuerier>(migration: BuilderMigrationDefinition<Q>): MigrationDefinition<Q>;

package/dist/migrate/migrator.js

@@ -2,7 +2,7 @@ import { mkdir, readdir, writeFile } from 'node:fs/promises';
 import { basename, extname, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { getEntities, getMeta } from '../entity/index.js';
-import { introspectSchema, SchemaAST } from '../schema/index.js';
+import { SchemaAST } from '../schema/index.js';
 import { LoggerWrapper } from '../util/index.js';
 import { buildMigrationModule } from './codegen/migrationFile.js';
 import { introspectorFor } from './introspection/registry.js';
@@ -88,13 +88,7 @@ export class Migrator {
         const executedMigrations = migrations.filter((m) => executedSet.has(m.name)).reverse(); // Rollback in reverse order
         return this.runInOrder(executedMigrations, 'down', options);
     }
-    /**
-     * Narrow a run list by `to`/`step` and execute it, stopping at the first failure.
-     *
-     * Both directions do exactly this and differ only in the list they start from: `up` takes the
-     * pending migrations, `down` the executed ones reversed. Keeping the selection in one place is what
-     * makes `--to` and `--step` mean the same thing whichever way you are going.
-     */
+    /** Runs the list narrowed by `to`/`step`, stopping at the first failure: `up` over the pending, `down` over the executed reversed. */
     async runInOrder(migrations, direction, options) {
         let selected = migrations;
         if (options.to) {
@@ -211,7 +205,7 @@ export class Migrator {
      */
     async getDiffs() {
         const generator = await this.getSchemaGenerator();
-        const ast = await this.introspectClaimedSchemas();
+        const ast = await this.introspectEntities(this.entities);
         // Both sides built once: the database's above, the entities' here. 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.
@@ -223,29 +217,22 @@ export class Migrator {
         });
     }
     /**
-     * One AST spanning every schema the entities claim, each table stamped with the schema it was read
-     * from. Read per schema rather than all at once, so a table comes back keyed exactly as the entity
-     * that wants it spells the key: `undefined` on both sides for the connection's default, a name on
-     * both sides otherwise. Ordinarily that is one schema and one pass, as before, and that pass keeps
-     * {@link schemaIntrospector} so a caller that replaced it still wins.
+     * 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 introspectClaimedSchemas() {
-        const claimed = new Set(this.entities.map((entity) => this.pool.dialect.resolveSchema(getMeta(entity))));
+    async introspectEntities(entities) {
+        const { dialect } = this.pool;
+        const bySchema = Map.groupBy(new Set(entities), (entity) => dialect.resolveSchema(getMeta(entity)));
         const merged = new SchemaAST();
-        for (const schema of claimed) {
-            for (const table of (await introspectSchema(this.schemaIntrospectorFor(schema))).getTables()) {
+        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()) {
                 merged.addTable(table);
             }
         }
         return merged;
     }
-    /**
-     * Applies the entity schema to the database: every registered entity, or the one `entity` names.
-     *
-     * The whole surface is this and {@link planSync}, which answers the same question without running
-     * it - `force` and a single entity included, so `--dry-run` means the same thing whatever else was
-     * asked for.
-     */
+    /** Applies the entity schema: every entity, or the one `entity` names. {@link planSync} answers the same without running it. */
     async sync(options = {}) {
         const statements = await this.planSync(options);
         if (statements.length) {
@@ -255,14 +242,7 @@ export class Migrator {
             this.logger.logSchema('Schema is already in sync.');
         }
     }
-    /**
-     * Every table dropped and recreated.
-     *
-     * Both directions span the whole entity set rather than looping an entity at a time. A per-entity
-     * AST cannot resolve a cross-entity foreign key, so the old create loop silently produced a schema
-     * with no referential integrity; and the old drop loop went in reverse *declaration* order, which
-     * says nothing about the relation graph and is rejected as soon as the constraints are really there.
-     */
+    /** Every table dropped and recreated, the whole entity set at once, so foreign keys resolve and drop in graph order. */
     forceStatements(generator) {
         return [
             ...generator.generateDropSchema(this.entities, { ifExists: true, cascade: true }),
@@ -276,14 +256,17 @@ export class Migrator {
      */
     async planEntity(generator, entity, options) {
         const meta = getMeta(entity);
-        const introspector = this.schemaIntrospectorFor(this.pool.dialect.resolveSchema(meta));
+        const { dialect } = this.pool;
+        const introspector = this.schemaIntrospectorFor(dialect.resolveSchema(meta));
         const tableName = generator.resolveTableName(meta);
-        return (await introspector.tableExists(tableName))
-            ? this.alterFromEntity(generator, entity, (await introspectSchema(introspector)).getTable(tableName), options)
-            : // Spanning the whole set, so a foreign key resolves against the tables it points at, and
-                // always including this entity: pinned to an explicit `entities` list, a sync of one outside
-                // it emitted nothing at all. `only` is what keeps the statements to this table.
-                generator.generateCreateSchema(this.entitiesWith(entity), { only: [tableName], ifNotExists: true });
+        if (!(await introspector.tableExists(dialect.resolveTableAlias(meta)))) {
+            // Spanning the whole set, so a foreign key resolves against the tables it points at, and always
+            // including this entity: `only` is what keeps the statements to this table.
+            return generator.generateCreateSchema(this.entitiesWith(entity), { only: [tableName], ifNotExists: true });
+        }
+        // With the tables it references, which its foreign keys resolve against.
+        const ast = await this.introspectEntities([entity, ...referencedEntities(meta)]);
+        return this.alterFromEntity(generator, entity, ast.getTable(tableName), options);
     }
     /** The same for one entity against the table it already has, and nothing where the two agree. */
     alterFromEntity(generator, entity, table, options) {
@@ -319,14 +302,7 @@ export class Migrator {
             ...altered.flatMap((diff) => generator.generateAlterTable(this.filterDiff(diff, options))),
         ];
     }
-    /**
-     * New tables are emitted together, never one at a time: a single-entity AST has no other table for a
-     * relation to resolve against, so every cross-entity foreign key was dropped and generated schemas
-     * carried none. Spanning the graph is also what lets a cyclic relation (any `createdBy`
-     * back-reference) be created at all.
-     *
-     * Empty in, empty out, so a diff with no new tables does not build an AST for the whole graph.
-     */
+    /** The new tables, created together so a foreign key between them, cyclic included, resolves. Empty in, empty out. */
     createSchema(generator, tableNames) {
         return tableNames.length ? generator.generateCreateSchema(this.entities, { only: tableNames }) : [];
     }
@@ -484,23 +460,8 @@ export function defineMigration(migration) {
     return migration;
 }
 /**
- * Define a migration using the type-safe builder API.
- *
- * @example
- * ```ts
- * export default defineBuilderMigration({
- *   async up(m) {
- *     await m.createTable('users', (t) => {
- *       t.id();
- *       t.string('email', { length: 255 }).unique();
- *       t.timestamps();
- *     });
- *   },
- *   async down(m) {
- *     await m.dropTable('users');
- *   }
- * });
- * ```
+ * Defines a migration with the builder:
+ * `defineBuilderMigration({ up: (m) => m.createTable('users', (t) => t.id()), down: (m) => m.dropTable('users') })`.
  */
 export function defineBuilderMigration(migration) {
     return {
@@ -509,3 +470,9 @@ export function defineBuilderMigration(migration) {
         down: async (querier) => migration.down(await migrationBuilderFor(querier), querier),
     };
 }
+/** The entities `meta` points at, through a relation or a foreign key field. */
+function referencedEntities(meta) {
+    const fields = Object.values(meta.fields).flatMap((field) => field?.references?.() ?? []);
+    const relations = Object.values(meta.relations).flatMap((relation) => relation?.entity?.() ?? []);
+    return [...fields, ...relations];
+}

package/dist/migrate/schemaGenerator.d.ts

@@ -28,35 +28,18 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
     /** Escape an identifier (table name, column name, etc.) */
     protected escapeId(identifier: string): string;
     /**
-     * How an auto-increment key of `type` is spelled: the type as any other column renders it, plus what
-     * the engine appends to make it generated.
-     *
-     * Derived rather than a fixed string per dialect, because a foreign key column takes its type from
-     * the key it points at, resolved through the same canonical type. A key whose spelling ignored that
-     * type could never be referenced: `@Id({ columnType: 'int' })` emitted `BIGINT` while the column
-     * pointing at it emitted `INT`, and every engine refuses that constraint.
+     * An auto-increment key's type: its canonical type rendered like any column's, plus the engine's generated
+     * suffix, so a foreign key taking its type from this key gets the same one.
      */
     protected serialType(type: CanonicalType): string;
-    /**
-     * The SQL type a column is spelled with: the engine's generated-key form for an auto-increment key,
-     * the canonical type otherwise.
-     *
-     * One method because both paths that spell a column need the same answer - written twice, with a
-     * comment asking the two to stay in sync, is how the generated key and the column referencing it
-     * came to disagree in the first place.
-     */
+    /** The SQL type a column is spelled with: the generated-key form for an auto-increment key, the canonical type otherwise. */
     protected columnSqlType(col: ColumnNode): string;
     protected canonicalTypeToSql(type: CanonicalType): string;
     /** The entity side as an AST, carrying this generator's default referential action. */
     buildAST(entities: readonly Type<object>[]): SchemaAST;
     /**
-     * Every `CREATE TABLE` for `entities`, then their foreign keys.
-     *
-     * Two phases rather than inline constraints, because a relation graph is routinely cyclic: any
-     * `createdBy`-style back-reference makes `A` reference `B` while `B` references `A`, and no create
-     * order satisfies that. TypeORM's schema builder splits for the same reason (`createNewTables()`
-     * then `createForeignKeys()`). SQLite is the exception and keeps them inline: it cannot `ALTER` a
-     * foreign key in, but it resolves targets lazily, so a forward reference is fine there.
+     * Every `CREATE TABLE` for `entities`, then their foreign keys, since a relation graph is routinely
+     * cyclic. SQLite keeps them inline: it cannot add one later, and resolves a forward reference lazily.
      */
     generateCreateSchema(entities: readonly Type<object>[], options?: CreateSchemaOptions): string[];
     /**
@@ -88,13 +71,8 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
      */
     generateDropIndex(tableName: string, indexName: string, schema?: string): string;
     /**
-     * A column definition from a {@link ColumnSchema}, whose type is already the engine's own spelling
-     * and may carry its own size.
-     *
-     * Kept apart from {@link generateColumnFromNode} rather than folded into it: a `ColumnSchema` has no
-     * `enum`, because introspection reads one back as a `CHECK` constraint and not as a property of the
-     * column, so only the node knows enough to emit that clause. Both spell the definition through
-     * {@link renderColumn}, which is the part that must not be written twice.
+     * A column definition from a {@link ColumnSchema}, whose type is already the engine's spelling. Apart from
+     * {@link generateColumnFromNode}, which alone knows an `enum`; both render through {@link renderColumn}.
      */
     generateColumnDefinitionFromSchema(column: ColumnSchema): string;
     /**
@@ -104,35 +82,25 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
      * enum's `CHECK` comes last, the only place MariaDB takes it.
      */
     private renderColumn;
+    /**
+     * The column type a field gets, resolved as its table resolves it. A field alone cannot tell that it is
+     * 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, on an engine that carries a comment
-     * that way. Empty on the others: MySQL writes them inline, SQLite has no comments at all.
-     *
-     * Emitted after the `CREATE TABLE` rather than folded into it, which is what `COMMENT ON` requires -
-     * and what makes a comment reach Postgres, where it was previously read as unsupported and dropped.
-     */
+    /** The `COMMENT ON` statements a table and its columns need, after the `CREATE TABLE`, where the engine uses them. */
     protected generateCommentStatements(table: TableNode): string[];
-    /**
-     * The `COMMENT ON COLUMN` one column needs, on an engine that carries a comment that way.
-     *
-     * Shared by `CREATE TABLE` and every path that adds a column: written only for the former, a column
-     * added later reached the database undocumented, the way its enum `CHECK` used to.
-     */
+    /** The `COMMENT ON COLUMN` a column needs where the engine uses one, for `CREATE TABLE` and every path adding a column. */
     protected generateColumnCommentStatement(tableName: string, column: {
         name: string;
         comment?: string;
     }, schema?: string): string[];
     /**
-     * How this entity differs from the table the database reported, as the migrator's `SchemaDiff`.
-     *
-     * The comparison itself is {@link diffTable}, the same one drift detection runs, so the two can no
-     * longer disagree about what has changed. Only two things are this side's own: the entity becomes a
-     * table node first, and types are compared as the *engine* would store them - see `normalizeType`.
+     * 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;
     /**
@@ -171,13 +139,7 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
     generateRenameTableSql(oldName: string, newName: string): string;
     /** `raw` is split, being the one SQL no generator wrote. */
     generateOperation(operation: AnyMigrationOperation): string[];
-    /**
-     * `ADD COLUMN`, plus the constraint and index the column declares.
-     *
-     * `CREATE TABLE` lifts a column's `references` and `index` onto the table it is building; this had
-     * no lift, so a hand-written `addColumn(...).references(...).index()` emitted the column alone and
-     * dropped both without a word.
-     */
+    /** `ADD COLUMN`, plus the foreign key and index the column declares, as `CREATE TABLE` lifts them. */
     generateAddColumnSql(tableName: string, column: FullColumnDefinition): string[];
     generateAlterColumnSql(tableName: string, columnName: string, column: FullColumnDefinition): string[];
     generateDropColumnSql(tableName: string, columnName: string): string[];
@@ -198,12 +160,8 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
      */
     generateAddPrimaryKeySql(tableName: string, columns: readonly string[], name?: string): string;
     /**
-     * Drops whatever key the table has.
-     *
-     * `constraintName` has to be what the constraint is *actually* called: the name introspection
-     * reported for a key the database already had, or the derived one for a key this generator itself
-     * added, which is what reversing a migration drops. Guessing either way names nothing. MySQL takes
-     * no name at all - a table's key is always `PRIMARY` there.
+     * Drops the table's key, by the name the constraint really has: introspected, or derived where this
+     * generator added it. MySQL takes no name.
      */
     generateDropPrimaryKeySql(tableName: string, constraintName?: string): string;
     /**
@@ -214,11 +172,7 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
     private assertPrimaryKeyAlterable;
 }
 /**
- * The entities as an AST, named the way `generator` names things.
- *
- * Its resolvers rather than a naming strategy, because the two disagree: a strategy renames whatever
- * it is handed, while a generator leaves an explicit `@Entity({ name })` alone. Build the AST the
- * other way and the table is created under one name and compared under another, which reports every
- * table of a project using a naming strategy as both missing and unexpected.
+ * The entities as an AST, named by `generator`'s resolvers rather than a naming strategy, which would
+ * also rename an explicit `@Entity({ name })` and so compare each table under another name.
  */
 export declare function buildEntityAST(generator: Pick<SchemaGenerator, 'resolveTableAlias' | 'resolveSchema' | 'resolveColumnName' | 'compileDdl' | 'compileIndexPredicate'>, entities: readonly Type<object>[], defaultForeignKeyAction?: ForeignKeyAction): SchemaAST;

package/dist/migrate/schemaGenerator.js

@@ -1,7 +1,7 @@
-import { getMeta, soleIdOf } from '../entity/index.js';
-import { canonicalToSql, engineType, fieldOptionsToCanonical, isVectorCategory } from '../schema/canonicalType.js';
+import { getMeta } from '../entity/index.js';
+import { canonicalToSql, engineType, isVectorCategory } from '../schema/canonicalType.js';
 import { indexSignature } from '../schema/indexDifferences.js';
-import { buildSchemaAST } from '../schema/schemaASTBuilder.js';
+import { buildSchemaAST, resolveColumnCanonicalType } from '../schema/schemaASTBuilder.js';
 import { diffRelationshipNodes, diffTable } from '../schema/schemaASTDiffer.js';
 import { isAutoIncrement, qualifyName } from '../util/index.js';
 import { derivedCheckName, derivedForeignKeyName, derivedPrimaryKeyName } from '../util/sql.util.js';
@@ -59,25 +59,13 @@ export class SqlSchemaGenerator {
         return this.dialect.escapeId(identifier);
     }
     /**
-     * How an auto-increment key of `type` is spelled: the type as any other column renders it, plus what
-     * the engine appends to make it generated.
-     *
-     * Derived rather than a fixed string per dialect, because a foreign key column takes its type from
-     * the key it points at, resolved through the same canonical type. A key whose spelling ignored that
-     * type could never be referenced: `@Id({ columnType: 'int' })` emitted `BIGINT` while the column
-     * pointing at it emitted `INT`, and every engine refuses that constraint.
+     * An auto-increment key's type: its canonical type rendered like any column's, plus the engine's generated
+     * suffix, so a foreign key taking its type from this key gets the same one.
      */
     serialType(type) {
         return `${this.canonicalTypeToSql(type)} ${this.dialect.autoIncrementSuffix}`;
     }
-    /**
-     * The SQL type a column is spelled with: the engine's generated-key form for an auto-increment key,
-     * the canonical type otherwise.
-     *
-     * One method because both paths that spell a column need the same answer - written twice, with a
-     * comment asking the two to stay in sync, is how the generated key and the column referencing it
-     * came to disagree in the first place.
-     */
+    /** The SQL type a column is spelled with: the generated-key form for an auto-increment key, the canonical type otherwise. */
     columnSqlType(col) {
         return col.isPrimaryKey && col.isAutoIncrement ? this.serialType(col.type) : this.canonicalTypeToSql(col.type);
     }
@@ -89,13 +77,8 @@ export class SqlSchemaGenerator {
         return buildEntityAST(this, entities, this.defaultForeignKeyAction);
     }
     /**
-     * Every `CREATE TABLE` for `entities`, then their foreign keys.
-     *
-     * Two phases rather than inline constraints, because a relation graph is routinely cyclic: any
-     * `createdBy`-style back-reference makes `A` reference `B` while `B` references `A`, and no create
-     * order satisfies that. TypeORM's schema builder splits for the same reason (`createNewTables()`
-     * then `createForeignKeys()`). SQLite is the exception and keeps them inline: it cannot `ALTER` a
-     * foreign key in, but it resolves targets lazily, so a forward reference is fine there.
+     * Every `CREATE TABLE` for `entities`, then their foreign keys, since a relation graph is routinely
+     * cyclic. SQLite keeps them inline: it cannot add one later, and resolves a forward reference lazily.
      */
     generateCreateSchema(entities, options = {}) {
         const tables = this.orderedTables(entities, 'create', options.only);
@@ -271,13 +254,8 @@ export class SqlSchemaGenerator {
         return `DROP INDEX IF EXISTS ${this.dialect.escapeQualifiedId(indexName, schema)};`;
     }
     /**
-     * A column definition from a {@link ColumnSchema}, whose type is already the engine's own spelling
-     * and may carry its own size.
-     *
-     * Kept apart from {@link generateColumnFromNode} rather than folded into it: a `ColumnSchema` has no
-     * `enum`, because introspection reads one back as a `CHECK` constraint and not as a property of the
-     * column, so only the node knows enough to emit that clause. Both spell the definition through
-     * {@link renderColumn}, which is the part that must not be written twice.
+     * A column definition from a {@link ColumnSchema}, whose type is already the engine's spelling. Apart from
+     * {@link generateColumnFromNode}, which alone knows an `enum`; both render through {@link renderColumn}.
      */
     generateColumnDefinitionFromSchema(column) {
         return this.renderColumn({ ...column, type: sizedType(column) });
@@ -309,23 +287,15 @@ export class SqlSchemaGenerator {
         }
         return def;
     }
+    /**
+     * The column type a field gets, resolved as its table resolves it. A field alone cannot tell that it is
+     * one column of a composite key, which its table never makes serial.
+     */
     getSqlType(field) {
-        // A foreign key takes the type of the key it points at. A `referencedKey` the target does not
-        // have falls through to this column's own options, as the AST builder does with the same case.
-        if (field.references) {
-            const refMeta = getMeta(field.references());
-            const refIdField = refMeta.fields[field.referencedKey ?? soleIdOf(refMeta, 'a foreign key')];
-            if (refIdField) {
-                return this.getSqlType({ ...refIdField, references: undefined, isId: undefined, autoIncrement: false });
-            }
-        }
-        // Get canonical type and convert to SQL
-        const canonical = fieldOptionsToCanonical(field);
-        // Special case for serial primary keys
-        if (isAutoIncrement(field, field.isId === true)) {
-            return this.serialType(canonical);
-        }
-        return this.canonicalTypeToSql(canonical);
+        const canonical = resolveColumnCanonicalType(field);
+        return isAutoIncrement(field, field.isId === true)
+            ? this.serialType(canonical)
+            : this.canonicalTypeToSql(canonical);
     }
     /** The statements that alter `column` in place, as this dialect spells them. */
     generateAlterColumnStatements(tableName, column, newDefinition) {
@@ -335,13 +305,7 @@ export class SqlSchemaGenerator {
     generateColumnComment(comment) {
         return this.features.commentSyntax === 'inline' ? ` COMMENT ${this.dialect.escape(comment)}` : '';
     }
-    /**
-     * The `COMMENT ON` statements a table and its columns need, on an engine that carries a comment
-     * that way. Empty on the others: MySQL writes them inline, SQLite has no comments at all.
-     *
-     * Emitted after the `CREATE TABLE` rather than folded into it, which is what `COMMENT ON` requires -
-     * and what makes a comment reach Postgres, where it was previously read as unsupported and dropped.
-     */
+    /** The `COMMENT ON` statements a table and its columns need, after the `CREATE TABLE`, where the engine uses them. */
     generateCommentStatements(table) {
         if (this.features.commentSyntax !== 'statement') {
             return [];
@@ -353,12 +317,7 @@ export class SqlSchemaGenerator {
         }
         return statements;
     }
-    /**
-     * The `COMMENT ON COLUMN` one column needs, on an engine that carries a comment that way.
-     *
-     * Shared by `CREATE TABLE` and every path that adds a column: written only for the former, a column
-     * added later reached the database undocumented, the way its enum `CHECK` used to.
-     */
+    /** The `COMMENT ON COLUMN` a column needs where the engine uses one, for `CREATE TABLE` and every path adding a column. */
     generateColumnCommentStatement(tableName, column, schema) {
         if (!column.comment || this.features.commentSyntax !== 'statement') {
             return [];
@@ -367,11 +326,8 @@ export class SqlSchemaGenerator {
         return [`COMMENT ON COLUMN ${tableRef}.${this.escapeId(column.name)} IS ${this.dialect.escape(column.comment)};`];
     }
     /**
-     * How this entity differs from the table the database reported, as the migrator's `SchemaDiff`.
-     *
-     * The comparison itself is {@link diffTable}, the same one drift detection runs, so the two can no
-     * longer disagree about what has changed. Only two things are this side's own: the entity becomes a
-     * table node first, and types are compared as the *engine* would store them - see `normalizeType`.
+     * 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) {
         const meta = getMeta(entity);
@@ -412,13 +368,8 @@ export class SqlSchemaGenerator {
             to: tableDiff.primaryKeyDiff.expected,
             fromName: tableDiff.primaryKeyDiff.actualName,
         };
-        // This table's own constraints, which is what `outgoingRelations` holds on both sides: the
-        // entity's as the AST derived them, the database's as the introspector read them back.
-        //
-        // None at all where the engine cannot alter one: SQLite resolves foreign keys lazily and keeps
-        // them inline at CREATE time, and its only way to change one afterwards is the twelve-step table
-        // rebuild, which a sync does not do. Reporting a difference nothing can apply would throw on
-        // every sync of an entity that has a relation. `drift:check` still names it.
+        // 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())
             : [];
@@ -512,7 +463,9 @@ export class SqlSchemaGenerator {
         // later `DROP` has something to name. The exception is a dialect whose serial type states the key
         // itself (SQLite's `INTEGER PRIMARY KEY AUTOINCREMENT`, which cannot be split): there the column
         // has already declared it, and saying it again is a second primary key.
-        const declaredByColumn = this.dialect.serialDeclaresPrimaryKey && table.primaryKey.length === 1 && table.primaryKey[0].isAutoIncrement;
+        const declaredByColumn = this.dialect.features.serialDeclaresPrimaryKey &&
+            table.primaryKey.length === 1 &&
+            table.primaryKey[0].isAutoIncrement;
         if (table.primaryKey.length && !declaredByColumn) {
             const pkColumns = table.primaryKey.map((c) => c.name);
             const pkName = table.primaryKeyName ?? derivedPrimaryKeyName(table.name, pkColumns);
@@ -614,13 +567,7 @@ export class SqlSchemaGenerator {
                 return splitSqlStatements(operation.sql);
         }
     }
-    /**
-     * `ADD COLUMN`, plus the constraint and index the column declares.
-     *
-     * `CREATE TABLE` lifts a column's `references` and `index` onto the table it is building; this had
-     * no lift, so a hand-written `addColumn(...).references(...).index()` emitted the column alone and
-     * dropped both without a word.
-     */
+    /** `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));
@@ -682,12 +629,8 @@ export class SqlSchemaGenerator {
         return `ALTER TABLE ${this.escapeId(tableName)} ADD CONSTRAINT ${constraintName} PRIMARY KEY (${pkCols});`;
     }
     /**
-     * Drops whatever key the table has.
-     *
-     * `constraintName` has to be what the constraint is *actually* called: the name introspection
-     * reported for a key the database already had, or the derived one for a key this generator itself
-     * added, which is what reversing a migration drops. Guessing either way names nothing. MySQL takes
-     * no name at all - a table's key is always `PRIMARY` there.
+     * Drops the table's key, by the name the constraint really has: introspected, or derived where this
+     * generator added it. MySQL takes no name.
      */
     generateDropPrimaryKeySql(tableName, constraintName) {
         this.assertPrimaryKeyAlterable(tableName);
@@ -747,12 +690,8 @@ function foreignKeyOf(relation) {
     };
 }
 /**
- * The entities as an AST, named the way `generator` names things.
- *
- * Its resolvers rather than a naming strategy, because the two disagree: a strategy renames whatever
- * it is handed, while a generator leaves an explicit `@Entity({ name })` alone. Build the AST the
- * other way and the table is created under one name and compared under another, which reports every
- * table of a project using a naming strategy as both missing and unexpected.
+ * The entities as an AST, named by `generator`'s resolvers rather than a naming strategy, which would
+ * also rename an explicit `@Entity({ name })` and so compare each table under another name.
  */
 export function buildEntityAST(generator, entities, defaultForeignKeyAction) {
     return buildSchemaAST(entities, {