uql-orm 0.21.0 → 0.23.0

package/dist/migrate/migrator.js

@@ -5,8 +5,9 @@ import { getEntities, getMeta } from '../entity/index.js';
 import { introspectSchema } from '../schema/index.js';
 import { isKnownMigratorDialect, isSqlQuerier } from '../type/index.js';
 import { LoggerWrapper } from '../util/index.js';
-import { acquireQuerierForMigrations } from './acquireQuerierForMigrations.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 { createSchemaGenerator } from './schemaGenerator.js';
 import { createSchemaGeneratorAsync } from './schemaGeneratorAsync.js';
@@ -32,12 +33,12 @@ export class Migrator {
     dialectName;
     schemaGenerator;
     schemaIntrospector;
-    _namingStrategy;
+    _defaultForeignKeyAction;
     _mongoSchemaLoadPromise;
     constructor(pool, options = {}) {
         this.pool = pool;
         this.dialectName = pool.dialect.dialectName ?? 'postgres';
-        this._namingStrategy = options.namingStrategy;
+        this._defaultForeignKeyAction = options.defaultForeignKeyAction;
         this.storage =
             options.storage ??
                 new DatabaseMigrationStorage(pool, {
@@ -48,8 +49,7 @@ export class Migrator {
         this._entities = options.entities;
         this.schemaIntrospector = this.createIntrospector();
         this.schemaGenerator =
-            options.schemaGenerator ??
-                (this.dialectName === 'mongodb' ? undefined : this.createGenerator(options.namingStrategy));
+            options.schemaGenerator ?? (this.dialectName === 'mongodb' ? undefined : this.createGenerator());
     }
     /** Loads MongoDB schema generator on first use; SQL generators are set in the constructor (or via {@link setSchemaGenerator}). */
     async ensureSchemaGenerator() {
@@ -57,7 +57,7 @@ export class Migrator {
             return;
         }
         if (!this._mongoSchemaLoadPromise) {
-            this._mongoSchemaLoadPromise = createSchemaGeneratorAsync(this.pool.dialect, this._namingStrategy).then((gen) => {
+            this._mongoSchemaLoadPromise = createSchemaGeneratorAsync(this.pool.dialect, this._defaultForeignKeyAction).then((gen) => {
                 if (gen) {
                     this.schemaGenerator = gen;
                 }
@@ -91,11 +91,11 @@ export class Migrator {
                 return undefined;
         }
     }
-    createGenerator(namingStrategy) {
+    createGenerator() {
         if (!isKnownMigratorDialect(this.dialectName)) {
             return undefined;
         }
-        return createSchemaGenerator(this.pool.dialect, namingStrategy);
+        return createSchemaGenerator(this.pool.dialect, this._defaultForeignKeyAction);
     }
     /**
      * Get all discovered migrations from the migrations directory
@@ -185,49 +185,42 @@ export class Migrator {
      */
     async runMigration(migration, direction) {
         const startTime = Date.now();
-        const querier = await acquireQuerierForMigrations(this.pool);
-        if (!isSqlQuerier(querier)) {
-            await querier.release();
-            throw new Error('Migrator requires a SQL-based querier');
-        }
-        try {
-            this.logger.logMigration(`${direction === 'up' ? 'Running' : 'Reverting'} migration: ${migration.name}`);
-            await querier.beginTransaction();
-            if (direction === 'up') {
-                await migration.up(querier);
-                // Log within the same transaction
-                await this.storage.logWithQuerier(querier, migration.name);
+        return withSqlQuerierForMigrations(this.pool, 'Migrator', async (querier) => {
+            try {
+                this.logger.logMigration(`${direction === 'up' ? 'Running' : 'Reverting'} migration: ${migration.name}`);
+                await querier.transaction(async () => {
+                    if (direction === 'up') {
+                        await migration.up(querier);
+                        // Log within the same transaction
+                        await this.storage.logWithQuerier(querier, migration.name);
+                    }
+                    else {
+                        await migration.down(querier);
+                        // Unlog within the same transaction
+                        await this.storage.unlogWithQuerier(querier, migration.name);
+                    }
+                });
+                const duration = Date.now() - startTime;
+                this.logger.logMigration(`Migration ${migration.name} ${direction === 'up' ? 'applied' : 'reverted'} in ${duration}ms`);
+                return {
+                    name: migration.name,
+                    direction,
+                    duration,
+                    success: true,
+                };
             }
-            else {
-                await migration.down(querier);
-                // Unlog within the same transaction
-                await this.storage.unlogWithQuerier(querier, migration.name);
+            catch (error) {
+                const duration = Date.now() - startTime;
+                this.logger.logError(`Migration ${migration.name} failed: ${error.message}`, error);
+                return {
+                    name: migration.name,
+                    direction,
+                    duration,
+                    success: false,
+                    error: error,
+                };
             }
-            await querier.commitTransaction();
-            const duration = Date.now() - startTime;
-            this.logger.logMigration(`Migration ${migration.name} ${direction === 'up' ? 'applied' : 'reverted'} in ${duration}ms`);
-            return {
-                name: migration.name,
-                direction,
-                duration,
-                success: true,
-            };
-        }
-        catch (error) {
-            await querier.rollbackTransaction();
-            const duration = Date.now() - startTime;
-            this.logger.logError(`Migration ${migration.name} failed: ${error.message}`, error);
-            return {
-                name: migration.name,
-                direction,
-                duration,
-                success: false,
-                error: error,
-            };
-        }
-        finally {
-            await querier.release();
-        }
+        });
     }
     /**
      * Generate a new migration file
@@ -251,26 +244,18 @@ export class Migrator {
      * Generate a migration based on entity schema differences
      */
     async generateFromEntities(name) {
-        await this.ensureSchemaGenerator();
-        if (!this.schemaGenerator) {
-            throw new Error('Schema generator not set. Call setSchemaGenerator() first.');
-        }
-        const diffs = await this.getDiffs();
         const upStatements = [];
         const downStatements = [];
-        for (const diff of diffs) {
+        for (const { diff, entity } of await this.pendingDiffs()) {
             if (diff.type === 'create') {
-                const entity = await this.findEntityForTable(diff.tableName);
                 if (entity) {
-                    upStatements.push(...this.schemaGenerator.generateCreateTable(entity));
-                    downStatements.push(this.schemaGenerator.generateDropTable(entity));
+                    upStatements.push(...this.generator.generateCreateTable(entity));
+                    downStatements.push(this.generator.generateDropTable(diff.tableName, { ifExists: true }));
                 }
             }
             else if (diff.type === 'alter') {
-                const alterStatements = this.schemaGenerator.generateAlterTable(diff);
-                upStatements.push(...alterStatements);
-                const alterDownStatements = this.schemaGenerator.generateAlterTableDown(diff);
-                downStatements.push(...alterDownStatements);
+                upStatements.push(...this.generator.generateAlterTable(diff));
+                downStatements.push(...this.generator.generateAlterTableDown(diff));
             }
         }
         if (upStatements.length === 0) {
@@ -342,70 +327,76 @@ export class Migrator {
      */
     async syncForce() {
         await this.ensureSchemaGenerator();
-        if (!this.schemaGenerator) {
-            throw new Error('Schema generator not set. Call setSchemaGenerator() first.');
-        }
-        const querier = await acquireQuerierForMigrations(this.pool);
-        if (!isSqlQuerier(querier)) {
-            await querier.release();
-            throw new Error('Migrator requires a SQL-based querier');
-        }
-        try {
-            await querier.beginTransaction();
+        await withSqlQuerierForMigrations(this.pool, 'Migrator', (querier) => querier.transaction(async () => {
             // Drop all tables first (in reverse order for foreign keys)
             for (const entity of [...this.entities].reverse()) {
-                const dropSql = this.schemaGenerator.generateDropTable(entity);
+                const tableName = this.generator.resolveTableName(entity, getMeta(entity));
+                const dropSql = this.generator.generateDropTable(tableName, { ifExists: true });
                 this.logger.logSchema(`Executing: ${dropSql}`);
                 await querier.run(dropSql);
             }
             // Create all tables
             for (const entity of this.entities) {
-                const createStmts = this.schemaGenerator.generateCreateTable(entity);
+                const createStmts = this.generator.generateCreateTable(entity);
                 for (const createSql of createStmts) {
                     this.logger.logSchema(`Executing: ${createSql}`);
                     await querier.run(createSql);
                 }
             }
-            await querier.commitTransaction();
-            this.logger.logSchema('Schema sync (force) completed');
-        }
-        catch (error) {
-            await querier.rollbackTransaction();
-            throw error;
-        }
-        finally {
-            await querier.release();
-        }
+        }));
+        this.logger.logSchema('Schema sync (force) completed');
     }
     /**
      * Safely synchronizes the schema by only adding missing tables and columns.
      */
     async autoSync(options = {}) {
-        await this.ensureSchemaGenerator();
-        if (!this.schemaGenerator || !this.schemaIntrospector) {
-            throw new Error('Schema generator and introspector must be set');
+        const statements = await this.planSync(options);
+        if (statements.length === 0) {
+            if (options.logging)
+                this.logger.logSchema('Schema is already in sync.');
+            return;
         }
-        const diffs = await this.getDiffs();
+        await this.executeSyncStatements(statements, options);
+    }
+    /**
+     * The DDL {@link autoSync} would run, without running it. Separate so `--dry-run` shows the real
+     * statements rather than a summary of a second, differently-computed diff.
+     */
+    async planSync(options = {}) {
         const statements = [];
-        for (const diff of diffs) {
+        for (const { diff, entity } of await this.pendingDiffs()) {
             if (diff.type === 'create') {
-                const entity = await this.findEntityForTable(diff.tableName);
-                if (entity) {
-                    statements.push(...this.schemaGenerator.generateCreateTable(entity));
-                }
+                if (entity)
+                    statements.push(...this.generator.generateCreateTable(entity));
             }
             else if (diff.type === 'alter') {
-                const filteredDiff = this.filterDiff(diff, options);
-                const alterStatements = this.schemaGenerator.generateAlterTable(filteredDiff);
-                statements.push(...alterStatements);
+                statements.push(...this.generator.generateAlterTable(this.filterDiff(diff, options)));
             }
         }
-        if (statements.length === 0) {
-            if (options.logging)
-                this.logger.logSchema('Schema is already in sync.');
-            return;
+        return statements;
+    }
+    /**
+     * Each pending diff with the entity it came from, since resolving that is async and every caller
+     * needs it. What to emit stays with the caller: a sync narrows the forward direction to what the
+     * caller allows and never asks for the rollback, which on SQLite cannot even be expressed (no
+     * `ALTER COLUMN`), so computing it eagerly for everyone would throw there.
+     */
+    async pendingDiffs() {
+        const diffs = await this.getDiffs();
+        return Promise.all(diffs.map(async (diff) => ({
+            diff,
+            entity: diff.type === 'create' ? await this.findEntityForTable(diff.tableName) : undefined,
+        })));
+    }
+    /**
+     * The schema generator. A getter because MongoDB's loads lazily (see {@link ensureSchemaGenerator}),
+     * so every caller had to repeat the same assertion after awaiting it.
+     */
+    get generator() {
+        if (!this.schemaGenerator) {
+            throw new Error('Schema generator not set. Call setSchemaGenerator() first.');
         }
-        await this.executeSyncStatements(statements, options);
+        return this.schemaGenerator;
     }
     filterDiff(diff, options) {
         const filteredDiff = { ...diff };
@@ -430,69 +421,29 @@ export class Migrator {
         return filteredDiff;
     }
     async executeSyncStatements(statements, options) {
-        const querier = await acquireQuerierForMigrations(this.pool);
-        try {
-            if (this.dialectName === 'mongodb') {
-                await this.executeMongoSyncStatements(statements, options, querier);
-            }
-            else {
-                await this.executeSqlSyncStatements(statements, options, querier);
-            }
-            if (options.logging)
-                this.logger.logSchema('Schema synchronization completed');
-        }
-        catch (error) {
-            if (this.dialectName !== 'mongodb' && isSqlQuerier(querier)) {
-                await querier.rollbackTransaction();
-            }
-            throw error;
-        }
-        finally {
-            await querier.release();
-        }
+        // Mongo creates collections and indexes outside any transaction, so only the SQL path opens one.
+        await withQuerierForMigrations(this.pool, (querier) => this.dialectName === 'mongodb'
+            ? this.executeMongoSyncStatements(statements, options, querier)
+            : querier.transaction(() => this.executeSqlSyncStatements(statements, options, querier)));
+        if (options.logging)
+            this.logger.logSchema('Schema synchronization completed');
     }
     async executeMongoSyncStatements(statements, options, querier) {
-        const db = querier.db;
-        for (const stmt of statements) {
-            const cmd = JSON.parse(stmt);
+        for (const statement of statements) {
             if (options.logging)
-                this.logger.logSchema(`Executing MongoDB: ${stmt}`);
-            const collectionName = cmd.name || cmd.collection;
-            if (!collectionName) {
-                throw new Error(`MongoDB command missing collection name: ${stmt}`);
-            }
-            const collection = db.collection(collectionName);
-            if (cmd.action === 'createCollection') {
-                await db.createCollection(cmd.name);
-                if (cmd.indexes?.length) {
-                    for (const idx of cmd.indexes) {
-                        const key = Object.fromEntries(idx.columns.map((c) => [c, 1]));
-                        await collection.createIndex(key, { unique: idx.unique, name: idx.name });
-                    }
-                }
-            }
-            else if (cmd.action === 'dropCollection') {
-                await collection.drop();
-            }
-            else if (cmd.action === 'createIndex') {
-                await collection.createIndex(cmd.key, cmd.options);
-            }
-            else if (cmd.action === 'dropIndex') {
-                await collection.dropIndex(cmd.name);
-            }
+                this.logger.logSchema(`Executing MongoDB: ${statement}`);
+            await runMongoCommand(querier.db, statement);
         }
     }
     async executeSqlSyncStatements(statements, options, querier) {
         if (!isSqlQuerier(querier)) {
             throw new Error('Migrator requires a SQL-based querier for this dialect');
         }
-        await querier.beginTransaction();
         for (const sql of statements) {
             if (options.logging)
                 this.logger.logSchema(`Executing: ${sql}`);
             await querier.run(sql);
         }
-        await querier.commitTransaction();
     }
     /**
      * Get migration status

package/dist/migrate/schemaGenerator.d.ts

@@ -1,12 +1,12 @@
 import { type AbstractDialect, AbstractSqlDialect } from '../dialect/index.js';
 import type { CanonicalType, ColumnNode, ForeignKeyAction, IndexNode, TableNode } from '../schema/types.js';
-import type { ColumnSchema, DialectFeatures, EntityMeta, FieldOptions, IndexSchema, NamingStrategy, SchemaDiff, SchemaGenerator, Type } from '../type/index.js';
+import type { ColumnSchema, DialectFeatures, EntityMeta, FieldOptions, IndexSchema, NamingStrategy, SchemaDiff, SqlDdlGenerator, Type } from '../type/index.js';
 import type { FullColumnDefinition, TableDefinition, TableForeignKeyDefinition } from './builder/types.js';
 /**
  * Unified SQL schema generator.
  * Parameterized by dialect to handle Postgres, MySQL, MariaDB, and SQLite.
  */
-export declare class SqlSchemaGenerator implements SchemaGenerator {
+export declare class SqlSchemaGenerator implements SqlDdlGenerator {
     protected readonly dialect: AbstractSqlDialect;
     protected readonly defaultForeignKeyAction: ForeignKeyAction;
     constructor(dialect: AbstractSqlDialect, defaultForeignKeyAction?: ForeignKeyAction);
@@ -26,15 +26,14 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
      * Convert FieldOptions to CanonicalType using the unified type system.
      */
     protected getCanonicalType(field: FieldOptions, fieldType?: unknown): CanonicalType;
-    /**
-     * Convert CanonicalType to SQL type string for this dialect.
-     * Also handles legacy string types for backward compatibility.
-     */
-    protected canonicalTypeToSql(type: CanonicalType | string): string;
+    protected canonicalTypeToSql(type: CanonicalType): string;
     generateCreateTable<E>(entity: Type<E>, options?: {
         ifNotExists?: boolean;
     }): string[];
-    generateDropTable<E>(entity: Type<E>): string;
+    generateDropTable(tableName: string, options?: {
+        ifExists?: boolean;
+        cascade?: boolean;
+    }): string;
     generateAlterTable(diff: SchemaDiff): string[];
     generateAlterTableDown(diff: SchemaDiff): string[];
     generateCreateIndex(tableName: string, index: IndexSchema, options?: {
@@ -42,25 +41,24 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
     }): string;
     generateDropIndex(tableName: string, indexName: string): string;
     /**
-     * Generate column definition from a ColumnSchema object
+     * Generate a column definition from a {@link ColumnSchema}, whose type is the engine's own spelling
+     * and may already carry its precision (or even `PRIMARY KEY`, for a serial).
      */
     generateColumnDefinitionFromSchema(column: ColumnSchema, options?: {
         includePrimaryKey?: boolean;
         includeUnique?: boolean;
     }): string;
-    getSqlType(field: FieldOptions, fieldType?: unknown): string;
     /**
-     * Get the boolean type for this database
+     * The one place a column definition is spelled. Both callers reach it - the `ColumnSchema` path above
+     * and the `ColumnNode` path below - because the clause order and the "no NOT NULL on a primary key"
+     * rules are the same everywhere, and having them written twice is how the two paths drifted.
      */
-    getBooleanType(): string;
+    private renderColumn;
+    getSqlType(field: FieldOptions, fieldType?: unknown): string;
     /**
      * Generate ALTER COLUMN statements (database-specific)
      */
     generateAlterColumnStatements(tableName: string, column: ColumnSchema, newDefinition: string): string[];
-    /**
-     * Get table options (e.g., ENGINE for MySQL)
-     */
-    getTableOptions<E>(_meta: EntityMeta<E>): string;
     /**
      * Generate column comment clause (if supported)
      */
@@ -75,7 +73,8 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
     diffSchema<E>(entity: Type<E>, currentTable: TableNode | undefined): SchemaDiff | undefined;
     private columnNodeToSchema;
     /**
-     * Convert field options to ColumnSchema
+     * Convert field options to ColumnSchema. Both sides of a diff are the engine's SQL spelling: what it
+     * would create for this field, against what it reported for the existing column.
      */
     protected fieldToColumnSchema<E>(fieldKey: string, field: FieldOptions, meta: EntityMeta<E>): ColumnSchema;
     /**
@@ -83,7 +82,13 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
      */
     protected columnsNeedAlteration(current: ColumnSchema, desired: ColumnSchema): boolean;
     /**
-     * Compare two column types for equality using the canonical type system
+     * Whether two column types are the same *as this engine stores them*.
+     *
+     * Both sides are SQL spellings, parsed back to canonical so that `INT` and `INTEGER`, or `DATETIME`
+     * and `TIMESTAMP`, do not read as a change. Do not "simplify" this into comparing the entity's
+     * canonical type against the column's: several canonical types share one storage type per engine
+     * (`boolean` is `TINYINT(1)` on MySQL and `INTEGER` on SQLite), so that comparison reports an
+     * alteration for those columns on every single sync.
      */
     protected isTypeEqual(current: ColumnSchema, desired: ColumnSchema): boolean;
     /**
@@ -94,14 +99,10 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
         ifNotExists?: boolean;
     }): string[];
     /**
-     * Generate a column definition from a ColumnNode.
+     * Generate a column definition from a ColumnNode. A composite key is declared as a table constraint,
+     * so only a lone primary key column carries `PRIMARY KEY` inline.
      */
     protected generateColumnFromNode(col: ColumnNode): string;
-    /**
-     * Generate an inline VECTOR INDEX clause for use inside CREATE TABLE.
-     * Syntax: `VECTOR INDEX (col) M=n DISTANCE=metric`
-     */
-    private generateInlineVectorIndex;
     /**
      * Generate CREATE INDEX SQL from an IndexNode.
      * Delegates to `generateCreateIndex` for unified SQL assembly.
@@ -109,26 +110,14 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
     generateCreateIndexFromNode(index: IndexNode, options?: {
         ifNotExists: boolean;
     }): string;
-    /**
-     * Generate DROP TABLE SQL from a TableNode.
-     */
-    generateDropTableFromNode(table: TableNode, options?: {
-        ifExists?: boolean;
-    }): string;
     generateCreateTableFromDefinition(table: TableDefinition, options?: {
         ifNotExists?: boolean;
     }): string[];
-    generateDropTableSql(tableName: string, options?: {
-        ifExists?: boolean;
-        cascade?: boolean;
-    }): string;
     generateRenameTableSql(oldName: string, newName: string): string;
     generateAddColumnSql(tableName: string, column: FullColumnDefinition): string;
     generateAlterColumnSql(tableName: string, columnName: string, column: FullColumnDefinition): string;
     generateDropColumnSql(tableName: string, columnName: string): string;
     generateRenameColumnSql(tableName: string, oldName: string, newName: string): string;
-    generateCreateIndexSql(tableName: string, index: IndexSchema): string;
-    generateDropIndexSql(tableName: string, indexName: string): string;
     generateAddForeignKeySql(tableName: string, foreignKey: TableForeignKeyDefinition): string;
     generateDropForeignKeySql(tableName: string, constraintName: string): string;
     private tableDefinitionToNode;
@@ -138,4 +127,4 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
  * 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.
  */
-export declare function createSchemaGenerator(dialect: AbstractDialect, namingStrategy?: NamingStrategy, defaultForeignKeyAction?: ForeignKeyAction): SchemaGenerator | undefined;
+export declare function createSchemaGenerator(dialect: AbstractDialect, defaultForeignKeyAction?: ForeignKeyAction): SqlSchemaGenerator | undefined;