uql-orm 0.25.1 → 0.26.1

package/dist/migrate/introspection/baseSqlIntrospector.js

@@ -6,6 +6,8 @@ import { escapeSqlId } from '../../util/index.js';
  */
 export class BaseSqlIntrospector {
     dialect;
+    /** Columns and uniqueness only; each introspector opts in to what its catalogue queries report. */
+    indexFacets = new Set();
     constructor(dialect) {
         this.dialect = dialect;
     }
@@ -82,8 +84,8 @@ export class BaseSqlIntrospector {
                 const toTable = tableNodes.get(fk.referencedTable);
                 if (!toTable)
                     continue;
-                const fromColumns = fk.columns.map((c) => fromTable.columns.get(c)).filter((c) => !!c);
-                const toColumns = fk.referencedColumns.map((c) => toTable.columns.get(c)).filter((c) => !!c);
+                const fromColumns = fk.columns.flatMap((name) => fromTable.columns.get(name) ?? []);
+                const toColumns = fk.referencedColumns.flatMap((name) => toTable.columns.get(name) ?? []);
                 if (fromColumns.length > 0 && toColumns.length > 0) {
                     const rel = {
                         name: fk.name,
@@ -106,13 +108,19 @@ export class BaseSqlIntrospector {
             if (!table)
                 continue;
             for (const idx of schema.indexes) {
-                const columns = idx.columns.map((e) => table.columns.get(e.column)).filter((c) => !!c);
-                if (columns.length > 0) {
+                // An expression has no column to resolve. Dropping the entries that name a column this table
+                // does not have, and the index if that leaves none, is what the entity side does too.
+                const entries = idx.entries.filter((entry) => entry.expression || table.columns.has(entry.column));
+                if (entries.length > 0) {
                     const index = {
                         name: idx.name,
                         table,
-                        columns,
+                        entries,
                         unique: idx.unique,
+                        type: idx.type,
+                        where: idx.where,
+                        include: idx.include,
+                        source: 'database',
                     };
                     ast.addIndex(index);
                 }

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

@@ -1,3 +1,4 @@
+import type { IndexFacet } from '../../schema/indexDifferences.js';
 import { SchemaAST } from '../../schema/schemaAST.js';
 import type { QuerierPool, SchemaIntrospector, TableSchema } from '../../type/index.js';
 /**
@@ -6,6 +7,8 @@ import type { QuerierPool, SchemaIntrospector, TableSchema } from '../../type/in
  */
 export declare class MongoSchemaIntrospector implements SchemaIntrospector {
     private readonly pool;
+    /** `listIndexes` reports keys and uniqueness; a `partialFilterExpression` is no SQL predicate. */
+    readonly indexFacets: ReadonlySet<IndexFacet>;
     constructor(pool: QuerierPool);
     introspect(): Promise<SchemaAST>;
     getTableSchema(tableName: string): Promise<TableSchema | undefined>;

package/dist/migrate/introspection/mongoIntrospector.js

@@ -5,6 +5,8 @@ import { SchemaAST } from '../../schema/schemaAST.js';
  */
 export class MongoSchemaIntrospector {
     pool;
+    /** `listIndexes` reports keys and uniqueness; a `partialFilterExpression` is no SQL predicate. */
+    indexFacets = new Set();
     constructor(pool) {
         this.pool = pool;
     }
@@ -26,8 +28,7 @@ export class MongoSchemaIntrospector {
                 };
                 if (schema.indexes) {
                     for (const idx of schema.indexes) {
-                        const indexColumns = [];
-                        for (const { column: colName } of idx.columns) {
+                        for (const { column: colName } of idx.entries) {
                             let column = columns.get(colName);
                             if (!column) {
                                 column = {
@@ -42,14 +43,8 @@ export class MongoSchemaIntrospector {
                                 };
                                 columns.set(colName, column);
                             }
-                            indexColumns.push(column);
                         }
-                        table.indexes.push({
-                            name: idx.name,
-                            table,
-                            columns: indexColumns,
-                            unique: idx.unique,
-                        });
+                        table.indexes.push({ name: idx.name, table, entries: idx.entries, unique: idx.unique });
                     }
                 }
                 ast.addTable(table);
@@ -73,7 +68,7 @@ export class MongoSchemaIntrospector {
                 columns: [], // We don't have columns in Mongo
                 indexes: indexes.map((idx) => ({
                     name: idx.name ?? Object.keys(idx.key).join('_'),
-                    columns: Object.keys(idx.key).map((column) => ({ column })),
+                    entries: Object.keys(idx.key).map((column) => ({ column })),
                     unique: !!idx.unique,
                 })),
             };

package/dist/migrate/introspection/mysqlIntrospector.js

@@ -110,7 +110,7 @@ export class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
     async mapIndexesResult(_read, _tableName, results) {
         return results.map((row) => ({
             name: row.index_name,
-            columns: (row.columns || '').split(',').map((column) => ({ column })),
+            entries: (row.columns || '').split(',').map((column) => ({ column })),
             unique: Boolean(row.is_unique),
         }));
     }

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

@@ -1,22 +1,44 @@
+import type { IndexFacet } from '../../schema/indexDifferences.js';
 import type { ColumnSchema, ForeignKeySchema, IndexSchema, RawRow } from '../../type/index.js';
 import { AbstractSqlSchemaIntrospector, type TableRowReader } from './abstractSqlSchemaIntrospector.js';
 /**
  * PostgreSQL schema introspector
  */
 export declare class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
+    /**
+     * Expressions and predicates are read back too, for `generate:from-db`, but they are text the
+     * database reprints in its own words, so they are not comparable and are not claimed here.
+     */
+    readonly indexFacets: ReadonlySet<IndexFacet>;
     protected getTableNamesQuery(): string;
     protected tableExistsQuery(): string;
     protected parseTableExistsResult(results: RawRow[]): boolean;
     protected getColumnsQuery(_tableName: string): string;
+    /**
+     * `attname` where the entry is a column, `pg_get_indexdef` for that one position where it is an
+     * expression. Neither alone will do: an expression entry has `attnum = 0`, so joining `pg_attribute`
+     * on it silently dropped the entry (a `lower(email)` index read back as having no columns at all),
+     * while `pg_get_indexdef` reprints an identifier *quoted*, so a camelCase column came back as
+     * `"tenantId"` and matched no column of the table. Prisma and drizzle-kit both split it this way.
+     *
+     * Indexes backing a constraint are left out, primary keys among them: `@Field({ unique })` emits a
+     * `UNIQUE` constraint and no index, so reporting the index Postgres builds underneath it told every
+     * project it had an index its entities never asked for.
+     */
     protected getIndexesQuery(_tableName: string): string;
+    /**
+     * Constraint kinds whose backing index is the constraint itself rather than an index anyone asked
+     * for. Postgres builds one for `PRIMARY KEY`, `UNIQUE` and `EXCLUDE`, and only for those: a plain
+     * `CREATE UNIQUE INDEX` has no `pg_constraint` row at all, so it survives.
+     *
+     * Nothing to do with {@link indexFacets}, which says which *attributes* of an index diffing may
+     * compare. This one decides which indexes are reported at all.
+     */
+    protected readonly constraintIndexTypes: readonly string[];
     protected getForeignKeysQuery(_tableName: string): string;
     protected getPrimaryKeyQuery(_tableName: string): string;
     protected mapColumnsResult(_read: TableRowReader, _tableName: string, results: PostgresColumnRow[]): Promise<ColumnSchema[]>;
-    protected mapIndexesResult(_read: TableRowReader, _tableName: string, results: {
-        index_name: string;
-        columns: string[];
-        is_unique: boolean;
-    }[]): Promise<IndexSchema[]>;
+    protected mapIndexesResult(_read: TableRowReader, _tableName: string, results: PostgresIndexRow[]): Promise<IndexSchema[]>;
     protected mapForeignKeysResult(_read: TableRowReader, _tableName: string, results: {
         constraint_name: string;
         columns: string[];
@@ -29,6 +51,36 @@ export declare class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrosp
     protected parseDefaultValue(defaultValue: string | null): unknown;
     protected isAutoIncrement(columnDefault: string | null, isIdentity: string): boolean;
 }
+/**
+ * CockroachDB answers the same catalogue queries and differs only in what it can express: v26.2.5
+ * still rejects `NULLS FIRST/LAST` and operator classes as "unimplemented", and it sorts nulls first
+ * on an ASC column where Postgres sorts them last. Reading a nulls order back would therefore report
+ * every ascending index as drifted, against an entity that could not have asked for one. Its access
+ * method, `prefix`, needs nothing: a method that is not a known index type is reported as no type.
+ */
+export declare class CockroachSchemaIntrospector extends PostgresSchemaIntrospector {
+    readonly indexFacets: ReadonlySet<IndexFacet>;
+    /**
+     * `'u'` is missing on purpose. CockroachDB registers a `UNIQUE` constraint for a plain `CREATE
+     * UNIQUE INDEX` too, naming it after the index, so filtering on it would hide every unique index a
+     * user asked for and report it missing forever. It leaves no way to tell the two apart, so the
+     * index a `@Field({ unique })` builds underneath itself stays visible there.
+     */
+    protected readonly constraintIndexTypes: readonly string[];
+}
+/** One entry of one index; what the index itself is repeats across its rows. */
+type PostgresIndexRow = {
+    index_name: string;
+    is_unique: boolean;
+    method: string;
+    predicate: string | null;
+    is_key: boolean;
+    is_expression: boolean;
+    entry: string;
+    descending: boolean;
+    nulls_first: boolean;
+    ops_class: string | null;
+};
 type PostgresColumnRow = {
     column_name: string;
     data_type: string;

package/dist/migrate/introspection/postgresIntrospector.js

@@ -1,8 +1,20 @@
+import { INDEX_TYPES } from '../../schema/types.js';
 import { AbstractSqlSchemaIntrospector } from './abstractSqlSchemaIntrospector.js';
 /**
  * PostgreSQL schema introspector
  */
 export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
+    /**
+     * Expressions and predicates are read back too, for `generate:from-db`, but they are text the
+     * database reprints in its own words, so they are not comparable and are not claimed here.
+     */
+    indexFacets = new Set([
+        'order',
+        'nulls',
+        'opsClass',
+        'accessMethod',
+        'include',
+    ]);
     getTableNamesQuery() {
         return /*sql*/ `
       SELECT table_name
@@ -67,25 +79,58 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
       ORDER BY c.ordinal_position
     `;
     }
+    /**
+     * `attname` where the entry is a column, `pg_get_indexdef` for that one position where it is an
+     * expression. Neither alone will do: an expression entry has `attnum = 0`, so joining `pg_attribute`
+     * on it silently dropped the entry (a `lower(email)` index read back as having no columns at all),
+     * while `pg_get_indexdef` reprints an identifier *quoted*, so a camelCase column came back as
+     * `"tenantId"` and matched no column of the table. Prisma and drizzle-kit both split it this way.
+     *
+     * Indexes backing a constraint are left out, primary keys among them: `@Field({ unique })` emits a
+     * `UNIQUE` constraint and no index, so reporting the index Postgres builds underneath it told every
+     * project it had an index its entities never asked for.
+     */
     getIndexesQuery(_tableName) {
         return /*sql*/ `
       SELECT
         i.relname AS index_name,
-        array_to_json(array_agg(a.attname ORDER BY k.n)) AS columns,
-        ix.indisunique AS is_unique
+        ix.indisunique AS is_unique,
+        am.amname AS method,
+        pg_get_expr(ix.indpred, ix.indrelid, true) AS predicate,
+        k.n <= ix.indnkeyatts AS is_key,
+        k.attnum = 0 AS is_expression,
+        COALESCE(a.attname::text, pg_get_indexdef(ix.indexrelid, k.n::int, true)) AS entry,
+        (ix.indoption[k.n - 1] & 1) <> 0 AS descending,
+        (ix.indoption[k.n - 1] & 2) <> 0 AS nulls_first,
+        CASE WHEN op.opcdefault THEN NULL ELSE op.opcname END AS ops_class
       FROM pg_class t
       JOIN pg_index ix ON t.oid = ix.indrelid
       JOIN pg_class i ON i.oid = ix.indexrelid
+      JOIN pg_am am ON am.oid = i.relam
       JOIN pg_namespace n ON n.oid = t.relnamespace
       CROSS JOIN LATERAL unnest(ix.indkey) WITH ORDINALITY AS k(attnum, n)
-      JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = k.attnum
+      LEFT JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = k.attnum AND k.attnum > 0
+      LEFT JOIN pg_opclass op ON op.oid = ix.indclass[k.n - 1]
       WHERE t.relname = $1
         AND n.nspname = 'public'
         AND NOT ix.indisprimary
-      GROUP BY i.relname, ix.indisunique
-      ORDER BY i.relname
+        AND NOT EXISTS (
+          SELECT 1 FROM pg_constraint con
+          WHERE con.conindid = ix.indexrelid
+            AND con.contype IN (${this.constraintIndexTypes.map((type) => `'${type}'`).join(', ')})
+        )
+      ORDER BY i.relname, k.n
     `;
     }
+    /**
+     * Constraint kinds whose backing index is the constraint itself rather than an index anyone asked
+     * for. Postgres builds one for `PRIMARY KEY`, `UNIQUE` and `EXCLUDE`, and only for those: a plain
+     * `CREATE UNIQUE INDEX` has no `pg_constraint` row at all, so it survives.
+     *
+     * Nothing to do with {@link indexFacets}, which says which *attributes* of an index diffing may
+     * compare. This one decides which indexes are reported at all.
+     */
+    constraintIndexTypes = ['p', 'u', 'x'];
     getForeignKeysQuery(_tableName) {
         return /*sql*/ `
       SELECT
@@ -141,11 +186,18 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         }));
     }
     async mapIndexesResult(_read, _tableName, results) {
-        return results.map((row) => ({
-            name: row.index_name,
-            columns: row.columns.map((column) => ({ column })),
-            unique: row.is_unique,
-        }));
+        // One row per index entry, ordered by position, so the rows of an index are its entries in order.
+        return [...Map.groupBy(results, (row) => row.index_name)].map(([name, rows]) => {
+            const include = rows.filter((row) => !row.is_key).map((row) => row.entry);
+            return {
+                name,
+                entries: rows.filter((row) => row.is_key).map(mapIndexEntry),
+                unique: rows[0].is_unique,
+                type: INDEX_TYPES.find((type) => type === rows[0].method),
+                where: rows[0].predicate ?? undefined,
+                include: include.length > 0 ? include : undefined,
+            };
+        });
     }
     async mapForeignKeysResult(_read, _tableName, results) {
         return results.map((row) => ({
@@ -200,3 +252,34 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         return columnDefault?.includes('nextval(') ?? false;
     }
 }
+/**
+ * Postgres states every entry in full: a plain column still reports `order: 'asc'`, and only a
+ * non-default operator class is named. The diff defaults the entity side to match, so an option
+ * omitted there and one written out are not read as two different indexes.
+ */
+function mapIndexEntry(row) {
+    return {
+        column: row.entry,
+        ...(row.is_expression && { expression: true }),
+        order: row.descending ? 'desc' : 'asc',
+        nulls: row.nulls_first ? 'first' : 'last',
+        ...(row.ops_class && { opsClass: row.ops_class }),
+    };
+}
+/**
+ * CockroachDB answers the same catalogue queries and differs only in what it can express: v26.2.5
+ * still rejects `NULLS FIRST/LAST` and operator classes as "unimplemented", and it sorts nulls first
+ * on an ASC column where Postgres sorts them last. Reading a nulls order back would therefore report
+ * every ascending index as drifted, against an entity that could not have asked for one. Its access
+ * method, `prefix`, needs nothing: a method that is not a known index type is reported as no type.
+ */
+export class CockroachSchemaIntrospector extends PostgresSchemaIntrospector {
+    indexFacets = new Set(['order', 'include']);
+    /**
+     * `'u'` is missing on purpose. CockroachDB registers a `UNIQUE` constraint for a plain `CREATE
+     * UNIQUE INDEX` too, naming it after the index, so filtering on it would hide every unique index a
+     * user asked for and report it missing forever. It leaves no way to tell the two apart, so the
+     * index a `@Field({ unique })` builds underneath itself stays visible there.
+     */
+    constraintIndexTypes = ['p', 'x'];
+}

package/dist/migrate/introspection/sqliteIntrospector.js

@@ -88,7 +88,7 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
             if (named.length === columns.length && (isUserCreated || isCompositeUnique)) {
                 indexSchemas.push({
                     name: index.name,
-                    columns: named.map((column) => ({ column: column.name })),
+                    entries: named.map((column) => ({ column: column.name })),
                     unique: Boolean(index.unique),
                 });
             }

package/dist/migrate/migrator.js

@@ -8,7 +8,7 @@ import { LoggerWrapper } from '../util/index.js';
 import { withQuerierForMigrations, withSqlQuerierForMigrations } from './acquireQuerierForMigrations.js';
 import { buildSqlQuerierMigrationModule, EMPTY_MANUAL_MIGRATION_DOWN_INNER, EMPTY_MANUAL_MIGRATION_UP_INNER, emitSqlRunCalls, } from './codegen/migrationFile.js';
 import { runMongoCommand } from './generator/mongoCommand.js';
-import { MongoSchemaIntrospector, MysqlSchemaIntrospector, PostgresSchemaIntrospector, SqliteSchemaIntrospector, } from './introspection/index.js';
+import { CockroachSchemaIntrospector, MongoSchemaIntrospector, MysqlSchemaIntrospector, PostgresSchemaIntrospector, SqliteSchemaIntrospector, } from './introspection/index.js';
 import { createSchemaGenerator } from './schemaGenerator.js';
 import { createSchemaGeneratorAsync } from './schemaGeneratorAsync.js';
 import { DatabaseMigrationStorage } from './storage/databaseStorage.js';
@@ -78,8 +78,9 @@ export class Migrator {
         }
         switch (d) {
             case 'postgres':
-            case 'cockroachdb':
                 return new PostgresSchemaIntrospector(this.pool);
+            case 'cockroachdb':
+                return new CockroachSchemaIntrospector(this.pool);
             case 'mysql':
             case 'mariadb':
                 return new MysqlSchemaIntrospector(this.pool);

package/dist/migrate/schemaGenerator.d.ts

@@ -1,6 +1,7 @@
 import { type AbstractDialect, AbstractSqlDialect } from '../dialect/index.js';
+import type { SchemaAST } from '../schema/schemaAST.js';
 import type { CanonicalType, ColumnNode, ForeignKeyAction, IndexNode, TableNode } from '../schema/types.js';
-import type { ColumnSchema, CreateSchemaOptions, DialectFeatures, DropSchemaOptions, EntityMeta, FieldOptions, IndexSchema, NamingStrategy, SchemaDiff, SqlDdlGenerator, Type } from '../type/index.js';
+import type { ColumnSchema, CreateSchemaOptions, DialectFeatures, DropSchemaOptions, EntityMeta, FieldOptions, IndexSchema, NamingStrategy, SchemaDiff, SchemaGenerator, SqlDdlGenerator, Type } from '../type/index.js';
 import type { FullColumnDefinition, TableDefinition, TableForeignKeyDefinition } from './builder/types.js';
 /**
  * Unified SQL schema generator.
@@ -82,6 +83,21 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
      * Compare an entity with a database table node and return the differences.
      */
     diffSchema<E>(entity: Type<E>, currentTable: TableNode | undefined): SchemaDiff | undefined;
+    /**
+     * Indexes the entity declares that the table does not have, matched by name and built the same way
+     * `CREATE TABLE` builds them, so adding an `@Index` to an entity already in the database is picked
+     * up rather than waiting for the table to be created from scratch somewhere else.
+     *
+     * Only ever additive. An index the entity does not name is left alone: it may well have been
+     * created deliberately outside the ORM, and dropping it is a decision for a reviewed migration.
+     */
+    private missingIndexes;
+    /**
+     * A vector index this dialect declares inside `CREATE TABLE` rather than as a statement of its own,
+     * which MariaDB is alone in doing. It has no `CREATE INDEX` form, so it can only ever be created
+     * with its table, never added to one.
+     */
+    private isInlineVectorIndex;
     private columnNodeToSchema;
     /**
      * Convert field options to ColumnSchema. Both sides of a diff are the engine's SQL spelling: what it
@@ -131,9 +147,16 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
     generateRenameColumnSql(tableName: string, oldName: string, newName: string): string;
     generateAddForeignKeySql(tableName: string, foreignKey: TableForeignKeyDefinition): string;
     generateDropForeignKeySql(tableName: string, constraintName: string): string;
-    private tableDefinitionToNode;
-    private fullColumnDefinitionToNode;
 }
+/**
+ * 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.
+ */
+export declare function buildEntityAST(generator: Pick<SchemaGenerator, 'resolveTableName' | 'resolveColumnName'>, entities: readonly Type<unknown>[], defaultForeignKeyAction?: ForeignKeyAction): SchemaAST;
 /**
  * Synchronous factory for SQL schema generators only.
  * For MongoDB, use `createSchemaGeneratorAsync` from `./schemaGeneratorAsync.js` so the optional `mongodb` peer is not loaded at import time.

package/dist/migrate/schemaGenerator.js

@@ -1,9 +1,10 @@
 import { AbstractSqlDialect } from '../dialect/index.js';
 import { getMeta } from '../entity/index.js';
 import { areTypesEqual, canonicalToSql, fieldOptionsToCanonical, isVectorCategory, sqlToCanonical, } from '../schema/canonicalType.js';
-import { SchemaASTBuilder } from '../schema/schemaASTBuilder.js';
+import { buildSchemaAST } from '../schema/schemaASTBuilder.js';
 import { escapeSqlId, getKeys, isAutoIncrement } from '../util/index.js';
 import { formatDefaultValue } from './builder/expressions.js';
+import { fullColumnDefinitionToNode, tableDefinitionToNode } from './generator/definitionToNode.js';
 import { indexNodeToSchema } from './generator/indexNodeToSchema.js';
 /**
  * Unified SQL schema generator.
@@ -90,7 +91,7 @@ export class SqlSchemaGenerator {
      * resolves instead of being silently dropped.
      */
     orderedTables(entities, direction, only) {
-        const ast = new SchemaASTBuilder(this.dialect.namingStrategy).fromEntities(entities);
+        const ast = buildEntityAST(this, entities, this.defaultForeignKeyAction);
         const tables = direction === 'create' ? ast.getCreateOrder() : ast.getDropOrder();
         if (!only) {
             return tables;
@@ -331,7 +332,11 @@ export class SqlSchemaGenerator {
         for (const [name] of currentColumns) {
             columnsToDrop.push(name);
         }
-        if (columnsToAdd.length === 0 && columnsToAlter.length === 0 && columnsToDrop.length === 0) {
+        const indexesToAdd = this.missingIndexes(entity, currentTable);
+        if (columnsToAdd.length === 0 &&
+            columnsToAlter.length === 0 &&
+            columnsToDrop.length === 0 &&
+            indexesToAdd.length === 0) {
             return undefined;
         }
         return {
@@ -340,8 +345,32 @@ export class SqlSchemaGenerator {
             columnsToAdd: columnsToAdd.length > 0 ? columnsToAdd : undefined,
             columnsToAlter: columnsToAlter.length > 0 ? columnsToAlter : undefined,
             columnsToDrop: columnsToDrop.length > 0 ? columnsToDrop : undefined,
+            indexesToAdd: indexesToAdd.length > 0 ? indexesToAdd : undefined,
         };
     }
+    /**
+     * Indexes the entity declares that the table does not have, matched by name and built the same way
+     * `CREATE TABLE` builds them, so adding an `@Index` to an entity already in the database is picked
+     * up rather than waiting for the table to be created from scratch somewhere else.
+     *
+     * Only ever additive. An index the entity does not name is left alone: it may well have been
+     * created deliberately outside the ORM, and dropping it is a decision for a reviewed migration.
+     */
+    missingIndexes(entity, currentTable) {
+        const desired = buildEntityAST(this, [entity]).getTable(currentTable.name)?.indexes ?? [];
+        const present = new Set(currentTable.indexes.map((index) => index.name));
+        return desired
+            .filter((index) => !present.has(index.name) && !this.isInlineVectorIndex(index))
+            .map(indexNodeToSchema);
+    }
+    /**
+     * A vector index this dialect declares inside `CREATE TABLE` rather than as a statement of its own,
+     * which MariaDB is alone in doing. It has no `CREATE INDEX` form, so it can only ever be created
+     * with its table, never added to one.
+     */
+    isInlineVectorIndex(index) {
+        return this.features.inlineVectorIndex && index.type === 'vector';
+    }
     columnNodeToSchema(col) {
         return {
             name: col.name,
@@ -430,12 +459,11 @@ export class SqlSchemaGenerator {
     generateCreateTableFromNode(table, options = {}) {
         const columns = [];
         const constraints = [];
-        const isInlineVectorIdx = this.features.inlineVectorIndex;
-        const vectorIndexes = isInlineVectorIdx ? table.indexes.filter((idx) => idx.type === 'vector') : [];
-        const regularIndexes = isInlineVectorIdx ? table.indexes.filter((idx) => idx.type !== 'vector') : table.indexes;
+        const vectorIndexes = table.indexes.filter((index) => this.isInlineVectorIndex(index));
+        const regularIndexes = table.indexes.filter((index) => !this.isInlineVectorIndex(index));
         // MariaDB rejects a `VECTOR INDEX` whose column is nullable ("All parts of a VECTOR index must
         // be NOT NULL"), so being indexed decides it rather than the entity's own nullability.
-        const indexedVectorColumns = new Set(vectorIndexes.flatMap((idx) => idx.columns.map((col) => col.name)));
+        const indexedVectorColumns = new Set(vectorIndexes.flatMap((idx) => idx.entries.map((entry) => entry.column)));
         for (const col of table.columns.values()) {
             const colDef = this.generateColumnFromNode(indexedVectorColumns.has(col.name) ? { ...col, nullable: false } : col);
             columns.push(colDef);
@@ -503,7 +531,7 @@ export class SqlSchemaGenerator {
         return this.generateCreateIndex(index.table.name, indexNodeToSchema(index), options);
     }
     generateCreateTableFromDefinition(table, options = {}) {
-        const tableNode = this.tableDefinitionToNode(table);
+        const tableNode = tableDefinitionToNode(table);
         return this.generateCreateTableFromNode(tableNode, options);
     }
     generateRenameTableSql(oldName, newName) {
@@ -513,11 +541,11 @@ export class SqlSchemaGenerator {
         return `ALTER TABLE ${this.escapeId(oldName)} RENAME TO ${this.escapeId(newName)};`;
     }
     generateAddColumnSql(tableName, column) {
-        const colSql = this.generateColumnFromNode(this.fullColumnDefinitionToNode(column, tableName));
+        const colSql = this.generateColumnFromNode(fullColumnDefinitionToNode(column, tableName));
         return `ALTER TABLE ${this.escapeId(tableName)} ADD COLUMN ${colSql};`;
     }
     generateAlterColumnSql(tableName, columnName, column) {
-        const node = this.fullColumnDefinitionToNode(column, tableName);
+        const node = fullColumnDefinitionToNode(column, tableName);
         return this.generateAlterColumnStatements(tableName, { ...this.columnNodeToSchema(node), name: columnName }, this.generateColumnFromNode(node)).join('\n');
     }
     generateDropColumnSql(tableName, columnName) {
@@ -542,88 +570,21 @@ export class SqlSchemaGenerator {
     generateDropForeignKeySql(tableName, constraintName) {
         return `ALTER TABLE ${this.escapeId(tableName)} ${this.dialect.dropForeignKeySyntax} ${this.escapeId(constraintName)};`;
     }
-    tableDefinitionToNode(def) {
-        const columns = new Map();
-        const pkNodes = [];
-        const table = {
-            name: def.name,
-            columns,
-            primaryKey: [], // placeholder
-            indexes: [],
-            schema: { tables: new Map(), relationships: [], indexes: [] },
-            incomingRelations: [],
-            outgoingRelations: [],
-            comment: def.comment,
-        };
-        for (const colDef of def.columns) {
-            const node = this.fullColumnDefinitionToNode(colDef, def.name);
-            node.table = table;
-            columns.set(node.name, node);
-            if (node.isPrimaryKey) {
-                pkNodes.push(node);
-            }
-        }
-        const finalPrimaryKey = def.primaryKey
-            ? def.primaryKey.map((name) => columns.get(name)).filter((c) => c !== undefined)
-            : pkNodes;
-        table.primaryKey = finalPrimaryKey;
-        for (const idxDef of def.indexes) {
-            const indexNode = {
-                ...idxDef,
-                table,
-                columns: idxDef.columns
-                    .map((entry) => (entry.expression ? undefined : columns.get(entry.column)))
-                    .filter((c) => c !== undefined),
-                entries: idxDef.columns,
-            };
-            table.indexes.push(indexNode);
-        }
-        for (const fkDef of def.foreignKeys) {
-            const relNode = {
-                name: fkDef.name ?? `fk_${def.name}_${fkDef.columns.join('_')}`,
-                type: 'ManyToOne', // Builder default
-                from: {
-                    table,
-                    columns: fkDef.columns.map((name) => columns.get(name)).filter((c) => c !== undefined),
-                },
-                to: {
-                    table: { name: fkDef.referencesTable },
-                    columns: fkDef.referencesColumns.map((name) => ({ name })),
-                },
-                onDelete: fkDef.onDelete,
-                onUpdate: fkDef.onUpdate,
-            };
-            table.outgoingRelations.push(relNode);
-        }
-        return table;
-    }
-    fullColumnDefinitionToNode(col, tableName) {
-        return {
-            name: col.name,
-            type: col.type,
-            nullable: col.nullable,
-            defaultValue: col.defaultValue,
-            isPrimaryKey: col.primaryKey,
-            isAutoIncrement: col.autoIncrement,
-            isUnique: col.unique,
-            comment: col.comment,
-            table: { name: tableName },
-            referencedBy: [],
-            references: col.foreignKey
-                ? {
-                    name: `fk_${tableName}_${col.name}`,
-                    type: 'ManyToOne',
-                    from: { table: { name: tableName }, columns: [] },
-                    to: {
-                        table: { name: col.foreignKey.table },
-                        columns: col.foreignKey.columns.map((name) => ({ name })),
-                    },
-                    onDelete: col.foreignKey.onDelete,
-                    onUpdate: col.foreignKey.onUpdate,
-                }
-                : undefined,
-        };
-    }
+}
+/**
+ * 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.
+ */
+export function buildEntityAST(generator, entities, defaultForeignKeyAction) {
+    return buildSchemaAST(entities, {
+        resolveTableName: (entity, meta) => generator.resolveTableName(entity, meta),
+        resolveColumnName: (key, field) => generator.resolveColumnName(key, field),
+        defaultForeignKeyAction,
+    });
 }
 /**
  * Synchronous factory for SQL schema generators only.

package/dist/schema/index.d.ts

@@ -18,8 +18,8 @@ export { areTypesEqual, canonicalToColumnType, canonicalToSql, canonicalToTypeSc
  */
 export declare function introspectSchema(introspector: SchemaIntrospector): Promise<SchemaAST>;
 export { SchemaAST } from './schemaAST.js';
-export type { BuildFromEntitiesOptions } from './schemaASTBuilder.js';
-export { SchemaASTBuilder } from './schemaASTBuilder.js';
+export type { BuildSchemaASTOptions } from './schemaASTBuilder.js';
+export { buildSchemaAST } from './schemaASTBuilder.js';
 export type { DiffOptions } from './schemaASTDiffer.js';
-export { diffSchemas, SchemaASTDiffer } from './schemaASTDiffer.js';
+export { diffSchemas } from './schemaASTDiffer.js';
 export type { CanonicalType, ColumnDiff, ColumnNode, Drift, DriftReport, DriftSeverity, DriftStatus, DriftType, ForeignKeyAction, IndexDiff, IndexNode, IndexSource, IndexSyncStatus, IndexType, RelationshipDiff, RelationshipNode, RelationshipSource, RelationshipType, SchemaAST as ISchemaAST, SchemaDiffResult, SizeVariant, TableDiff, TableNode, TypeCategory, ValidationError, ValidationErrorType, } from './types.js';