uql-orm 0.63.0 → 0.64.0

package/dist/migrate/migrator.js

@@ -3,16 +3,10 @@ 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 { isKnownMigratorDialect, isMongoQuerier, isSqlQuerier } from '../type/index.js';
 import { LoggerWrapper } from '../util/index.js';
-import { withMongoQuerierForMigrations, withSqlQuerierForMigrations } from './acquireQuerierForMigrations.js';
-import { MigrationBuilder } from './builder/migrationBuilder.js';
-import { buildMigrationModule, migrationSource, } from './codegen/migrationFile.js';
-import { runMongoCommand } from './generator/mongoCommand.js';
+import { buildMigrationModule } from './codegen/migrationFile.js';
 import { introspectorFor } from './introspection/registry.js';
-import { createSchemaGenerator } from './schemaGenerator.js';
-import { DatabaseMigrationStorage } from './storage/databaseStorage.js';
-import { MongoMigrationStorage } from './storage/mongoStorage.js';
+import { migrationBuilderFor, migrationTargetFor } from './migrationTarget.js';
 /**
  * Main class for managing database migrations
  */
@@ -32,55 +26,35 @@ export class Migrator {
         return this._entities ?? getEntities();
     }
     dialectName;
+    /** The generator given, or this dialect's once {@link getSchemaGenerator} has loaded it. */
     schemaGenerator;
     schemaIntrospector;
-    _defaultForeignKeyAction;
-    _mongoSchemaLoadPromise;
+    defaultForeignKeyAction;
+    target;
     constructor(pool, options = {}) {
         this.pool = pool;
         this.dialectName = pool.dialect.dialectName;
-        this._defaultForeignKeyAction = options.defaultForeignKeyAction;
-        this.storage =
-            options.storage ??
-                (this.dialectName === 'mongodb'
-                    ? new MongoMigrationStorage(pool, { tableName: options.tableName })
-                    : new DatabaseMigrationStorage(pool, { tableName: options.tableName }));
+        this.target = migrationTargetFor(pool.dialect);
+        this.defaultForeignKeyAction = options.defaultForeignKeyAction;
+        this.storage = options.storage ?? this.target.storage(pool, options.tableName);
         this.migrationsPath = options.migrationsPath ?? './migrations';
         this._logger = new LoggerWrapper(options.logger, { logValues: options.logValues, slowQuery: options.slowQuery });
         this._entities = options.entities;
         this.schemaIntrospector = this.createIntrospector();
-        this.schemaGenerator =
-            options.schemaGenerator ?? (this.dialectName === 'mongodb' ? undefined : this.createGenerator());
+        this.schemaGenerator = options.schemaGenerator;
     }
-    /**
-     * Loads MongoDB's schema generator on first use, so the optional `mongodb` peer loads only then. SQL
-     * generators are set in the constructor (or via {@link setSchemaGenerator}).
-     */
-    async ensureSchemaGenerator() {
-        if (this.schemaGenerator || this.dialectName !== 'mongodb') {
-            return;
+    /** The schema generator, loaded on first use: MongoDB's needs its optional peer. */
+    async getSchemaGenerator() {
+        this.schemaGenerator ??= await this.target.generator(this.pool.dialect, this.defaultForeignKeyAction);
+        if (!this.schemaGenerator) {
+            throw new TypeError(`No schema generator for dialect '${this.dialectName}'`);
         }
-        this._mongoSchemaLoadPromise ??= import('./generator/mongoSchemaGenerator.js').then(({ MongoSchemaGenerator }) => {
-            this.schemaGenerator = new MongoSchemaGenerator(this.pool.dialect.namingStrategy, this._defaultForeignKeyAction);
-        });
-        await this._mongoSchemaLoadPromise;
-    }
-    /**
-     * Set the schema generator for DDL operations
-     */
-    setSchemaGenerator(generator) {
-        this.schemaGenerator = generator;
+        return this.schemaGenerator;
     }
     /** `schema` reads one namespace instead of the connection's own; see {@link BaseSqlIntrospector.schema}. */
     createIntrospector(schema) {
         return introspectorFor(this.dialectName, this.pool, schema);
     }
-    createGenerator() {
-        if (!isKnownMigratorDialect(this.dialectName)) {
-            return undefined;
-        }
-        return createSchemaGenerator(this.pool.dialect, this._defaultForeignKeyAction);
-    }
     /**
      * Get all discovered migrations from the migrations directory
      */
@@ -159,10 +133,10 @@ export class Migrator {
      */
     async runMigration(migration, direction) {
         const startTime = Date.now();
-        return this.withMigrationQuerier(async (querier, inTransaction) => {
+        return this.target.withSession(this.pool, async ({ querier, transaction }) => {
             try {
                 this.logger.logMigration(`${direction === 'up' ? 'Running' : 'Reverting'} migration: ${migration.name}`);
-                await inTransaction(async () => {
+                await transaction(async () => {
                     if (direction === 'up') {
                         await migration.up(querier);
                         await this.storage.logWithQuerier(querier, migration.name);
@@ -194,25 +168,11 @@ export class Migrator {
             }
         });
     }
-    /**
-     * A migration querier, and how to run work in one transaction on it. MongoDB gets none: it creates
-     * collections and indexes outside any transaction. SQL asserts its querier before opening one, so a
-     * wrong querier reports which one the dialect needs rather than a missing `transaction`.
-     */
-    withMigrationQuerier(task) {
-        return this.dialectName === 'mongodb'
-            ? withMongoQuerierForMigrations(this.pool, 'Migrator', (querier) => task(querier, (work) => work()))
-            : withSqlQuerierForMigrations(this.pool, 'Migrator', (querier) => task(querier, (work) => querier.transaction(work)));
-    }
-    /** What this dialect's migration files are written against. */
-    get migrationQuerier() {
-        return this.dialectName === 'mongodb' ? 'MongoQuerier' : 'SqlQuerier';
-    }
     /**
      * Generate a new migration file
      */
     async generate(name) {
-        const { emptyUp, emptyDown } = migrationSource[this.migrationQuerier];
+        const { emptyUp, emptyDown } = this.target.source;
         const filePath = await this.writeMigration(name, { upInner: emptyUp, downInner: emptyDown });
         this.logger.logInfo(`Created migration: ${filePath}`);
         return filePath;
@@ -223,7 +183,7 @@ export class Migrator {
         const content = buildMigrationModule({
             migrationName: name,
             createdAt: new Date(),
-            querier: this.migrationQuerier,
+            querier: this.target.source.querier,
             ...body,
         });
         await mkdir(this.migrationsPath, { recursive: true });
@@ -234,31 +194,25 @@ export class Migrator {
      * Generate a migration based on entity schema differences
      */
     async generateFromEntities(name) {
-        const creating = [];
-        const altering = [];
-        const downStatements = [];
-        for (const { diff, entity } of await this.pendingDiffs()) {
-            if (diff.type === 'create') {
-                if (entity) {
-                    creating.push(diff.tableName);
-                    downStatements.push(this.generator.generateDropTable(diff.tableName, { ifExists: true }));
-                }
-            }
-            else if (diff.type === 'alter') {
-                altering.push(...this.generator.generateAlterTable(diff));
-                downStatements.push(...this.generator.generateAlterTableDown(diff));
-            }
-        }
-        const upStatements = [...this.createSchema(creating), ...altering];
-        if (upStatements.length === 0) {
+        const generator = await this.getSchemaGenerator();
+        const { created, altered } = await this.pendingChanges();
+        const up = [
+            ...this.createSchema(generator, created),
+            ...altered.flatMap((diff) => generator.generateAlterTable(diff)),
+        ];
+        if (up.length === 0) {
             this.logger.logInfo('No schema changes detected.');
             return '';
         }
-        const { emit } = migrationSource[this.migrationQuerier];
+        const down = [
+            ...created.map((tableName) => generator.generateDropTable(tableName, { ifExists: true })),
+            ...altered.flatMap((diff) => generator.generateAlterTableDown(diff)),
+        ];
+        const { emit } = this.target.source;
         const filePath = await this.writeMigration(name, {
             docExtraLines: ['Generated from entity definitions'],
-            upInner: emit(upStatements),
-            downInner: emit([...downStatements].reverse()),
+            upInner: emit(up),
+            downInner: emit(down.reverse()),
         });
         this.logger.logInfo(`Created migration from entities: ${filePath}`);
         return filePath;
@@ -267,26 +221,20 @@ export class Migrator {
      * Get all schema differences between entities and database
      */
     async getDiffs() {
-        await this.ensureSchemaGenerator();
-        if (!this.schemaGenerator || !this.schemaIntrospector) {
-            throw new TypeError('Schema generator and introspector must be set');
+        const generator = await this.getSchemaGenerator();
+        if (!this.schemaIntrospector) {
+            throw new TypeError(`No introspector for dialect '${this.dialectName}'`);
         }
         const ast = await this.introspectClaimedSchemas();
         // 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.
-        const desiredAst = this.schemaGenerator.buildAST?.(this.entities);
-        const diffs = [];
-        for (const entity of this.entities) {
-            const meta = getMeta(entity);
-            const tableName = this.schemaGenerator.resolveTableName(meta);
-            const currentTable = ast.getTable(tableName);
-            const diff = this.schemaGenerator.diffSchema(entity, currentTable, desiredAst);
-            if (diff) {
-                diffs.push(diff);
-            }
-        }
-        return diffs;
+        const desiredAst = generator.buildAST?.(this.entities);
+        return this.entities.flatMap((entity) => {
+            const table = ast.getTable(generator.resolveTableName(getMeta(entity)));
+            const diff = generator.diffSchema(entity, table, desiredAst);
+            return diff ? [diff] : [];
+        });
     }
     /**
      * One AST spanning every schema the entities claim, each table stamped with the schema it was read
@@ -309,17 +257,6 @@ export class Migrator {
         }
         return merged;
     }
-    async findEntityForTable(tableName) {
-        await this.ensureSchemaGenerator();
-        for (const entity of this.entities) {
-            const meta = getMeta(entity);
-            const name = this.generator.resolveTableName(meta);
-            if (name === tableName) {
-                return entity;
-            }
-        }
-        return undefined;
-    }
     /**
      * Applies the entity schema to the database: every registered entity, or the one `entity` names.
      *
@@ -344,10 +281,10 @@ export class Migrator {
      * 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.
      */
-    forceStatements() {
+    forceStatements(generator) {
         return [
-            ...this.generator.generateDropSchema(this.entities, { ifExists: true, cascade: true }),
-            ...this.generator.generateCreateSchema(this.entities),
+            ...generator.generateDropSchema(this.entities, { ifExists: true, cascade: true }),
+            ...generator.generateCreateSchema(this.entities),
         ];
     }
     /**
@@ -355,32 +292,26 @@ export class Migrator {
      * existence check and is created with `IF NOT EXISTS`, so instances racing the same admin save
      * settle instead of colliding; an existing one still pays for introspection, as a diff needs columns.
      */
-    async planEntity(entity, options) {
+    async planEntity(generator, entity, options) {
         const meta = getMeta(entity);
-        // Before anything reads `this.generator`, whose own failure names neither the entity nor the
-        // dialect that has no support.
         const introspector = this.introspectorFor(this.pool.dialect.resolveSchema(meta));
         if (!introspector) {
             throw new TypeError(`No introspector for '${meta.entity.name}' on '${this.dialectName}'`);
         }
-        const tableName = this.generator.resolveTableName(meta);
+        const tableName = generator.resolveTableName(meta);
         return (await introspector.tableExists(tableName))
-            ? this.alterFromEntity(entity, (await introspectSchema(introspector)).getTable(tableName), options)
+            ? 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.
-                this.generator.generateCreateSchema(this.entitiesWith(entity), { only: [tableName], ifNotExists: true });
-    }
-    /** An alter diff as statements, narrowed to what the caller allows. */
-    alterFromDiff(diff, options) {
-        return this.generator.generateAlterTable(this.filterDiff(diff, options));
+                generator.generateCreateSchema(this.entitiesWith(entity), { only: [tableName], ifNotExists: true });
     }
     /** The same for one entity against the table it already has, and nothing where the two agree. */
-    alterFromEntity(entity, table, options) {
+    alterFromEntity(generator, entity, table, options) {
         // Spanning the set for the reason `planEntity` spells out: a foreign key needs the table it
         // points at, which a sync of one entity outside the configured list would not otherwise have.
-        const diff = this.generator.diffSchema(entity, table, this.generator.buildAST?.(this.entitiesWith(entity)));
-        return diff?.type === 'alter' ? this.alterFromDiff(diff, options) : [];
+        const diff = generator.diffSchema(entity, table, generator.buildAST?.(this.entitiesWith(entity)));
+        return diff?.type === 'alter' ? generator.generateAlterTable(this.filterDiff(diff, options)) : [];
     }
     /** The configured entities, with `entity` among them however the migrator was built. */
     entitiesWith(entity) {
@@ -396,25 +327,18 @@ export class Migrator {
      * statements rather than a summary of a second, differently-computed diff.
      */
     async planSync(options = {}) {
-        await this.ensureSchemaGenerator();
+        const generator = await this.getSchemaGenerator();
         if (options.force) {
-            return this.forceStatements();
+            return this.forceStatements(generator);
         }
         if (options.entity) {
-            return this.planEntity(options.entity, options);
+            return this.planEntity(generator, options.entity, options);
         }
-        const creating = [];
-        const altering = [];
-        for (const { diff, entity } of await this.pendingDiffs()) {
-            if (diff.type === 'create') {
-                if (entity)
-                    creating.push(diff.tableName);
-            }
-            else if (diff.type === 'alter') {
-                altering.push(...this.alterFromDiff(diff, options));
-            }
-        }
-        return [...this.createSchema(creating), ...altering];
+        const { created, altered } = await this.pendingChanges();
+        return [
+            ...this.createSchema(generator, created),
+            ...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
@@ -424,31 +348,20 @@ export class Migrator {
      *
      * Empty in, empty out, so a diff with no new tables does not build an AST for the whole graph.
      */
-    createSchema(tableNames) {
-        return tableNames.length ? this.generator.generateCreateSchema(this.entities, { only: tableNames }) : [];
+    createSchema(generator, tableNames) {
+        return tableNames.length ? generator.generateCreateSchema(this.entities, { only: tableNames }) : [];
     }
     /**
-     * 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.
+     * The pending diffs a sync or a generated migration acts on: the tables to create and the tables to
+     * alter. What to emit for each stays with the caller: a sync narrows an alter to what it allows and
+     * never asks for the rollback, which on SQLite cannot even be expressed (no `ALTER COLUMN`).
      */
-    async pendingDiffs() {
+    async pendingChanges() {
         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 TypeError('Schema generator not set. Call setSchemaGenerator() first.');
-        }
-        return this.schemaGenerator;
+        return {
+            created: diffs.filter((diff) => diff.type === 'create').map((diff) => diff.tableName),
+            altered: diffs.filter((diff) => diff.type === 'alter'),
+        };
     }
     filterDiff(diff, options) {
         const filteredDiff = { ...diff };
@@ -484,30 +397,18 @@ export class Migrator {
         }
         return filteredDiff;
     }
+    /** Runs the statements a generator wrote, in one transaction where the engine takes DDL in one. */
     async executeSyncStatements(statements, options) {
-        await this.withMigrationQuerier((querier, inTransaction) => inTransaction(() => isMongoQuerier(querier)
-            ? this.executeMongoSyncStatements(statements, options, querier)
-            : this.executeSqlSyncStatements(statements, options, querier)));
+        await this.target.withSession(this.pool, ({ run, transaction }) => transaction(async () => {
+            for (const statement of statements) {
+                if (options.logging)
+                    this.logger.logSchema(`Executing: ${statement}`);
+                await run(statement);
+            }
+        }));
         if (options.logging)
             this.logger.logSchema('Schema synchronization completed');
     }
-    async executeMongoSyncStatements(statements, options, querier) {
-        for (const statement of statements) {
-            if (options.logging)
-                this.logger.logSchema(`Executing MongoDB: ${statement}`);
-            await runMongoCommand(querier.db, statement);
-        }
-    }
-    async executeSqlSyncStatements(statements, options, querier) {
-        if (!isSqlQuerier(querier)) {
-            throw new TypeError('Migrator requires a SQL-based querier for this dialect');
-        }
-        for (const sql of statements) {
-            if (options.logging)
-                this.logger.logSchema(`Executing: ${sql}`);
-            await querier.run(sql);
-        }
-    }
     /**
      * Get migration status
      */
@@ -625,7 +526,7 @@ export function defineMigration(migration) {
 export function defineBuilderMigration(migration) {
     return {
         ...migration,
-        up: (querier) => migration.up(new MigrationBuilder(querier), querier),
-        down: (querier) => migration.down(new MigrationBuilder(querier), querier),
+        up: async (querier) => migration.up(await migrationBuilderFor(querier), querier),
+        down: async (querier) => migration.down(await migrationBuilderFor(querier), querier),
     };
 }

package/dist/migrate/schemaGenerator.d.ts

@@ -2,14 +2,14 @@ import type { AbstractSqlDialect } from '../dialect/index.js';
 import type { SchemaAST } from '../schema/schemaAST.js';
 import { type DiffOptions } from '../schema/schemaASTDiffer.js';
 import type { CanonicalType, ColumnNode, ForeignKeyAction, IndexNode, TableNode } from '../schema/types.js';
-import type { ColumnSchema, CreateSchemaOptions, DialectFeatures, DropSchemaOptions, EntityMeta, EntityWhereMeta, FieldMeta, FieldOptions, ForeignKeySchema, IndexSchema, MigratorDialect, NamingStrategy, SchemaDiff, SchemaGenerator, SqlDdlGenerator, Type } from '../type/index.js';
-import type { FullColumnDefinition, IndexDefinition, TableDefinition } from './builder/types.js';
+import type { ColumnSchema, CreateSchemaOptions, DialectFeatures, DropSchemaOptions, EntityMeta, EntityWhereMeta, FieldMeta, FieldOptions, ForeignKeySchema, IndexSchema, MigratorDialect, NamingStrategy, SchemaDiff, SchemaGenerator, Type } from '../type/index.js';
+import type { AnyMigrationOperation, FullColumnDefinition, IndexDefinition, TableDefinition } from './builder/types.js';
 import { type IndexDdl, type TableDdl } from './ddl/index.js';
 /**
  * Unified SQL schema generator.
  * Parameterized by dialect to handle Postgres, MySQL, MariaDB, and SQLite.
  */
-export declare class SqlSchemaGenerator implements SqlDdlGenerator {
+export declare class SqlSchemaGenerator implements SchemaGenerator {
     protected readonly dialect: AbstractSqlDialect;
     protected readonly defaultForeignKeyAction: ForeignKeyAction;
     /** `CREATE INDEX` for this dialect: the migrator's, so a runtime import carries none of it. */
@@ -24,6 +24,7 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
     resolveSchema<E>(meta: EntityMeta<E>): string | undefined;
     resolveColumnName(key: string, field: FieldOptions): string;
     compileDdl(sql: EntityWhereMeta<object>, entity: Type<object>): string;
+    compileIndexPredicate(where: EntityWhereMeta<object>, entity: Type<object>, indexName: string): string;
     /** Escape an identifier (table name, column name, etc.) */
     protected escapeId(identifier: string): string;
     /**
@@ -168,17 +169,18 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
     }): string[];
     generateCreateIndexFromDefinition(tableName: string, index: IndexDefinition): string;
     generateRenameTableSql(oldName: string, newName: string): string;
+    /** `raw` is split, being the one SQL no generator wrote. */
+    generateOperation(operation: AnyMigrationOperation): string[];
     /**
      * `ADD COLUMN`, plus the constraint and index the column declares.
      *
      * `CREATE TABLE` lifts a column's `references` and `index` onto the table it is building; this had
      * no lift, so a hand-written `addColumn(...).references(...).index()` emitted the column alone and
-     * dropped both without a word. Several statements in one string is what `generateAlterColumnSql`
-     * already returns, and `execute` splits them.
+     * dropped both without a word.
      */
-    generateAddColumnSql(tableName: string, column: FullColumnDefinition): string;
-    generateAlterColumnSql(tableName: string, columnName: string, column: FullColumnDefinition): string;
-    generateDropColumnSql(tableName: string, columnName: 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;
     /**
      * `CONSTRAINT <name> FOREIGN KEY (...) REFERENCES ... ON DELETE ... ON UPDATE ...`.
@@ -219,9 +221,6 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
  * 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, 'resolveTableAlias' | 'resolveSchema' | 'resolveColumnName' | 'compileDdl'>, entities: readonly Type<object>[], 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.
- */
+export declare function buildEntityAST(generator: Pick<SchemaGenerator, 'resolveTableAlias' | 'resolveSchema' | 'resolveColumnName' | 'compileDdl' | 'compileIndexPredicate'>, entities: readonly Type<object>[], defaultForeignKeyAction?: ForeignKeyAction): SchemaAST;
+/** The SQL schema generator for `dialect`, `undefined` on MongoDB, whose generator needs its optional peer. */
 export declare function createSchemaGenerator(dialect: MigratorDialect, defaultForeignKeyAction?: ForeignKeyAction): SqlSchemaGenerator | undefined;

package/dist/migrate/schemaGenerator.js

@@ -6,10 +6,12 @@ import { diffRelationshipNodes, diffTable } from '../schema/schemaASTDiffer.js';
 import { isAutoIncrement, qualifyName } from '../util/index.js';
 import { derivedCheckName, derivedForeignKeyName, derivedPrimaryKeyName } from '../util/sql.util.js';
 import { formatDefaultValue, SqlExpression } from './builder/expressions.js';
+import { splitSqlStatements } from './builder/splitSqlStatements.js';
 import { indexDdlFor, tableDdlFor } from './ddl/index.js';
 import { sizedType } from './ddl/tableDdl.js';
 import { columnForeignKey, columnIndex, fullColumnDefinitionToNode, renderIndexDefinition, tableDefinitionToNode, } from './generator/definitionToNode.js';
 import { indexNodeToSchema } from './generator/indexNodeToSchema.js';
+import { assertIndexPredicate } from './indexPredicate.js';
 /**
  * Unified SQL schema generator.
  * Parameterized by dialect to handle Postgres, MySQL, MariaDB, and SQLite.
@@ -48,6 +50,10 @@ export class SqlSchemaGenerator {
     compileDdl(sql, entity) {
         return this.dialect.compileDdl(sql, entity);
     }
+    compileIndexPredicate(where, entity, indexName) {
+        assertIndexPredicate(where, this.dialect.dialectName, indexName);
+        return this.dialect.compileDdl(where, entity);
+    }
     /** Escape an identifier (table name, column name, etc.) */
     escapeId(identifier) {
         return this.dialect.escapeId(identifier);
@@ -577,13 +583,43 @@ export class SqlSchemaGenerator {
     generateRenameTableSql(oldName, newName) {
         return this.tableDdl.renameTable(oldName, newName);
     }
+    /** `raw` is split, being the one SQL no generator wrote. */
+    generateOperation(operation) {
+        switch (operation.type) {
+            case 'createTable':
+                return this.generateCreateTableFromDefinition(operation.table);
+            case 'dropTable':
+                return [
+                    this.generateDropTable(operation.tableName, { ifExists: operation.ifExists, cascade: operation.cascade }),
+                ];
+            case 'renameTable':
+                return [this.generateRenameTableSql(operation.oldName, operation.newName)];
+            case 'addColumn':
+                return this.generateAddColumnSql(operation.tableName, operation.column);
+            case 'dropColumn':
+                return this.generateDropColumnSql(operation.tableName, operation.columnName);
+            case 'renameColumn':
+                return [this.generateRenameColumnSql(operation.tableName, operation.oldName, operation.newName)];
+            case 'alterColumn':
+                return this.generateAlterColumnSql(operation.tableName, operation.columnName, operation.changes);
+            case 'createIndex':
+                return [this.generateCreateIndexFromDefinition(operation.tableName, operation.index)];
+            case 'dropIndex':
+                return [this.generateDropIndex(operation.tableName, operation.indexName)];
+            case 'addForeignKey':
+                return [this.generateAddForeignKeySql(operation.tableName, operation.foreignKey)];
+            case 'dropForeignKey':
+                return [this.generateDropForeignKeySql(operation.tableName, operation.constraintName)];
+            case 'raw':
+                return splitSqlStatements(operation.sql);
+        }
+    }
     /**
      * `ADD COLUMN`, plus the constraint and index the column declares.
      *
      * `CREATE TABLE` lifts a column's `references` and `index` onto the table it is building; this had
      * no lift, so a hand-written `addColumn(...).references(...).index()` emitted the column alone and
-     * dropped both without a word. Several statements in one string is what `generateAlterColumnSql`
-     * already returns, and `execute` splits them.
+     * dropped both without a word.
      */
     generateAddColumnSql(tableName, column) {
         this.assertColumnAddable(tableName, column);
@@ -598,14 +634,14 @@ export class SqlSchemaGenerator {
             statements.push(this.generateCreateIndex(tableName, index));
         }
         statements.push(...this.generateColumnCommentStatement(tableName, column));
-        return statements.join('\n');
+        return statements;
     }
     generateAlterColumnSql(tableName, columnName, column) {
         const node = fullColumnDefinitionToNode(column, tableName);
-        return this.generateAlterColumnStatements(tableName, { ...this.columnNodeToSchema(node), name: columnName }, this.generateColumnFromNode(node)).join('\n');
+        return this.generateAlterColumnStatements(tableName, { ...this.columnNodeToSchema(node), name: columnName }, this.generateColumnFromNode(node));
     }
     generateDropColumnSql(tableName, columnName) {
-        return this.tableDdl.dropColumn(tableName, columnName).join('\n');
+        return this.tableDdl.dropColumn(tableName, columnName);
     }
     generateRenameColumnSql(tableName, oldName, newName) {
         return this.tableDdl.renameColumn(tableName, oldName, newName);
@@ -726,13 +762,11 @@ export function buildEntityAST(generator, entities, defaultForeignKeyAction) {
         resolveSchema: (meta) => generator.resolveSchema(meta),
         resolveColumnName: (key, field) => generator.resolveColumnName(key, field),
         compileDdl: (sql, entity) => generator.compileDdl(sql, entity),
+        compileIndexPredicate: (where, entity, indexName) => generator.compileIndexPredicate(where, entity, indexName),
         defaultForeignKeyAction,
     });
 }
-/**
- * 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.
- */
+/** The SQL schema generator for `dialect`, `undefined` on MongoDB, whose generator needs its optional peer. */
 export function createSchemaGenerator(dialect, defaultForeignKeyAction) {
     return dialect.dialectName === 'mongodb' ? undefined : new SqlSchemaGenerator(dialect, defaultForeignKeyAction);
 }

package/dist/mongo/mongoDialect.d.ts

@@ -10,6 +10,11 @@ type MongoReadStages = {
     /** Keys merged into the query's projection, when it has one: a vector search's score. */
     readonly project?: Record<string, 1>;
 };
+/** Accumulator threaded through `$where` rendering: the relation lookups it needs, and their temp fields. */
+type RelationLookups = {
+    readonly stages: MongoAggregationPipelineEntry<Document>[];
+    readonly temps: string[];
+};
 /** Default {@link DialectFeatures} for MongoDB; shared by {@link MongoDialect} and its schema generator. */
 export declare const mongoDialectFeatures: DialectFeatures;
 export declare class MongoDialect extends AbstractDialect {
@@ -46,7 +51,7 @@ export declare class MongoDialect extends AbstractDialect {
      * recursion). Relation keys need `$lookup` stages, so they are only accepted when `lookups` is
      * given - a plain `find`/`updateMany` filter has nowhere to put them.
      */
-    private renderFilter;
+    protected renderFilter<E extends Document>(entity: Type<E>, where?: QueryWhere<E>, lookups?: RelationLookups): Filter<E>;
     /**
      * Renders `$and`/`$or`/`$not`/`$nor` into `filter`. MongoDB has no root-level `$not`, so both
      * negating operators become its `$nor`, which is exactly `NOT (a OR b)` - and by De Morgan that

package/dist/schema/schemaASTBuilder.d.ts

@@ -29,6 +29,8 @@ export interface BuildSchemaASTOptions {
      * predicate - which only a dialect can render. `buildEntityAST` supplies it from the generator.
      */
     compileDdl?: (sql: EntityWhereMeta<object>, entity: Type<object>) => string;
+    /** A partial index's predicate as the engine writes it, `compileDdl` where none is given. `buildEntityAST` supplies it. */
+    compileIndexPredicate?: (where: EntityWhereMeta<object>, entity: Type<object>, indexName: string) => string;
 }
 /**
  * Build a SchemaAST from entity classes (decorated with `@Entity`, `@Field`, etc.).