uql-orm 0.42.0 → 0.43.0

package/dist/dialect/abstractSqlDialect.js

@@ -1,15 +1,22 @@
 import { getMeta, soleIdOf } from '../entity/index.js';
 import { parseQueryLock, QueryRaw, RAW_ALIAS, RAW_VALUE, VECTOR_QUERY_KEYS, } from '../type/index.js';
-import { asSelectMap, assertNonNegativeInteger, buildQueryWhereAsMap, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getSoftDeleteValue, hasKeys, isBooleanType, isJsonType, isJsonUpdateOp, isNumericType, isOperatorMap, isOperatorObject, isOperatorOnlyObject, isVectorSearch, normalizeScalarFieldSelection, parentJoins, targetKeyColumns, parseGroupMap, parseRelationSize, parseSortByCount, populatesRelations, raw, someValue, throwUnknownAggregateColumn, withoutSoftDeleteFilter, } from '../util/index.js';
+import { asSelectMap, assertNonNegativeInteger, buildQueryWhereAsMap, escapeSqlId, fillOnFields, filterFieldKeys, getInsertFieldKeys, getKeys, getSoftDeleteValue, hasKeys, columnFamily, isJsonUpdateOp, isOperatorMap, isOperatorObject, isOperatorOnlyObject, isVectorSearch, normalizeScalarFieldSelection, parentJoins, targetKeyColumns, parseGroupMap, parseRelationSize, parseSortByCount, populatesRelations, raw, someValue, throwUnknownAggregateColumn, withoutSoftDeleteFilter, } from '../util/index.js';
 import { escapeAnsiSqlLiteral, escapeSingleQuotes } from '../util/sqlLiteral.js';
 import { COUNT_ALIAS, DISTINCT_DERIVED_ALIAS, JSON_ELEM_ALIAS_PREFIX } from './aliases.js';
 import { buildElemMatchConditions } from './jsonArrayElemMatchUtils.js';
 import { isJsonbOp, jsonCompareMode, jsonElemExists } from './jsonSql.js';
 import { SqlQueryContext } from './queryContext.js';
 import { NO_JOINS, resolveQueryJoins, resolveSortableJoin, } from './queryJoins.js';
-import { isVectorFieldType, resolveVectorCast } from './vectorCast.js';
+import { resolveVectorCast } from './vectorCast.js';
 import { VectorSqlDialect } from './vectorSqlDialect.js';
 export class AbstractSqlDialect extends VectorSqlDialect {
+    /**
+     * Whether {@link serialType} states `PRIMARY KEY` itself, so the table must not state it again.
+     *
+     * True on SQLite alone, where `AUTOINCREMENT` is legal only in the exact phrase
+     * `INTEGER PRIMARY KEY AUTOINCREMENT` - the key cannot be lifted out of the column there.
+     */
+    serialDeclaresPrimaryKey = false;
     /**
      * How this engine declares a namespace, so a generated migration creates the schemas its tables
      * need before creating them. Only reached where {@link DialectFeatures.schemas} is on. MySQL and
@@ -22,6 +29,11 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     alterColumnStrategy = 'single-statement';
     alterColumnSyntax = 'ALTER COLUMN';
     dropForeignKeySyntax = 'DROP CONSTRAINT';
+    /**
+     * `DROP CONSTRAINT <name>` where a primary key is a named constraint like any other; MySQL spells
+     * it `DROP PRIMARY KEY` and takes no name, since a table's key is always called `PRIMARY` there.
+     */
+    dropPrimaryKeySyntax = 'DROP CONSTRAINT';
     dropIndexSyntax = 'standalone';
     renameTableSyntax = 'alter-table';
     booleanLiteral = 'native';
@@ -90,9 +102,22 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     placeholder(_index) {
         return '?';
     }
+    /**
+     * `RETURNING <id column> AS id`, or nothing at all for a composite key.
+     *
+     * The alias names one column, and every column of a composite came from the caller, so there is no
+     * id the statement could report that the payload does not already carry - the same "no id to give"
+     * a `firstId` dialect already answers with. Empty rather than a refusal, so an insert and an upsert
+     * of a composite row both run; `idOf(meta, row)` names such a row.
+     */
     returningId(meta) {
-        const idName = this.columnOf(meta, soleIdOf(meta, 'returning an inserted id'));
-        return `RETURNING ${this.escapeId(idName)} ${this.escapeId('id')}`;
+        const expression = this.returningIdExpression(meta);
+        return expression ? `RETURNING ${expression}` : '';
+    }
+    /** `<id column> AS id` on its own, for a statement composing a `RETURNING` list of several items. */
+    returningIdExpression(meta) {
+        const [idKey] = meta.ids;
+        return meta.ids.length === 1 ? `${this.escapeId(this.columnOf(meta, idKey))} ${this.escapeId('id')}` : '';
     }
     search(ctx, entity, q = {}, opts = {}, joins = NO_JOINS) {
         const meta = getMeta(entity);
@@ -965,12 +990,13 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     insert(ctx, entity, payload, opts) {
         this.appendInsertValues(ctx, entity, payload);
         // 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. A composite key
-        // has nothing to ask for: the alias names one column, and every column of it came from the
-        // caller, so there is no id the statement could report that the payload does not already carry.
-        const meta = getMeta(entity);
-        if (this.insertIdSource === 'returning' && meta.ids.length === 1) {
-            ctx.append(` ${this.returningId(meta)}`);
+        // appended once here instead of in an identical `insert` override per dialect. `returningId` is
+        // empty on a composite key, which has no id to ask for.
+        if (this.insertIdSource === 'returning') {
+            const returning = this.returningId(getMeta(entity));
+            if (returning) {
+                ctx.append(` ${returning}`);
+            }
         }
     }
     /**
@@ -1063,14 +1089,19 @@ export class AbstractSqlDialect extends VectorSqlDialect {
      * {@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 = '') {
+    upsert(ctx, entity, conflictPaths, payload, 
+    /** One more `RETURNING` item, as a bare expression: this joins the list and adds the keyword. */
+    extraReturning = '') {
         const meta = getMeta(entity);
         const updateCtx = this.upsertUpdateBindsInPlace ? ctx : this.createContext();
         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';
+        // Composed rather than concatenated: a composite key contributes no id item, and a dialect's own
+        // item (Postgres's `_created`) still has to be the *first* thing after the keyword when it is.
+        const returning = [this.returningIdExpression(meta), extraReturning].filter(Boolean).join(', ');
         this.appendInsertValues(ctx, entity, payload);
-        ctx.append(` ON CONFLICT (${keys}) ${onConflict} ${this.returningId(meta)}${extraReturning}`);
+        ctx.append(` ON CONFLICT (${keys}) ${onConflict}${returning ? ` RETURNING ${returning}` : ''}`);
         if (updateCtx !== ctx) {
             ctx.pushValue(...updateCtx.values);
         }
@@ -1156,22 +1187,19 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     }
     /**
      * 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.
+     * classifies each column once instead of re-deciding per row: a 20-row, 6-column insert used to ask
+     * 120 times to get the same six answers.
      */
     persistKind(field) {
-        const type = field?.type;
-        if (isJsonType(type)) {
-            return 'json';
-        }
-        return isVectorFieldType(type) ? 'vector' : 'plain';
+        const family = columnFamily(field?.type);
+        return family === 'json' || family === 'vector' ? family : 'plain';
     }
     /**
      * Which of an entity's columns need decoding on READ, and how: the inverse of {@link persistKind},
      * cached per entity for the same reason it classifies per column. A 1000-row read of a 10-field
-     * entity otherwise asks `isJsonType` (which lowercases a string on every call) 10,000 times to get
-     * the same ten answers. Most entities land here for their numeric columns alone, where the per-row
-     * cost is one `typeof` against a value the driver usually decoded already.
+     * entity otherwise asks {@link columnFamily} (which lowercases a string on every call) 10,000 times
+     * to get the same ten answers. Most entities land here for their numeric columns alone, where the
+     * per-row cost is one `typeof` against a value the driver usually decoded already.
      *
      * Dialect-aware exactly like {@link supportedVectorType}, because it has to be: a `sparsevec` field
      * is written as a plain dense vector everywhere but Postgres, so reading it back by the field's own
@@ -1183,23 +1211,26 @@ export class AbstractSqlDialect extends VectorSqlDialect {
      * the field says it was meant as a number; and `type: BigInt` shares BIGINT with `type: Number`, so
      * the wire decode has to be undone for it. All are no-ops where the driver already decoded.
      *
-     * Classified through the same `isNumericType`/`isBooleanType`/`isJsonType` the rest of the library
-     * uses, not against the constructors: `type` accepts a string logical type for every one of these
-     * (`@Field({ type: 'decimal' })`), and matching `=== Number` alone left those reading back as text.
+     * Classified through the same {@link columnFamily} the rest of the library uses, not against the
+     * constructors: `type` accepts a string logical type for every one of these (`@Field({ type:
+     * 'decimal' })`), and matching `=== Number` alone left those reading back as text.
      */
     hydratableFields(entity) {
+        const meta = getMeta(entity);
         const cached = this.hydratable.get(entity);
-        if (cached) {
-            return cached;
+        // Against the revision, not merely present: a field added to an entity already read - a content
+        // type the admin extended - would otherwise decode by the list its columns are missing from.
+        if (cached?.[0] === meta.revision) {
+            return cached[1];
         }
         const decoded = [];
-        for (const [key, field] of Object.entries(getMeta(entity).fields)) {
+        for (const [key, field] of Object.entries(meta.fields)) {
             const kind = this.hydrateKind(field);
             if (kind) {
                 decoded.push([key, kind]);
             }
         }
-        this.hydratable.set(entity, decoded);
+        this.hydratable.set(entity, [meta.revision, decoded]);
         return decoded;
     }
     /**
@@ -1233,26 +1264,26 @@ export class AbstractSqlDialect extends VectorSqlDialect {
     /**
      * The mirror of {@link persistKind}: what one column decodes as, or nothing if it needs no decode.
      *
-     * Ordered for correctness, not for speed - this runs once per entity, cached, never per row. The
-     * one order that is load-bearing is `BigInt` before {@link isNumericType}, which answers true for
-     * `BigInt` as well as `Number`: swap them and every `type: BigInt` property silently decodes to a
-     * JS number again.
+     * `BigInt` is asked first because it shares the numeric family with `Number`: let the switch answer
+     * it and every `type: BigInt` property silently decodes to a JS number again.
      */
     hydrateKind(field) {
         const type = field?.type;
-        if (isJsonType(type)) {
-            return 'json';
-        }
-        if (isVectorFieldType(type)) {
-            return this.supportedVectorType(resolveVectorCast(field));
-        }
-        if (isBooleanType(type)) {
-            return 'boolean';
-        }
         if (type === BigInt) {
             return 'bigint';
         }
-        return isNumericType(type) ? 'number' : undefined;
+        switch (columnFamily(type)) {
+            case 'json':
+                return 'json';
+            case 'vector':
+                return this.supportedVectorType(resolveVectorCast(field));
+            case 'boolean':
+                return 'boolean';
+            case 'numeric':
+                return 'number';
+            default:
+                return undefined;
+        }
     }
     hydratable = new WeakMap();
     /** The one type dispatch for a persisted value, over a column kind decided by the caller. */
@@ -1350,7 +1381,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         }
         const root = key.slice(0, dotIndex);
         const field = meta.fields[root];
-        if (!field || !isJsonType(field.type)) {
+        if (!field || columnFamily(field.type) !== 'json') {
             return undefined;
         }
         const colName = this.resolveColumnName(root, field);

package/dist/dialect/jsonSql.d.ts

@@ -45,8 +45,9 @@ export declare function jsonCompareMode(value: unknown): JsonAccessMode;
  * operand. An index over a JSON path is only reachable by a comparison that extracts it the same way,
  * so the two have to answer alike - which is why they are one pair over one vocabulary.
  *
- * Reads the type through `util/field.util`'s predicates, which the dialects already carry: resolving
- * it through `schema/canonicalType` instead pulls that whole module into every consumer bundle.
+ * Reads the type through `util/field.util`'s own classifier, which the dialects already carry:
+ * resolving it through `schema/canonicalType` instead pulls that whole module into every consumer
+ * bundle.
  */
 export declare function jsonTypeMode(type: FieldType): JsonAccessMode;
 /**

package/dist/dialect/jsonSql.js

@@ -1,4 +1,4 @@
-import { isBooleanType, isNumericType } from '../util/field.util.js';
+import { columnFamily } from '../util/field.util.js';
 import { escapeSingleQuotes } from '../util/sqlLiteral.js';
 /**
  * A `'$.a.b'` JSON path literal, each dot-separated segment escaped. `suffix` appends an accessor
@@ -62,14 +62,16 @@ export function jsonCompareMode(value) {
  * operand. An index over a JSON path is only reachable by a comparison that extracts it the same way,
  * so the two have to answer alike - which is why they are one pair over one vocabulary.
  *
- * Reads the type through `util/field.util`'s predicates, which the dialects already carry: resolving
- * it through `schema/canonicalType` instead pulls that whole module into every consumer bundle.
+ * Reads the type through `util/field.util`'s own classifier, which the dialects already carry:
+ * resolving it through `schema/canonicalType` instead pulls that whole module into every consumer
+ * bundle.
  */
 export function jsonTypeMode(type) {
-    if (isNumericType(type)) {
+    const family = columnFamily(type);
+    if (family === 'numeric') {
         return 'numeric';
     }
-    return isBooleanType(type) ? 'json' : 'text';
+    return family === 'boolean' ? 'json' : 'text';
 }
 /**
  * Whether the operator reads the JSON *value* instead of its text form. The array operators always

package/dist/dialect/mysqlLikeSqlDialect.d.ts

@@ -24,7 +24,7 @@ export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
     estimatedCount<E>(ctx: QueryContext, entity: Type<E>): void;
     /** `OFFSET` is only legal after a `LIMIT` here, so a bare `$skip` needs one. */
     pager(ctx: QueryContext, opts: QueryPager): void;
-    readonly serialPrimaryKey = "BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY";
+    readonly serialType = "BIGINT UNSIGNED AUTO_INCREMENT";
     readonly escapeIdChar = "`";
     readonly tableOptions = "ENGINE=InnoDB DEFAULT CHARSET=utf8mb4";
     readonly beginTransactionCommand = "START TRANSACTION";
@@ -32,6 +32,7 @@ export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
     readonly rollbackTransactionCommand = "ROLLBACK";
     readonly isolationLevelStrategy = "set-before";
     readonly dropForeignKeySyntax = "DROP FOREIGN KEY";
+    readonly dropPrimaryKeySyntax = "DROP PRIMARY KEY";
     readonly dropIndexSyntax = "on-table";
     readonly renameTableSyntax = "rename-table";
     readonly alterColumnSyntax = "MODIFY COLUMN";

package/dist/dialect/mysqlLikeSqlDialect.js

@@ -31,6 +31,7 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
         dropTableCascade: false,
         renameColumn: true,
         foreignKeyAlter: true,
+        primaryKeyAlter: true,
         columnComment: true,
         vectorIndexRequiresNotNull: false,
         vectorSupportsLength: false,
@@ -62,7 +63,7 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
         }
         super.pager(ctx, opts);
     }
-    serialPrimaryKey = 'BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY';
+    serialType = 'BIGINT UNSIGNED AUTO_INCREMENT';
     escapeIdChar = '`';
     tableOptions = 'ENGINE=InnoDB DEFAULT CHARSET=utf8mb4';
     beginTransactionCommand = 'START TRANSACTION';
@@ -70,6 +71,7 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
     rollbackTransactionCommand = 'ROLLBACK';
     isolationLevelStrategy = 'set-before';
     dropForeignKeySyntax = 'DROP FOREIGN KEY';
+    dropPrimaryKeySyntax = 'DROP PRIMARY KEY';
     dropIndexSyntax = 'on-table';
     renameTableSyntax = 'rename-table';
     alterColumnSyntax = 'MODIFY COLUMN';

package/dist/dialect/pgLikeSqlDialect.d.ts

@@ -15,7 +15,7 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
     /** Default {@link DialectFeatures} for Postgres-wire dialects. */
     protected readonly featureDefaults: DialectFeatures;
     readonly escapeIdChar = "\"";
-    readonly serialPrimaryKey: string;
+    readonly serialType: string;
     readonly tableOptions = "";
     readonly beginTransactionCommand = "BEGIN";
     readonly commitTransactionCommand = "COMMIT";

package/dist/dialect/pgLikeSqlDialect.js

@@ -28,6 +28,7 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
         dropTableCascade: true,
         renameColumn: true,
         foreignKeyAlter: true,
+        primaryKeyAlter: true,
         columnComment: false,
         vectorIndexRequiresNotNull: false,
         vectorSupportsLength: true,
@@ -39,7 +40,7 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
     // under heavy concurrent insert load (writes concentrate on one range); this default still beats
     // `SERIAL` (CockroachDB's `unique_rowid()`, a ~64-bit value that overflows JS's safe-integer
     // range). High-throughput CockroachDB users should override this per-entity with a UUID PK.
-    serialPrimaryKey = 'BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY';
+    serialType = 'BIGINT GENERATED BY DEFAULT AS IDENTITY';
     tableOptions = '';
     beginTransactionCommand = 'BEGIN';
     commitTransactionCommand = 'COMMIT';

package/dist/dialect/vectorCast.d.ts

@@ -4,12 +4,6 @@
  */
 /** Vector cast types supported by pgvector. */
 export type VectorCast = 'vector' | 'halfvec' | 'sparsevec';
-/**
- * Whether a declared field type is a vector of any width. Every dialect that treats vectors specially
- * has to answer this for all three, not just `vector`: matching that one alone left `halfvec` and
- * `sparsevec` fields binding as plain arrays on insert and reading back raw.
- */
-export declare function isVectorFieldType(type: unknown): boolean;
 /** Resolves the effective cast from field options, `columnType` taking priority over `type`. */
 export declare function resolveVectorCast(field: {
     type?: unknown;

package/dist/dialect/vectorCast.js

@@ -2,14 +2,6 @@
  * Kept out of `schema/canonicalType.ts`: importing one function from that migration/codegen module
  * pulled all ~18 KB of its type-mapping tables into every consumer's bundle.
  */
-/**
- * Whether a declared field type is a vector of any width. Every dialect that treats vectors specially
- * has to answer this for all three, not just `vector`: matching that one alone left `halfvec` and
- * `sparsevec` fields binding as plain arrays on insert and reading back raw.
- */
-export function isVectorFieldType(type) {
-    return type === 'vector' || type === 'halfvec' || type === 'sparsevec';
-}
 /** Resolves the effective cast from field options, `columnType` taking priority over `type`. */
 export function resolveVectorCast(field) {
     const raw = field?.columnType ?? field?.type;

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

@@ -21,7 +21,7 @@ export declare function Filter<E>(name: string, opts: FilterOptions<E>): (entity
  * `E` is inferred from the class the returned decorator is applied to, which is what lets the column
  * names be checked against it: `@Index(['nope'])` does not compile.
  *
- * @example `@Index(['lastName', 'firstName'], { name: 'idx_users_fullname' })`
+ * @example `@Index(['lastName', 'firstName'], { name: 'users_fullname_idx' })`
  * @example `@Index(['email'], { unique: true })`
  * @example `@Index(['status'], { where: "status = 'active'" })`
  */

package/dist/entity/decorator/entity.js

@@ -33,7 +33,7 @@ export function Filter(name, opts) {
  * `E` is inferred from the class the returned decorator is applied to, which is what lets the column
  * names be checked against it: `@Index(['nope'])` does not compile.
  *
- * @example `@Index(['lastName', 'firstName'], { name: 'idx_users_fullname' })`
+ * @example `@Index(['lastName', 'firstName'], { name: 'users_fullname_idx' })`
  * @example `@Index(['email'], { unique: true })`
  * @example `@Index(['status'], { where: "status = 'active'" })`
  */

package/dist/entity/decorator/members.d.ts

@@ -1,4 +1,5 @@
 import type { EntityGetter, FieldOptions, FieldType, IdValue, RelationManyToManyOptions, RelationManyToOneOptions, RelationOneToManyOptions, RelationOneToOneOptions, TsTypeOf } from '../../type/index.js';
+import type { RejectIncompatible } from '../../util/index.js';
 /** A member decorator that also constrains the property it may be applied to. */
 type MemberDecorator<V> = (value: undefined, context: ClassFieldDecoratorContext<unknown, V>) => void;
 /**
@@ -51,7 +52,7 @@ export declare function Field<O extends FieldOptions<DeclaredValue<O>> & ({
     type: FieldType;
 } | {
     references: EntityGetter;
-}) & RejectUnknown<O, FieldOptions>>(opts: O): MemberDecorator<DeclaredValue<O> | undefined>;
+}) & RejectUnknown<O, FieldOptions> & RejectIncompatible<O>>(opts: O): MemberDecorator<DeclaredValue<O> | undefined>;
 /**
  * Declares the primary key, checked the same way as `@Field`.
  *
@@ -60,7 +61,9 @@ export declare function Field<O extends FieldOptions<DeclaredValue<O>> & ({
  */
 export declare function Id<O extends FieldOptions<DeclaredValue<O>> & {
     type: FieldType;
-} & RejectUnknown<O, FieldOptions>>(opts: O): MemberDecorator<DeclaredValue<O> | undefined>;
+} & RejectUnknown<O, FieldOptions> & RejectIncompatible<O> & {
+    readonly nullable?: false;
+}>(opts: O): MemberDecorator<DeclaredValue<O> | undefined>;
 /**
  * `E` comes from the mandatory `entity` getter, so the context can insist the property really holds that
  * entity: `@ManyToOne({ entity: () => Other })` on a `Company` field stops compiling, and a to-many

package/dist/entity/metadata/definition.js

@@ -1,5 +1,5 @@
 import { SOFT_DELETE_FILTER } from '../../type/index.js';
-import { getKeys, ddlText, hasKeys, isToManyRelation, lowerFirst, normalizeIndexColumn, upperFirst, } from '../../util/index.js';
+import { fieldOptionConflict, getKeys, ddlText, hasKeys, isToManyRelation, lowerFirst, normalizeIndexColumn, upperFirst, } from '../../util/index.js';
 import { ownRegistrations } from '../decorator/bag.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). Version-suffixed
@@ -10,11 +10,15 @@ const metaKey = Symbol.for('uql-orm/entity/metadata/v1');
 const metas = holder[metaKey] ?? new Map();
 holder[metaKey] = metas;
 export function defineField(entity, key, opts = {}) {
-    const meta = ensureMeta(entity);
+    const meta = ensureWritableMeta(entity);
     if (!opts.type && !opts.references && !opts.virtual) {
         throw new TypeError(`'${entity.name}.${key}' needs a 'type'. Declare it - '@Field({ type: String })' - or point the field ` +
             "at another entity with 'references', which resolves the column type from its primary key.");
     }
+    const conflict = fieldOptionConflict(opts);
+    if (conflict) {
+        throw new TypeError(`'${entity.name}.${key}' ${conflict}.`);
+    }
     const fieldKey = key;
     // Flagged when the author gave `references` but no `type`, so schema generation knows to resolve the
     // column from the referenced primary key (picking up its `columnType`, length and chained keys)
@@ -32,7 +36,7 @@ export function defineRelation(entity, key, opts) {
     if (!opts.entity) {
         throw new TypeError(`'${entity.name}.${key}' needs an 'entity' getter, e.g. '@ManyToOne({ entity: () => Company })'.`);
     }
-    const meta = ensureMeta(entity);
+    const meta = ensureWritableMeta(entity);
     // Registration writes the authored shape into a map declared as resolved: `getMeta` runs
     // `fillRelations`, which settles `entity`, `references` and `mappedBy` or throws. Bridging the two
     // shapes here is what lets every consumer read `RelationMeta` without asserting.
@@ -41,7 +45,7 @@ export function defineRelation(entity, key, opts) {
     return meta;
 }
 export function defineHook(entity, methodName, event) {
-    const meta = ensureMeta(entity);
+    const meta = ensureWritableMeta(entity);
     if (!meta.hooks)
         meta.hooks = {};
     if (!meta.hooks[event])
@@ -54,7 +58,7 @@ export function defineHook(entity, methodName, event) {
  * lets the dialects render one shape instead of re-parsing it.
  */
 export function defineIndex(entity, index) {
-    const meta = ensureMeta(entity);
+    const meta = ensureWritableMeta(entity);
     if (!meta.indexes)
         meta.indexes = [];
     meta.indexes.push({
@@ -66,7 +70,7 @@ export function defineIndex(entity, index) {
     return meta;
 }
 export function defineFilter(entity, name, opts) {
-    const meta = ensureMeta(entity);
+    const meta = ensureWritableMeta(entity);
     if (name === SOFT_DELETE_FILTER) {
         throw TypeError(`'${entity.name}' filter name '${SOFT_DELETE_FILTER}' is reserved; it is auto-registered from @Field({ softDelete })`);
     }
@@ -112,7 +116,7 @@ export function defineEntity(entity, opts = {}) {
         throw new TypeError(`'${entity.name}' has a dotted name '${opts.name}'. Name the schema separately as ` +
             `{ schema: '${schema}', name: '${rest.join('.')}' }.`);
     }
-    const meta = ensureMeta(entity);
+    const meta = ensureWritableMeta(entity);
     // Covers `defineEntity(Decorated)` called on a class whose members carry decorators. `@Entity()`
     // drains `context.metadata` itself, because TypeScript only attaches `Symbol.metadata` to the class
     // after class decorators return; draining empties the bag, so whichever runs second is a no-op.
@@ -132,8 +136,9 @@ export function defineEntity(entity, opts = {}) {
     if (!hasKeys(meta.fields)) {
         throw TypeError(`'${entity.name}' must have fields`);
     }
-    meta.name = opts.name ?? entity.name;
-    meta.schema = opts.schema;
+    // A later call composes onto the entity, so saying nothing about the table retracts nothing.
+    meta.name = opts.name ?? meta.name ?? entity.name;
+    meta.schema = opts.schema ?? meta.schema;
     let proto = Object.getPrototypeOf(entity.prototype);
     while (proto.constructor !== Object) {
         const parent = proto.constructor;
@@ -211,12 +216,21 @@ export function getEntities() {
         return acc;
     }, []);
 }
+/**
+ * The metadata of `entity`, marked as changed. Every `define*` goes through this, and nothing outside
+ * this file writes to a meta, so it is the one place a derived cache can be told it has gone stale.
+ */
+function ensureWritableMeta(entity) {
+    const meta = ensureMeta(entity);
+    meta.revision++;
+    return meta;
+}
 function ensureMeta(entity) {
     let meta = metas.get(entity);
     if (meta) {
         return meta;
     }
-    meta = { entity, ids: [], fields: {}, relations: {} };
+    meta = { entity, ids: [], fields: {}, relations: {}, revision: 0 };
     metas.set(entity, meta);
     return meta;
 }
@@ -225,10 +239,13 @@ export function getMeta(entity) {
     if (!meta) {
         throw TypeError(`'${entity.name}' is not an entity`);
     }
-    if (meta.processed) {
+    if (meta.processedAt === meta.revision) {
         return meta;
     }
-    meta.processed = true;
+    // Stamped before finalizing, not after: `fillInverseSide` reads the other side through `getMeta`,
+    // and with each side mapped by the other that recursion has to find this half-filled meta rather
+    // than run again. Finalizing twice is harmless anyway - every step of it skips what it settled.
+    meta.processedAt = meta.revision;
     return fillRelations(meta);
 }
 function fillRelations(meta) {

package/dist/maria/mariaDialect.js

@@ -1,7 +1,7 @@
 import { jsonPath } from '../dialect/jsonSql.js';
 import { MysqlLikeSqlDialect } from '../dialect/mysqlLikeSqlDialect.js';
-import { isVectorFieldType } from '../dialect/vectorCast.js';
 import { getMeta } from '../entity/index.js';
+import { columnFamily } from '../util/field.util.js';
 import { MARIA_VECTOR_METRICS } from './mariaVectorMetrics.js';
 export class MariaDialect extends MysqlLikeSqlDialect {
     dialectName = 'mariadb';
@@ -19,7 +19,8 @@ export class MariaDialect extends MysqlLikeSqlDialect {
         indexIfNotExists: true,
     };
     upsertReturning(meta) {
-        return ` ${this.returningId(meta)}`;
+        const returning = this.returningId(meta);
+        return returning ? ` ${returning}` : '';
     }
     /**
      * MariaDB supports neither MySQL's `->`/`->>` shorthand nor the base's chained form. `JSON_VALUE`
@@ -75,6 +76,6 @@ export class MariaDialect extends MysqlLikeSqlDialect {
     }
     /** 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;
+        return columnFamily(field.type) === 'vector' ? `VEC_ToText(${escapedColumn})` : escapedColumn;
     }
 }

package/dist/migrate/builder/tableBuilder.js

@@ -154,10 +154,10 @@ export class TableBuilder {
         return this;
     }
     unique(columns, options) {
-        return this.addIndex('uq', columns, options, true);
+        return this.addIndex(columns, options, true);
     }
     index(columns, options) {
-        return this.addIndex('idx', columns, options, false);
+        return this.addIndex(columns, options, false);
     }
     /**
      * `@Index` and `table.index(...)` differ only in how the name is defaulted, so both normalize their
@@ -165,12 +165,13 @@ export class TableBuilder {
      * form, and anything left as a bare string would reach it as a column literally named `[object
      * Object]`.
      */
-    addIndex(prefix, columns, options, unique) {
+    addIndex(columns, options, unique) {
         const { name, ...rest } = typeof options === 'string' ? { name: options } : (options ?? {});
         const entries = columns.map(normalizeIndexColumn);
         this._indexes.push({
             ...rest,
-            name: name ?? `${prefix}_${this._name}_${entries.map((entry) => entry.column).join('_')}`,
+            name: name ??
+                derivedIndexName(this._name, entries.map((entry) => entry.column), unique),
             where: ddlText(rest.where, 'a partial-index predicate'),
             entries,
             unique,

package/dist/migrate/drift/driftDetector.js

@@ -4,7 +4,7 @@
  * Detects schema drift between expected schema (from entities) and
  * actual database schema.
  */
-import { canonicalToSql } from '../../schema/canonicalType.js';
+import { canonicalToSql, engineType } from '../../schema/canonicalType.js';
 import { diffSchemas } from '../../schema/schemaASTDiffer.js';
 function resolveOptions(options) {
     return {
@@ -24,16 +24,21 @@ function resolveOptions(options) {
  */
 export function detectDrift(expectedAST, actualAST, options = {}) {
     const opts = resolveOptions(options);
+    const { dialect } = opts;
     const diff = diffSchemas(expectedAST, actualAST, {
         compareIndexes: opts.checkIndexes,
         indexFacets: opts.indexFacets,
         compareRelationships: opts.checkForeignKeys,
         excludeTables: opts.excludeTables,
+        // Without a dialect there is no engine to compare through, and `formatType` below then reports no
+        // type drift at all.
+        ...(dialect && { normalizeType: engineType(dialect) }),
     });
     const drifts = [
         ...detectTableDrifts(diff),
         ...detectColumnDrifts(diff, opts),
         ...detectIndexDrifts(diff),
+        ...detectPrimaryKeyDrifts(diff),
         ...detectRelationshipDrifts(diff),
     ];
     return {
@@ -43,6 +48,21 @@ export function detectDrift(expectedAST, actualAST, options = {}) {
         generatedAt: new Date(),
     };
 }
+/**
+ * A table whose key holds different columns than the entity declares.
+ *
+ * Critical, and reported as a `constraint_mismatch` like any other: rows the database will accept
+ * are not the rows the ORM believes are unique, so it addresses by a key nothing enforces.
+ */
+function detectPrimaryKeyDrifts(diff) {
+    return diff.primaryKeyDiffs.map((pkDiff) => ({
+        type: 'constraint_mismatch',
+        severity: 'critical',
+        table: pkDiff.table,
+        details: `Primary key of "${pkDiff.table}" is (${pkDiff.actual.join(', ') || 'none'}) in the database but (${pkDiff.expected.join(', ') || 'none'}) in the entity`,
+        suggestion: 'Generate a migration to change the primary key',
+    }));
+}
 /**
  * Detect table-level drifts (missing/unexpected tables).
  */