uql-orm 0.21.0 → 0.23.0

package/dist/dialect/abstractSqlDialect.js

@@ -1,12 +1,13 @@
 import { getMeta } from '../entity/index.js';
 import { QueryRaw, RAW_ALIAS, RAW_VALUE, } from '../type/index.js';
-import { asSelectMap, buildQueryWhereAsMap, buildSortMap, escapeSqlId, fillOnFields, filterFieldKeys, flatObject, getFieldKeys, getInsertFieldKeys, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, hasMultipleKeys, isJsonType, isJsonUpdateOp, isOperatorObject, isOperatorOnlyObject, isPopulatingRelations, isVectorSearch, normalizeScalarFieldSelection, parseGroupMap, parseRelationAtKey, parseRelationSize, raw, someValue, withoutSoftDeleteFilter, } from '../util/index.js';
+import { asSelectMap, buildQueryWhereAsMap, buildSortMap, escapeSqlId, fillOnFields, filterFieldKeys, flatObject, getInsertFieldKeys, getKeys, getRelationRequestSummary, getSoftDeleteValue, hasKeys, hasMultipleKeys, isJsonType, isJsonUpdateOp, isOperatorObject, isOperatorOnlyObject, isPopulatingRelations, isVectorSearch, normalizeScalarFieldSelection, parseGroupMap, parseRelationAtKey, parseRelationSize, raw, someValue, withoutSoftDeleteFilter, } from '../util/index.js';
 import { escapeAnsiSqlLiteral, escapeSingleQuotes } from '../util/sqlLiteral.js';
+import { IndexSqlDialect } from './indexSqlDialect.js';
 import { buildElemMatchConditions } from './jsonArrayElemMatchUtils.js';
 import { JSON_ELEM_ALIAS_PREFIX, jsonElemExists } from './jsonSql.js';
 import { SqlQueryContext } from './queryContext.js';
-import { VectorSqlDialect } from './vectorSqlDialect.js';
-export class AbstractSqlDialect extends VectorSqlDialect {
+import { isVectorFieldType } from './vectorCast.js';
+export class AbstractSqlDialect extends IndexSqlDialect {
     isolationLevelStrategy = 'inline';
     alterColumnStrategy = 'single-statement';
     alterColumnSyntax = 'ALTER COLUMN';
@@ -135,7 +136,6 @@ export class AbstractSqlDialect extends VectorSqlDialect {
                 const field = meta.fields[key];
                 if (!field)
                     return;
-                const columnName = this.resolveColumnName(key, field);
                 if (field.virtual) {
                     this.getRawValue(ctx, {
                         value: raw(field.virtual[RAW_VALUE], key),
@@ -143,17 +143,35 @@ export class AbstractSqlDialect extends VectorSqlDialect {
                         escapedPrefix,
                         autoPrefixAlias: opts.autoPrefixAlias,
                     });
+                    return;
                 }
-                else {
-                    ctx.append(escapedPrefix + this.escapeId(columnName));
-                }
-                if (!field.virtual && (columnName !== key || opts.autoPrefixAlias)) {
-                    const aliasStr = prefix + key;
-                    ctx.append(' ' + this.escapeId(aliasStr, true));
+                const columnName = this.resolveColumnName(key, field);
+                const column = escapedPrefix + this.escapeId(columnName);
+                const expr = this.selectFieldExpr(column, field);
+                ctx.append(expr);
+                // An expression needs the alias too, or the row comes back keyed by the expression text.
+                if (expr !== column || columnName !== key || opts.autoPrefixAlias) {
+                    ctx.append(' ' + this.escapeId(prefix + key, true));
                 }
             }
         });
     }
+    /**
+     * The expression a scalar field is read through, the plain column by default. MariaDB reads a
+     * vector column back with `VEC_ToText`, since selecting it raw yields its binary form.
+     */
+    selectFieldExpr(escapedColumn, _field) {
+        return escapedColumn;
+    }
+    /**
+     * The `$text` full-text predicate, which every engine spells differently: `MATCH ... AGAINST`
+     * (MySQL family), `to_tsvector @@ websearch_to_tsquery` (Postgres-wire), an FTS5 `MATCH` against
+     * the table itself (SQLite). No portable form exists, so a dialect without one says so here rather
+     * than inheriting another engine's syntax.
+     */
+    appendTextSearch(_ctx, _entity, _meta, _search) {
+        throw new TypeError(`${this.dialectName} does not support $text full-text search`);
+    }
     select(ctx, entity, select, exclude, populate, opts = {}, distinct, sort) {
         const meta = getMeta(entity);
         const tableName = this.resolveTableName(entity, meta);
@@ -296,16 +314,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
             return;
         }
         if (key === '$text') {
-            const search = val;
-            const searchFields = search.$fields ?? getFieldKeys(meta.fields);
-            const fields = searchFields.map((fKey) => {
-                const field = meta.fields[fKey];
-                const columnName = this.resolveColumnName(fKey, field);
-                return this.escapeId(columnName);
-            });
-            ctx.append(`MATCH(${fields.join(', ')}) AGAINST(`);
-            ctx.addValue(search.$value);
-            ctx.append(')');
+            this.appendTextSearch(ctx, entity, meta, val);
             return;
         }
         if (key === '$and' || key === '$or' || key === '$not' || key === '$nor') {
@@ -911,6 +920,18 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         this.search(ctx, entity, q, opts);
     }
     insert(ctx, entity, payload, opts) {
+        this.appendInsertValues(ctx, entity, payload, opts);
+        // Every engine whose ids come back from the statement itself wants the same clause, so it is
+        // appended once here instead of in an identical `insert` override per dialect.
+        if (this.insertIdSource === 'returning') {
+            ctx.append(` ${this.returningId(entity)}`);
+        }
+    }
+    /**
+     * `INSERT INTO ... VALUES (...)` and nothing more. The upsert builders extend this rather than
+     * {@link insert}: their own clause has to come before the `RETURNING`, not after it.
+     */
+    appendInsertValues(ctx, entity, payload, opts) {
         const meta = getMeta(entity);
         const payloads = fillOnFields(meta, payload, 'onInsert');
         const keys = getInsertFieldKeys(meta, payloads);
@@ -919,10 +940,13 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         const width = keys.length;
         const fields = new Array(width);
         const columns = new Array(width);
+        const kinds = new Array(width);
         for (let i = 0; i < width; i++) {
             const key = keys[i];
-            fields[i] = meta.fields[key];
+            const field = meta.fields[key];
+            fields[i] = field;
             columns[i] = this.escapedColumnName(meta, key);
+            kinds[i] = this.persistKind(field);
         }
         const tableName = this.resolveTableName(entity, meta);
         ctx.append(`INSERT INTO ${this.escapeId(tableName)} (${columns.join(', ')}) VALUES (`);
@@ -939,8 +963,12 @@ export class AbstractSqlDialect extends VectorSqlDialect {
                 if (value === undefined) {
                     this.appendDefaultInsertValue(ctx, fields[i]);
                 }
+                else if (kinds[i] === 'plain' && !(value instanceof QueryRaw)) {
+                    // The overwhelmingly common case in a bulk insert, so it binds without a dispatch.
+                    ctx.addValue(value);
+                }
                 else {
-                    this.formatPersistableValue(ctx, fields[i], value);
+                    this.writePersistableValue(ctx, kinds[i], fields[i], value);
                 }
             }
         }
@@ -978,22 +1006,29 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         }
         this.search(ctx, entity, q, opts);
     }
-    upsert(ctx, entity, conflictPaths, payload) {
+    /**
+     * `INSERT ... ON CONFLICT (...) DO UPDATE/NOTHING RETURNING ...`, which SQLite adopted from Postgres
+     * and which every dialect here speaks except the MySQL family (see {@link MysqlLikeSqlDialect}).
+     *
+     * Two orderings matter, and they pull in opposite directions. The assignments are computed *before*
+     * the insert, because `appendInsertValues` fills `onInsert` fields into the payload and a column that
+     * exists only there - `createdAt` - must not join the update set. Their bound values are pushed
+     * *after* it, because a `?` placeholder is positional and the clause comes last in the statement.
+     * {@link PgLikeSqlDialect} overrides this: `$N` placeholders make array order irrelevant, so it can
+     * bind into the main context and skip the second one.
+     */
+    upsert(ctx, entity, conflictPaths, payload, extraReturning = '') {
         const meta = getMeta(entity);
         const updateCtx = this.createContext();
-        const update = this.getUpsertUpdateAssignments(updateCtx, meta, conflictPaths, payload, (name) => `VALUES(${name})`);
-        if (update) {
-            this.insert(ctx, entity, payload);
-            ctx.append(` ON DUPLICATE KEY UPDATE ${update}`);
-            ctx.pushValue(...updateCtx.values);
-        }
-        else {
-            const insertCtx = this.createContext();
-            this.insert(insertCtx, entity, payload);
-            ctx.append(insertCtx.sql.replace(/^INSERT/, 'INSERT IGNORE'));
-            ctx.pushValue(...insertCtx.values);
-        }
-    }
+        const update = this.getUpsertUpdateAssignments(updateCtx, meta, conflictPaths, payload, this.upsertExcluded);
+        const keys = this.getUpsertConflictPathsStr(meta, conflictPaths);
+        const onConflict = update ? `DO UPDATE SET ${update}` : 'DO NOTHING';
+        this.appendInsertValues(ctx, entity, payload);
+        ctx.append(` ON CONFLICT (${keys}) ${onConflict} ${this.returningId(entity)}${extraReturning}`);
+        ctx.pushValue(...updateCtx.values);
+    }
+    /** How an `ON CONFLICT` assignment reads the row that was being inserted. */
+    upsertExcluded = (columnName) => `EXCLUDED.${columnName}`;
     getUpsertUpdateAssignments(ctx, meta, conflictPaths, payload, callback) {
         const sample = Array.isArray(payload) ? payload[0] : payload;
         const cloned = { ...sample };
@@ -1045,22 +1080,38 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         return escapeSqlId(val, this.escapeIdChar, forbidQualified, addDot);
     }
     /**
-     * The single type dispatch for a persisted value. Dialects override {@link appendJsonValue} and
-     * {@link appendVectorValue} rather than this, so the chain runs once per value - overriding this
-     * and delegating back to `super` ran every check twice, measurably slowing every INSERT/UPDATE.
+     * Bind one persisted value, classifying its column on the spot. Dialects override
+     * {@link appendJsonValue} and {@link appendVectorValue} rather than this, so the chain runs once per
+     * value - overriding this and delegating back to `super` ran every check twice, measurably slowing
+     * every INSERT/UPDATE.
      */
     formatPersistableValue(ctx, field, value) {
+        this.writePersistableValue(ctx, this.persistKind(field), field, value);
+    }
+    /**
+     * How a column's values are written. A function of the column, not of the value, so a bulk insert
+     * classifies each column once instead of re-deciding per row: a 20-row, 6-column insert asked
+     * `isJsonType` and `isVectorFieldType` 120 times to get the same six answers.
+     */
+    persistKind(field) {
+        const type = field?.type;
+        if (isJsonType(type)) {
+            return 'json';
+        }
+        return isVectorFieldType(type) ? 'vector' : 'plain';
+    }
+    /** The one type dispatch for a persisted value, over a column kind decided by the caller. */
+    writePersistableValue(ctx, kind, field, value) {
         if (value instanceof QueryRaw) {
             this.getRawValue(ctx, { value });
             return;
         }
-        const type = field?.type;
-        if (isJsonType(type)) {
-            this.appendJsonValue(ctx, value, type);
+        if (kind === 'json') {
+            this.appendJsonValue(ctx, value, field?.type);
             return;
         }
-        if (type === 'vector' && Array.isArray(value)) {
-            this.appendVectorValue(ctx, value);
+        if (kind === 'vector' && Array.isArray(value)) {
+            this.appendVectorValue(ctx, value, field);
             return;
         }
         ctx.addValue(value);
@@ -1068,9 +1119,6 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     appendJsonValue(ctx, value, _type) {
         ctx.addValue(value == null ? null : JSON.stringify(value));
     }
-    appendVectorValue(ctx, value) {
-        ctx.addValue(`[${value.join(',')}]`);
-    }
     /**
      * Reads `operand` as a JSON value. Passing the `?` placeholder yields the cast for a bound
      * parameter, and passing an expression re-reads text as JSON - the same SQL either way, which is

package/dist/dialect/index.d.ts

@@ -4,5 +4,6 @@ export { PostgresDialect } from '../postgres/postgresDialect.js';
 export { SqliteDialect } from '../sqlite/sqliteDialect.js';
 export * from './abstractDialect.js';
 export * from './abstractSqlDialect.js';
+export * from './indexSqlDialect.js';
 export * from './mysqlLikeSqlDialect.js';
 export * from './queryContext.js';

package/dist/dialect/index.js

@@ -4,5 +4,6 @@ export { PostgresDialect } from '../postgres/postgresDialect.js';
 export { SqliteDialect } from '../sqlite/sqliteDialect.js';
 export * from './abstractDialect.js';
 export * from './abstractSqlDialect.js';
+export * from './indexSqlDialect.js';
 export * from './mysqlLikeSqlDialect.js';
 export * from './queryContext.js';

package/dist/dialect/indexSqlDialect.d.ts

@@ -0,0 +1,57 @@
+import { type IndexColumnSchema, type IndexFeature, type IndexSchema } from '../type/index.js';
+import { VectorSqlDialect } from './vectorSqlDialect.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.
+ */
+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.
+     */
+    getCreateIndexStatement(tableName: string, index: IndexSchema, opts?: {
+        ifNotExists?: boolean;
+    }): string;
+    /**
+     * Index features this dialect can express. Everything here is supported by at least one engine and
+     * refused by at least one other, so an index asking for a missing one is rejected rather than
+     * emitted: each of them is a hard error at the server, not a slower plan.
+     */
+    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.
+     */
+    getInlineVectorIndexDeclaration(index: IndexSchema): string;
+    /** Only CockroachDB's native vector index replaces the `INDEX` keyword. */
+    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.
+     */
+    protected indexColumnTarget(entry: IndexColumnSchema): 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. */
+    protected indexColumnOrder(entry: IndexColumnSchema): string;
+    /** ` INCLUDE (...)`: non-key columns stored for index-only scans. Postgres-wire only. */
+    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 = ...)`. */
+    protected indexTuning(_index: IndexSchema): string;
+    /**
+     * The partial-index predicate. Dialects without partial indexes throw instead of dropping it:
+     * silently widening a partial unique index changes which rows the database accepts.
+     */
+    protected indexPredicate(index: IndexSchema): string;
+}

package/dist/dialect/indexSqlDialect.js

@@ -0,0 +1,101 @@
+import { INDEX_FEATURE_LABELS } from '../type/index.js';
+import { VectorSqlDialect } from './vectorSqlDialect.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.
+ */
+export 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.
+     */
+    getCreateIndexStatement(tableName, index, opts = {}) {
+        this.assertIndexFeatures(index);
+        const unique = index.unique ? 'UNIQUE ' : '';
+        const ifNotExists = (opts.ifNotExists ?? this.features.indexIfNotExists) ? 'IF NOT EXISTS ' : '';
+        const columns = index.columns.map((entry) => this.indexColumn(entry, index)).join(', ');
+        return (`CREATE ${unique}${this.indexKeyword(index)} ${ifNotExists}${this.escapeId(index.name)} ` +
+            `ON ${this.escapeId(tableName)}${this.indexAccessMethod(index)} (${columns})` +
+            `${this.indexInclude(index)}${this.indexTuning(index)}${this.indexPredicate(index)};`);
+    }
+    /**
+     * Index features this dialect can express. Everything here is supported by at least one engine and
+     * refused by at least one other, so an index asking for a missing one is rejected rather than
+     * emitted: each of them is a hard error at the server, not a slower plan.
+     */
+    indexFeatures = new Set(['expression']);
+    assertIndexFeatures(index) {
+        const requested = [
+            ['expression', index.columns.some((entry) => entry.expression)],
+            ['prefixLength', index.columns.some((entry) => entry.length !== undefined)],
+            ['nullsOrder', index.columns.some((entry) => entry.nulls !== undefined)],
+            ['opsClass', index.columns.some((entry) => entry.opsClass !== undefined)],
+            ['include', Boolean(index.include?.length)],
+        ];
+        for (const [feature, needed] of requested) {
+            if (needed && !this.indexFeatures.has(feature)) {
+                throw new TypeError(`${this.dialectName} does not support ${INDEX_FEATURE_LABELS[feature]} (index "${index.name}")`);
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    getInlineVectorIndexDeclaration(index) {
+        throw new TypeError(`${this.dialectName} has no inline vector index (index "${index.name}")`);
+    }
+    /** Only CockroachDB's native vector index replaces the `INDEX` keyword. */
+    indexKeyword(_index) {
+        return 'INDEX';
+    }
+    /** One index entry: what is indexed, its operator class if any, then its stored order. */
+    indexColumn(entry, index) {
+        return `${this.indexColumnTarget(entry)}${this.indexColumnOpsClass(entry, index)}${this.indexColumnOrder(entry)}`;
+    }
+    /**
+     * 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.
+     */
+    indexColumnTarget(entry) {
+        if (entry.expression) {
+            return `(${entry.column})`;
+        }
+        const column = this.escapeId(entry.column);
+        return entry.length === undefined ? column : `${column}(${entry.length})`;
+    }
+    /** Postgres-wire dialects put a vector or user-declared operator class here. */
+    indexColumnOpsClass(_entry, _index) {
+        return '';
+    }
+    /** `ASC` is every engine's default, so only `DESC` is worth emitting. */
+    indexColumnOrder(entry) {
+        const order = entry.order === 'desc' ? ' DESC' : '';
+        return entry.nulls ? `${order} NULLS ${entry.nulls.toUpperCase()}` : order;
+    }
+    /** ` INCLUDE (...)`: non-key columns stored for index-only scans. Postgres-wire only. */
+    indexInclude(_index) {
+        return '';
+    }
+    /** ` USING <method>`, which SQLite's grammar has no place for at all. */
+    indexAccessMethod(_index) {
+        return '';
+    }
+    /** pgvector's ` WITH (m = ..., ef_construction = ..., lists = ...)`. */
+    indexTuning(_index) {
+        return '';
+    }
+    /**
+     * The partial-index predicate. Dialects without partial indexes throw instead of dropping it:
+     * silently widening a partial unique index changes which rows the database accepts.
+     */
+    indexPredicate(index) {
+        return index.where ? ` WHERE ${index.where}` : '';
+    }
+}

package/dist/dialect/mysqlLikeSqlDialect.d.ts

@@ -1,4 +1,4 @@
-import type { DialectFeatures, FieldOptions, InsertIdSource, QueryContext, QuerySizeComparisonOps } from '../type/index.js';
+import type { DialectFeatures, EntityMeta, FieldOptions, IndexFeature, IndexSchema, InsertIdSource, QueryConflictPaths, QueryContext, QuerySizeComparisonOps, QueryTextSearchOptions, Type } from '../type/index.js';
 import { AbstractSqlDialect } from './abstractSqlDialect.js';
 /**
  * Shared JSON-array / JSON-object operator implementation between MySQL and MariaDB.
@@ -26,8 +26,33 @@ export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
     readonly alterColumnSyntax = "MODIFY COLUMN";
     readonly booleanLiteral = "integer";
     readonly insertIdSource: InsertIdSource;
+    /**
+     * `INSERT ... ON DUPLICATE KEY UPDATE`, and `INSERT IGNORE` when every non-conflict column is itself a
+     * conflict key so there is nothing to assign. Neither form takes a conflict target: MySQL picks the
+     * unique index for you.
+     *
+     * The update assignments are built into their own context and pushed afterwards, since they read
+     * `VALUES(col)` rather than binding, and any value they *do* bind (an `onUpdate` field absent from the
+     * payload) has to land after the insert's for a `?`-placeholder driver.
+     */
+    upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[]): void;
     readonly maxBindValues: number;
     escape(value: unknown): string;
+    /**
+     * `MATCH(cols) AGAINST(?)`, which needs a `FULLTEXT` index over exactly those columns: without one
+     * the server answers "Can't find FULLTEXT index matching the column list". Declare it with
+     * `@Index([...], { type: 'fulltext' })`.
+     */
+    protected appendTextSearch<E>(ctx: QueryContext, _entity: Type<E>, meta: EntityMeta<E>, search: QueryTextSearchOptions<E>): void;
+    /**
+     * 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.
+     */
+    protected indexKeyword(index: IndexSchema): string;
+    protected readonly indexFeatures: Set<IndexFeature>;
+    protected indexAccessMethod(index: IndexSchema): string;
+    /** Neither MySQL nor MariaDB has partial indexes, and quietly widening one changes which rows it rejects. */
+    protected indexPredicate(index: IndexSchema): string;
     protected numericCast(expr: string): string;
     protected ilikeExpr(f: string, ph: string): string;
     protected neExpr(field: string, ph: string): string;

package/dist/dialect/mysqlLikeSqlDialect.js

@@ -1,3 +1,5 @@
+import { getMeta } from '../entity/index.js';
+import { getFieldKeys } from '../util/index.js';
 import { escapeMysqlSqlLiteral, escapeSingleQuotes } from '../util/sqlLiteral.js';
 import { AbstractSqlDialect } from './abstractSqlDialect.js';
 import { JSON_PULL_ALIAS, jsonAssignCall, jsonPath, jsonRemoveCall, jsonSetTarget } from './jsonSql.js';
@@ -23,7 +25,7 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
         renameColumn: true,
         foreignKeyAlter: true,
         columnComment: true,
-        vectorIndexStyle: 'inline',
+        inlineVectorIndex: false,
         vectorSupportsLength: false,
         supportsTimestamptz: false,
         defaultStringAsText: false,
@@ -43,10 +45,64 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
     // No `RETURNING` support, so multi-row insert IDs are inferred from the header - see the
     // `innodb_autoinc_lock_mode` caveat on `buildUpdateResult` in `util/sql.util.ts`.
     insertIdSource = 'firstId';
+    /**
+     * `INSERT ... ON DUPLICATE KEY UPDATE`, and `INSERT IGNORE` when every non-conflict column is itself a
+     * conflict key so there is nothing to assign. Neither form takes a conflict target: MySQL picks the
+     * unique index for you.
+     *
+     * The update assignments are built into their own context and pushed afterwards, since they read
+     * `VALUES(col)` rather than binding, and any value they *do* bind (an `onUpdate` field absent from the
+     * payload) has to land after the insert's for a `?`-placeholder driver.
+     */
+    upsert(ctx, entity, conflictPaths, payload) {
+        const meta = getMeta(entity);
+        const updateCtx = this.createContext();
+        const update = this.getUpsertUpdateAssignments(updateCtx, meta, conflictPaths, payload, (name) => `VALUES(${name})`);
+        if (update) {
+            this.appendInsertValues(ctx, entity, payload);
+            ctx.append(` ON DUPLICATE KEY UPDATE ${update}`);
+            ctx.pushValue(...updateCtx.values);
+            return;
+        }
+        const insertCtx = this.createContext();
+        this.appendInsertValues(insertCtx, entity, payload);
+        ctx.append(insertCtx.sql.replace(/^INSERT/, 'INSERT IGNORE'));
+        ctx.pushValue(...insertCtx.values);
+    }
     maxBindValues = 65535;
     escape(value) {
         return escapeMysqlSqlLiteral(value);
     }
+    /**
+     * `MATCH(cols) AGAINST(?)`, which needs a `FULLTEXT` index over exactly those columns: without one
+     * the server answers "Can't find FULLTEXT index matching the column list". Declare it with
+     * `@Index([...], { type: 'fulltext' })`.
+     */
+    appendTextSearch(ctx, _entity, meta, search) {
+        const searchFields = search.$fields ?? getFieldKeys(meta.fields);
+        const columns = searchFields.map((key) => this.escapeId(this.resolveColumnName(key, meta.fields[key])));
+        ctx.append(`MATCH(${columns.join(', ')}) AGAINST(`);
+        ctx.addValue(search.$value);
+        ctx.append(')');
+    }
+    /**
+     * 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.
+     */
+    indexKeyword(index) {
+        return index.type === 'fulltext' ? 'FULLTEXT INDEX' : super.indexKeyword(index);
+    }
+    indexFeatures = new Set(['expression', 'prefixLength']);
+    indexAccessMethod(index) {
+        return index.type && index.type !== 'fulltext' ? ` USING ${index.type}` : '';
+    }
+    /** Neither MySQL nor MariaDB has partial indexes, and quietly widening one changes which rows it rejects. */
+    indexPredicate(index) {
+        if (index.where) {
+            throw new TypeError(`${this.dialectName} does not support partial indexes (index "${index.name}" declares a "where" condition)`);
+        }
+        return '';
+    }
     numericCast(expr) {
         return `CAST(${expr} AS DECIMAL)`;
     }

package/dist/dialect/pgLikeSqlDialect.d.ts

@@ -1,4 +1,4 @@
-import { type DialectFeatures, type EntityMeta, type FieldOptions, type JsonColumnType, type QueryComparisonOptions, type QueryConflictPaths, type QueryContext, type QueryOptions, type QuerySizeComparisonOps, type QueryVectorSearch, type Type, type VectorDistance } from '../type/index.js';
+import { type DialectFeatures, type EntityMeta, type FieldOptions, type IndexColumnSchema, type IndexFeature, type IndexSchema, type JsonColumnType, type QueryConflictPaths, type QueryContext, type QuerySizeComparisonOps, type QueryTextSearchOptions, type QueryVectorSearch, type Type, type VectorDistance } from '../type/index.js';
 import { AbstractSqlDialect } from './abstractSqlDialect.js';
 /**
  * Shared AST/quoting/JSONB/full-text-search/vector-search implementation between Postgres and
@@ -21,25 +21,43 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
     readonly alterColumnStrategy = "separate-clauses";
     readonly insertIdSource = "returning";
     readonly maxBindValues: number;
-    readonly vectorOpsClass: ReadonlyMap<VectorDistance, string> | undefined;
+    /**
+     * Each metric's pgvector distance operator and the operator-class suffix its index takes, in one
+     * place so a dialect cannot end up with the operator but not the opclass. The key set is the single
+     * source of truth for which metrics the dialect supports at all: CockroachDB narrows it to three.
+     */
+    readonly vectorMetrics: ReadonlyMap<VectorDistance, {
+        op: string;
+        opsSuffix: string;
+    }>;
     normalizeValue(value: unknown): unknown;
+    /** pgvector's own index types; CockroachDB's native one widens this. */
+    protected isVectorIndex(index: IndexSchema): boolean;
+    protected indexAccessMethod(index: IndexSchema): string;
+    protected readonly indexFeatures: Set<IndexFeature>;
+    /**
+     * A vector index's operator class is named `{type}_{metric}_ops`: an index on a `halfvec` column
+     * needs `halfvec_cosine_ops`, and `vector_cosine_ops` there is rejected outright. An unsupported
+     * distance throws rather than being omitted, since a bare `USING hnsw ("embedding")` would build
+     * with the dialect's default metric instead of the one requested, with nothing signalling it.
+     * Everything else takes the operator class the entry declares, e.g. `jsonb_path_ops` for GIN.
+     */
+    protected indexColumnOpsClass(entry: IndexColumnSchema, index: IndexSchema): string;
+    protected indexInclude(index: IndexSchema): string;
+    protected indexTuning(index: IndexSchema): string;
     placeholder(index: number): string;
-    insert<E>(ctx: QueryContext, entity: Type<E>, payload: E | E[], opts?: QueryOptions): void;
-    upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[]): void;
     /**
-     * Shared `INSERT ... ON CONFLICT (...) DO UPDATE/NOTHING RETURNING ...` builder, assembling
-     * everything upfront rather than handing back fragments, for the `$N`-placeholder Postgres-wire
-     * dialects. `extraReturning` lets {@link PostgresDialect} append `(xmax = 0) AS "_created"` to
-     * detect insert-vs-update; CockroachDB has no `xmax`/`ctid` system columns, so it uses the default
-     * (empty) and `created` stays `undefined` in the result.
+     * The same statement as the base, binding the assignments into the main context instead of a second
+     * one: `$N` placeholders carry their own index, so the values need not be in statement order, and
+     * computing them first is what keeps `appendInsertValues`' `onInsert` fields out of the update set.
      */
-    protected buildUpsertOnConflict<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[], extraReturning?: string): void;
+    upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[], extraReturning?: string): void;
     /**
-     * Full-text search: `to_tsvector(...) @@ websearch_to_tsquery(...)`. `websearch_to_tsquery` takes
-     * free-form user input (quoted phrases, `or`, `-negation`) and never raises a syntax error, unlike
-     * `to_tsquery`, which rejects anything unparseable - including a plain two-word search.
+     * `to_tsvector(...) @@ websearch_to_tsquery(...)`. `websearch_to_tsquery` takes free-form user input
+     * (quoted phrases, `or`, `-negation`) and never raises a syntax error, unlike `to_tsquery`, which
+     * rejects anything unparseable - including a plain two-word search.
      */
-    compare<E>(ctx: QueryContext, entity: Type<E>, key: string, val: unknown, opts?: QueryComparisonOptions): void;
+    protected appendTextSearch<E>(ctx: QueryContext, _entity: Type<E>, meta: EntityMeta<E>, search: QueryTextSearchOptions<E>): void;
     protected jsonAll(ctx: QueryContext, jsonField: string, value: unknown): string;
     protected jsonSize(ctx: QueryContext, jsonField: string, value: number | QuerySizeComparisonOps): string;
     /**
@@ -54,7 +72,11 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
     protected formatIn(ctx: QueryContext, values: unknown[], negate: boolean): string;
     protected numericCast(expr: string): string;
     protected appendJsonValue(ctx: QueryContext, value: unknown, type: JsonColumnType): void;
-    protected appendVectorValue(ctx: QueryContext, value: readonly unknown[]): void;
+    /**
+     * pgvector needs the cast to pick the right type, and `sparsevec` needs its own literal: the dense
+     * `[1,0,2]` every other type takes is rejected as "invalid input syntax for type sparsevec".
+     */
+    protected appendVectorValue(ctx: QueryContext, value: readonly unknown[], field?: FieldOptions): void;
     /**
      * `create_if_missing => false` keeps an absent key (and a NULL column) untouched; `WITH
      * ORDINALITY` keeps the surviving elements in their original order.
@@ -70,13 +92,6 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
      * Helper to add a JSON value to context with appropriate stringification and cast.
      */
     private jsonVal;
-    /**
-     * pgvector distance operators. Not every dialect supports every metric - see
-     * {@link CockroachDialect.vectorOpsClass} for which ones each dialect actually has; the
-     * `vectorOpsClass` key set (checked in `appendVectorSort` below via `vectorOpsClass.get`)
-     * is the single source of truth for that, not this map.
-     */
-    private static readonly VECTOR_OPS;
     /** Emit a pgvector-style distance expression: `"col" <op> $N::<vectorType>`. */
     protected appendVectorSort<E>(ctx: QueryContext, meta: EntityMeta<E>, key: string, search: QueryVectorSearch): void;
 }