uql-orm 0.56.0 → 0.57.0

package/dist/dialect/queryJoins.d.ts

@@ -1,5 +1,4 @@
-import type { EntityMeta, Query, QuerySortMap, RelationMeta, Type } from '../type/index.js';
-import { type RelationQuery } from '../util/index.js';
+import type { EntityMeta, Query, QuerySortMap, RelationMeta, RelationQuery, Type } from '../type/index.js';
 /**
  * One relation a statement joins, keyed by the alias its columns are addressed by (`tax`,
  * `tax.category`). `projected` tells a `$populate` join, whose columns are selected, from one only
@@ -8,8 +7,10 @@ import { type RelationQuery } from '../util/index.js';
 export type QueryJoin = {
     /** The relation key on its parent, which is how MongoDB names the field a `$lookup` adds. */
     readonly key: string;
-    /** Dotted path from the queried entity, which is how the SQL dialects alias the join. */
+    /** Dotted path from the queried entity, which is what a joined row's columns answer under. */
     readonly path: string;
+    /** The alias the statement reads it through: its path, unless another table of the statement took it. */
+    readonly alias: string;
     readonly entity: Type<object>;
     readonly meta: EntityMeta<object>;
     readonly relation: RelationMeta;
@@ -38,14 +39,17 @@ export type QuerySortOptions = {
  * related column needs that relation joined just as much as selecting it does. The two sources meet
  * here, so the columns, the `ORDER BY` and the row lock cannot disagree about what is in the
  * statement. `$sort` contributes to-one relations only; the rest is rejected where it is rendered.
+ * `claimAlias` names each join's table, parents first.
  */
-export declare function resolveQueryJoins<E>(meta: EntityMeta<E>, q: Query<E>): QueryJoins;
+export declare function resolveQueryJoins<E>(meta: EntityMeta<E>, q: Query<E>, claimAlias?: (path: string) => string): QueryJoins;
 /**
  * Whether a join drops parents that have no match, which is the one thing a join does to *how many*
  * rows a read returns rather than how wide they are. A count that skips the joins has to be told, or
  * it counts the parents the read will never hand back.
  */
 export declare function hasRequiredJoin<E>(meta: EntityMeta<E>, q: Query<E>): boolean;
+/** Whether a statement aggregates a relation's rows: a to-many off its own row, or off a row it joins. */
+export declare function aggregatesRelations<E>(meta: EntityMeta<E>, q: Query<E>): boolean;
 /**
  * The join an ordering may address at `path`, with the relation's own sort map, or why it may not.
  * Every backend answers this the same way - a to-many has no single value to order by, a relation

package/dist/dialect/queryJoins.js

@@ -1,19 +1,20 @@
 import { getMeta, relationOf } from '../entity/index.js';
-import { getKeys, getRelationRequestSummary, isToManyRelation, parseRelationAtKey, } from '../util/index.js';
+import { getKeys, getRelationRequestSummary, isToManyRelation, parseRelationAtKey } from '../util/index.js';
 export const NO_JOINS = new Map();
 /**
  * What the statement joins, from the whole query rather than from `$populate` alone: ordering by a
  * related column needs that relation joined just as much as selecting it does. The two sources meet
  * here, so the columns, the `ORDER BY` and the row lock cannot disagree about what is in the
  * statement. `$sort` contributes to-one relations only; the rest is rejected where it is rendered.
+ * `claimAlias` names each join's table, parents first.
  */
-export function resolveQueryJoins(meta, q) {
+export function resolveQueryJoins(meta, q, claimAlias = (path) => path) {
     if (!q.$populate && !q.$sort) {
         return NO_JOINS;
     }
     const joins = new Map();
-    addPopulateJoins(joins, meta, q.$populate);
-    addSortJoins(joins, meta, q.$sort);
+    addPopulateJoins(joins, claimAlias, meta, q.$populate);
+    addSortJoins(joins, claimAlias, meta, q.$sort);
     return joins;
 }
 /**
@@ -29,7 +30,19 @@ export function hasRequiredJoin(meta, q) {
     }
     return false;
 }
-function addJoin(joins, parent, key, relation, query, required, projected) {
+/** Whether a statement aggregates a relation's rows: a to-many off its own row, or off a row it joins. */
+export function aggregatesRelations(meta, q) {
+    if (getRelationRequestSummary(meta, q.$populate).toManyKeys.length) {
+        return true;
+    }
+    for (const join of resolveQueryJoins(meta, q).values()) {
+        if (getRelationRequestSummary(join.meta, join.query.$populate).toManyKeys.length) {
+            return true;
+        }
+    }
+    return false;
+}
+function addJoin(joins, claimAlias, parent, key, relation, query, required, projected) {
     const path = parent ? `${parent.path}.${key}` : key;
     const existing = joins.get(path);
     // `$populate` runs first, so an already-joined relation keeps its columns and its `$required`
@@ -41,6 +54,7 @@ function addJoin(joins, parent, key, relation, query, required, projected) {
     const join = {
         key,
         path,
+        alias: claimAlias(path),
         entity,
         meta: getMeta(entity),
         relation,
@@ -52,15 +66,15 @@ function addJoin(joins, parent, key, relation, query, required, projected) {
     joins.set(path, join);
     return join;
 }
-function addPopulateJoins(joins, meta, populate, parent) {
+function addPopulateJoins(joins, claimAlias, meta, populate, parent) {
     for (const key of getRelationRequestSummary(meta, populate).joinableKeys) {
         const relation = relationOf(meta, key);
         const { query, required } = parseRelationAtKey(key, populate);
-        const join = addJoin(joins, parent, key, relation, query, required, true);
-        addPopulateJoins(joins, join.meta, query.$populate, join);
+        const join = addJoin(joins, claimAlias, parent, key, relation, query, required, true);
+        addPopulateJoins(joins, claimAlias, join.meta, query.$populate, join);
     }
 }
-function addSortJoins(joins, meta, sort, parent) {
+function addSortJoins(joins, claimAlias, meta, sort, parent) {
     if (!sort) {
         return;
     }
@@ -72,8 +86,8 @@ function addSortJoins(joins, meta, sort, parent) {
         if (!relation || isToManyRelation(relation) || !isSortMap(value)) {
             continue;
         }
-        const join = addJoin(joins, parent, key, relation, {}, false, false);
-        addSortJoins(joins, join.meta, value, join);
+        const join = addJoin(joins, claimAlias, parent, key, relation, {}, false, false);
+        addSortJoins(joins, claimAlias, join.meta, value, join);
     }
 }
 /**

package/dist/dialect/vectorSqlDialect.d.ts

@@ -78,8 +78,8 @@ export declare abstract class VectorSqlDialect extends AbstractDialect {
      */
     supportedVectorType(cast: VectorCast): VectorCast;
     /**
-     * Append a vector distance projection.
-     * Delegates to `appendVectorSort` so each dialect's distance syntax is written once.
+     * The distance a vector `$sort` projects, which the projection names after `$project`. Delegates to
+     * `appendVectorSort` so each dialect's distance syntax is written once.
      */
     protected appendVectorProjection<E>(ctx: QueryContext, meta: EntityMeta<E>, key: string, search: QueryVectorSearch): void;
     /**

package/dist/dialect/vectorSqlDialect.js

@@ -96,8 +96,8 @@ export class VectorSqlDialect extends AbstractDialect {
         return this.hasNarrowVectorTypes ? cast : 'vector';
     }
     /**
-     * Append a vector distance projection.
-     * Delegates to `appendVectorSort` so each dialect's distance syntax is written once.
+     * The distance a vector `$sort` projects, which the projection names after `$project`. Delegates to
+     * `appendVectorSort` so each dialect's distance syntax is written once.
      */
     appendVectorProjection(ctx, meta, key, search) {
         const alias = search.$project;
@@ -108,7 +108,6 @@ export class VectorSqlDialect extends AbstractDialect {
             throw new TypeError(`$project '${alias}' collides with a field of '${entityName(meta)}'`);
         }
         this.appendVectorSort(ctx, meta, key, search);
-        ctx.append(` AS ${this.escapeId(alias)}`);
     }
     /**
      * The distance expression, in whichever of the two shapes this dialect spells it. One method for

package/dist/entity/metadata/definition.js

@@ -337,9 +337,9 @@ function fillRelations(meta) {
 function fillOwningSide(at, meta, relKey, relOpts) {
     const relMeta = ensureMeta(relOpts.entity());
     if (relOpts.through) {
-        // Both columns live on the junction, whatever the cardinality: `fillToManyThroughRelation`,
-        // `deleteRelations` and every dialect read them as junction columns. A composite key contributes
-        // one pair per column of it, which is what makes the join address a whole key rather than part.
+        // Both columns live on the junction, whatever the cardinality: `deleteRelations` and every dialect
+        // read them as junction columns. A composite key contributes one pair per column of it, which is
+        // what makes the join address a whole key rather than part.
         relOpts.references = [
             ...meta.ids.map((key) => ({ local: junctionColumn(meta, key), foreign: key })),
             ...relMeta.ids.map((key) => ({ local: junctionColumn(relMeta, key), foreign: key })),

package/dist/maria/mariaDialect.d.ts

@@ -1,5 +1,6 @@
+import { type RelationRows } from '../dialect/abstractSqlDialect.js';
 import { MysqlLikeSqlDialect } from '../dialect/mysqlLikeSqlDialect.js';
-import type { DialectFeatures, EntityMeta, FieldOptions, Query, QueryContext, QueryOptions, Type, VectorDistance, VectorMetric } from '../type/index.js';
+import type { DialectFeatures, EntityMeta, FieldOptions, Query, QueryContext, Type, VectorDistance, VectorMetric } from '../type/index.js';
 export declare class MariaDialect extends MysqlLikeSqlDialect {
     readonly dialectName = "mariadb";
     readonly insertIdSource = "returning";
@@ -10,6 +11,11 @@ export declare class MariaDialect extends MysqlLikeSqlDialect {
      * and `CREATE INDEX` takes `IF NOT EXISTS` - which MySQL's grammar has no place for.
      */
     protected readonly featureOverrides: Partial<DialectFeatures>;
+    /**
+     * A derived table here reads no column of the statement around it, so the aggregate reads the
+     * related table itself, and orders and pages inside `JSON_ARRAYAGG`, which takes both.
+     */
+    protected appendRelationArray(ctx: QueryContext, { entity, query, alias, joins }: RelationRows): void;
     protected upsertReturning<E>(meta: EntityMeta<E>): string;
     /**
      * MariaDB supports neither MySQL's `->`/`->>` shorthand nor the base's chained form. `JSON_VALUE`
@@ -36,12 +42,13 @@ export declare class MariaDialect extends MysqlLikeSqlDialect {
      */
     protected appendVectorValue(ctx: QueryContext, value: readonly unknown[]): void;
     /**
-     * `SET STATEMENT mhnsw_ef_search=N FOR SELECT ...` - MariaDB scopes a variable to one statement, so
-     * the tuning needs neither a transaction nor a restore afterwards, and cannot leak to the next
-     * query on this pooled connection. That is why it prefixes the SQL here instead of coming back
-     * from `vectorTuningStatements`, which is Postgres's `SET LOCAL` shape.
+     * `mhnsw_ef_search` too, where a vector search is tuned. A setting scoped to one statement needs
+     * neither a transaction nor a restore, and cannot leak to the next query on this pooled connection,
+     * which is why the tuning is not `vectorTuningStatements`, Postgres's `SET LOCAL` shape.
      */
-    find<E>(ctx: QueryContext, entity: Type<E>, q?: Query<E>, opts?: QueryOptions, totalAlias?: string): void;
+    protected statementSettings<E>(entity: Type<E>, q: Query<E>): string[];
+    /** `SET STATEMENT ... FOR`, which scopes a variable to the statement it prefixes. */
+    protected applySettings(sql: string, settings: readonly string[]): string;
     /** The reverse: selecting a `VECTOR` column raw yields that blob, so it is read back as text. */
     protected selectFieldExpr(escapedColumn: string, field: FieldOptions): string;
 }

package/dist/maria/mariaDialect.js

@@ -1,3 +1,4 @@
+import { relationTermKey } from '../dialect/abstractSqlDialect.js';
 import { jsonPath } from '../dialect/jsonSql.js';
 import { MysqlLikeSqlDialect } from '../dialect/mysqlLikeSqlDialect.js';
 import { getMeta } from '../entity/index.js';
@@ -18,6 +19,24 @@ export class MariaDialect extends MysqlLikeSqlDialect {
         vectorIndexRequiresNotNull: true,
         indexIfNotExists: true,
     };
+    /**
+     * A derived table here reads no column of the statement around it, so the aggregate reads the
+     * related table itself, and orders and pages inside `JSON_ARRAYAGG`, which takes both.
+     */
+    appendRelationArray(ctx, { entity, query, alias, joins }) {
+        const meta = getMeta(entity);
+        const terms = this.projection(ctx, entity, query, { prefix: alias, json: true }, joins);
+        const sortOpts = { prefix: alias, joins, distinct: query.$distinct };
+        const order = this.buildFragment(ctx, (fragmentCtx) => this.sort(fragmentCtx, entity, query.$sort, sortOpts));
+        const page = this.buildFragment(ctx, (fragmentCtx) => this.pager(fragmentCtx, query));
+        const from = this.buildFragment(ctx, (fragmentCtx) => {
+            this.selectRelationJoins(fragmentCtx, meta, alias, joins);
+            this.where(fragmentCtx, entity, query.$where, { prefix: alias });
+        });
+        const object = this.jsonObject(terms.map((term) => [relationTermKey(term), term.sql]));
+        const rows = `${query.$distinct ? 'DISTINCT ' : ''}${object}${order}${page}`;
+        ctx.append(`COALESCE((SELECT JSON_ARRAYAGG(${rows}) FROM ${this.tableRef(meta, alias).ref}${from}), JSON_ARRAY())`);
+    }
     upsertReturning(meta) {
         const returning = this.returningId(meta);
         return returning ? ` ${returning}` : '';
@@ -61,18 +80,19 @@ export class MariaDialect extends MysqlLikeSqlDialect {
         ctx.append(')');
     }
     /**
-     * `SET STATEMENT mhnsw_ef_search=N FOR SELECT ...` - MariaDB scopes a variable to one statement, so
-     * the tuning needs neither a transaction nor a restore afterwards, and cannot leak to the next
-     * query on this pooled connection. That is why it prefixes the SQL here instead of coming back
-     * from `vectorTuningStatements`, which is Postgres's `SET LOCAL` shape.
+     * `mhnsw_ef_search` too, where a vector search is tuned. A setting scoped to one statement needs
+     * neither a transaction nor a restore, and cannot leak to the next query on this pooled connection,
+     * which is why the tuning is not `vectorTuningStatements`, Postgres's `SET LOCAL` shape.
      */
-    find(ctx, entity, q = {}, opts, totalAlias) {
+    statementSettings(entity, q) {
         // `$candidates` first: `getMeta` would otherwise be resolved on every read, to discover that
         // almost none of them tune anything.
-        if (q.$candidates !== undefined && this.tunedVectorIndex(getMeta(entity), q)) {
-            ctx.append(`SET STATEMENT mhnsw_ef_search=${q.$candidates} FOR `);
-        }
-        super.find(ctx, entity, q, opts, totalAlias);
+        const tuned = q.$candidates !== undefined && this.tunedVectorIndex(getMeta(entity), q);
+        return [...(tuned ? [`mhnsw_ef_search=${q.$candidates}`] : []), ...super.statementSettings(entity, q)];
+    }
+    /** `SET STATEMENT ... FOR`, which scopes a variable to the statement it prefixes. */
+    applySettings(sql, settings) {
+        return `SET STATEMENT ${settings.join(', ')} FOR ${sql}`;
     }
     /** The reverse: selecting a `VECTOR` column raw yields that blob, so it is read back as text. */
     selectFieldExpr(escapedColumn, field) {

package/dist/migrate/cli.d.ts

@@ -1,11 +1,10 @@
 #!/usr/bin/env node
-import type { AbstractDialect } from '../dialect/index.js';
 import type { ForeignKeyAction } from '../schema/types.js';
-import type { Config } from '../type/index.js';
+import type { Config, MigratorDialect } from '../type/index.js';
 import { Migrator } from './migrator.js';
 import { createSchemaGeneratorAsync } from './schemaGeneratorAsync.js';
 /** Sync helper for SQL dialects only; returns `undefined` for MongoDB - use {@link createSchemaGeneratorAsync}. */
-export declare function getSchemaGenerator(dialect: AbstractDialect, defaultForeignKeyAction?: ForeignKeyAction): import("./schemaGenerator.js").SqlSchemaGenerator | undefined;
+export declare function getSchemaGenerator(dialect: MigratorDialect, defaultForeignKeyAction?: ForeignKeyAction): import("./schemaGenerator.js").SqlSchemaGenerator | undefined;
 export { createSchemaGeneratorAsync };
 export declare function main(args?: string[]): Promise<void>;
 export declare function runUp(migrator: Migrator, args: string[]): Promise<void>;

package/dist/migrate/cli.js

@@ -308,7 +308,7 @@ function printDriftGroup(title, drifts, icon, showSuggestion) {
                 console.log(`    Expected: ${drift.expected}, Actual: ${drift.actual}`);
             }
             if (showSuggestion) {
-                console.log(`    → ${drift.suggestion}`);
+                console.log(`    -> ${drift.suggestion}`);
             }
         }
         console.log('');
@@ -358,7 +358,7 @@ Configuration:
   Create a uql.config.ts or uql.config.js file in your project root.
   You can also specify a custom config path using --config or -c.
   The CLI requires pool.dialect (dialect id = pool.dialect.dialectName).
-  See the repo README section "Driver → pool → dialect class".
+  See the repo README section "Driver -> pool -> dialect class".
 
   export default {
     pool: new PgQuerierPool({ ... }),

package/dist/migrate/ddl/index.d.ts

@@ -2,15 +2,11 @@ import type { AbstractSqlDialect } from '../../dialect/abstractSqlDialect.js';
 import { IndexDdl } from './indexDdl.js';
 import { TableDdl } from './tableDdl.js';
 export { IndexDdl } from './indexDdl.js';
+export { MsSqlIndexDdl } from './mssqlIndexDdl.js';
 export { MsSqlTableDdl } from './mssqlTableDdl.js';
 export { MariaIndexDdl, MySqlIndexDdl, MysqlLikeIndexDdl } from './mysqlIndexDdl.js';
 export { CockroachIndexDdl, PgIndexDdl } from './pgIndexDdl.js';
 export { TableDdl } from './tableDdl.js';
-/**
- * The index DDL a dialect gets, most specific first. `instanceof` rather than the `dialectName`
- * {@link tableDdlFor} reads, because each family's index DDL is typed to its dialect and the narrowing
- * is what hands it one. Anything else gets the portable form, which is SQLite's.
- */
 export declare function indexDdlFor(dialect: AbstractSqlDialect): IndexDdl;
 /**
  * The table DDL a dialect gets: SQL Server's, or the portable form every other engine takes. By

package/dist/migrate/ddl/index.js

@@ -1,40 +1,29 @@
-import { CockroachDialect } from '../../cockroachdb/cockroachDialect.js';
-import { MysqlLikeSqlDialect } from '../../dialect/mysqlLikeSqlDialect.js';
-import { PgLikeSqlDialect } from '../../dialect/pgLikeSqlDialect.js';
-import { MariaDialect } from '../../maria/mariaDialect.js';
-import { MySqlDialect } from '../../mysql/mysqlDialect.js';
 import { IndexDdl } from './indexDdl.js';
+import { MsSqlIndexDdl } from './mssqlIndexDdl.js';
 import { MsSqlTableDdl } from './mssqlTableDdl.js';
-import { MariaIndexDdl, MySqlIndexDdl, MysqlLikeIndexDdl } from './mysqlIndexDdl.js';
+import { MariaIndexDdl, MySqlIndexDdl } from './mysqlIndexDdl.js';
 import { CockroachIndexDdl, PgIndexDdl } from './pgIndexDdl.js';
 import { TableDdl } from './tableDdl.js';
 export { IndexDdl } from './indexDdl.js';
+export { MsSqlIndexDdl } from './mssqlIndexDdl.js';
 export { MsSqlTableDdl } from './mssqlTableDdl.js';
 export { MariaIndexDdl, MySqlIndexDdl, MysqlLikeIndexDdl } from './mysqlIndexDdl.js';
 export { CockroachIndexDdl, PgIndexDdl } from './pgIndexDdl.js';
 export { TableDdl } from './tableDdl.js';
 /**
- * The index DDL a dialect gets, most specific first. `instanceof` rather than the `dialectName`
- * {@link tableDdlFor} reads, because each family's index DDL is typed to its dialect and the narrowing
- * is what hands it one. Anything else gets the portable form, which is SQLite's.
+ * Each engine's index DDL, by the `dialectName` a subclass inherits: by name, so this entry carries no
+ * dialect, and exhaustive, so a new engine has to name its own. SQLite's is the portable form.
  */
+const INDEX_DDL = {
+    postgres: PgIndexDdl,
+    cockroachdb: CockroachIndexDdl,
+    mysql: MySqlIndexDdl,
+    mariadb: MariaIndexDdl,
+    mssql: MsSqlIndexDdl,
+    sqlite: IndexDdl,
+};
 export function indexDdlFor(dialect) {
-    if (dialect instanceof CockroachDialect) {
-        return new CockroachIndexDdl(dialect);
-    }
-    if (dialect instanceof PgLikeSqlDialect) {
-        return new PgIndexDdl(dialect);
-    }
-    if (dialect instanceof MySqlDialect) {
-        return new MySqlIndexDdl(dialect);
-    }
-    if (dialect instanceof MariaDialect) {
-        return new MariaIndexDdl(dialect);
-    }
-    if (dialect instanceof MysqlLikeSqlDialect) {
-        return new MysqlLikeIndexDdl(dialect);
-    }
-    return new IndexDdl(dialect);
+    return new INDEX_DDL[dialect.dialectName](dialect);
 }
 /**
  * The table DDL a dialect gets: SQL Server's, or the portable form every other engine takes. By

package/dist/migrate/ddl/indexDdl.d.ts

@@ -1,5 +1,5 @@
 import type { AbstractSqlDialect } from '../../dialect/abstractSqlDialect.js';
-import type { IndexType } from '../../schema/types.js';
+import { type IndexType } from '../../schema/types.js';
 import { type IndexColumnSchema, type IndexFeature, type IndexJsonArray, type IndexSchema } from '../../type/index.js';
 /**
  * `CREATE INDEX` for SQL dialects: the statement and the fragments each engine spells differently.
@@ -20,6 +20,15 @@ export declare class IndexDdl<D extends AbstractSqlDialect = AbstractSqlDialect>
      * emitted: each of them is a hard error at the server, not a slower plan.
      */
     protected readonly indexFeatures: ReadonlySet<IndexFeature>;
+    /**
+     * Index types this dialect's `CREATE INDEX` takes. SQLite's grammar has no `USING` clause, so every
+     * type builds the plain index it has there, which is what lets an entity written for Postgres
+     * migrate unchanged. An engine that would reject a type narrows this, and the type is refused.
+     */
+    protected readonly indexTypes: ReadonlySet<IndexType>;
+    /** What to declare instead of a type this dialect lacks, appended to its refusal. */
+    protected readonly indexTypeHints: ReadonlyMap<IndexType, string>;
+    private assertIndexType;
     private assertIndexFeatures;
     /**
      * Index types this dialect spells as a keyword of their own (`FULLTEXT INDEX`, `VECTOR INDEX`)
@@ -51,7 +60,7 @@ export declare class IndexDdl<D extends AbstractSqlDialect = AbstractSqlDialect>
     protected indexInclude(_index: IndexSchema): string;
     /** ` USING <method>`, which SQLite's grammar has no place for at all. */
     protected indexAccessMethod(_index: IndexSchema): string;
-    /** pgvector's ` WITH (m = ..., ef_construction = ..., lists = ...)`. */
+    /** What trails the columns: pgvector's ` WITH (m = ...)`, MySQL's ` USING btree`, MariaDB's ` M=8`. */
     protected indexTuning(_index: IndexSchema): string;
     /**
      * The partial-index predicate. Engines without one reject the index in {@link assertIndexFeatures}

package/dist/migrate/ddl/indexDdl.js

@@ -1,4 +1,5 @@
 import { jsonTypeMode } from '../../dialect/jsonSql.js';
+import { INDEX_TYPES } from '../../schema/types.js';
 import { INDEX_FEATURE_LABELS, } from '../../type/index.js';
 import { getKeys } from '../../util/index.js';
 /**
@@ -29,6 +30,7 @@ export class IndexDdl {
         this.dialect = dialect;
     }
     getCreateIndexStatement(tableName, index, opts = {}) {
+        this.assertIndexType(index);
         this.assertIndexFeatures(index);
         const unique = index.unique ? 'UNIQUE ' : '';
         const ifNotExists = (opts.ifNotExists ?? this.dialect.features.indexIfNotExists) ? 'IF NOT EXISTS ' : '';
@@ -47,6 +49,20 @@ export class IndexDdl {
         'partial',
         'jsonPath',
     ]);
+    /**
+     * Index types this dialect's `CREATE INDEX` takes. SQLite's grammar has no `USING` clause, so every
+     * type builds the plain index it has there, which is what lets an entity written for Postgres
+     * migrate unchanged. An engine that would reject a type narrows this, and the type is refused.
+     */
+    indexTypes = new Set(INDEX_TYPES);
+    /** What to declare instead of a type this dialect lacks, appended to its refusal. */
+    indexTypeHints = new Map();
+    assertIndexType(index) {
+        if (index.type && !this.indexTypes.has(index.type)) {
+            throw new TypeError(`${this.dialect.dialectName} has no ${index.type} index (index "${index.name}")` +
+                (this.indexTypeHints.get(index.type) ?? ''));
+        }
+    }
     assertIndexFeatures(index) {
         for (const feature of getKeys(INDEX_FEATURE_PROBES)) {
             if (INDEX_FEATURE_PROBES[feature](index) && !this.indexFeatures.has(feature)) {
@@ -111,7 +127,7 @@ export class IndexDdl {
     indexAccessMethod(_index) {
         return '';
     }
-    /** pgvector's ` WITH (m = ..., ef_construction = ..., lists = ...)`. */
+    /** What trails the columns: pgvector's ` WITH (m = ...)`, MySQL's ` USING btree`, MariaDB's ` M=8`. */
     indexTuning(_index) {
         return '';
     }

package/dist/migrate/ddl/mssqlIndexDdl.d.ts

@@ -0,0 +1,10 @@
+import { IndexDdl } from './indexDdl.js';
+/**
+ * SQL Server's `CREATE INDEX` is the portable form minus what 2025 rejects: an expression (Msg 16216),
+ * the subquery a JSON path compiles to (Msg 1046), and any type but the plain rowstore B-tree, since
+ * the index built in its place fails on a `VECTOR` or `nvarchar(max)` column (Msg 1978).
+ */
+export declare class MsSqlIndexDdl extends IndexDdl {
+    protected readonly indexFeatures: Set<"expression" | "include" | "jsonArray" | "jsonPath" | "nullsOrder" | "opsClass" | "partial" | "prefixLength">;
+    protected readonly indexTypes: Set<"brin" | "btree" | "fulltext" | "gin" | "gist" | "hash" | "hnsw" | "ivfflat" | "vector" | "vectorSearch">;
+}

package/dist/migrate/ddl/mssqlIndexDdl.js

@@ -0,0 +1,10 @@
+import { IndexDdl } from './indexDdl.js';
+/**
+ * SQL Server's `CREATE INDEX` is the portable form minus what 2025 rejects: an expression (Msg 16216),
+ * the subquery a JSON path compiles to (Msg 1046), and any type but the plain rowstore B-tree, since
+ * the index built in its place fails on a `VECTOR` or `nvarchar(max)` column (Msg 1978).
+ */
+export class MsSqlIndexDdl extends IndexDdl {
+    indexFeatures = new Set(['partial']);
+    indexTypes = new Set(['btree']);
+}

package/dist/migrate/ddl/mysqlIndexDdl.d.ts

@@ -1,19 +1,13 @@
 import type { IndexType } from '../../schema/types.js';
 import type { IndexJsonArray, IndexSchema } from '../../type/index.js';
 import { IndexDdl } from './indexDdl.js';
-/** `CREATE INDEX ... USING btree`, plus the types this family spells as a keyword instead. */
+/** `CREATE INDEX ... (cols) USING btree`, plus the types this family spells as a keyword instead. */
 export declare class MysqlLikeIndexDdl extends IndexDdl {
     protected readonly indexFeatures: Set<"expression" | "include" | "jsonArray" | "jsonPath" | "nullsOrder" | "opsClass" | "partial" | "prefixLength">;
+    protected readonly indexTypes: ReadonlySet<IndexType>;
     protected readonly indexTypeKeywords: ReadonlyMap<IndexType, string>;
-    /**
-     * ` USING btree|hash`, for the types this family does *not* spell as a keyword of its own. A vector
-     * type that is neither is one this engine has no index for at all, refused here rather than
-     * compiled into a ` USING hnsw` the server can only answer with a syntax error: which of them a
-     * dialect *does* have is `indexTypeKeywords`, so declaring one there is all it takes to serve it.
-     */
-    protected indexAccessMethod(index: IndexSchema): string;
-    /** What to do instead, appended to the refusal above. */
-    protected readonly vectorIndexHint: string;
+    /** ` USING btree|hash` trails the columns: between the table and them, it is a syntax error here. */
+    protected indexTuning(index: IndexSchema): string;
 }
 export declare class MySqlIndexDdl extends MysqlLikeIndexDdl {
     /** The multi-valued index is the only JSON index MySQL has - see `IndexFeature` for why. */
@@ -25,12 +19,10 @@ export declare class MySqlIndexDdl extends MysqlLikeIndexDdl {
      */
     protected jsonArrayIndexExpr(escapedColumn: string, json: IndexJsonArray): string;
     /**
-     * MySQL has no vector index of any kind, so one is refused rather than compiled to DDL the server
-     * rejects: `USING hnsw` is a syntax error, and MariaDB's `VECTOR INDEX` is not MySQL syntax either.
-     * Verified against 26.7, which does have `VECTOR` columns and `STRING_TO_VECTOR`, but no distance
-     * function outside HeatWave - hence nothing to index for.
+     * MySQL 26.7 has `VECTOR` columns and `STRING_TO_VECTOR`, but no distance function outside
+     * HeatWave, hence no vector index to build: `USING hnsw` is a syntax error, `VECTOR INDEX` MariaDB's.
      */
-    protected readonly vectorIndexHint = ". Vector search on MySQL needs HeatWave";
+    protected readonly indexTypeHints: Map<"brin" | "btree" | "fulltext" | "gin" | "gist" | "hash" | "hnsw" | "ivfflat" | "vector" | "vectorSearch", string>;
 }
 export declare class MariaIndexDdl extends MysqlLikeIndexDdl {
     /**
@@ -41,12 +33,13 @@ export declare class MariaIndexDdl extends MysqlLikeIndexDdl {
     protected readonly indexFeatures: Set<"expression" | "include" | "jsonArray" | "jsonPath" | "nullsOrder" | "opsClass" | "partial" | "prefixLength">;
     /** The family's, plus a vector index of its own: `CREATE VECTOR INDEX ... ON t (col)`, 11.7+. */
     protected readonly indexTypeKeywords: ReadonlyMap<IndexType, string>;
+    protected readonly indexTypes: Set<"brin" | "btree" | "fulltext" | "gin" | "gist" | "hash" | "hnsw" | "ivfflat" | "vector" | "vectorSearch">;
+    /** pgvector's names are not access methods it has; `vector` is its own keyword above. */
+    protected readonly indexTypeHints: Map<"brin" | "btree" | "fulltext" | "gin" | "gist" | "hash" | "hnsw" | "ivfflat" | "vector" | "vectorSearch", string>;
     /**
      * `M=n DISTANCE=metric`, trailing its `CREATE VECTOR INDEX`. The metric names are MariaDB's own
      * (`euclidean`, not `l2`), and an unsupported one throws rather than being dropped, which would
      * silently build the index on euclidean - its default - instead of what the entity asked for.
      */
     protected indexTuning(index: IndexSchema): string;
-    /** `vector` is its own keyword above; pgvector's names are not access methods it has. */
-    protected readonly vectorIndexHint = "; declare type: 'vector' instead";
 }

package/dist/migrate/ddl/mysqlIndexDdl.js

@@ -1,34 +1,21 @@
 import { jsonPath } from '../../dialect/jsonSql.js';
 import { MARIA_VECTOR_METRICS } from '../../maria/mariaVectorMetrics.js';
-import { isVectorIndexType, unsupportedVectorMetric } from '../../type/vector.js';
+import { unsupportedVectorMetric, VECTOR_INDEX_TYPES } from '../../type/vector.js';
 import { IndexDdl } from './indexDdl.js';
 /**
  * A full-text index is its own keyword here (`CREATE FULLTEXT INDEX ... (cols)`); `USING fulltext` is
  * a syntax error, so it is the keyword that changes rather than the access method.
  */
 const MYSQL_LIKE_INDEX_KEYWORDS = new Map([['fulltext', 'FULLTEXT INDEX']]);
-/** `CREATE INDEX ... USING btree`, plus the types this family spells as a keyword instead. */
+/** `CREATE INDEX ... (cols) USING btree`, plus the types this family spells as a keyword instead. */
 export class MysqlLikeIndexDdl extends IndexDdl {
     indexFeatures = new Set(['expression', 'prefixLength']);
+    indexTypes = new Set(['btree', 'hash', 'fulltext']);
     indexTypeKeywords = MYSQL_LIKE_INDEX_KEYWORDS;
-    /**
-     * ` USING btree|hash`, for the types this family does *not* spell as a keyword of its own. A vector
-     * type that is neither is one this engine has no index for at all, refused here rather than
-     * compiled into a ` USING hnsw` the server can only answer with a syntax error: which of them a
-     * dialect *does* have is `indexTypeKeywords`, so declaring one there is all it takes to serve it.
-     */
-    indexAccessMethod(index) {
-        const type = index.type;
-        if (!type || this.indexTypeKeywords.has(type)) {
-            return '';
-        }
-        if (isVectorIndexType(type)) {
-            throw new TypeError(`${this.dialect.dialectName} has no ${type} index (index "${index.name}")${this.vectorIndexHint}`);
-        }
-        return ` USING ${type}`;
+    /** ` USING btree|hash` trails the columns: between the table and them, it is a syntax error here. */
+    indexTuning(index) {
+        return index.type && !this.indexTypeKeywords.has(index.type) ? ` USING ${index.type}` : '';
     }
-    /** What to do instead, appended to the refusal above. */
-    vectorIndexHint = '';
 }
 export class MySqlIndexDdl extends MysqlLikeIndexDdl {
     /** The multi-valued index is the only JSON index MySQL has - see `IndexFeature` for why. */
@@ -43,12 +30,10 @@ export class MySqlIndexDdl extends MysqlLikeIndexDdl {
         return `CAST(${source} AS ${arrayCastType(json)} ARRAY)`;
     }
     /**
-     * MySQL has no vector index of any kind, so one is refused rather than compiled to DDL the server
-     * rejects: `USING hnsw` is a syntax error, and MariaDB's `VECTOR INDEX` is not MySQL syntax either.
-     * Verified against 26.7, which does have `VECTOR` columns and `STRING_TO_VECTOR`, but no distance
-     * function outside HeatWave - hence nothing to index for.
+     * MySQL 26.7 has `VECTOR` columns and `STRING_TO_VECTOR`, but no distance function outside
+     * HeatWave, hence no vector index to build: `USING hnsw` is a syntax error, `VECTOR INDEX` MariaDB's.
      */
-    vectorIndexHint = '. Vector search on MySQL needs HeatWave';
+    indexTypeHints = new Map(VECTOR_INDEX_TYPES.map((type) => [type, '. Vector search on MySQL needs HeatWave']));
 }
 export class MariaIndexDdl extends MysqlLikeIndexDdl {
     /**
@@ -62,13 +47,19 @@ export class MariaIndexDdl extends MysqlLikeIndexDdl {
         ...MYSQL_LIKE_INDEX_KEYWORDS,
         ['vector', 'VECTOR INDEX'],
     ]);
+    indexTypes = new Set(['btree', 'hash', 'fulltext', 'vector']);
+    /** pgvector's names are not access methods it has; `vector` is its own keyword above. */
+    indexTypeHints = new Map([
+        ['hnsw', "; declare type: 'vector' instead"],
+        ['ivfflat', "; declare type: 'vector' instead"],
+    ]);
     /**
      * `M=n DISTANCE=metric`, trailing its `CREATE VECTOR INDEX`. The metric names are MariaDB's own
      * (`euclidean`, not `l2`), and an unsupported one throws rather than being dropped, which would
      * silently build the index on euclidean - its default - instead of what the entity asked for.
      */
     indexTuning(index) {
-        let tuning = index.m === undefined ? '' : ` M=${index.m}`;
+        let tuning = super.indexTuning(index) + (index.m === undefined ? '' : ` M=${index.m}`);
         if (index.distance) {
             const metric = MARIA_VECTOR_METRICS.get(index.distance);
             if (!metric) {
@@ -78,8 +69,6 @@ export class MariaIndexDdl extends MysqlLikeIndexDdl {
         }
         return tuning;
     }
-    /** `vector` is its own keyword above; pgvector's names are not access methods it has. */
-    vectorIndexHint = "; declare type: 'vector' instead";
 }
 /**
  * MySQL's `CAST(... AS <type> ARRAY)` targets, the closed list its multi-valued index takes: no