@mikro-orm/sql 7.2.7-dev.6 → 7.2.7-dev.8

package/AbstractSqlDriver.d.ts

@@ -18,6 +18,8 @@ export declare abstract class AbstractSqlDriver<Connection extends AbstractSqlCo
     evaluateFormula(formula: (...args: any[]) => string | Raw, columns: any, table: FormulaTable): string;
     /** For TPT entities, returns ownProps (columns in this table); otherwise returns all props. */
     protected getTableProps<T extends object>(meta: EntityMetadata<T>): EntityProperty<T>[];
+    /** Columns reloaded by INSERT: generated/default columns any row leaves to the database, and explicit `returning` hints. */
+    protected getInsertReturningProperties<T extends object>(meta: EntityMetadata<T>, data: EntityDictionary<T>[]): EntityProperty<T>[];
     /** Columns reloaded by UPDATE: raw values, PKs, generated/version columns and explicit `returning` hints. */
     protected getUpdateReturningProperties<T extends object>(meta: EntityMetadata<T>, data: EntityDictionary<T>[]): EntityProperty<T>[];
     /** Column expression for the `returning` clause of batch updates, applying `convertToJSValueSQL` of custom types. */
@@ -63,6 +65,8 @@ export declare abstract class AbstractSqlDriver<Connection extends AbstractSqlCo
     private buildCloneFields;
     private getCloneableProps;
     nativeInsertMany<T extends object>(entityName: EntityName<T>, data: EntityDictionary<T>[], options?: NativeInsertUpdateManyOptions<T>, transform?: (sql: string) => string): Promise<QueryResult<T>>;
+    /** Resolves the primary key of every inserted row from the supplied data or the returned rows, and reports them via `insertedIds` when all are known. */
+    protected resolveInsertedPrimaryKeys<T extends object>(meta: EntityMetadata<T>, data: EntityDictionary<T>[], res: QueryResult<T>): any[][];
     nativeUpdate<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>, data: EntityDictionary<T>, options?: NativeInsertUpdateOptions<T> & UpsertOptions<T>): Promise<QueryResult<T>>;
     nativeUpdateMany<T extends object>(entityName: EntityName<T>, where: FilterQuery<T>[], data: EntityDictionary<T>[], options?: NativeInsertUpdateManyOptions<T> & UpsertManyOptions<T>, transform?: (sql: string, params: any[]) => string): Promise<QueryResult<T>>;
     nativeDelete<T extends object>(entityName: EntityName<T>, where: FilterQuery<T> | string | any, options?: DeleteOptions<T>): Promise<QueryResult<T>>;

package/AbstractSqlDriver.js

@@ -49,6 +49,12 @@ export class AbstractSqlDriver extends DatabaseDriver {
     getTableProps(meta) {
         return meta.inheritanceType === 'tpt' && meta.ownProps ? meta.ownProps : meta.props;
     }
+    /** Columns reloaded by INSERT: generated/default columns any row leaves to the database, and explicit `returning` hints. */
+    getInsertReturningProperties(meta, data) {
+        return this.getTableProps(meta).filter(prop => prop.returning ||
+            (((prop.persist !== false && prop.defaultRaw) || prop.autoincrement || prop.generated) &&
+                data.some(d => !(prop.name in d) || isRaw(d[prop.name]))));
+    }
     /** Columns reloaded by UPDATE: raw values, PKs, generated/version columns and explicit `returning` hints. */
     getUpdateReturningProperties(meta, data) {
         const returning = new Set();
@@ -801,10 +807,7 @@ export class AbstractSqlDriver extends DatabaseDriver {
                 ? '(' + fields.map(k => this.platform.quoteIdentifier(k)).join(', ') + ')'
                 : `(${this.platform.quoteIdentifier(pks[0])})`;
         if (this.platform.usesOutputStatement()) {
-            const returningProps = this.getTableProps(meta).filter(prop => prop.returning ||
-                (((prop.persist !== false && prop.defaultRaw) || prop.autoincrement || prop.generated) &&
-                    (!(prop.name in data[0]) || isRaw(data[0][prop.name]))));
-            const returningFields = Utils.flatten(returningProps.map(prop => prop.fieldNames));
+            const returningFields = Utils.flatten(this.getInsertReturningProperties(meta, data).map(prop => prop.fieldNames));
             sql +=
                 returningFields.length > 0
                     ? ` output ${returningFields.map(field => 'inserted.' + this.platform.quoteIdentifier(field)).join(', ')}`
@@ -931,10 +934,7 @@ export class AbstractSqlDriver extends DatabaseDriver {
                 .join(', ');
         }
         if (meta && this.platform.usesReturningStatement()) {
-            const returningProps = this.getTableProps(meta).filter(prop => prop.returning ||
-                (((prop.persist !== false && prop.defaultRaw) || prop.autoincrement || prop.generated) &&
-                    (!(prop.name in data[0]) || isRaw(data[0][prop.name]))));
-            const returningFields = Utils.flatten(returningProps.map(prop => prop.fieldNames));
+            const returningFields = Utils.flatten(this.getInsertReturningProperties(meta, data).map(prop => prop.fieldNames));
             /* v8 ignore next */
             sql +=
                 returningFields.length > 0
@@ -945,22 +945,35 @@ export class AbstractSqlDriver extends DatabaseDriver {
             sql = transform(sql);
         }
         const res = await this.execute(sql, params, 'run', options.ctx, withAbortContext(options.loggerContext, options));
-        let pk;
-        if (pks.length > 1) {
-            // owner has composite pk
-            pk = data.map(d => Utils.getOrderedPrimaryKeys(d, meta));
-        }
-        else {
-            res.row ??= {};
-            res.rows ??= [];
-            pk = data.map((d, i) => d[pks[0]] ?? res.rows[i]?.[pks[0]]).map(d => [d]);
-            res.insertId = res.insertId || res.row[pks[0]];
-        }
+        const pk = this.resolveInsertedPrimaryKeys(meta, data, res);
         for (let i = 0; i < collections.length; i++) {
             await this.processManyToMany(meta, pk[i], collections[i], false, options);
         }
         return res;
     }
+    /** Resolves the primary key of every inserted row from the supplied data or the returned rows, and reports them via `insertedIds` when all are known. */
+    resolveInsertedPrimaryKeys(meta, data, res) {
+        const pks = this.getPrimaryKeyFields(meta);
+        if (pks.length > 1) {
+            // owner has composite pk
+            const pk = data.map(d => Utils.getOrderedPrimaryKeys(d, meta));
+            res.insertedIds = pk;
+            return pk;
+        }
+        res.row ??= {};
+        res.rows ??= [];
+        const ids = data.map((d, i) => {
+            // a raw pk expression is resolved by the database, its value only exists in the returned row
+            const supplied = d[meta.primaryKeys[0]] ?? d[pks[0]];
+            return supplied == null || isRaw(supplied) ? res.rows[i]?.[pks[0]] : supplied;
+        });
+        res.insertId = res.insertId || res.row[pks[0]];
+        // drivers without `returning` leave the ids unknown here, keep the `insertId` fallback for them
+        if (ids.every(id => id != null)) {
+            res.insertedIds = ids;
+        }
+        return ids.map(id => [id]);
+    }
     async nativeUpdate(entityName, where, data, options = {}) {
         options.convertCustomTypes ??= true;
         const meta = this.metadata.get(entityName);
@@ -2544,7 +2557,9 @@ export class AbstractSqlDriver extends DatabaseDriver {
         if (ret.length > 0 && !hasExplicitFields && addFormulas) {
             // `toString()` must yield the quoted alias like `QueryBuilder.finalize()`, which dedupes formulas by rendered SQL
             const quotedAlias = this.platform.quoteIdentifier(alias);
-            const columns = meta.createColumnMappingObject(alias, quotedAlias.toString());
+            // TPT parent aliases are only known once the parent joins exist
+            qb.ensureTPTJoins();
+            const columns = meta.createColumnMappingObject(p => qb.helper.getTPTAliasForProperty(p.name, alias), quotedAlias.toString());
             const effectiveSchema = schema ?? (meta.schema !== '*' ? meta.schema : undefined);
             for (const prop of meta.props) {
                 if (lazyProps.includes(prop)) {

package/dialects/postgresql/BasePostgreSqlPlatform.d.ts

@@ -59,6 +59,7 @@ export declare class BasePostgreSqlPlatform extends AbstractSqlPlatform {
     };
     isBigIntProperty(prop: EntityProperty): boolean;
     getArrayDeclarationSQL(): string;
+    supportsArrayOverlap(): boolean;
     getFloatDeclarationSQL(): string;
     getDoubleDeclarationSQL(): string;
     getEnumTypeDeclarationSQL(column: {

package/dialects/postgresql/BasePostgreSqlPlatform.js

@@ -199,6 +199,9 @@ export class BasePostgreSqlPlatform extends AbstractSqlPlatform {
     getArrayDeclarationSQL() {
         return 'text[]';
     }
+    supportsArrayOverlap() {
+        return true;
+    }
     getFloatDeclarationSQL() {
         return 'real';
     }

package/dialects/postgresql/PostgreSqlExceptionConverter.js

@@ -25,6 +25,7 @@ export class PostgreSqlExceptionConverter extends ExceptionConverter {
                 break;
             case '23502':
                 return new NotNullConstraintViolationException(exception);
+            case '23001':
             case '23503':
                 return new ForeignKeyConstraintViolationException(exception);
             case '23505':

package/dialects/postgresql/PostgreSqlSchemaHelper.js

@@ -409,14 +409,19 @@ export class PostgreSqlSchemaHelper extends SchemaHelper {
             const key = this.getTableKey(col);
             ret[key] ??= [];
             let type = col.data_type.toLowerCase() === 'array' ? col.udt_name.replace(/^_(.*)$/, '$1[]') : col.udt_name;
+            // `udt_name` drops array element typmods (`_numeric` for `numeric(12,2)[]`), recover them from `format_type`
+            const arrayModifier = type.endsWith('[]')
+                ? /^[^(]*(\([^)]*\))[^(]*\[\]$/.exec(col.format_type ?? '')?.[1]
+                : undefined;
+            if (arrayModifier) {
+                type = `${type.slice(0, -2)}${arrayModifier}[]`;
+            }
             if (col.data_type === 'USER-DEFINED' &&
                 col.udt_schema &&
                 col.udt_schema !== this.platform.getDefaultSchemaName()) {
                 type = `${col.udt_schema}.${type}`;
             }
-            if (type === 'bpchar') {
-                type = 'char';
-            }
+            type = type.replace(/^bpchar\b/, 'char');
             // postgis stores the geometry/geography typmod (`geometry(point,4326)`) in atttypmod, which
             // information_schema does not expose — recover the full type via format_type so it round-trips
             if ((col.udt_name === 'geometry' || col.udt_name === 'geography') && col.format_type) {

package/dialects/sqlite/SqlitePlatform.d.ts

@@ -1,4 +1,4 @@
-import { type EntityProperty, type IsolationLevel } from '@mikro-orm/core';
+import { type EntityMetadata, type EntityProperty, type IsolationLevel } from '@mikro-orm/core';
 import { AbstractSqlPlatform } from '../../AbstractSqlPlatform.js';
 import { SqliteNativeQueryBuilder } from './SqliteNativeQueryBuilder.js';
 import { SqliteSchemaHelper } from './SqliteSchemaHelper.js';
@@ -74,6 +74,7 @@ export declare class SqlitePlatform extends AbstractSqlPlatform {
      */
     supportsSchemas(): boolean;
     getDefaultSchemaName(): string | undefined;
+    validateMetadata(meta: EntityMetadata): void;
     getFullTextWhereClause(): string;
     escape(value: any): string;
     convertVersionValue(value: Date | number, prop: EntityProperty): number | {

package/dialects/sqlite/SqlitePlatform.js

@@ -1,3 +1,4 @@
+import { MetadataError } from '@mikro-orm/core';
 import { AbstractSqlPlatform } from '../../AbstractSqlPlatform.js';
 import { SqliteNativeQueryBuilder } from './SqliteNativeQueryBuilder.js';
 import { SqliteSchemaHelper } from './SqliteSchemaHelper.js';
@@ -110,6 +111,14 @@ export class SqlitePlatform extends AbstractSqlPlatform {
         // Return 'main' only when schema support is active (i.e., databases are attached)
         return this.supportsSchemas() ? 'main' : undefined;
     }
+    validateMetadata(meta) {
+        super.validateMetadata(meta);
+        // `main` always exists and `*` resolves at runtime; anything else fails later as `unknown database` unless attached
+        const attached = this.config.get('attachDatabases')?.some(db => db.name === meta.schema);
+        if (meta.schema && !['main', '*'].includes(meta.schema) && !attached) {
+            throw new MetadataError(`Entity ${meta.className} declares schema '${meta.schema}', but SQLite cannot address it: attach it via \`attachDatabases\` or remove the schema in \`discovery.onMetadata\` when sharing entities between drivers`);
+        }
+    }
     getFullTextWhereClause() {
         return `:column: match :query`;
     }

package/dialects/sqlite/SqliteSchemaHelper.js

@@ -242,7 +242,8 @@ export class SqliteSchemaHelper extends SchemaHelper {
             }
             for (let i = cols.length - 1; i >= 0; i--) {
                 const col = cols[i];
-                const re = ` *, *[\`"']?${col.name}[\`"']? (.*)`;
+                // the first column is not preceded by a comma
+                const re = ` *(?:^|,) *[\`"']?${col.name}[\`"']? (.*)`;
                 const columnDef = new RegExp(re, 'i').exec(columnsDef);
                 if (columnDef) {
                     columns[col.name] = { name: col.name, definition: columnDef[1] };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikro-orm/sql",
-  "version": "7.2.7-dev.6",
+  "version": "7.2.7-dev.8",
   "description": "TypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. Supports MongoDB, MySQL, PostgreSQL and SQLite databases as well as usage with vanilla JavaScript.",
   "keywords": [
     "data-mapper",
@@ -53,7 +53,7 @@
     "@mikro-orm/core": "^7.2.6"
   },
   "peerDependencies": {
-    "@mikro-orm/core": "7.2.7-dev.6"
+    "@mikro-orm/core": "7.2.7-dev.8"
   },
   "engines": {
     "node": ">= 22.17.0"

package/query/CriteriaNode.d.ts

@@ -27,6 +27,7 @@ export declare class CriteriaNode<T extends object> implements ICriteriaNode<T>
         parentPath?: string;
     }): string;
     private isPivotJoin;
+    protected isOperatorPayload(payload: any): boolean;
     getPivotPath(path: string): string;
     aliased(field: string, alias?: string): string;
     isStrict(): boolean;

package/query/CriteriaNode.js

@@ -125,8 +125,17 @@ export class CriteriaNode {
             this.payload instanceof RegExp ||
             this.payload instanceof Date ||
             rawField;
-        const operator = Utils.isObject(this.payload) && Utils.getObjectQueryKeys(this.payload).every(k => Utils.isOperator(k, false));
-        return this.prop.kind === ReferenceKind.MANY_TO_MANY && (scalar || operator);
+        return this.prop.kind === ReferenceKind.MANY_TO_MANY && (scalar || this.isOperatorPayload(this.payload));
+    }
+    isOperatorPayload(payload) {
+        return (Utils.isObject(payload) &&
+            Utils.getObjectQueryKeys(payload).every(k => {
+                if (k === '$not' && payload[k] instanceof CriteriaNode && Utils.isPlainObject(payload[k].payload)) {
+                    // `$not` wrapping entity conditions is a condition on the target entity, not on the relation itself
+                    return Utils.getObjectQueryKeys(payload[k].payload).every(ik => Utils.isOperator(ik, false));
+                }
+                return Utils.isOperator(k, false);
+            }));
     }
     getPivotPath(path) {
         return `${path}[pivot]`;

package/query/ObjectCriteriaNode.js

@@ -283,18 +283,7 @@ export class ObjectCriteriaNode extends CriteriaNode {
         const embeddable = this.prop.kind === ReferenceKind.EMBEDDED;
         const knownKey = [ReferenceKind.SCALAR, ReferenceKind.MANY_TO_ONE, ReferenceKind.EMBEDDED].includes(this.prop.kind) ||
             (this.prop.kind === ReferenceKind.ONE_TO_ONE && this.prop.owner);
-        const operatorKeys = knownKey &&
-            keys.every(key => {
-                if (key === '$not') {
-                    // $not wraps conditions like $and/$or, check if it wraps entity property conditions (needs auto-join)
-                    // vs simple operator conditions on the FK (doesn't need auto-join)
-                    const childPayload = this.payload[key].payload;
-                    if (Utils.isPlainObject(childPayload)) {
-                        return Utils.getObjectQueryKeys(childPayload).every(k => Utils.isOperator(k, false));
-                    }
-                }
-                return Utils.isOperator(key, false);
-            });
+        const operatorKeys = knownKey && this.isOperatorPayload(this.payload);
         const primaryKeys = knownKey &&
             keys.every(key => {
                 if (key === '$not') {
@@ -322,8 +311,7 @@ export class ObjectCriteriaNode extends CriteriaNode {
             this.payload instanceof RegExp ||
             this.payload instanceof Date ||
             rawField;
-        const operator = Utils.isPlainObject(this.payload) &&
-            Utils.getObjectQueryKeys(this.payload).every(k => Utils.isOperator(k, false));
+        const operator = Utils.isPlainObject(this.payload) && this.isOperatorPayload(this.payload);
         const field = `${alias}.${this.prop.name}`;
         const method = qb.hasFlag(QueryFlag.INFER_POPULATE) ? 'joinAndSelect' : 'join';
         const path = this.getPath();

package/query/QueryBuilder.d.ts

@@ -821,6 +821,7 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
      * ```
      */
     stream(options?: QBStreamOptions): AsyncIterableIterator<Loaded<Entity, Hint, Fields>>;
+    private convertStreamExceptions;
     /**
      * Alias for `qb.getResultList()`
      */
@@ -1003,6 +1004,10 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
     processPopulateHint(): void;
     private processPopulateWhere;
     private mergeOnConditions;
+    /**
+     * `$not` can be moved to a join's `on` clause as a whole only when all of its conditions target that join.
+     */
+    private getNotConditionAlias;
     /**
      * `$or` branches can be moved to a join's `on` clause only when they all target that same join
      * and stay flat — a partial `$or` in the `on` clause would drop rows matching a sibling branch,
@@ -1012,9 +1017,9 @@ export declare class QueryBuilder<Entity extends object = AnyEntity, RootAlias e
     private canDistributeOrBranches;
     private getOrBranchAliases;
     /**
-     * An entity filter's `$or` that cannot be distributed is applied intact to the `on` clause of the
-     * outermost join common to all targeted joins, nesting the targeted joins under it so the clause
-     * can reference their aliases.
+     * A condition that cannot be distributed (an entity filter's `$or`, or a `$not` spanning several joins)
+     * is applied intact to the `on` clause of the outermost join common to all targeted joins, nesting
+     * the targeted joins under it so the clause can reference their aliases.
      */
     private mergeFilterOrCondition;
     /**

package/query/QueryBuilder.js

@@ -1080,12 +1080,19 @@ export class QueryBuilder {
         const conn = this.getConnection();
         // outside a transaction, wrap in a short implicit one so RLS `set local` session context applies (no-op when unset)
         const sessionContext = this.context ? undefined : this.em?.getTransactionSessionContext();
-        const res = await (sessionContext
-            ? conn.transactional(trx => conn.execute(query.sql, query.params, method, trx, loggerContext), {
-                sessionContext,
-                loggerContext,
-            })
-            : conn.execute(query.sql, query.params, method, this.context, loggerContext));
+        let res;
+        // a QueryBuilder used directly must honour the same `convertException` contract as the driver methods
+        try {
+            res = await (sessionContext
+                ? conn.transactional(trx => conn.execute(query.sql, query.params, method, trx, loggerContext), {
+                    sessionContext,
+                    loggerContext,
+                })
+                : conn.execute(query.sql, query.params, method, this.context, loggerContext));
+        }
+        catch (e) {
+            throw this.driver.convertException(e);
+        }
         const meta = this.mainAlias.meta;
         if (!options.mapResults || !meta) {
             await this.em?.storeCache(this.#state.cache, cached, res);
@@ -1146,7 +1153,7 @@ export class QueryBuilder {
         const chunkSize = options.chunkSize ?? 100;
         const query = this.toQuery();
         const loggerContext = { id: this.em?.id, ...this.loggerContext, ...this.#abortOptions };
-        const res = this.getConnection().stream(query.sql, query.params, this.context, loggerContext, chunkSize);
+        const res = this.convertStreamExceptions(this.getConnection().stream(query.sql, query.params, this.context, loggerContext, chunkSize));
         const meta = this.mainAlias.meta;
         if (options.rawResults || !meta) {
             yield* res;
@@ -1180,6 +1187,14 @@ export class QueryBuilder {
             }
         }
     }
+    async *convertStreamExceptions(res) {
+        try {
+            yield* res;
+        }
+        catch (e) {
+            throw this.driver.convertException(e);
+        }
+    }
     /**
      * Alias for `qb.getResultList()`
      */
@@ -1558,7 +1573,10 @@ export class QueryBuilder {
                 field = asMatch[1].trim();
                 customAlias = asMatch[2];
             }
-            const join = Object.keys(this.#state.joins).find(k => field === k.substring(0, k.indexOf('#')));
+            // an aliased field is always a column, never a relation to expand, even when an FK column is named like its relation
+            const join = customAlias
+                ? undefined
+                : Object.keys(this.#state.joins).find(k => field === k.substring(0, k.indexOf('#')));
             if (join && type === 'where') {
                 ret.push(...this.helper.mapJoinColumns(this.type, this.#state.joins[join]));
                 return;
@@ -2102,7 +2120,13 @@ export class QueryBuilder {
     }
     mergeOnConditions(joins, cond, filter, op) {
         for (const k of Object.keys(cond)) {
-            if (Utils.isOperator(k)) {
+            const notAlias = k === '$not' ? this.getNotConditionAlias(cond[k], joins) : undefined;
+            if (k === '$not' && !notAlias) {
+                // splitting a `$not` across joins would drop the negation, so it is kept intact on their common ancestor join
+                this.mergeFilterOrCondition([{ $not: cond[k] }], joins);
+                continue;
+            }
+            if (Utils.isOperator(k) && !notAlias) {
                 if (Array.isArray(cond[k])) {
                     if (k === '$or' && !this.canDistributeOrBranches(cond[k], joins)) {
                         // entity filters have no other sink, so their `$or` is kept intact on the outermost targeted join instead
@@ -2116,7 +2140,7 @@ export class QueryBuilder {
                 /* v8 ignore next */
                 this.mergeOnConditions(joins, cond[k], filter, k);
             }
-            const [alias] = this.helper.splitField(k);
+            const alias = notAlias ?? this.helper.splitField(k)[0];
             const join = joins.find(j => j.alias === alias);
             if (join) {
                 const parentJoin = joins.find(j => j.alias === join.ownerAlias);
@@ -2145,6 +2169,14 @@ export class QueryBuilder {
             }
         }
     }
+    /**
+     * `$not` can be moved to a join's `on` clause as a whole only when all of its conditions target that join.
+     */
+    getNotConditionAlias(cond, joins) {
+        const aliases = this.getOrBranchAliases([cond]);
+        const [alias] = aliases;
+        return aliases.size === 1 && joins.some(j => j.alias === alias) ? alias : undefined;
+    }
     /**
      * `$or` branches can be moved to a join's `on` clause only when they all target that same join
      * and stay flat — a partial `$or` in the `on` clause would drop rows matching a sibling branch,
@@ -2173,9 +2205,9 @@ export class QueryBuilder {
         return aliases;
     }
     /**
-     * An entity filter's `$or` that cannot be distributed is applied intact to the `on` clause of the
-     * outermost join common to all targeted joins, nesting the targeted joins under it so the clause
-     * can reference their aliases.
+     * A condition that cannot be distributed (an entity filter's `$or`, or a `$not` spanning several joins)
+     * is applied intact to the `on` clause of the outermost join common to all targeted joins, nesting
+     * the targeted joins under it so the clause can reference their aliases.
      */
     mergeFilterOrCondition(branches, joins) {
         const aliases = this.getOrBranchAliases(branches);

package/query/QueryBuilderHelper.js

@@ -623,6 +623,19 @@ export class QueryBuilderHelper {
                 parts.push(`${this.#platform.quoteIdentifier(mappedKey)} ${replacement} ${sql}`);
                 params.push(...query.params);
             }
+            else if (['$in', '$nin'].includes(op) &&
+                prop?.customType instanceof ArrayType &&
+                Array.isArray(opValue) &&
+                !opValue.every((v) => Array.isArray(v))) {
+                // a flat list on an array column matches any of its elements, like in mongo
+                if (!this.#platform.supportsArrayOverlap()) {
+                    throw new ValidationError(`${op} on array property ${prop.name} expects a list of arrays, use $eq for an exact match`);
+                }
+                const mappedKey = this.mapper(key, type, opValue, null);
+                const sql = `${this.#platform.quoteIdentifier(mappedKey)} && ?`;
+                parts.push(op === '$in' ? sql : `not (${sql})`);
+                params.push(prop.customType.convertToDatabaseValue(opValue, this.#platform, { fromQuery: true, key: op, mode: 'query' }));
+            }
             else {
                 const mappedKey = this.mapper(key, type, opValue, null);
                 const val = this.getValueReplacement(fields, opValue, params, op, prop, rowValues);
@@ -641,16 +654,15 @@ export class QueryBuilderHelper {
                 }
                 return `(${tmp.join(', ')})`;
             }
-            // array custom types (e.g. `$contains`/`$overlap` on `string[]` columns) are converted to a single
-            // array literal, so we emit a single bound parameter — not one per element wrapped in a tuple
+            // array custom types convert a whole array into one literal, so each candidate array binds a single parameter
             if (prop?.customType instanceof ArrayType) {
-                const item = prop.customType.convertToDatabaseValue(value, this.#platform, {
-                    fromQuery: true,
-                    key,
-                    mode: 'query',
-                });
-                params.push(item);
-                return '?';
+                const list = key === '$in' || key === '$nin';
+                const items = list ? value : [value];
+                for (const item of items) {
+                    params.push(prop.customType.convertToDatabaseValue(item, this.#platform, { fromQuery: true, key, mode: 'query' }));
+                }
+                const sql = items.map(() => '?').join(', ');
+                return list ? `(${sql})` : sql;
             }
             value.forEach(p => params.push(p));
             return `(${value.map(() => '?').join(', ')})`;

package/schema/DatabaseTable.js

@@ -760,6 +760,10 @@ export class DatabaseTable {
                 !idx.primary &&
                 !idx.where &&
                 !this.hasAdvancedIndexOptions(idx));
+        // `getMappedType('timestamptz(3)[]')` resolves to the element type so diffing keeps the modifier, but the property is still an array
+        if (column.type?.endsWith('[]') && !column.enumItems?.length) {
+            column = { ...column, mappedType: Type.getType(t.array) };
+        }
         const kind = this.getReferenceKind(fk, unique);
         const runtimeType = this.getPropertyTypeForColumn(namingStrategy, column, fk);
         const type = fk