uql-orm 0.37.1 → 0.39.0

package/dist/migrate/ddl/indexDdl.js

@@ -0,0 +1,126 @@
+import { jsonTypeMode } from '../../dialect/jsonSql.js';
+import { INDEX_FEATURE_LABELS, } from '../../type/index.js';
+import { getKeys } from '../../util/index.js';
+/**
+ * What in an index asks for each feature. A `Record` over the feature union rather than a list, so a
+ * feature added to {@link INDEX_FEATURE_LABELS} cannot reach a dialect without the test that decides
+ * whether an index wants it - which is how a JSON path once slipped past the entry comparison.
+ */
+const INDEX_FEATURE_PROBES = {
+    expression: (index) => index.entries.some((entry) => entry.expression),
+    jsonPath: (index) => index.entries.some((entry) => entry.jsonPath),
+    jsonArray: (index) => index.entries.some((entry) => entry.jsonArray),
+    partial: (index) => index.where !== undefined,
+    prefixLength: (index) => index.entries.some((entry) => entry.length !== undefined),
+    nullsOrder: (index) => index.entries.some((entry) => entry.nulls !== undefined),
+    opsClass: (index) => index.entries.some((entry) => entry.opsClass !== undefined),
+    include: (index) => Boolean(index.include?.length),
+};
+/**
+ * `CREATE INDEX` for SQL dialects: the statement and the fragments each engine spells differently.
+ * 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 class IndexDdl {
+    dialect;
+    constructor(dialect) {
+        this.dialect = dialect;
+    }
+    getCreateIndexStatement(tableName, index, opts = {}) {
+        this.assertIndexFeatures(index);
+        const unique = index.unique ? 'UNIQUE ' : '';
+        const ifNotExists = (opts.ifNotExists ?? this.dialect.features.indexIfNotExists) ? 'IF NOT EXISTS ' : '';
+        const columns = index.entries.map((entry) => this.indexColumn(entry, index)).join(', ');
+        return (`CREATE ${unique}${this.indexKeyword(index)} ${ifNotExists}${this.dialect.escapeId(index.name)} ` +
+            `ON ${this.dialect.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',
+        'partial',
+        'jsonPath',
+    ]);
+    assertIndexFeatures(index) {
+        for (const feature of getKeys(INDEX_FEATURE_PROBES)) {
+            if (INDEX_FEATURE_PROBES[feature](index) && !this.indexFeatures.has(feature)) {
+                throw new TypeError(`${this.dialect.dialectName} does not support ${INDEX_FEATURE_LABELS[feature]} (index "${index.name}")`);
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    indexTypeKeywords = new Map();
+    /** The keyword an index type replaces `INDEX` with, or `INDEX` for the types that do not. */
+    indexKeyword(index) {
+        return (index.type && this.indexTypeKeywords.get(index.type)) || '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. A JSON entry is one of those too, its
+     * expression compiled from the path rather than written out by the caller.
+     */
+    indexColumnTarget(entry) {
+        if (entry.expression) {
+            return `(${entry.column})`;
+        }
+        const column = this.dialect.escapeId(entry.column);
+        if (entry.jsonPath) {
+            return `(${this.dialect.jsonPathExpr(column, entry.jsonPath.path, jsonTypeMode(entry.jsonPath.type))})`;
+        }
+        if (entry.jsonArray) {
+            return `(${this.jsonArrayIndexExpr(column, entry.jsonArray)})`;
+        }
+        return entry.length === undefined ? column : `${column}(${entry.length})`;
+    }
+    /**
+     * 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.
+     */
+    jsonArrayIndexExpr(_escapedColumn, _json) {
+        throw new TypeError(`${this.dialect.dialectName} has no multi-valued index`);
+    }
+    /** 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. Engines without one reject the index in {@link assertIndexFeatures}
+     * rather than reaching here: silently widening a partial unique index changes which rows the
+     * database accepts.
+     */
+    indexPredicate(index) {
+        return index.where ? ` WHERE ${index.where}` : '';
+    }
+}

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

@@ -0,0 +1,52 @@
+import type { IndexType } from '../../schema/types.js';
+import type { IndexJsonArray, IndexSchema } from '../../type/index.js';
+import { IndexDdl } from './indexDdl.js';
+/** `CREATE INDEX ... USING btree`, plus the types this family spells as a keyword instead. */
+export declare class MysqlLikeIndexDdl extends IndexDdl {
+    protected readonly indexFeatures: Set<"expression" | "include" | "jsonArray" | "jsonPath" | "nullsOrder" | "opsClass" | "partial" | "prefixLength">;
+    protected readonly indexTypeKeywords: ReadonlyMap<IndexType, string>;
+    /**
+     * ` USING btree|hash`, for the types this family does *not* spell as a keyword of its own. A vector
+     * type that is neither is one this engine has no index for at all, refused here rather than
+     * compiled into a ` USING hnsw` the server can only answer with a syntax error: which of them a
+     * dialect *does* have is `indexTypeKeywords`, so declaring one there is all it takes to serve it.
+     */
+    protected indexAccessMethod(index: IndexSchema): string;
+    /** What to do instead, appended to the refusal above. */
+    protected readonly vectorIndexHint: string;
+}
+export declare class MySqlIndexDdl extends MysqlLikeIndexDdl {
+    /** The multi-valued index is the only JSON index MySQL has - see `IndexFeature` for why. */
+    protected readonly indexFeatures: Set<"expression" | "include" | "jsonArray" | "jsonPath" | "nullsOrder" | "opsClass" | "partial" | "prefixLength">;
+    /**
+     * `CAST(col AS CHAR(64) ARRAY)`, over the column itself where the array is the whole document -
+     * which is what `$all` reads, and what its `JSON_CONTAINS(col, ?)` is matched against. A `path`
+     * indexes the array at that path instead, as `'tags.ids': { $all: [...] }` reads it.
+     */
+    protected jsonArrayIndexExpr(escapedColumn: string, json: IndexJsonArray): string;
+    /**
+     * MySQL has no vector index of any kind, so one is refused rather than compiled to DDL the server
+     * rejects: `USING hnsw` is a syntax error, and MariaDB's `VECTOR INDEX` is not MySQL syntax either.
+     * Verified against 26.7, which does have `VECTOR` columns and `STRING_TO_VECTOR`, but no distance
+     * function outside HeatWave - hence nothing to index for.
+     */
+    protected readonly vectorIndexHint = ". Vector search on MySQL needs HeatWave";
+}
+export declare class MariaIndexDdl extends MysqlLikeIndexDdl {
+    /**
+     * 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 - and with them both JSON index forms, which are expressions.
+     */
+    protected readonly indexFeatures: Set<"expression" | "include" | "jsonArray" | "jsonPath" | "nullsOrder" | "opsClass" | "partial" | "prefixLength">;
+    /** The family's, plus a vector index of its own: `CREATE VECTOR INDEX ... ON t (col)`, 11.7+. */
+    protected readonly indexTypeKeywords: ReadonlyMap<IndexType, string>;
+    /**
+     * `M=n DISTANCE=metric`, trailing its `CREATE VECTOR INDEX`. The metric names are MariaDB's own
+     * (`euclidean`, not `l2`), and an unsupported one throws rather than being dropped, which would
+     * silently build the index on euclidean - its default - instead of what the entity asked for.
+     */
+    protected indexTuning(index: IndexSchema): string;
+    /** `vector` is its own keyword above; pgvector's names are not access methods it has. */
+    protected readonly vectorIndexHint = "; declare type: 'vector' instead";
+}

package/dist/migrate/ddl/mysqlIndexDdl.js

@@ -0,0 +1,125 @@
+import { jsonPath } from '../../dialect/jsonSql.js';
+import { MARIA_VECTOR_METRICS } from '../../maria/mariaVectorMetrics.js';
+import { isVectorIndexType, unsupportedVectorMetric } from '../../type/vector.js';
+import { IndexDdl } from './indexDdl.js';
+/**
+ * A full-text index is its own keyword here (`CREATE FULLTEXT INDEX ... (cols)`); `USING fulltext` is
+ * a syntax error, so it is the keyword that changes rather than the access method.
+ */
+const MYSQL_LIKE_INDEX_KEYWORDS = new Map([['fulltext', 'FULLTEXT INDEX']]);
+/** `CREATE INDEX ... USING btree`, plus the types this family spells as a keyword instead. */
+export class MysqlLikeIndexDdl extends IndexDdl {
+    indexFeatures = new Set(['expression', 'prefixLength']);
+    indexTypeKeywords = MYSQL_LIKE_INDEX_KEYWORDS;
+    /**
+     * ` USING btree|hash`, for the types this family does *not* spell as a keyword of its own. A vector
+     * type that is neither is one this engine has no index for at all, refused here rather than
+     * compiled into a ` USING hnsw` the server can only answer with a syntax error: which of them a
+     * dialect *does* have is `indexTypeKeywords`, so declaring one there is all it takes to serve it.
+     */
+    indexAccessMethod(index) {
+        const type = index.type;
+        if (!type || this.indexTypeKeywords.has(type)) {
+            return '';
+        }
+        if (isVectorIndexType(type)) {
+            throw new TypeError(`${this.dialect.dialectName} has no ${type} index (index "${index.name}")${this.vectorIndexHint}`);
+        }
+        return ` USING ${type}`;
+    }
+    /** What to do instead, appended to the refusal above. */
+    vectorIndexHint = '';
+}
+export class MySqlIndexDdl extends MysqlLikeIndexDdl {
+    /** The multi-valued index is the only JSON index MySQL has - see `IndexFeature` for why. */
+    indexFeatures = new Set(['expression', 'prefixLength', 'jsonArray']);
+    /**
+     * `CAST(col AS CHAR(64) ARRAY)`, over the column itself where the array is the whole document -
+     * which is what `$all` reads, and what its `JSON_CONTAINS(col, ?)` is matched against. A `path`
+     * indexes the array at that path instead, as `'tags.ids': { $all: [...] }` reads it.
+     */
+    jsonArrayIndexExpr(escapedColumn, json) {
+        const source = json.path ? `${escapedColumn}->${jsonPath(json.path)}` : escapedColumn;
+        return `CAST(${source} AS ${arrayCastType(json)} ARRAY)`;
+    }
+    /**
+     * MySQL has no vector index of any kind, so one is refused rather than compiled to DDL the server
+     * rejects: `USING hnsw` is a syntax error, and MariaDB's `VECTOR INDEX` is not MySQL syntax either.
+     * Verified against 26.7, which does have `VECTOR` columns and `STRING_TO_VECTOR`, but no distance
+     * function outside HeatWave - hence nothing to index for.
+     */
+    vectorIndexHint = '. Vector search on MySQL needs HeatWave';
+}
+export class MariaIndexDdl extends MysqlLikeIndexDdl {
+    /**
+     * 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 - and with them both JSON index forms, which are expressions.
+     */
+    indexFeatures = new Set(['prefixLength']);
+    /** The family's, plus a vector index of its own: `CREATE VECTOR INDEX ... ON t (col)`, 11.7+. */
+    indexTypeKeywords = new Map([
+        ...MYSQL_LIKE_INDEX_KEYWORDS,
+        ['vector', 'VECTOR INDEX'],
+    ]);
+    /**
+     * `M=n DISTANCE=metric`, trailing its `CREATE VECTOR INDEX`. The metric names are MariaDB's own
+     * (`euclidean`, not `l2`), and an unsupported one throws rather than being dropped, which would
+     * silently build the index on euclidean - its default - instead of what the entity asked for.
+     */
+    indexTuning(index) {
+        let tuning = index.m === undefined ? '' : ` M=${index.m}`;
+        if (index.distance) {
+            const metric = MARIA_VECTOR_METRICS.get(index.distance);
+            if (!metric) {
+                throw unsupportedVectorMetric(this.dialect.dialectName, index.distance, index.name);
+            }
+            tuning += ` DISTANCE=${metric}`;
+        }
+        return tuning;
+    }
+    /** `vector` is its own keyword above; pgvector's names are not access methods it has. */
+    vectorIndexHint = "; declare type: 'vector' instead";
+}
+/**
+ * MySQL's `CAST(... AS <type> ARRAY)` targets, the closed list its multi-valued index takes: no
+ * `FLOAT`, no `BOOLEAN`, no `JSON`. A `DECIMAL` element is the way to index a fractional one.
+ */
+const ARRAY_CASTS = new Map([
+    [String, 'CHAR'],
+    [Number, 'SIGNED'],
+    [BigInt, 'SIGNED'],
+    [Date, 'DATETIME'],
+    ['char', 'CHAR'],
+    ['varchar', 'CHAR'],
+    ['text', 'CHAR'],
+    ['uuid', 'CHAR'],
+    ['int', 'SIGNED'],
+    ['integer', 'SIGNED'],
+    ['tinyint', 'SIGNED'],
+    ['smallint', 'SIGNED'],
+    ['bigint', 'SIGNED'],
+    ['decimal', 'DECIMAL'],
+    ['numeric', 'DECIMAL'],
+    ['date', 'DATE'],
+    ['time', 'TIME'],
+    ['datetime', 'DATETIME'],
+    ['timestamp', 'DATETIME'],
+    ['blob', 'BINARY'],
+    ['bytea', 'BINARY'],
+]);
+/** The cast an element type compiles to; the sized ones need their length, since it sizes the key. */
+function arrayCastType(json) {
+    const type = json.type;
+    const cast = ARRAY_CASTS.get(typeof type === 'string' ? type.toLowerCase() : type);
+    if (!cast) {
+        throw new TypeError(`mysql has no array cast for ${typeof type === 'string' ? type : type.name} elements`);
+    }
+    if (cast !== 'CHAR' && cast !== 'BINARY') {
+        return cast;
+    }
+    if (!json.length) {
+        throw new TypeError(`a multi-valued index over ${cast === 'CHAR' ? 'string' : 'binary'} elements needs a length`);
+    }
+    return `${cast}(${json.length})`;
+}

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

@@ -0,0 +1,36 @@
+import type { PgLikeSqlDialect } from '../../dialect/pgLikeSqlDialect.js';
+import type { IndexColumnSchema, IndexSchema } from '../../type/index.js';
+import { IndexDdl } from './indexDdl.js';
+/** `CREATE INDEX ... USING hnsw ("embedding" vector_cosine_ops) WITH (m = ...)`, pgvector's form. */
+export declare class PgIndexDdl extends IndexDdl<PgLikeSqlDialect> {
+    protected readonly indexFeatures: Set<"expression" | "include" | "jsonArray" | "jsonPath" | "nullsOrder" | "opsClass" | "partial" | "prefixLength">;
+    /** pgvector's own index types; CockroachDB's native one widens this. */
+    protected isVectorIndex(index: IndexSchema): boolean;
+    protected indexAccessMethod(index: IndexSchema): string;
+    /**
+     * 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;
+}
+/**
+ * CockroachDB's vector index is native and has its own syntax: `CREATE VECTOR INDEX ... ("col"
+ * vector_cosine_ops)`, with no access-method keyword, and tuning knobs of its own names that UQL
+ * does not map. `type: 'vector'` is its trigger, the same generic value MariaDB's index uses.
+ *
+ * `NULLS FIRST/LAST` answers "unimplemented: this syntax" and `jsonb_path_ops` "operator class is
+ * not supported" (both verified on v26.2), so neither is offered here.
+ */
+export declare class CockroachIndexDdl extends PgIndexDdl {
+    protected readonly indexFeatures: Set<"expression" | "include" | "jsonArray" | "jsonPath" | "nullsOrder" | "opsClass" | "partial" | "prefixLength">;
+    private isNativeVectorIndex;
+    protected isVectorIndex(index: IndexSchema): boolean;
+    protected indexKeyword(index: IndexSchema): string;
+    protected indexAccessMethod(index: IndexSchema): string;
+    protected indexTuning(index: IndexSchema): string;
+}

package/dist/migrate/ddl/pgIndexDdl.js

@@ -0,0 +1,87 @@
+import { unsupportedVectorMetric } from '../../type/vector.js';
+import { IndexDdl } from './indexDdl.js';
+/** `CREATE INDEX ... USING hnsw ("embedding" vector_cosine_ops) WITH (m = ...)`, pgvector's form. */
+export class PgIndexDdl extends IndexDdl {
+    indexFeatures = new Set([
+        'expression',
+        'partial',
+        'nullsOrder',
+        'opsClass',
+        'include',
+        'jsonPath',
+    ]);
+    /** pgvector's own index types; CockroachDB's native one widens this. */
+    isVectorIndex(index) {
+        return index.type === 'hnsw' || index.type === 'ivfflat';
+    }
+    indexAccessMethod(index) {
+        return index.type ? ` USING ${index.type}` : '';
+    }
+    /**
+     * 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.
+     */
+    indexColumnOpsClass(entry, index) {
+        if (!this.isVectorIndex(index) || !index.distance) {
+            return entry.opsClass ? ` ${entry.opsClass}` : '';
+        }
+        const metric = this.dialect.vectorMetrics.get(index.distance);
+        if (!metric) {
+            throw unsupportedVectorMetric(this.dialect.dialectName, index.distance, index.name);
+        }
+        const vectorType = this.dialect.supportedVectorType(index.vectorType ?? 'vector');
+        const opsClass = `${vectorType}_${metric.opsSuffix}_ops`;
+        // IVFFlat has neither a sparsevec nor an L1 operator class; HNSW has all of them (pgvector 0.8.2).
+        if (index.type === 'ivfflat' && (vectorType === 'sparsevec' || index.distance === 'l1')) {
+            throw new TypeError(`ivfflat has no ${opsClass} operator class (index "${index.name}"); use hnsw`);
+        }
+        return ` ${opsClass}`;
+    }
+    indexInclude(index) {
+        return index.include?.length
+            ? ` INCLUDE (${index.include.map((column) => this.dialect.escapeId(column)).join(', ')})`
+            : '';
+    }
+    indexTuning(index) {
+        if (!this.isVectorIndex(index)) {
+            return '';
+        }
+        const params = [];
+        if (index.m !== undefined)
+            params.push(`m = ${index.m}`);
+        if (index.efConstruction !== undefined)
+            params.push(`ef_construction = ${index.efConstruction}`);
+        if (index.lists !== undefined)
+            params.push(`lists = ${index.lists}`);
+        return params.length > 0 ? ` WITH (${params.join(', ')})` : '';
+    }
+}
+/**
+ * CockroachDB's vector index is native and has its own syntax: `CREATE VECTOR INDEX ... ("col"
+ * vector_cosine_ops)`, with no access-method keyword, and tuning knobs of its own names that UQL
+ * does not map. `type: 'vector'` is its trigger, the same generic value MariaDB's index uses.
+ *
+ * `NULLS FIRST/LAST` answers "unimplemented: this syntax" and `jsonb_path_ops` "operator class is
+ * not supported" (both verified on v26.2), so neither is offered here.
+ */
+export class CockroachIndexDdl extends PgIndexDdl {
+    indexFeatures = new Set(['expression', 'partial', 'include', 'jsonPath']);
+    isNativeVectorIndex(index) {
+        return index.type === 'vector';
+    }
+    isVectorIndex(index) {
+        return this.isNativeVectorIndex(index) || super.isVectorIndex(index);
+    }
+    indexKeyword(index) {
+        return this.isNativeVectorIndex(index) ? 'VECTOR INDEX' : super.indexKeyword(index);
+    }
+    indexAccessMethod(index) {
+        return this.isNativeVectorIndex(index) ? '' : super.indexAccessMethod(index);
+    }
+    indexTuning(index) {
+        return this.isNativeVectorIndex(index) ? '' : super.indexTuning(index);
+    }
+}

package/dist/migrate/drift/driftDetector.js

@@ -108,7 +108,12 @@ function addAlterColumnDrifts(colDiff, drifts, opts) {
     if (!colDiff.expected || !colDiff.actual) {
         return;
     }
-    if (opts.checkTypes) {
+    // An auto-increment key is created through the dialect's `serialPrimaryKey`, whose spelling the
+    // entity never states - `BIGINT UNSIGNED AUTO_INCREMENT` on the MySQL family, where the column then
+    // reads back as `BIGINT UNSIGNED` against an entity that can only say `BIGINT`. Comparing the two
+    // reported every table uql created itself as drifting on its own id.
+    const dialectOwnsType = colDiff.expected.isPrimaryKey && colDiff.expected.isAutoIncrement;
+    if (opts.checkTypes && !dialectOwnsType) {
         const expectedType = formatType(colDiff.expected.type, opts.dialect);
         const actualType = formatType(colDiff.actual.type, opts.dialect);
         if (expectedType !== actualType) {

package/dist/migrate/generator/mongoSchemaGenerator.js

@@ -87,7 +87,7 @@ export class MongoSchemaGenerator extends AbstractDialect {
     generateCreateIndex(tableName, index) {
         const key = {};
         for (const entry of index.entries) {
-            if (entry.expression || entry.length !== undefined || entry.nulls || entry.opsClass) {
+            if (entry.expression || entry.jsonArray || entry.length !== undefined || entry.nulls || entry.opsClass) {
                 throw new TypeError(`mongodb does not support that index column option (index "${index.name}")`);
             }
             key[entry.column] = index.type === 'fulltext' ? 'text' : entry.order === 'desc' ? -1 : 1;

package/dist/migrate/index.d.ts

@@ -5,6 +5,7 @@ export { assertCliConfig } from './assertCliConfig.js';
 export * from './builder/index.js';
 export { loadConfig } from './cli-config.js';
 export * from './codegen/index.js';
+export * from './ddl/index.js';
 export * from './drift/index.js';
 export * from './introspection/index.js';
 export { type BuilderMigrationDefinition, defineBuilderMigration, defineMigration, Migrator } from './migrator.js';

package/dist/migrate/index.js

@@ -6,6 +6,8 @@ export * from './builder/index.js';
 export { loadConfig } from './cli-config.js';
 // Entity code generation
 export * from './codegen/index.js';
+// `CREATE INDEX`, per dialect family
+export * from './ddl/index.js';
 // Drift detection
 export * from './drift/index.js';
 // Schema introspection

package/dist/migrate/introspection/mysqlIntrospector.d.ts

@@ -44,8 +44,14 @@ type MysqlColumnRow = {
     column_comment: string | null;
 };
 /**
- * Alias for MysqlSchemaIntrospector.
- * MariaDB uses the same information_schema structure as MySQL.
+ * MariaDB reads out of the same `information_schema` as MySQL, save for one column type it does not
+ * have: `JSON` there is an alias for `LONGTEXT` plus a `json_valid()` check constraint named after
+ * the column, and the catalogue reports the column as `longtext`. That check is the only thing
+ * telling one from a column somebody really declared `LONGTEXT`, so it is what the type is read back
+ * through - without it every JSON column drifts against the entity that declared it ("expected
+ * JSON, got LONGTEXT", flagged as data loss) on a table uql created itself.
  */
-export declare const MariadbSchemaIntrospector: typeof MysqlSchemaIntrospector;
+export declare class MariadbSchemaIntrospector extends MysqlSchemaIntrospector {
+    protected mapColumnsResult(read: TableRowReader, tableName: string, results: MysqlColumnRow[]): Promise<ColumnSchema[]>;
+}
 export {};

package/dist/migrate/introspection/mysqlIntrospector.js

@@ -54,7 +54,7 @@ export class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         return /*sql*/ `
       SELECT
         INDEX_NAME as index_name,
-        GROUP_CONCAT(COLUMN_NAME ORDER BY SEQ_IN_INDEX) as columns,
+        GROUP_CONCAT(COALESCE(COLUMN_NAME, '') ORDER BY SEQ_IN_INDEX) as columns,
         NOT NON_UNIQUE as is_unique
       FROM information_schema.STATISTICS
       WHERE TABLE_SCHEMA = ${this.schemaExpr}
@@ -112,7 +112,10 @@ export class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
     async mapIndexesResult(_read, _tableName, results) {
         return results.map((row) => ({
             name: row.index_name,
-            entries: (row.columns || '').split(',').map((column) => ({ column })),
+            // A functional or multi-valued key part has no `COLUMN_NAME` - the `COALESCE` above keeps its
+            // place in the list, and it is reported as the expression it is, which is what stops diffing
+            // from comparing an entry list the server cannot state against the entity's own.
+            entries: (row.columns ?? '').split(',').map((column) => (column ? { column } : { column, expression: true })),
             unique: Boolean(row.is_unique),
         }));
     }
@@ -150,7 +153,26 @@ export class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
     }
 }
 /**
- * Alias for MysqlSchemaIntrospector.
- * MariaDB uses the same information_schema structure as MySQL.
+ * MariaDB reads out of the same `information_schema` as MySQL, save for one column type it does not
+ * have: `JSON` there is an alias for `LONGTEXT` plus a `json_valid()` check constraint named after
+ * the column, and the catalogue reports the column as `longtext`. That check is the only thing
+ * telling one from a column somebody really declared `LONGTEXT`, so it is what the type is read back
+ * through - without it every JSON column drifts against the entity that declared it ("expected
+ * JSON, got LONGTEXT", flagged as data loss) on a table uql created itself.
  */
-export const MariadbSchemaIntrospector = MysqlSchemaIntrospector;
+export class MariadbSchemaIntrospector extends MysqlSchemaIntrospector {
+    async mapColumnsResult(read, tableName, results) {
+        const columns = await super.mapColumnsResult(read, tableName, results);
+        const checks = await read(
+        /*sql*/ `
+      SELECT CONSTRAINT_NAME as column_name
+      FROM information_schema.CHECK_CONSTRAINTS
+      WHERE CONSTRAINT_SCHEMA = ${this.schemaExpr}
+        AND TABLE_NAME = ?
+        AND CHECK_CLAUSE = CONCAT('json_valid(\`', CONSTRAINT_NAME, '\`)')
+    `, [tableName]);
+        const jsonColumns = new Set(checks.map((row) => row.column_name));
+        // The reported `LONGTEXT` length is that type's maximum, which means nothing for a JSON column.
+        return columns.map((column) => jsonColumns.has(column.name) ? { ...column, type: 'JSON', length: undefined } : column);
+    }
+}

package/dist/migrate/migrator.js

@@ -8,7 +8,7 @@ import { LoggerWrapper } from '../util/index.js';
 import { withQuerierForMigrations, withSqlQuerierForMigrations } from './acquireQuerierForMigrations.js';
 import { buildSqlQuerierMigrationModule, EMPTY_MANUAL_MIGRATION_DOWN_INNER, EMPTY_MANUAL_MIGRATION_UP_INNER, emitSqlRunCalls, } from './codegen/migrationFile.js';
 import { runMongoCommand } from './generator/mongoCommand.js';
-import { CockroachSchemaIntrospector, MongoSchemaIntrospector, MysqlSchemaIntrospector, PostgresSchemaIntrospector, SqliteSchemaIntrospector, } from './introspection/index.js';
+import { CockroachSchemaIntrospector, MariadbSchemaIntrospector, MongoSchemaIntrospector, MysqlSchemaIntrospector, PostgresSchemaIntrospector, SqliteSchemaIntrospector, } from './introspection/index.js';
 import { createSchemaGenerator } from './schemaGenerator.js';
 import { createSchemaGeneratorAsync } from './schemaGeneratorAsync.js';
 import { DatabaseMigrationStorage } from './storage/databaseStorage.js';
@@ -83,8 +83,9 @@ export class Migrator {
             case 'cockroachdb':
                 return new CockroachSchemaIntrospector(this.pool, schema);
             case 'mysql':
-            case 'mariadb':
                 return new MysqlSchemaIntrospector(this.pool, schema);
+            case 'mariadb':
+                return new MariadbSchemaIntrospector(this.pool, schema);
             case 'sqlite':
                 return new SqliteSchemaIntrospector(this.pool);
             case 'mongodb':

package/dist/migrate/schemaGenerator.d.ts

@@ -3,6 +3,7 @@ import type { SchemaAST } from '../schema/schemaAST.js';
 import type { CanonicalType, ColumnNode, ForeignKeyAction, IndexNode, TableNode } from '../schema/types.js';
 import type { ColumnSchema, CreateSchemaOptions, DialectFeatures, DropSchemaOptions, EntityMeta, FieldOptions, IndexSchema, NamingStrategy, SchemaDiff, SchemaGenerator, SqlDdlGenerator, Type } from '../type/index.js';
 import type { FullColumnDefinition, TableDefinition, TableForeignKeyDefinition } from './builder/types.js';
+import { type IndexDdl } from './ddl/index.js';
 /**
  * Unified SQL schema generator.
  * Parameterized by dialect to handle Postgres, MySQL, MariaDB, and SQLite.
@@ -10,6 +11,8 @@ import type { FullColumnDefinition, TableDefinition, TableForeignKeyDefinition }
 export declare class SqlSchemaGenerator implements SqlDdlGenerator {
     protected readonly dialect: AbstractSqlDialect;
     protected readonly defaultForeignKeyAction: ForeignKeyAction;
+    /** `CREATE INDEX` for this dialect: the migrator's, so a runtime import carries none of it. */
+    protected readonly indexDdl: IndexDdl;
     constructor(dialect: AbstractSqlDialect, defaultForeignKeyAction?: ForeignKeyAction);
     get namingStrategy(): NamingStrategy | undefined;
     get features(): DialectFeatures;
@@ -99,14 +102,11 @@ export declare class SqlSchemaGenerator implements SqlDdlGenerator {
      *
      * Only ever additive. An index the entity does not name is left alone: it may well have been
      * created deliberately outside the ORM, and dropping it is a decision for a reviewed migration.
+     *
+     * A vector index is one of these like any other: MariaDB's `CREATE VECTOR INDEX ... ON t (col)`
+     * adds one to a table that already exists, which the inline `CREATE TABLE` form it also has cannot.
      */
     private missingIndexes;
-    /**
-     * A vector index this dialect declares inside `CREATE TABLE` rather than as a statement of its own,
-     * which MariaDB is alone in doing. It has no `CREATE INDEX` form, so it can only ever be created
-     * with its table, never added to one.
-     */
-    private isInlineVectorIndex;
     private columnNodeToSchema;
     /**
      * Convert field options to ColumnSchema. Both sides of a diff are the engine's SQL spelling: what it