uql-orm 0.37.1 → 0.39.0

package/dist/maria/mariaDialect.js

@@ -1,24 +1,23 @@
 import { jsonPath } from '../dialect/jsonSql.js';
 import { MysqlLikeSqlDialect } from '../dialect/mysqlLikeSqlDialect.js';
 import { isVectorFieldType } from '../dialect/vectorCast.js';
+import { getMeta } from '../entity/index.js';
+import { MARIA_VECTOR_METRICS } from './mariaVectorMetrics.js';
 export class MariaDialect extends MysqlLikeSqlDialect {
     dialectName = 'mariadb';
-    // MariaDB 10.5+ supports `INSERT ... RETURNING` (see `insert` below), so IDs are exact per row.
+    // MariaDB 10.5+ has `INSERT ... RETURNING`, so ids come back exact per row - the upsert's too.
     insertIdSource = 'returning';
-    /**
-     * MariaDB has no functional indexes: `CREATE INDEX ... ((lower(col)))` is a syntax error even on
-     * 12.3, where the documented workaround is a generated column. So it keeps the prefix lengths the
-     * family shares and drops expressions.
-     */
-    indexFeatures = new Set(['prefixLength']);
     /** MariaDB has no `FOR ... OF`, so a lock cannot be narrowed to one table of a join. */
     supportsLockOf = false;
-    /** Unlike MySQL: `VECTOR(n)` takes its dimension, and its vector index is declared inline. */
+    /**
+     * Unlike MySQL: `VECTOR(n)` takes its dimension, every column of a vector index has to be NOT NULL,
+     * and `CREATE INDEX` takes `IF NOT EXISTS` - which MySQL's grammar has no place for.
+     */
     featureOverrides = {
         vectorSupportsLength: true,
-        inlineVectorIndex: true,
+        vectorIndexRequiresNotNull: true,
+        indexIfNotExists: true,
     };
-    /** MariaDB 10.5+ supports `INSERT ... RETURNING`, so the ids are exact per row. */
     upsertReturning(entity) {
         return ` ${this.returningId(entity)}`;
     }
@@ -47,16 +46,8 @@ export class MariaDialect extends MysqlLikeSqlDialect {
     jsonPullKeep(alias, operand) {
         return `NOT JSON_EQUALS(${alias}.v, ${operand})`;
     }
-    /** MariaDB's own names for the metrics its vector index accepts. */
-    static INLINE_VECTOR_METRICS = new Map([
-        ['cosine', 'cosine'],
-        ['l2', 'euclidean'],
-    ]);
-    /** MariaDB 11.7+ vector distance functions. */
-    vectorDistanceFns = new Map([
-        ['cosine', 'VEC_DISTANCE_COSINE'],
-        ['l2', 'VEC_DISTANCE_EUCLIDEAN'],
-    ]);
+    /** `VEC_DISTANCE_COSINE`/`VEC_DISTANCE_EUCLIDEAN`, 11.7+: the metric's own name, uppercased. */
+    vectorMetrics = new Map([...MARIA_VECTOR_METRICS].map(([metric, name]) => [metric, { fn: `VEC_DISTANCE_${name.toUpperCase()}` }]));
     /**
      * A `VECTOR` column holds a packed little-endian float32 blob, and MariaDB refuses text where one
      * belongs: inserting `'[1,2,3]'` fails with `Incorrect vector value`, and passing it to
@@ -69,24 +60,18 @@ export class MariaDialect extends MysqlLikeSqlDialect {
         ctx.append(')');
     }
     /**
-     * MariaDB declares a vector index inside `CREATE TABLE`: `VECTOR INDEX (col) M=n DISTANCE=metric`.
-     * Its metric names are its own (`euclidean`, not `l2`), and an unsupported one throws rather than
-     * being dropped, which would silently build the index on cosine instead.
+     * `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.
      */
-    getInlineVectorIndexDeclaration(index) {
-        const columns = index.entries.map((entry) => this.indexColumnTarget(entry)).join(', ');
-        let clause = `VECTOR INDEX (${columns})`;
-        if (index.m !== undefined) {
-            clause += ` M=${index.m}`;
-        }
-        if (index.distance) {
-            const metric = MariaDialect.INLINE_VECTOR_METRICS.get(index.distance);
-            if (!metric) {
-                throw new TypeError(`${this.dialectName} does not support vector distance metric: ${index.distance} (index "${index.name}")`);
-            }
-            clause += ` DISTANCE=${metric}`;
+    find(ctx, entity, q = {}, opts, totalAlias) {
+        // `$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 `);
         }
-        return clause;
+        super.find(ctx, entity, q, opts, totalAlias);
     }
     /** The reverse: selecting a `VECTOR` column raw yields that blob, so it is read back as text. */
     selectFieldExpr(escapedColumn, field) {

package/dist/maria/mariaVectorMetrics.d.ts

@@ -0,0 +1,8 @@
+import type { VectorDistance } from '../type/index.js';
+/**
+ * MariaDB's own name for each metric it supports (`euclidean`, not `l2`), which its index clause and
+ * its distance function are both spelled from - one list, so a metric can never be searchable and
+ * unindexable or the reverse. Its own module because the two ends now live apart: the distance
+ * function on the dialect, the `DISTANCE=` clause in the migrator's index DDL.
+ */
+export declare const MARIA_VECTOR_METRICS: Map<VectorDistance, string>;

package/dist/maria/mariaVectorMetrics.js

@@ -0,0 +1,10 @@
+/**
+ * MariaDB's own name for each metric it supports (`euclidean`, not `l2`), which its index clause and
+ * its distance function are both spelled from - one list, so a metric can never be searchable and
+ * unindexable or the reverse. Its own module because the two ends now live apart: the distance
+ * function on the dialect, the `DISTANCE=` clause in the migrator's index DDL.
+ */
+export const MARIA_VECTOR_METRICS = new Map([
+    ['cosine', 'cosine'],
+    ['l2', 'euclidean'],
+]);

package/dist/maria/mariadbQuerier.d.ts

@@ -7,5 +7,10 @@ export declare class MariadbQuerier extends AbstractPoolQuerier<PoolConnection>
     internalAll<T>(query: string, values?: unknown[]): Promise<T[]>;
     internalRun(query: string, values?: unknown[]): Promise<import("../type/query.js").QueryUpdateResult>;
     internalStream<T>(query: string, values?: unknown[]): AsyncGenerator<Awaited<T>, void, unknown>;
+    /**
+     * No `discard` branch, unlike mysql2's: this driver resets the connection on release, so one taken
+     * back mid-transaction rolls back rather than handing the next caller an open one. Verified on
+     * 12.3 - same `threadId` on reacquire, `@@in_transaction` 0, the uncommitted row gone.
+     */
     protected releaseConn(conn: PoolConnection): Promise<void>;
 }

package/dist/maria/mariadbQuerier.js

@@ -24,6 +24,11 @@ export class MariadbQuerier extends AbstractPoolQuerier {
             stream.destroy();
         }
     }
+    /**
+     * No `discard` branch, unlike mysql2's: this driver resets the connection on release, so one taken
+     * back mid-transaction rolls back rather than handing the next caller an open one. Verified on
+     * 12.3 - same `threadId` on reacquire, `@@in_transaction` 0, the uncommitted row gone.
+     */
     async releaseConn(conn) {
         await conn.release();
     }

package/dist/migrate/builder/migrationBuilder.d.ts

@@ -24,6 +24,12 @@ type ForeignKeyOptions = {
  */
 export declare class OperationRecorder implements IMigrationBuilder {
     protected readonly operations: AnyMigrationOperation[];
+    /**
+     * Where every operation this class builds lands, and the one thing {@link MigrationBuilder}
+     * overrides: it records and then runs. Each operation is spelled once, here, rather than once per
+     * class, which is what let the two drift into recording different shapes of the same change.
+     */
+    protected record(operation: AnyMigrationOperation): Promise<void>;
     createTable(name: string, callback: (table: ITableBuilder) => void): Promise<void>;
     dropTable(name: string, options?: {
         ifExists?: boolean;
@@ -41,7 +47,6 @@ export declare class OperationRecorder implements IMigrationBuilder {
     dropForeignKey(tableName: string, constraintName: string): Promise<void>;
     raw(sql: string): Promise<void>;
     getOperations(): AnyMigrationOperation[];
-    recordOperationSync(operation: AnyMigrationOperation): void;
 }
 /**
  * Executes DDL operations via a SQL querier.
@@ -62,22 +67,8 @@ export declare class MigrationBuilder extends OperationRecorder {
     private readonly querier;
     private readonly sqlGenerator;
     constructor(querier: SqlQuerier);
-    recordOperationSync(operation: AnyMigrationOperation): void;
-    raw(sql: string): Promise<void>;
-    createTable(name: string, callback: (table: ITableBuilder) => void): Promise<void>;
-    dropTable(name: string, options?: {
-        ifExists?: boolean;
-        cascade?: boolean;
-    }): Promise<void>;
-    renameTable(oldName: string, newName: string): Promise<void>;
-    addColumn(tableName: string, callback: (columns: IColumnFactory) => IColumnBuilder): Promise<void>;
-    dropColumn(tableName: string, columnName: string): Promise<void>;
-    alterColumn(tableName: string, callback: (columns: IColumnFactory) => IColumnBuilder): Promise<void>;
-    renameColumn(tableName: string, oldName: string, newName: string): Promise<void>;
-    createIndex(tableName: string, columns: readonly IndexColumnInput[], options?: IndexOptions): Promise<void>;
-    dropIndex(tableName: string, indexName: string): Promise<void>;
-    addForeignKey(tableName: string, columns: string[], target: ForeignKeyTarget, options?: ForeignKeyOptions): Promise<void>;
-    dropForeignKey(tableName: string, constraintName: string): Promise<void>;
+    /** The recorder's sink, plus the statements the operation turns into. */
+    protected record(operation: AnyMigrationOperation): Promise<void>;
     private getCreateTableStatements;
     private execute;
     private operationToSql;

package/dist/migrate/builder/migrationBuilder.js

@@ -63,15 +63,21 @@ function addForeignKeyOperation(tableName, columns, target, options = {}) {
 function buildOneColumn(callback) {
     return callback(new TableBuilder('')).build();
 }
+/**
+ * Collects the operations one `alterTable` callback declares, in the order it declared them.
+ *
+ * Collected rather than dispatched to the parent as they are made: the chaining methods are
+ * synchronous by contract, so a builder that executes could only fire and forget, which returned from
+ * `alterTable` with the statements still in flight and turned a failure into an unhandled rejection.
+ */
 class AlterTableBuilder {
     tableName;
-    parentBuilder;
-    constructor(tableName, parentBuilder) {
+    operations = [];
+    constructor(tableName) {
         this.tableName = tableName;
-        this.parentBuilder = parentBuilder;
     }
     addColumn(callback) {
-        this.parentBuilder.recordOperationSync({
+        this.operations.push({
             type: 'addColumn',
             tableName: this.tableName,
             column: buildOneColumn(callback),
@@ -79,7 +85,7 @@ class AlterTableBuilder {
         return this;
     }
     dropColumn(name) {
-        this.parentBuilder.recordOperationSync({
+        this.operations.push({
             type: 'dropColumn',
             tableName: this.tableName,
             columnName: name,
@@ -87,7 +93,7 @@ class AlterTableBuilder {
         return this;
     }
     renameColumn(oldName, newName) {
-        this.parentBuilder.recordOperationSync({
+        this.operations.push({
             type: 'renameColumn',
             tableName: this.tableName,
             oldName,
@@ -97,7 +103,7 @@ class AlterTableBuilder {
     }
     alterColumn(callback) {
         const column = buildOneColumn(callback);
-        this.parentBuilder.recordOperationSync({
+        this.operations.push({
             type: 'alterColumn',
             tableName: this.tableName,
             columnName: column.name,
@@ -106,11 +112,11 @@ class AlterTableBuilder {
         return this;
     }
     addIndex(columns, options) {
-        this.parentBuilder.recordOperationSync(createIndexOperation(this.tableName, columns, options));
+        this.operations.push(createIndexOperation(this.tableName, columns, options));
         return this;
     }
     dropIndex(name) {
-        this.parentBuilder.recordOperationSync({
+        this.operations.push({
             type: 'dropIndex',
             tableName: this.tableName,
             indexName: name,
@@ -118,11 +124,11 @@ class AlterTableBuilder {
         return this;
     }
     addForeignKey(columns, target, options) {
-        this.parentBuilder.recordOperationSync(addForeignKeyOperation(this.tableName, columns, target, options));
+        this.operations.push(addForeignKeyOperation(this.tableName, columns, target, options));
         return this;
     }
     dropForeignKey(name) {
-        this.parentBuilder.recordOperationSync({
+        this.operations.push({
             type: 'dropForeignKey',
             tableName: this.tableName,
             constraintName: name,
@@ -130,22 +136,35 @@ class AlterTableBuilder {
         return this;
     }
 }
+function collectAlterOperations(tableName, callback) {
+    const builder = new AlterTableBuilder(tableName);
+    callback(builder);
+    return builder.operations;
+}
 /**
  * Records migration operations without executing them.
  * Use for migration code generation and dry-run scenarios.
  */
 export class OperationRecorder {
     operations = [];
+    /**
+     * Where every operation this class builds lands, and the one thing {@link MigrationBuilder}
+     * overrides: it records and then runs. Each operation is spelled once, here, rather than once per
+     * class, which is what let the two drift into recording different shapes of the same change.
+     */
+    async record(operation) {
+        this.operations.push(operation);
+    }
     async createTable(name, callback) {
         const builder = new TableBuilder(name);
         callback(builder);
-        this.recordOperationSync({
+        await this.record({
             type: 'createTable',
             table: builder.build(),
         });
     }
     async dropTable(name, options = {}) {
-        this.recordOperationSync({
+        await this.record({
             type: 'dropTable',
             tableName: name,
             ifExists: options.ifExists,
@@ -153,25 +172,26 @@ export class OperationRecorder {
         });
     }
     async renameTable(oldName, newName) {
-        this.recordOperationSync({
+        await this.record({
             type: 'renameTable',
             oldName,
             newName,
         });
     }
     async alterTable(name, callback) {
-        const builder = new AlterTableBuilder(name, this);
-        callback(builder);
+        for (const operation of collectAlterOperations(name, callback)) {
+            await this.record(operation);
+        }
     }
     async addColumn(tableName, callback) {
-        this.recordOperationSync({
+        await this.record({
             type: 'addColumn',
             tableName,
             column: buildOneColumn(callback),
         });
     }
     async dropColumn(tableName, columnName) {
-        this.recordOperationSync({
+        await this.record({
             type: 'dropColumn',
             tableName,
             columnName,
@@ -179,7 +199,7 @@ export class OperationRecorder {
     }
     async alterColumn(tableName, callback) {
         const column = buildOneColumn(callback);
-        this.recordOperationSync({
+        await this.record({
             type: 'alterColumn',
             tableName,
             columnName: column.name,
@@ -187,7 +207,7 @@ export class OperationRecorder {
         });
     }
     async renameColumn(tableName, oldName, newName) {
-        this.recordOperationSync({
+        await this.record({
             type: 'renameColumn',
             tableName,
             oldName,
@@ -195,27 +215,27 @@ export class OperationRecorder {
         });
     }
     async createIndex(tableName, columns, options) {
-        this.recordOperationSync(createIndexOperation(tableName, columns, options));
+        await this.record(createIndexOperation(tableName, columns, options));
     }
     async dropIndex(tableName, indexName) {
-        this.recordOperationSync({
+        await this.record({
             type: 'dropIndex',
             tableName,
             indexName,
         });
     }
     async addForeignKey(tableName, columns, target, options = {}) {
-        this.recordOperationSync(addForeignKeyOperation(tableName, columns, target, options));
+        await this.record(addForeignKeyOperation(tableName, columns, target, options));
     }
     async dropForeignKey(tableName, constraintName) {
-        this.recordOperationSync({
+        await this.record({
             type: 'dropForeignKey',
             tableName,
             constraintName,
         });
     }
     async raw(sql) {
-        this.recordOperationSync({
+        await this.record({
             type: 'raw',
             sql,
         });
@@ -223,9 +243,6 @@ export class OperationRecorder {
     getOperations() {
         return [...this.operations];
     }
-    recordOperationSync(operation) {
-        this.operations.push(operation);
-    }
 }
 /**
  * Executes DDL operations via a SQL querier.
@@ -254,114 +271,9 @@ export class MigrationBuilder extends OperationRecorder {
         }
         this.sqlGenerator = generator;
     }
-    recordOperationSync(operation) {
-        super.recordOperationSync(operation);
-        // Fire and forget execution - for sync contexts (AlterTableBuilder)
-        void this.execute(operation);
-    }
-    async raw(sql) {
-        const operation = {
-            type: 'raw',
-            sql,
-        };
-        this.operations.push(operation);
-        await this.querier.run(sql);
-    }
-    // Override async methods to execute immediately
-    async createTable(name, callback) {
-        const builder = new TableBuilder(name);
-        callback(builder);
-        const operation = {
-            type: 'createTable',
-            table: builder.build(),
-        };
-        this.operations.push(operation);
-        await this.execute(operation);
-    }
-    async dropTable(name, options = {}) {
-        const operation = {
-            type: 'dropTable',
-            tableName: name,
-            ifExists: options.ifExists,
-            cascade: options.cascade,
-        };
-        this.operations.push(operation);
-        await this.execute(operation);
-    }
-    async renameTable(oldName, newName) {
-        const operation = {
-            type: 'renameTable',
-            oldName,
-            newName,
-        };
-        this.operations.push(operation);
-        await this.execute(operation);
-    }
-    async addColumn(tableName, callback) {
-        const operation = {
-            type: 'addColumn',
-            tableName,
-            column: buildOneColumn(callback),
-        };
-        this.operations.push(operation);
-        await this.execute(operation);
-    }
-    async dropColumn(tableName, columnName) {
-        const operation = {
-            type: 'dropColumn',
-            tableName,
-            columnName,
-        };
-        this.operations.push(operation);
-        await this.execute(operation);
-    }
-    async alterColumn(tableName, callback) {
-        const column = buildOneColumn(callback);
-        const operation = {
-            type: 'alterColumn',
-            tableName,
-            columnName: column.name,
-            changes: column,
-        };
-        this.operations.push(operation);
-        await this.execute(operation);
-    }
-    async renameColumn(tableName, oldName, newName) {
-        const operation = {
-            type: 'renameColumn',
-            tableName,
-            oldName,
-            newName,
-        };
-        this.operations.push(operation);
-        await this.execute(operation);
-    }
-    async createIndex(tableName, columns, options) {
-        const operation = createIndexOperation(tableName, columns, options);
-        this.operations.push(operation);
-        await this.execute(operation);
-    }
-    async dropIndex(tableName, indexName) {
-        const operation = {
-            type: 'dropIndex',
-            tableName,
-            indexName,
-        };
-        this.operations.push(operation);
-        await this.execute(operation);
-    }
-    async addForeignKey(tableName, columns, target, options = {}) {
-        const operation = addForeignKeyOperation(tableName, columns, target, options);
-        this.operations.push(operation);
-        await this.execute(operation);
-    }
-    async dropForeignKey(tableName, constraintName) {
-        const operation = {
-            type: 'dropForeignKey',
-            tableName,
-            constraintName,
-        };
-        this.operations.push(operation);
+    /** The recorder's sink, plus the statements the operation turns into. */
+    async record(operation) {
+        await super.record(operation);
         await this.execute(operation);
     }
     getCreateTableStatements(operation) {

package/dist/migrate/builder/types.d.ts

@@ -449,6 +449,4 @@ export interface IMigrationBuilder {
     raw(sql: string): Promise<void>;
     /** Get all recorded operations */
     getOperations(): AnyMigrationOperation[];
-    /** Record an operation synchronously */
-    recordOperationSync(operation: AnyMigrationOperation): void;
 }

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

@@ -0,0 +1,11 @@
+import type { AbstractSqlDialect } from '../../dialect/abstractSqlDialect.js';
+import { IndexDdl } from './indexDdl.js';
+export { IndexDdl } from './indexDdl.js';
+export { MariaIndexDdl, MySqlIndexDdl, MysqlLikeIndexDdl } from './mysqlIndexDdl.js';
+export { CockroachIndexDdl, PgIndexDdl } from './pgIndexDdl.js';
+/**
+ * The index DDL a dialect gets, most specific first. `instanceof` rather than `dialectName` so a
+ * dialect subclassed by a user keeps its family's DDL, which is what overriding gave it while this
+ * lived on the dialect itself. Anything else gets the portable form, which is SQLite's.
+ */
+export declare function indexDdlFor(dialect: AbstractSqlDialect): IndexDdl;

package/dist/migrate/ddl/index.js

@@ -0,0 +1,34 @@
+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 { MariaIndexDdl, MySqlIndexDdl, MysqlLikeIndexDdl } from './mysqlIndexDdl.js';
+import { CockroachIndexDdl, PgIndexDdl } from './pgIndexDdl.js';
+export { IndexDdl } from './indexDdl.js';
+export { MariaIndexDdl, MySqlIndexDdl, MysqlLikeIndexDdl } from './mysqlIndexDdl.js';
+export { CockroachIndexDdl, PgIndexDdl } from './pgIndexDdl.js';
+/**
+ * The index DDL a dialect gets, most specific first. `instanceof` rather than `dialectName` so a
+ * dialect subclassed by a user keeps its family's DDL, which is what overriding gave it while this
+ * lived on the dialect itself. Anything else gets the portable form, which is SQLite's.
+ */
+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);
+}

package/dist/{dialect/indexSqlDialect.d.ts → migrate/ddl/indexDdl.d.ts}

@@ -1,19 +1,16 @@
-import { type IndexColumnSchema, type IndexFeature, type IndexSchema } from '../type/index.js';
-import { VectorSqlDialect } from './vectorSqlDialect.js';
+import type { AbstractSqlDialect } from '../../dialect/abstractSqlDialect.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.
- *
- * A layer of its own for the same reason as {@link VectorSqlDialect} below it - it needs only
- * `escapeId` and `features.indexIfNotExists` from the SQL dialect above, so keeping it here spares
- * that 2000-line class thirteen more members. What each engine can express at all is data
- * ({@link indexFeatures}), validated once, rather than a throw per feature per dialect.
+ * The migrator's rather than the dialect's, since {@link SqlSchemaGenerator} is the only thing that
+ * emits DDL - which is what keeps a `CAST(... ARRAY)` table out of every runtime consumer's entry.
+ * The form here is the portable one, which SQLite (and so libSQL, Turso and D1) takes verbatim: no
+ * access-method clause, no operator classes, no tuning parameters.
  */
-export declare abstract class IndexSqlDialect extends VectorSqlDialect {
-    /**
-     * The `CREATE INDEX` statement for this dialect. The form here is the portable one, which SQLite
-     * (and so libSQL, Turso and D1) takes verbatim: no access-method clause, no operator classes, no
-     * tuning parameters. Dialects that have those override the fragments below rather than this.
-     */
+export declare class IndexDdl<D extends AbstractSqlDialect = AbstractSqlDialect> {
+    protected readonly dialect: D;
+    constructor(dialect: D);
     getCreateIndexStatement(tableName: string, index: IndexSchema, opts?: {
         ifNotExists?: boolean;
     }): string;
@@ -25,20 +22,27 @@ export declare abstract class IndexSqlDialect extends VectorSqlDialect {
     protected readonly indexFeatures: ReadonlySet<IndexFeature>;
     private assertIndexFeatures;
     /**
-     * The column-level declaration for a vector index that lives inside `CREATE TABLE` rather than in
-     * its own statement, which the `inlineVectorIndex` feature flags. Only MariaDB has one.
+     * Index types this dialect spells as a keyword of their own (`FULLTEXT INDEX`, `VECTOR INDEX`)
+     * rather than as an access method after the table. One table drives both, so a type that is a
+     * keyword here can never also leak out as a ` USING` clause the engine has no word for.
      */
-    getInlineVectorIndexDeclaration(index: IndexSchema): string;
-    /** Only CockroachDB's native vector index replaces the `INDEX` keyword. */
-    protected indexKeyword(_index: IndexSchema): string;
+    protected readonly indexTypeKeywords: ReadonlyMap<IndexType, string>;
+    /** The keyword an index type replaces `INDEX` with, or `INDEX` for the types that do not. */
+    protected indexKeyword(index: IndexSchema): string;
     /** One index entry: what is indexed, its operator class if any, then its stored order. */
     protected indexColumn(entry: IndexColumnSchema, index: IndexSchema): string;
     /**
      * A quoted column, optionally prefix-limited, or an expression in its own parentheses - the form
      * `((lower("email")))` that MySQL requires and Postgres, CockroachDB and SQLite all accept, so one
-     * rendering serves every engine that has expression indexes.
+     * rendering serves every engine that has expression indexes. A JSON entry is one of those too, its
+     * expression compiled from the path rather than written out by the caller.
      */
     protected indexColumnTarget(entry: IndexColumnSchema): string;
+    /**
+     * One key per *element* of the JSON array, which is MySQL's multi-valued index and nothing else's -
+     * every other dialect refuses `jsonArray` in {@link assertIndexFeatures} and never reaches this.
+     */
+    protected jsonArrayIndexExpr(_escapedColumn: string, _json: IndexJsonArray): string;
     /** Postgres-wire dialects put a vector or user-declared operator class here. */
     protected indexColumnOpsClass(_entry: IndexColumnSchema, _index: IndexSchema): string;
     /** `ASC` is every engine's default, so only `DESC` is worth emitting. */