uql-orm 0.66.0 → 0.67.0

package/dist/migrate/introspection/mysqlIntrospector.js

@@ -1,3 +1,4 @@
+import { unescapeMysqlString } from '../../util/sqlLiteral.js';
 import { AbstractSqlSchemaIntrospector } from './abstractSqlSchemaIntrospector.js';
 /**
  * MySQL/MariaDB schema introspector.
@@ -23,9 +24,8 @@ export class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         AND TABLE_NAME = ?
     `;
     }
-    parseTableExistsResult(results) {
-        // No row, or no count in it, reads as `NaN`, which is not above zero.
-        return Number(results[0]?.count) > 0;
+    parseTableExistsResult([row]) {
+        return Number(row.count) > 0;
     }
     getColumnsQuery(_tableName) {
         return /*sql*/ `
@@ -98,7 +98,7 @@ export class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
             nullable: row.is_nullable === 'YES',
             defaultValue: this.parseDefaultValue(row.column_default),
             isPrimaryKey: row.column_key === 'PRI',
-            isAutoIncrement: (row.extra || '').toLowerCase().includes('auto_increment'),
+            isAutoIncrement: row.extra.toLowerCase().includes('auto_increment'),
             isUnique: row.column_key === 'UNI',
             length: this.toNumber(row.character_maximum_length),
             precision: this.toNumber(row.numeric_precision),
@@ -112,7 +112,7 @@ export class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
             // A functional or multi-valued key part has no `COLUMN_NAME` - the `COALESCE` above keeps its
             // place in the list, and it is reported as the expression it is, which is what stops diffing
             // from comparing an entry list the server cannot state against the entity's own.
-            entries: (row.columns ?? '').split(',').map((column) => (column ? { column } : { column, expression: true })),
+            entries: row.columns.split(',').map((column) => (column ? { column } : { column, expression: true })),
             unique: Boolean(row.is_unique),
         }));
     }
@@ -125,6 +125,11 @@ export class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
             onUpdate: this.normalizeReferentialAction(row.update_rule),
         }));
     }
+    /**
+     * MariaDB prints a string default as the literal it is (`'it''s'`). MySQL prints one bare, save an
+     * expression default (`DEFAULT ('x')`, what a `TEXT` column takes), which comes with a charset
+     * introducer and every quote and backslash escaped once more: `_utf8mb4\'x\'`.
+     */
     parseDefaultValue(defaultValue) {
         if (defaultValue === null) {
             return undefined;
@@ -136,16 +141,13 @@ export class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         if (normalized === 'CURRENT_TIMESTAMP' || normalized === 'CURRENT_TIMESTAMP()') {
             return 'CURRENT_TIMESTAMP';
         }
-        if (/^-?\d+$/.test(defaultValue)) {
-            return Number.parseInt(defaultValue, 10);
+        if (/^-?\d+(\.\d+)?$/.test(defaultValue)) {
+            return Number(defaultValue);
         }
-        if (/^-?\d+\.\d+$/.test(defaultValue)) {
-            return Number.parseFloat(defaultValue);
-        }
-        if (defaultValue?.startsWith("'") && defaultValue?.endsWith("'")) {
-            return defaultValue.slice(1, -1);
-        }
-        return defaultValue;
+        const introduced = /^_\w+(\\'.*\\')$/s.exec(defaultValue);
+        const literal = introduced ? unescapeMysqlString(introduced[1]) : defaultValue;
+        const quoted = /^'(.*)'$/s.exec(literal);
+        return quoted ? unescapeMysqlString(quoted[1]) : literal;
     }
 }
 /**

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

@@ -13,7 +13,7 @@ export declare class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrosp
     readonly indexFacets: ReadonlySet<IndexFacet>;
     protected getTableNamesQuery(): string;
     protected tableExistsQuery(): string;
-    protected parseTableExistsResult(results: RawRow[]): boolean;
+    protected parseTableExistsResult([row]: 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
@@ -36,22 +36,29 @@ export declare class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrosp
      * compare. This one decides which indexes are reported at all.
      */
     protected readonly constraintIndexTypes: readonly string[];
+    /** From `pg_constraint`, whose key arrays keep each column paired with the one it references. */
     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: PostgresIndexRow[]): Promise<IndexSchema[]>;
-    protected mapForeignKeysResult(_read: TableRowReader, _tableName: string, results: {
-        constraint_name: string;
-        columns: string[];
-        referenced_table: string;
-        referenced_columns: string[];
-        delete_rule: string;
-        update_rule: string;
-    }[]): Promise<ForeignKeySchema[]>;
+    protected mapForeignKeysResult(_read: TableRowReader, _tableName: string, results: PostgresForeignKeyRow[]): Promise<ForeignKeySchema[]>;
     protected normalizeType(dataType: string, udtName: string): string;
+    /**
+     * Postgres quotes a negative number (`'-3'::integer`); CockroachDB parenthesizes one (`(-3)`) and
+     * writes a quote-bearing string in escape syntax (`e'it\'s'`). Any other cast is dropped, and a
+     * function call (`now()`, `nextval(...)`) is returned as written.
+     */
     protected parseDefaultValue(defaultValue: string | null): unknown;
     protected isAutoIncrement(columnDefault: string | null, isIdentity: string): boolean;
 }
+/** `pg_constraint`'s one-letter spelling of each action. */
+declare const FOREIGN_KEY_ACTION_CODES: {
+    readonly a: 'NO ACTION';
+    readonly r: 'RESTRICT';
+    readonly c: 'CASCADE';
+    readonly n: 'SET NULL';
+    readonly d: 'SET DEFAULT';
+};
 /**
  * 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
@@ -69,6 +76,14 @@ export declare class CockroachSchemaIntrospector extends PostgresSchemaIntrospec
      */
     protected readonly constraintIndexTypes: readonly string[];
 }
+type PostgresForeignKeyRow = {
+    constraint_name: string;
+    columns: string[];
+    referenced_table: string;
+    referenced_columns: string[];
+    delete_rule: keyof typeof FOREIGN_KEY_ACTION_CODES;
+    update_rule: keyof typeof FOREIGN_KEY_ACTION_CODES;
+};
 /** One entry of one index; what the index itself is repeats across its rows. */
 type PostgresIndexRow = {
     index_name: string;

package/dist/migrate/introspection/postgresIntrospector.js

@@ -34,8 +34,8 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
       ) AS exists
     `;
     }
-    parseTableExistsResult(results) {
-        return results[0]?.['exists'] ?? false;
+    parseTableExistsResult([row]) {
+        return row['exists'] === true;
     }
     getColumnsQuery(_tableName) {
         return /*sql*/ `
@@ -50,28 +50,25 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         c.numeric_scale,
         c.is_identity,
         c.identity_generation,
-        COALESCE(
-          (SELECT TRUE FROM information_schema.table_constraints tc
-           JOIN information_schema.key_column_usage kcu
-             ON tc.constraint_name = kcu.constraint_name
-           WHERE tc.table_name = c.table_name
-             AND tc.constraint_type = 'PRIMARY KEY'
-             AND kcu.column_name = c.column_name
-           LIMIT 1),
-          FALSE
+        EXISTS (
+          SELECT 1 FROM information_schema.table_constraints tc
+          JOIN information_schema.key_column_usage kcu USING (constraint_schema, constraint_name)
+          WHERE tc.table_schema = c.table_schema
+            AND tc.table_name = c.table_name
+            AND tc.constraint_type = 'PRIMARY KEY'
+            AND kcu.column_name = c.column_name
         ) AS is_primary_key,
-        COALESCE(
-          (SELECT TRUE FROM information_schema.table_constraints tc
-           JOIN information_schema.key_column_usage kcu
-             ON tc.constraint_name = kcu.constraint_name
-           WHERE tc.table_name = c.table_name
-             AND tc.constraint_type = 'UNIQUE'
-             AND kcu.column_name = c.column_name
-           LIMIT 1),
-          FALSE
+        EXISTS (
+          SELECT 1 FROM information_schema.table_constraints tc
+          JOIN information_schema.key_column_usage kcu USING (constraint_schema, constraint_name)
+          WHERE tc.table_schema = c.table_schema
+            AND tc.table_name = c.table_name
+            AND tc.constraint_type = 'UNIQUE'
+          GROUP BY tc.constraint_name
+          HAVING COUNT(*) = 1 AND MIN(kcu.column_name) = c.column_name
         ) AS is_unique,
         pg_catalog.col_description(
-          (SELECT oid FROM pg_catalog.pg_class WHERE relname = c.table_name),
+          (quote_ident(c.table_schema) || '.' || quote_ident(c.table_name))::regclass,
           c.ordinal_position
         ) AS column_comment
       FROM information_schema.columns c
@@ -113,7 +110,7 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
       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 n.nspname = ${this.schemaExpr}
         AND NOT ix.indisprimary
         AND NOT EXISTS (
           SELECT 1 FROM pg_constraint con
@@ -132,30 +129,29 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
      * compare. This one decides which indexes are reported at all.
      */
     constraintIndexTypes = ['p', 'u', 'x'];
+    /** From `pg_constraint`, whose key arrays keep each column paired with the one it references. */
     getForeignKeysQuery(_tableName) {
+        const columnsOf = (keys, table) => /*sql*/ `ARRAY_TO_JSON(ARRAY(
+      SELECT a.attname FROM UNNEST(${keys}) WITH ORDINALITY AS k(attnum, n)
+      JOIN pg_attribute a ON a.attrelid = ${table} AND a.attnum = k.attnum
+      ORDER BY k.n
+    ))`;
         return /*sql*/ `
       SELECT
-        tc.constraint_name,
-        ARRAY_TO_JSON(ARRAY_AGG(kcu.column_name ORDER BY kcu.ordinal_position)) AS columns,
-        ccu.table_name AS referenced_table,
-        ARRAY_TO_JSON(ARRAY_AGG(ccu.column_name ORDER BY kcu.ordinal_position)) AS referenced_columns,
-        rc.delete_rule,
-        rc.update_rule
-      FROM information_schema.table_constraints tc
-      JOIN information_schema.key_column_usage kcu
-        ON tc.constraint_name = kcu.constraint_name
-        AND tc.table_schema = kcu.table_schema
-      JOIN information_schema.constraint_column_usage ccu
-        ON ccu.constraint_name = tc.constraint_name
-        AND ccu.table_schema = tc.table_schema
-      JOIN information_schema.referential_constraints rc
-        ON rc.constraint_name = tc.constraint_name
-        AND rc.constraint_schema = tc.table_schema
-      WHERE tc.constraint_type = 'FOREIGN KEY'
-        AND tc.table_name = $1
-        AND tc.table_schema = ${this.schemaExpr}
-      GROUP BY tc.constraint_name, ccu.table_name, rc.delete_rule, rc.update_rule
-      ORDER BY tc.constraint_name
+        con.conname AS constraint_name,
+        ${columnsOf('con.conkey', 'con.conrelid')} AS columns,
+        ref.relname AS referenced_table,
+        ${columnsOf('con.confkey', 'con.confrelid')} AS referenced_columns,
+        con.confdeltype AS delete_rule,
+        con.confupdtype AS update_rule
+      FROM pg_constraint con
+      JOIN pg_class t ON t.oid = con.conrelid
+      JOIN pg_namespace n ON n.oid = t.relnamespace
+      JOIN pg_class ref ON ref.oid = con.confrelid
+      WHERE con.contype = 'f'
+        AND t.relname = $1
+        AND n.nspname = ${this.schemaExpr}
+      ORDER BY con.conname
     `;
     }
     getPrimaryKeyQuery(_tableName) {
@@ -205,8 +201,8 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
             name: row.constraint_name,
             columns: row.columns,
             references: { table: row.referenced_table, columns: row.referenced_columns },
-            onDelete: this.normalizeReferentialAction(row.delete_rule),
-            onUpdate: this.normalizeReferentialAction(row.update_rule),
+            onDelete: FOREIGN_KEY_ACTION_CODES[row.delete_rule],
+            onUpdate: FOREIGN_KEY_ACTION_CODES[row.update_rule],
         }));
     }
     normalizeType(dataType, udtName) {
@@ -219,29 +215,32 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         }
         return dataType.toUpperCase();
     }
+    /**
+     * Postgres quotes a negative number (`'-3'::integer`); CockroachDB parenthesizes one (`(-3)`) and
+     * writes a quote-bearing string in escape syntax (`e'it\'s'`). Any other cast is dropped, and a
+     * function call (`now()`, `nextval(...)`) is returned as written.
+     */
     parseDefaultValue(defaultValue) {
         if (!defaultValue) {
             return undefined;
         }
-        // Remove type casting (e.g., ::text, ::character varying, ::text[])
         const cleaned = defaultValue.replace(/::[a-z_]+(\s+[a-z_]+)?(\[\])?/gi, '').trim();
-        if (cleaned.startsWith("'") && cleaned.endsWith("'")) {
-            return cleaned.slice(1, -1);
+        const number = NUMBER_DEFAULT.exec(cleaned) ?? QUOTED_NUMBER_DEFAULT.exec(defaultValue);
+        if (number) {
+            return Number(number[1]);
         }
-        if (cleaned === 'true' || cleaned === 'false') {
-            return cleaned === 'true';
+        const quoted = /^'(.*)'$/s.exec(cleaned);
+        if (quoted) {
+            return quoted[1].replaceAll("''", "'");
         }
-        if (cleaned === 'NULL') {
-            return null;
+        const escaped = /^e'(.*)'$/s.exec(cleaned);
+        if (escaped) {
+            return escaped[1].replace(/\\(.)/gs, '$1');
         }
-        if (/^-?\d+$/.test(cleaned)) {
-            return Number.parseInt(cleaned, 10);
-        }
-        if (/^-?\d+\.\d+$/.test(cleaned)) {
-            return Number.parseFloat(cleaned);
+        if (cleaned === 'true' || cleaned === 'false') {
+            return cleaned === 'true';
         }
-        // Return cleaned value for functions like CURRENT_TIMESTAMP, nextval(), etc.
-        return cleaned;
+        return cleaned === 'NULL' ? null : cleaned;
     }
     isAutoIncrement(columnDefault, isIdentity) {
         // PostgreSQL identity columns (GENERATED ... AS IDENTITY)
@@ -252,6 +251,16 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         return columnDefault?.includes('nextval(') ?? false;
     }
 }
+/** `pg_constraint`'s one-letter spelling of each action. */
+const FOREIGN_KEY_ACTION_CODES = {
+    a: 'NO ACTION',
+    r: 'RESTRICT',
+    c: 'CASCADE',
+    n: 'SET NULL',
+    d: 'SET DEFAULT',
+};
+const NUMBER_DEFAULT = /^\(?(-?\d+(?:\.\d+)?)\)?$/;
+const QUOTED_NUMBER_DEFAULT = /^'(-?\d+(?:\.\d+)?)'::(?:smallint|integer|bigint|numeric|real|double precision)$/;
 /**
  * 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

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

@@ -6,7 +6,7 @@ import { AbstractSqlSchemaIntrospector, type TableRowReader } from './abstractSq
 export declare class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
     protected getTableNamesQuery(): string;
     protected tableExistsQuery(): string;
-    protected parseTableExistsResult(results: SqliteCountRow[]): boolean;
+    protected parseTableExistsResult([row]: SqliteCountRow[]): boolean;
     /**
      * `table_xinfo`, not `table_info`: the latter omits generated columns entirely, so a table carrying
      * one read back without it and every sync offered to add a column that was already there - which

package/dist/migrate/introspection/sqliteIntrospector.js

@@ -21,9 +21,8 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         AND name = ?
     `;
     }
-    parseTableExistsResult(results) {
-        // No row, or no count in it, reads as `NaN`, which is not above zero.
-        return Number(results[0]?.count) > 0;
+    parseTableExistsResult([row]) {
+        return Number(row.count) > 0;
     }
     /**
      * `table_xinfo`, not `table_info`: the latter omits generated columns entirely, so a table carrying
@@ -59,15 +58,16 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         return row.name;
     }
     async mapColumnsResult(read, tableName, results) {
-        // Get unique columns from indexes
         const uniqueColumns = await this.getUniqueColumns(read, tableName);
+        // Only a sole `INTEGER PRIMARY KEY` is the rowid, which is what numbers itself.
+        const soleKey = results.filter((row) => row.pk > 0).length === 1;
         return results.map((row) => ({
             name: row.name,
             type: this.normalizeType(row.type),
             nullable: row.notnull === 0,
             defaultValue: this.parseDefaultValue(row.dflt_value),
             isPrimaryKey: row.pk > 0,
-            isAutoIncrement: row.pk > 0 && row.type.toUpperCase() === 'INTEGER',
+            isAutoIncrement: soleKey && row.pk > 0 && row.type.toUpperCase() === 'INTEGER',
             isUnique: uniqueColumns.has(row.name),
             length: this.extractLength(row.type),
             precision: undefined,
@@ -130,8 +130,9 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
     async getUniqueColumns(read, tableName) {
         const indexes = await read(this.getIndexesQuery(tableName));
         const uniqueColumns = new Set();
+        // The key's own index is left out: a key column is unique already, which the entity side never states.
         for (const index of indexes) {
-            if (index.unique) {
+            if (index.unique && index.origin !== 'pk') {
                 const columns = await this.getIndexColumns(read, index.name);
                 // Only single-column unique constraints, and only over a real column (not an expression)
                 const [column] = columns;
@@ -165,14 +166,11 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
             return defaultValue;
         }
         if (/^'.*'$/.test(defaultValue)) {
-            return defaultValue.slice(1, -1);
+            return defaultValue.slice(1, -1).replaceAll("''", "'");
         }
         if (/^-?\d+$/.test(defaultValue)) {
             return Number.parseInt(defaultValue, 10);
         }
-        if (typeof defaultValue !== 'string') {
-            return defaultValue;
-        }
         if (/^-?\d+\.\d+$/.test(defaultValue)) {
             return Number.parseFloat(defaultValue);
         }

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];
+}