uql-orm 0.21.0 → 0.22.0

package/dist/dialect/vectorSqlDialect.js

@@ -1,5 +1,5 @@
 import { AbstractDialect } from './abstractDialect.js';
-import { resolveVectorCast } from './vectorCast.js';
+import { MULTI_VECTOR_TYPE_DIALECTS } from './vectorCast.js';
 /**
  * Vector similarity search for SQL dialects: the `ORDER BY <distance>` expression, its projection as
  * a named score, and the index metadata the schema generator reads.
@@ -13,8 +13,6 @@ import { resolveVectorCast } from './vectorCast.js';
  * {@link appendVectorSort} or filling {@link vectorDistanceFns}.
  */
 export class VectorSqlDialect extends AbstractDialect {
-    /** Vector index operator classes, keyed by distance metric. Partial: not every dialect supports every metric. */
-    vectorOpsClass = undefined;
     vectorExtension = undefined;
     /**
      * Mapping of UQL vector distance metrics to native SQL functions.
@@ -30,21 +28,34 @@ export class VectorSqlDialect extends AbstractDialect {
         const field = meta.fields[key];
         const colName = this.resolveColumnName(key, field);
         const distance = search.$distance ?? field?.distance ?? 'cosine';
-        const vectorCast = resolveVectorCast(field);
-        return { colName, distance, field, vectorCast };
+        return { colName, distance, field };
+    }
+    /**
+     * Binds a vector, both as a persisted value and as the query vector of a distance expression, so a
+     * dialect needing a conversion around it (`$1::vector`, `VEC_FromText(?)`) declares it once.
+     */
+    appendVectorValue(ctx, value, _field) {
+        ctx.addValue(`[${value.join(',')}]`);
+    }
+    /**
+     * The vector type this dialect actually has for a declared one, so the cast follows the column
+     * rather than naming a type the engine does not define. See {@link MULTI_VECTOR_TYPE_DIALECTS}.
+     */
+    supportedVectorType(cast) {
+        return MULTI_VECTOR_TYPE_DIALECTS.has(this.dialectName) ? cast : 'vector';
     }
     /**
      * Append a vector similarity function call: `fn(col, ?)`.
      * Used by dialects that express vector distance via SQL functions (SQLite, MariaDB).
      */
     appendFunctionVectorSort(ctx, meta, key, search) {
-        const { colName, distance } = this.resolveVectorSortParams(meta, key, search);
+        const { colName, distance, field } = this.resolveVectorSortParams(meta, key, search);
         const fn = this.vectorDistanceFns.get(distance);
         if (!fn) {
             throw Error(`${this.dialectName} does not support vector distance metric: ${distance}`);
         }
         ctx.append(`${fn}(${this.escapeId(colName)}, `);
-        ctx.addValue(`[${search.$vector.join(',')}]`);
+        this.appendVectorValue(ctx, search.$vector, field);
         ctx.append(')');
     }
     /**
@@ -64,6 +75,6 @@ export class VectorSqlDialect extends AbstractDialect {
             this.appendFunctionVectorSort(ctx, meta, key, search);
             return;
         }
-        throw new TypeError('Vector similarity sort is not supported by this dialect. Use raw() for vector queries.');
+        throw new TypeError(`${this.dialectName} does not support vector similarity sort. Use raw() for vector queries.`);
     }
 }

package/dist/entity/decorator/index-decorator.d.ts

@@ -1,11 +1,4 @@
-import type { DistributiveOmit, EntityIndexMeta, Type } from '../../type/index.js';
-/**
- * Options for the @Index decorator - {@link EntityIndexMeta} minus `columns`, which the decorator
- * takes as its own positional argument. `DistributiveOmit` (not plain `Omit`) keeps `type`/`distance`
- * a discriminated pair - `EntityIndexMeta`'s vector-index invariant, that omitting `distance` on a
- * vector index type is a compile error.
- */
-export type IndexDecoratorOptions = DistributiveOmit<EntityIndexMeta, 'columns'>;
+import type { IndexColumnInput, IndexOptions, Type } from '../../type/index.js';
 /**
  * Define a composite index on an entity class.
  *
@@ -26,4 +19,4 @@ export type IndexDecoratorOptions = DistributiveOmit<EntityIndexMeta, 'columns'>
  * export class User { ... }
  * ```
  */
-export declare function Index<E>(columns: string[], options?: IndexDecoratorOptions): (target: Type<E>) => void;
+export declare function Index<E>(columns: readonly IndexColumnInput[], options?: IndexOptions): (target: Type<E>) => void;

package/dist/entity/metadata/definition.d.ts

@@ -1,13 +1,14 @@
-import type { EntityIndexMeta, EntityMeta, EntityOptions, FieldOptions, FilterOptions, HookEvent, RelationOptions, Type } from '../../type/index.js';
+import type { EntityIndexInput, EntityMeta, EntityOptions, FieldOptions, FilterOptions, HookEvent, RelationOptions, Type } from '../../type/index.js';
 /**
- * Append a composite index entry with normalized `unique` (default false).
+ * Append a composite index entry with normalized `unique` (default false) and columns. Normalizing
+ * here is what lets the dialects render one shape instead of re-parsing the authored sugar.
  */
-export declare function appendEntityIndex<E>(meta: EntityMeta<E>, index: EntityIndexMeta): void;
+export declare function appendEntityIndex<E>(meta: EntityMeta<E>, index: EntityIndexInput): void;
 export declare function defineField<E>(entity: Type<E>, key: string, opts?: FieldOptions): EntityMeta<E>;
 export declare function defineId<E>(entity: Type<E>, key: string, opts: FieldOptions): EntityMeta<E>;
 export declare function defineRelation<E>(entity: Type<E>, key: string, opts: RelationOptions<E>): EntityMeta<E>;
 export declare function defineHook<E>(entity: Type<E>, methodName: string, event: HookEvent): EntityMeta<E>;
-export declare function defineIndex<E>(entity: Type<E>, index: EntityIndexMeta): EntityMeta<E>;
+export declare function defineIndex<E>(entity: Type<E>, index: EntityIndexInput): EntityMeta<E>;
 export declare function defineFilter<E>(entity: Type<E>, name: string, opts: FilterOptions<E>): EntityMeta<E>;
 export declare function defineEntity<E>(entity: Type<E>, opts?: EntityOptions<E>): EntityMeta<E>;
 export declare function getEntities(): Type<unknown>[];

package/dist/entity/metadata/definition.js

@@ -1,4 +1,4 @@
-import { getKeys, hasKeys, lowerFirst, upperFirst } from '../../util/index.js';
+import { getKeys, hasKeys, lowerFirst, normalizeIndexColumn, upperFirst } from '../../util/index.js';
 import { LoggerWrapper } from '../../util/logger.js';
 // Held on `globalThis` via the global symbol registry so a single metadata map survives multiple
 // evaluations of this module (HMR, duplicated/federated bundles, ESM+CJS dual-loading).
@@ -8,12 +8,13 @@ const metas = holder[metaKey] ?? new Map();
 holder[metaKey] = metas;
 const registrationLogger = new LoggerWrapper(true);
 /**
- * Append a composite index entry with normalized `unique` (default false).
+ * Append a composite index entry with normalized `unique` (default false) and columns. Normalizing
+ * here is what lets the dialects render one shape instead of re-parsing the authored sugar.
  */
 export function appendEntityIndex(meta, index) {
     if (!meta.indexes)
         meta.indexes = [];
-    meta.indexes.push({ ...index, unique: index.unique ?? false });
+    meta.indexes.push({ ...index, unique: index.unique ?? false, columns: index.columns.map(normalizeIndexColumn) });
 }
 export function defineField(entity, key, opts = {}) {
     const meta = ensureMeta(entity);

package/dist/libsql/libsqlDialect.d.ts

@@ -1,9 +1,19 @@
 import { SqliteDialect } from '../sqlite/sqliteDialect.js';
+import type { VectorDistance } from '../type/index.js';
 /**
  * SQLite Dialect specialization for the `@libsql/client` driver.
  *
- * @remarks Empty subclass by design: distinct type for `LibsqlQuerierPool` and a hook
- * for future libsql-specific behavior.
+ * @remarks Distinct type for `LibsqlQuerierPool` and the home of the libSQL engine's built-in vector
+ * functions, which `TursoDialect` inherits.
  */
 export declare class LibsqlDialect extends SqliteDialect {
+    /**
+     * libSQL has vector search built in, under its own names, so the sqlite-vec `vec_distance_*`
+     * functions this dialect would otherwise inherit are never present.
+     *
+     * @remarks `inner` and `l1` are left out: `vector_distance_dot` only exists in the newer Rust
+     * engine (see `TursoDialect`) and no libSQL build has an L1 metric. Both raise the same
+     * "does not support vector distance metric" error as any other unsupported metric.
+     */
+    protected readonly vectorDistanceFns: ReadonlyMap<VectorDistance, string>;
 }

package/dist/libsql/libsqlDialect.js

@@ -2,8 +2,20 @@ import { SqliteDialect } from '../sqlite/sqliteDialect.js';
 /**
  * SQLite Dialect specialization for the `@libsql/client` driver.
  *
- * @remarks Empty subclass by design: distinct type for `LibsqlQuerierPool` and a hook
- * for future libsql-specific behavior.
+ * @remarks Distinct type for `LibsqlQuerierPool` and the home of the libSQL engine's built-in vector
+ * functions, which `TursoDialect` inherits.
  */
 export class LibsqlDialect extends SqliteDialect {
+    /**
+     * libSQL has vector search built in, under its own names, so the sqlite-vec `vec_distance_*`
+     * functions this dialect would otherwise inherit are never present.
+     *
+     * @remarks `inner` and `l1` are left out: `vector_distance_dot` only exists in the newer Rust
+     * engine (see `TursoDialect`) and no libSQL build has an L1 metric. Both raise the same
+     * "does not support vector distance metric" error as any other unsupported metric.
+     */
+    vectorDistanceFns = new Map([
+        ['cosine', 'vector_distance_cos'],
+        ['l2', 'vector_distance_l2'],
+    ]);
 }

package/dist/libsql/libsqlQuerier.d.ts

@@ -1,23 +1,10 @@
-import type { Client } from '@libsql/client';
-import { AbstractSqliteQuerier } from '../sqlite/abstractSqliteQuerier.js';
-import type { SqliteDialect } from '../sqlite/sqliteDialect.js';
-import type { ExtraOptions, TransactionOptions } from '../type/index.js';
-/** Connection lifecycle for a {@link LibsqlQuerier} (separate from {@link ExtraOptions}). */
-export type LibsqlQuerierConnectionOptions = {
-    /** When set, {@link release} closes {@link LibsqlQuerier.client} (one-shot migration connections). */
-    closeClientOnRelease?: boolean;
-};
-export declare class LibsqlQuerier extends AbstractSqliteQuerier {
-    readonly client: Client;
-    readonly extra?: ExtraOptions | undefined;
-    private tx?;
-    private readonly closeClientOnRelease;
-    constructor(client: Client, dialect: SqliteDialect, extra?: ExtraOptions | undefined, connection?: LibsqlQuerierConnectionOptions);
-    internalAll<T>(query: string, values?: unknown[]): Promise<T[]>;
-    internalRun(query: string, values?: unknown[]): Promise<import("../type/query.js").QueryUpdateResult>;
-    get hasOpenTransaction(): boolean;
-    beginTransaction(_opts?: TransactionOptions): Promise<void>;
-    commitTransaction(): Promise<void>;
-    rollbackTransaction(): Promise<void>;
-    internalRelease(): Promise<void>;
+import { HranaQuerier } from '../sqlite/hranaQuerier.js';
+/**
+ * Querier for the `@libsql/client` driver.
+ *
+ * @remarks Empty subclass by design: that client speaks the Hrana protocol, so the whole
+ * implementation is inherited. Kept as a distinct type for `LibsqlQuerierPool` and as a hook for
+ * future libsql-specific behavior.
+ */
+export declare class LibsqlQuerier extends HranaQuerier {
 }

package/dist/libsql/libsqlQuerier.js

@@ -1,86 +1,10 @@
-var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-};
-var __metadata = (this && this.__metadata) || function (k, v) {
-    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-};
-import { Serialized } from '../querier/decorator/index.js';
-import { AbstractSqliteQuerier } from '../sqlite/abstractSqliteQuerier.js';
-import { throwNoPendingTransaction, throwPendingTransaction } from '../util/index.js';
-export class LibsqlQuerier extends AbstractSqliteQuerier {
-    client;
-    extra;
-    tx;
-    closeClientOnRelease;
-    constructor(client, dialect, extra, connection) {
-        super(dialect, extra);
-        this.client = client;
-        this.extra = extra;
-        this.closeClientOnRelease = connection?.closeClientOnRelease ?? false;
-    }
-    async internalAll(query, values) {
-        const target = this.tx || this.client;
-        const res = await target.execute({ sql: query, args: values });
-        return res.rows;
-    }
-    async internalRun(query, values) {
-        const target = this.tx || this.client;
-        const res = await target.execute({ sql: query, args: values });
-        const rows = res.rows;
-        // `rowsAffected` is unreliably 0 whenever the statement has a RETURNING clause, so prefer
-        // the actual row count when rows were returned.
-        return this.buildUpdateResult({ rows, changes: rows.length || res.rowsAffected, id: res.lastInsertRowid });
-    }
-    get hasOpenTransaction() {
-        return !!this.tx;
-    }
-    async beginTransaction(_opts) {
-        if (this.tx) {
-            throwPendingTransaction();
-        }
-        this.tx = await this.client.transaction('write');
-    }
-    async commitTransaction() {
-        if (!this.tx) {
-            throwNoPendingTransaction();
-        }
-        await this.tx.commit();
-        this.tx = undefined;
-    }
-    async rollbackTransaction() {
-        if (!this.tx) {
-            throwNoPendingTransaction();
-        }
-        await this.tx.rollback();
-        this.tx = undefined;
-    }
-    async internalRelease() {
-        if (this.tx) {
-            throwPendingTransaction();
-        }
-        if (this.closeClientOnRelease) {
-            this.client.close();
-        }
-    }
+import { HranaQuerier } from '../sqlite/hranaQuerier.js';
+/**
+ * Querier for the `@libsql/client` driver.
+ *
+ * @remarks Empty subclass by design: that client speaks the Hrana protocol, so the whole
+ * implementation is inherited. Kept as a distinct type for `LibsqlQuerierPool` and as a hook for
+ * future libsql-specific behavior.
+ */
+export class LibsqlQuerier extends HranaQuerier {
 }
-__decorate([
-    Serialized(),
-    __metadata("design:type", Function),
-    __metadata("design:paramtypes", [Object]),
-    __metadata("design:returntype", Promise)
-], LibsqlQuerier.prototype, "beginTransaction", null);
-__decorate([
-    Serialized(),
-    __metadata("design:type", Function),
-    __metadata("design:paramtypes", []),
-    __metadata("design:returntype", Promise)
-], LibsqlQuerier.prototype, "commitTransaction", null);
-__decorate([
-    Serialized(),
-    __metadata("design:type", Function),
-    __metadata("design:paramtypes", []),
-    __metadata("design:returntype", Promise)
-], LibsqlQuerier.prototype, "rollbackTransaction", null);

package/dist/libsql/libsqlQuerierPool.d.ts

@@ -1,19 +1,21 @@
-import { type Client, type Config } from '@libsql/client';
-import { AbstractSqlQuerierPool } from '../querier/index.js';
+import type { Config } from '@libsql/client';
+import type { HranaClient, HranaQuerierConnectionOptions } from '../sqlite/hranaQuerier.js';
+import { AbstractHranaQuerierPool } from '../sqlite/hranaQuerierPool.js';
 import type { ExtraOptions } from '../type/index.js';
 import { LibsqlDialect } from './libsqlDialect.js';
 import { LibsqlQuerier } from './libsqlQuerier.js';
 /** Embedded replica: local `file:` DB + `syncUrl` remote - DDL should run on the remote (sqld). */
 export declare function libsqlUseRemoteForMigrations(config: Pick<Config, 'url' | 'syncUrl'>): boolean;
-export declare class LibsqlQuerierPool extends AbstractSqlQuerierPool<LibsqlQuerier, LibsqlDialect> {
-    readonly client: Client;
-    private readonly libsqlConfig;
+export declare class LibsqlQuerierPool extends AbstractHranaQuerierPool<LibsqlQuerier, LibsqlDialect> {
+    private readonly conf;
     constructor(conf: Config, extra?: ExtraOptions);
-    getQuerier(): Promise<LibsqlQuerier>;
+    protected openClient(): Promise<HranaClient>;
+    protected buildQuerier(client: HranaClient, connection?: HranaQuerierConnectionOptions): LibsqlQuerier;
     /**
      * For embedded replicas (`file:` + `syncUrl`), returns a querier connected to `syncUrl` so migrations hit sqld.
-     * Otherwise same as {@link getQuerier}. The migrator calls this for `up`/`down`, `syncForce`, and `autoSync` DDL.
+     * Otherwise same as `getQuerier`. The migrator calls this for `up`/`down`, `syncForce`, and `autoSync` DDL.
      */
     getMigrationQuerier(): Promise<LibsqlQuerier>;
-    end(): Promise<void>;
+    /** Imported on use, so `uql-orm/libsql` loads without the optional `@libsql/client` peer installed. */
+    private createClient;
 }

package/dist/libsql/libsqlQuerierPool.js

@@ -1,5 +1,4 @@
-import { createClient } from '@libsql/client';
-import { AbstractSqlQuerierPool } from '../querier/index.js';
+import { AbstractHranaQuerierPool } from '../sqlite/hranaQuerierPool.js';
 import { LibsqlDialect } from './libsqlDialect.js';
 import { LibsqlQuerier } from './libsqlQuerier.js';
 /** Embedded replica: local `file:` DB + `syncUrl` remote - DDL should run on the remote (sqld). */
@@ -11,29 +10,32 @@ function remoteMigrationClientConfig(config) {
     const { syncUrl, url: _localUrl, ...rest } = config;
     return { ...rest, url: syncUrl };
 }
-export class LibsqlQuerierPool extends AbstractSqlQuerierPool {
-    client;
-    libsqlConfig;
+export class LibsqlQuerierPool extends AbstractHranaQuerierPool {
+    conf;
     constructor(conf, extra) {
         super(new LibsqlDialect({ namingStrategy: extra?.namingStrategy }), extra);
-        this.libsqlConfig = conf;
-        this.client = createClient(conf);
+        this.conf = conf;
     }
-    async getQuerier() {
-        return new LibsqlQuerier(this.client, this.dialect, this.extra);
+    openClient() {
+        return this.createClient(this.conf);
+    }
+    buildQuerier(client, connection) {
+        return new LibsqlQuerier(client, this.dialect, this.extra, connection);
     }
     /**
      * For embedded replicas (`file:` + `syncUrl`), returns a querier connected to `syncUrl` so migrations hit sqld.
-     * Otherwise same as {@link getQuerier}. The migrator calls this for `up`/`down`, `syncForce`, and `autoSync` DDL.
+     * Otherwise same as `getQuerier`. The migrator calls this for `up`/`down`, `syncForce`, and `autoSync` DDL.
      */
     async getMigrationQuerier() {
-        if (!libsqlUseRemoteForMigrations(this.libsqlConfig)) {
+        if (!libsqlUseRemoteForMigrations(this.conf)) {
             return this.getQuerier();
         }
-        const remote = createClient(remoteMigrationClientConfig(this.libsqlConfig));
-        return new LibsqlQuerier(remote, this.dialect, this.extra, { closeClientOnRelease: true });
+        const remote = await this.createClient(remoteMigrationClientConfig(this.conf));
+        return this.buildQuerier(remote, { closeClientOnRelease: true });
     }
-    async end() {
-        this.client.close();
+    /** Imported on use, so `uql-orm/libsql` loads without the optional `@libsql/client` peer installed. */
+    async createClient(conf) {
+        const { createClient } = await import('@libsql/client');
+        return createClient(conf);
     }
 }

package/dist/maria/mariaDialect.d.ts

@@ -1,11 +1,16 @@
-import type { DialectOptions } from '../dialect/abstractDialect.js';
 import { MysqlLikeSqlDialect } from '../dialect/mysqlLikeSqlDialect.js';
-import type { QueryConflictPaths, QueryContext, QueryOptions, Type, VectorDistance } from '../type/index.js';
+import type { DialectFeatures, FieldOptions, IndexFeature, IndexSchema, QueryConflictPaths, QueryContext, Type, VectorDistance } from '../type/index.js';
 export declare class MariaDialect extends MysqlLikeSqlDialect {
     readonly dialectName = "mariadb";
     readonly insertIdSource = "returning";
-    constructor(options?: DialectOptions);
-    insert<E>(ctx: QueryContext, entity: Type<E>, payload: E | E[], opts?: QueryOptions): void;
+    /**
+     * 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.
+     */
+    protected readonly indexFeatures: Set<IndexFeature>;
+    /** Unlike MySQL: `VECTOR(n)` takes its dimension, and its vector index is declared inline. */
+    protected readonly featureOverrides: Partial<DialectFeatures>;
     upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[]): void;
     /**
      * MariaDB supports neither MySQL's `->`/`->>` shorthand nor the base's chained form. `JSON_VALUE`
@@ -22,6 +27,23 @@ export declare class MariaDialect extends MysqlLikeSqlDialect {
     protected jsonPullElem(alias: string): string;
     /** Text-backed JSON compares as text, so use JSON_EQUALS for key-order-independent equality. */
     protected jsonPullKeep(alias: string, operand: string): string;
+    /** MariaDB's own names for the metrics its vector index accepts. */
+    private static readonly INLINE_VECTOR_METRICS;
     /** MariaDB 11.7+ vector distance functions. */
     protected readonly vectorDistanceFns: ReadonlyMap<VectorDistance, string>;
+    /**
+     * 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
+     * `VEC_DISTANCE_COSINE` with `Illegal parameter data type varchar`. `VEC_FromText` is the
+     * conversion, needed on both paths.
+     */
+    protected appendVectorValue(ctx: QueryContext, value: readonly unknown[]): void;
+    /**
+     * 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.
+     */
+    getInlineVectorIndexDeclaration(index: IndexSchema): 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,36 +1,35 @@
 import { jsonPath } from '../dialect/jsonSql.js';
 import { MysqlLikeSqlDialect } from '../dialect/mysqlLikeSqlDialect.js';
+import { isVectorFieldType } from '../dialect/vectorCast.js';
 import { getMeta } from '../entity/index.js';
 export class MariaDialect extends MysqlLikeSqlDialect {
     dialectName = 'mariadb';
     // MariaDB 10.5+ supports `INSERT ... RETURNING` (see `insert` below), so IDs are exact per row.
     insertIdSource = 'returning';
-    constructor(options = {}) {
-        super({
-            ...options,
-            driverCapabilities: {
-                vectorSupportsLength: true,
-                ...options.driverCapabilities,
-            },
-        });
-    }
-    insert(ctx, entity, payload, opts) {
-        super.insert(ctx, entity, payload, opts);
-        ctx.append(' ' + this.returningId(entity));
-    }
+    /**
+     * 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']);
+    /** Unlike MySQL: `VECTOR(n)` takes its dimension, and its vector index is declared inline. */
+    featureOverrides = {
+        vectorSupportsLength: true,
+        inlineVectorIndex: true,
+    };
     upsert(ctx, entity, conflictPaths, payload) {
         const meta = getMeta(entity);
         const updateCtx = this.createContext();
         const update = this.getUpsertUpdateAssignments(updateCtx, meta, conflictPaths, payload, (name) => `VALUES(${name})`);
         const returning = this.returningId(entity);
         if (update) {
-            super.insert(ctx, entity, payload);
+            this.appendInsertValues(ctx, entity, payload);
             ctx.append(` ON DUPLICATE KEY UPDATE ${update} ${returning}`);
             ctx.pushValue(...updateCtx.values);
         }
         else {
             const insertCtx = this.createContext();
-            super.insert(insertCtx, entity, payload);
+            this.appendInsertValues(insertCtx, entity, payload);
             ctx.append(insertCtx.sql.replace(/^INSERT/, 'INSERT IGNORE'));
             ctx.append(' ' + returning);
             ctx.pushValue(...insertCtx.values);
@@ -61,9 +60,49 @@ 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'],
     ]);
+    /**
+     * 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
+     * `VEC_DISTANCE_COSINE` with `Illegal parameter data type varchar`. `VEC_FromText` is the
+     * conversion, needed on both paths.
+     */
+    appendVectorValue(ctx, value) {
+        ctx.append('VEC_FromText(');
+        super.appendVectorValue(ctx, value);
+        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.
+     */
+    getInlineVectorIndexDeclaration(index) {
+        const columns = index.columns.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}`;
+        }
+        return clause;
+    }
+    /** The reverse: selecting a `VECTOR` column raw yields that blob, so it is read back as text. */
+    selectFieldExpr(escapedColumn, field) {
+        return isVectorFieldType(field.type) ? `VEC_ToText(${escapedColumn})` : escapedColumn;
+    }
 }

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

@@ -6,9 +6,9 @@
  * - MigrationBuilder: Execute DDL operations (for integration tests/runtime)
  */
 import type { ForeignKeyAction } from '../../schema/types.js';
-import type { NamingStrategy } from '../../type/namingStrategy.js';
+import type { IndexColumnInput, IndexOptions } from '../../type/index.js';
 import type { SqlQuerier } from '../../type/querier.js';
-import type { AnyMigrationOperation, IAlterTableBuilder, IColumnBuilder, IMigrationBuilder, ITableBuilder } from './types.js';
+import type { AnyMigrationOperation, IAlterTableBuilder, IColumnBuilder, IColumnFactory, IMigrationBuilder, ITableBuilder } from './types.js';
 /**
  * Records migration operations without executing them.
  * Use for migration code generation and dry-run scenarios.
@@ -22,15 +22,11 @@ export declare class OperationRecorder implements IMigrationBuilder {
     }): Promise<void>;
     renameTable(oldName: string, newName: string): Promise<void>;
     alterTable(name: string, callback: (table: IAlterTableBuilder) => void): Promise<void>;
-    addColumn(tableName: string, columnName: string, callback: (column: IColumnBuilder) => void): Promise<void>;
+    addColumn(tableName: string, callback: (columns: IColumnFactory) => IColumnBuilder): Promise<void>;
     dropColumn(tableName: string, columnName: string): Promise<void>;
-    alterColumn(tableName: string, columnName: string, callback: (column: IColumnBuilder) => void): Promise<void>;
+    alterColumn(tableName: string, callback: (columns: IColumnFactory) => IColumnBuilder): Promise<void>;
     renameColumn(tableName: string, oldName: string, newName: string): Promise<void>;
-    createIndex(tableName: string, columns: string[], options?: {
-        name?: string;
-        unique?: boolean;
-        where?: 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: {
         table: string;
@@ -45,13 +41,6 @@ export declare class OperationRecorder implements IMigrationBuilder {
     getOperations(): AnyMigrationOperation[];
     recordOperationSync(operation: AnyMigrationOperation): void;
 }
-/**
- * Options for the migration builder.
- */
-export interface MigrationBuilderOptions {
-    /** Custom naming strategy for generated SQL */
-    namingStrategy?: NamingStrategy;
-}
 /**
  * Executes DDL operations via a SQL querier.
  * Use for integration tests and runtime schema management.
@@ -70,7 +59,7 @@ export interface MigrationBuilderOptions {
 export declare class MigrationBuilder extends OperationRecorder {
     private readonly querier;
     private readonly sqlGenerator;
-    constructor(querier: SqlQuerier, options?: MigrationBuilderOptions);
+    constructor(querier: SqlQuerier);
     recordOperationSync(operation: AnyMigrationOperation): void;
     raw(sql: string): Promise<void>;
     createTable(name: string, callback: (table: ITableBuilder) => void): Promise<void>;
@@ -79,15 +68,11 @@ export declare class MigrationBuilder extends OperationRecorder {
         cascade?: boolean;
     }): Promise<void>;
     renameTable(oldName: string, newName: string): Promise<void>;
-    addColumn(tableName: string, columnName: string, callback: (column: IColumnBuilder) => void): Promise<void>;
+    addColumn(tableName: string, callback: (columns: IColumnFactory) => IColumnBuilder): Promise<void>;
     dropColumn(tableName: string, columnName: string): Promise<void>;
-    alterColumn(tableName: string, columnName: string, callback: (column: IColumnBuilder) => void): Promise<void>;
+    alterColumn(tableName: string, callback: (columns: IColumnFactory) => IColumnBuilder): Promise<void>;
     renameColumn(tableName: string, oldName: string, newName: string): Promise<void>;
-    createIndex(tableName: string, columns: string[], options?: {
-        name?: string;
-        unique?: boolean;
-        where?: 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: {
         table: string;
@@ -102,8 +87,3 @@ export declare class MigrationBuilder extends OperationRecorder {
     private execute;
     private operationToSql;
 }
-/**
- * Create an operation recorder for dry-run (recording only).
- * @deprecated Use `new OperationRecorder()` directly
- */
-export declare function createDryRunBuilder(): OperationRecorder;