@atscript/db-mysql 0.1.146 → 0.1.148

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDefaultFn, TDbDeleteResult, TDbFieldMeta, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TExistingTableOption, TFieldOps, TPrimaryKeyChange, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TTableOptionDiff, TValueFormatterPair } from "@atscript/db";
+import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDefaultFn, TDbDeleteResult, TDbFieldMeta, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TExistingTableOption, TFieldOps, TPrimaryKeyChange, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TTableOptionDiff, TValueFormatterPair, TViewCapability } from "@atscript/db";
 import { TMetadataMap } from "@atscript/typescript/utils";
 import { FilterExpr as FilterExpr$1 } from "@uniqu/core";
-import { TSqlFragment, TSqlFragment as TSqlFragment$1 } from "@atscript/db-sql-tools";
+import { TFilterVisitorOptions, TSqlFragment, TSqlFragment as TSqlFragment$1 } from "@atscript/db-sql-tools";
 
 //#region src/types.d.ts
 /**
@@ -136,6 +136,15 @@ declare class MysqlAdapter extends BaseDbAdapter {
    * to `NO_ENGINE_SUBSTITUTION`) would turn `'abc'` into `0` silently.
    */
   private _withStrictSession;
+  /**
+   * Relational predicates (`$some` / `$none`) render as correlated
+   * `[NOT] EXISTS` subqueries — in reads and in mutation filters alike.
+   * An UPDATE / DELETE whose predicate reads the mutated table itself is
+   * rewritten through a materialized derived table (MySQL error 1093).
+   *
+   * @since 0.1.147
+   */
+  supportsRelationFilters(_mode: "read" | "write"): boolean;
   /** MySQL InnoDB enforces FK constraints natively. */
   supportsNativeForeignKeys(): boolean;
   prepareId(id: unknown, _fieldType: unknown): unknown;
@@ -146,8 +155,12 @@ declare class MysqlAdapter extends BaseDbAdapter {
    * server's time zone tables (probed per zone in `aggregate()`).
    */
   calendarBucketUnits(): ReadonlySet<BucketUnit>;
-  /** Every aggregate function, `countDistinct` included. */
+  /** Every aggregate function: `countDistinct`, `first` and `last` included. */
   aggregateFns(): ReadonlySet<AggregateFn>;
+  /** Arithmetic in an aggregate `$select` (`{ $expr }`, `{ $fn, $expr }`). */
+  supportsAggregateExpressions(): boolean;
+  /** Computed view columns and first-row joins. */
+  viewCapabilities(): ReadonlySet<TViewCapability>;
   onBeforeFlatten(_type: unknown): void;
   onFieldScanned(field: string, _type: unknown, metadata: TMetadataMap<AtscriptMetadata>): void;
   getDesiredTableOptions(): TExistingTableOption[];
@@ -165,15 +178,89 @@ declare class MysqlAdapter extends BaseDbAdapter {
    *
    * MySQL uses numeric error codes:
    * - 1062 = ER_DUP_ENTRY (unique constraint violation)
+   * - 1586 = ER_DUP_ENTRY_WITH_KEY_NAME (same, for a multi-row INSERT)
    * - 1451 = ER_ROW_IS_REFERENCED_2 (FK violation on delete)
    * - 1452 = ER_NO_REFERENCED_ROW_2 (FK violation on insert/update)
    */
   private _wrapConstraintError;
+  /** Rethrows `error` as a structured `DbError` when it is a unique / FK violation, else as is. */
+  private _mapConstraintError;
   private _mapFkError;
   insertOne(data: Record<string, unknown>): Promise<TDbInsertResult>;
   insertMany(data: Array<Record<string, unknown>>): Promise<TDbInsertManyResult>;
+  /** Physical column of the single-column AUTO_INCREMENT primary key, if the table has one. */
+  private _autoIncrementPk;
+  /**
+   * Splits `rows` into runs that each map to ONE statement with a derivable
+   * id sequence. MySQL reports only the first GENERATED id of a statement, and
+   * an explicit auto-increment value above the counter bumps the counter, so a
+   * statement mixing explicit and generated PKs cannot be mapped by
+   * `insertId + i * step`: the chunk is cut into CONSECUTIVE runs of one kind,
+   * executed in input order (so "an earlier row wins" a unique collision, even
+   * under a case-insensitive collation). A table without an AUTO_INCREMENT PK,
+   * or a chunk of one kind, stays one group.
+   */
+  private _idGroups;
+  /** The session `sql_mode` text on the current connection (`undefined` when the server returns no row). */
+  private _sessionSqlMode;
+  /** The {@link TZeroIsExplicit} of one `insertMany` / `insertManyIgnore` call. */
+  private _zeroIsExplicit;
+  /**
+   * Warns ONCE per driver when the session `sql_mode` is not strict: writes
+   * (insert-ignore included) assume `STRICT_TRANS_TABLES` / `STRICT_ALL_TABLES`
+   * (the MySQL 8 default); a non-strict mode coerces a NOT NULL violation to the
+   * column default instead of failing. Only probes when the adapter has a logger.
+   */
+  private _warnNonStrictMode;
+  /** The {@link TIncrementStep} of one `insertMany` / `insertManyIgnore` call. */
+  private _incrementStep;
+  /**
+   * Ids of the rows of ONE successful multi-row INSERT of a homogeneous
+   * {@link _idGroups} group: generated rows get ids from `insertId` stepping by
+   * the session's `@@auto_increment_increment` (consecutive within one
+   * statement under `innodb_autoinc_lock_mode` 0 / 1, and — for a known row
+   * count — mode 2, the 8.0 default), explicit rows keep their own value.
+   */
+  private _groupInsertedIds;
+  supportsInsertIgnore(): boolean;
+  /**
+   * Per chunk: ONE optimistic multi-row INSERT (an all-new batch costs a single
+   * statement). Only when it hits a duplicate key (errno 1062 / 1586) does ONE
+   * SELECT of the chunk's primary / unique key tuples find the stored rows
+   * (skipped as conflicts) and the survivors go in as one more multi-row
+   * INSERT — a dense-duplicate chunk is three statements, never O(rows). Only
+   * if that INSERT still collides (a concurrent writer raced in, or a
+   * collation-equal value the exact-match pre-check missed) are the survivors
+   * bisected: each half is retried, recursively, and a single row that still
+   * collides is skipped. A failed statement is rolled back by InnoDB alone, so
+   * the transaction stays usable. A chunk mixing explicit and generated
+   * auto-increment ids is processed as one such sequence per consecutive run of a kind. Deliberately
+   * NOT `INSERT IGNORE` (it would downgrade NOT NULL / FK / truncation errors
+   * to warnings) and not `ON DUPLICATE KEY UPDATE` (a no-op update is
+   * indistinguishable from an insert in the affected-rows count).
+   */
+  insertManyIgnore(data: Array<Record<string, unknown>>): Promise<TDbInsertIgnoreSlot[]>;
+  /**
+   * Indices of `rows` whose primary / unique-index key tuple is already stored
+   * (a row with a null / missing key component never collides). One SELECT
+   * covers every key set; it is split only to stay under the parameter limit.
+   * Skipped entirely when no row carries a key value (generated PK, no unique
+   * index values).
+   */
+  private _findStoredKeyConflicts;
+  /** Optimistic INSERT of a group, then pre-check + survivor INSERT (+ bisect on a race). */
+  private _insertIgnoringGroup;
+  /** Retries the halves of a group whose one INSERT is known to collide; a lone colliding row is skipped. */
+  private _bisectGroup;
+  /** ONE INSERT of a group's rows; `undefined` on a duplicate key (errno 1062 / 1586). */
+  private _tryInsertGroup;
   findOne(query: DbQuery): Promise<Record<string, unknown> | null>;
   findMany(query: DbQuery): Promise<Array<Record<string, unknown>>>;
+  /**
+   * `$skip` / `$limit` per partition in one statement: a `ROW_NUMBER()`
+   * window over `partitionBy` (the generic `$with` loader's per-parent page).
+   */
+  findManyPerPartition(query: DbQuery, partitionBy: readonly string[]): Promise<Array<Record<string, unknown>>>;
   count(query: DbQuery): Promise<number>;
   aggregate(query: DbQuery): Promise<Array<Record<string, unknown>>>;
   /**
@@ -186,6 +273,26 @@ declare class MysqlAdapter extends BaseDbAdapter {
    * expression skips `CONVERT_TZ`. Successes are cached per driver.
    */
   private _ensureBucketZone;
+  /**
+   * The WHERE of an UPDATE / DELETE on this table. MySQL rejects a statement
+   * whose WHERE reads the mutated table in a subquery (error 1093,
+   * `ER_UPDATE_TABLE_USED`) — what a relational predicate (`$some` / `$none`)
+   * does when its target or junction table, at any nesting level, is this
+   * table (a self relation such as `parent`). Such a filter is re-keyed on the
+   * primary key through a materialized derived table:
+   *
+   * ```sql
+   * WHERE (<pk…>) IN (SELECT * FROM (SELECT DISTINCT <pk…> FROM t WHERE <where>) AS `_rfm`)
+   * ```
+   *
+   * `DISTINCT` keeps the optimizer from merging the derived table back into
+   * the statement. Every other filter renders as-is.
+   *
+   * @since 0.1.147
+   */
+  private _mutationWhere;
+  /** `true` when a relational predicate of `filter` (nested ones included) reads this table. */
+  private _filterReadsOwnTable;
   updateOne(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps, expectedVersion?: number): Promise<TDbUpdateResult>;
   updateMany(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps): Promise<TDbUpdateResult>;
   replaceOne(filter: FilterExpr, data: Record<string, unknown>, expectedVersion?: number): Promise<TDbUpdateResult>;
@@ -284,6 +391,18 @@ declare class MysqlAdapter extends BaseDbAdapter {
 }
 //#endregion
 //#region src/mysql2-driver.d.ts
+/** Options of {@link Mysql2Driver}. */
+interface TMysql2DriverOptions {
+  /**
+   * Add `STRICT_TRANS_TABLES` to the session `sql_mode` of every new pool
+   * connection (default `true`, since 0.1.148). The server's own modes are
+   * kept — the mode is appended, never replaced. A non-strict server (Amazon
+   * RDS defaults to `NO_ENGINE_SUBSTITUTION`) otherwise coerces a `NOT NULL`,
+   * out-of-range or too-long value instead of failing the write. Pass `false`
+   * to keep the server's `sql_mode` untouched.
+   */
+  strictMode?: boolean;
+}
 /**
  * {@link TMysqlDriver} implementation backed by `mysql2/promise`.
  *
@@ -311,6 +430,11 @@ declare class MysqlAdapter extends BaseDbAdapter {
  * const driver = new Mysql2Driver(pool)
  * ```
  *
+ * Every new pool connection gets `STRICT_TRANS_TABLES` appended to its session
+ * `sql_mode` (since 0.1.148); pass `{ strictMode: false }` as the second
+ * argument to opt out. A pre-created `Pool` is covered too: connections it
+ * opened earlier get the statement when they are first acquired through it.
+ *
  * Requires `mysql2` to be installed:
  * ```bash
  * pnpm add mysql2
@@ -319,13 +443,15 @@ declare class MysqlAdapter extends BaseDbAdapter {
 declare class Mysql2Driver implements TMysqlDriver {
   private pool;
   private poolInit;
-  constructor(poolOrConfig: string | import("mysql2/promise").Pool | import("mysql2/promise").PoolOptions);
+  constructor(poolOrConfig: string | import("mysql2/promise").Pool | import("mysql2/promise").PoolOptions, options?: TMysql2DriverOptions);
   private getPool;
   run(sql: string, params?: unknown[]): Promise<TMysqlRunResult>;
   all<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
   get<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null>;
   exec(sql: string): Promise<void>;
   getConnection(): Promise<TMysqlConnection>;
+  private _closing?;
+  /** Idempotent: every call returns the first call's promise. */
   close(): Promise<void>;
 }
 //#endregion
@@ -335,17 +461,24 @@ declare class Mysql2Driver implements TMysqlDriver {
  *
  * @returns `{ sql, params }` — the WHERE clause (without "WHERE") and bound params.
  *          Returns `{ sql: '1=1', params: [] }` for empty/null filters.
+ *
+ * Relational predicates (`$some` / `$none`) render as correlated `EXISTS`
+ * subqueries referencing the outer table by `opts.qualifier` (default: the
+ * source table) — a statement with an aliased FROM must pass its alias.
+ *
+ * @param opts - since 0.1.147
  */
-declare function buildWhere(filter: FilterExpr$1): TSqlFragment$1;
+declare function buildWhere(filter: FilterExpr$1, opts?: TFilterVisitorOptions): TSqlFragment$1;
 //#endregion
 //#region src/index.d.ts
 /**
  * Creates a {@link DbSpace} backed by a MySQL connection pool.
  *
  * @param uri - MySQL connection URI (e.g., `mysql://root@localhost:3306/mydb`)
- * @param options - Additional pool options passed to mysql2.
+ * @param options - Additional pool options passed to mysql2. `strictMode: false`
+ *   (not a pool option) opts out of the per-session `STRICT_TRANS_TABLES` ({@link Mysql2Driver}).
  * @returns A `DbSpace` that creates `MysqlAdapter` instances per table.
  */
 declare function createAdapter(uri: string, options?: Record<string, unknown>): DbSpace;
 //#endregion
-export { Mysql2Driver, MysqlAdapter, type TMysqlConnection, type TMysqlDriver, type TMysqlRunResult, type TSqlFragment, buildWhere, createAdapter };
+export { Mysql2Driver, MysqlAdapter, type TMysql2DriverOptions, type TMysqlConnection, type TMysqlDriver, type TMysqlRunResult, type TSqlFragment, buildWhere, createAdapter };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDefaultFn, TDbDeleteResult, TDbFieldMeta, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TExistingTableOption, TFieldOps, TPrimaryKeyChange, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TTableOptionDiff, TValueFormatterPair } from "@atscript/db";
-import { TSqlFragment, TSqlFragment as TSqlFragment$1 } from "@atscript/db-sql-tools";
+import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDefaultFn, TDbDeleteResult, TDbFieldMeta, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TExistingTableOption, TFieldOps, TPrimaryKeyChange, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TTableOptionDiff, TValueFormatterPair, TViewCapability } from "@atscript/db";
+import { TFilterVisitorOptions, TSqlFragment, TSqlFragment as TSqlFragment$1 } from "@atscript/db-sql-tools";
 import { FilterExpr as FilterExpr$1 } from "@uniqu/core";
 import { TMetadataMap } from "@atscript/typescript/utils";
 
@@ -136,6 +136,15 @@ declare class MysqlAdapter extends BaseDbAdapter {
    * to `NO_ENGINE_SUBSTITUTION`) would turn `'abc'` into `0` silently.
    */
   private _withStrictSession;
+  /**
+   * Relational predicates (`$some` / `$none`) render as correlated
+   * `[NOT] EXISTS` subqueries — in reads and in mutation filters alike.
+   * An UPDATE / DELETE whose predicate reads the mutated table itself is
+   * rewritten through a materialized derived table (MySQL error 1093).
+   *
+   * @since 0.1.147
+   */
+  supportsRelationFilters(_mode: "read" | "write"): boolean;
   /** MySQL InnoDB enforces FK constraints natively. */
   supportsNativeForeignKeys(): boolean;
   prepareId(id: unknown, _fieldType: unknown): unknown;
@@ -146,8 +155,12 @@ declare class MysqlAdapter extends BaseDbAdapter {
    * server's time zone tables (probed per zone in `aggregate()`).
    */
   calendarBucketUnits(): ReadonlySet<BucketUnit>;
-  /** Every aggregate function, `countDistinct` included. */
+  /** Every aggregate function: `countDistinct`, `first` and `last` included. */
   aggregateFns(): ReadonlySet<AggregateFn>;
+  /** Arithmetic in an aggregate `$select` (`{ $expr }`, `{ $fn, $expr }`). */
+  supportsAggregateExpressions(): boolean;
+  /** Computed view columns and first-row joins. */
+  viewCapabilities(): ReadonlySet<TViewCapability>;
   onBeforeFlatten(_type: unknown): void;
   onFieldScanned(field: string, _type: unknown, metadata: TMetadataMap<AtscriptMetadata>): void;
   getDesiredTableOptions(): TExistingTableOption[];
@@ -165,15 +178,89 @@ declare class MysqlAdapter extends BaseDbAdapter {
    *
    * MySQL uses numeric error codes:
    * - 1062 = ER_DUP_ENTRY (unique constraint violation)
+   * - 1586 = ER_DUP_ENTRY_WITH_KEY_NAME (same, for a multi-row INSERT)
    * - 1451 = ER_ROW_IS_REFERENCED_2 (FK violation on delete)
    * - 1452 = ER_NO_REFERENCED_ROW_2 (FK violation on insert/update)
    */
   private _wrapConstraintError;
+  /** Rethrows `error` as a structured `DbError` when it is a unique / FK violation, else as is. */
+  private _mapConstraintError;
   private _mapFkError;
   insertOne(data: Record<string, unknown>): Promise<TDbInsertResult>;
   insertMany(data: Array<Record<string, unknown>>): Promise<TDbInsertManyResult>;
+  /** Physical column of the single-column AUTO_INCREMENT primary key, if the table has one. */
+  private _autoIncrementPk;
+  /**
+   * Splits `rows` into runs that each map to ONE statement with a derivable
+   * id sequence. MySQL reports only the first GENERATED id of a statement, and
+   * an explicit auto-increment value above the counter bumps the counter, so a
+   * statement mixing explicit and generated PKs cannot be mapped by
+   * `insertId + i * step`: the chunk is cut into CONSECUTIVE runs of one kind,
+   * executed in input order (so "an earlier row wins" a unique collision, even
+   * under a case-insensitive collation). A table without an AUTO_INCREMENT PK,
+   * or a chunk of one kind, stays one group.
+   */
+  private _idGroups;
+  /** The session `sql_mode` text on the current connection (`undefined` when the server returns no row). */
+  private _sessionSqlMode;
+  /** The {@link TZeroIsExplicit} of one `insertMany` / `insertManyIgnore` call. */
+  private _zeroIsExplicit;
+  /**
+   * Warns ONCE per driver when the session `sql_mode` is not strict: writes
+   * (insert-ignore included) assume `STRICT_TRANS_TABLES` / `STRICT_ALL_TABLES`
+   * (the MySQL 8 default); a non-strict mode coerces a NOT NULL violation to the
+   * column default instead of failing. Only probes when the adapter has a logger.
+   */
+  private _warnNonStrictMode;
+  /** The {@link TIncrementStep} of one `insertMany` / `insertManyIgnore` call. */
+  private _incrementStep;
+  /**
+   * Ids of the rows of ONE successful multi-row INSERT of a homogeneous
+   * {@link _idGroups} group: generated rows get ids from `insertId` stepping by
+   * the session's `@@auto_increment_increment` (consecutive within one
+   * statement under `innodb_autoinc_lock_mode` 0 / 1, and — for a known row
+   * count — mode 2, the 8.0 default), explicit rows keep their own value.
+   */
+  private _groupInsertedIds;
+  supportsInsertIgnore(): boolean;
+  /**
+   * Per chunk: ONE optimistic multi-row INSERT (an all-new batch costs a single
+   * statement). Only when it hits a duplicate key (errno 1062 / 1586) does ONE
+   * SELECT of the chunk's primary / unique key tuples find the stored rows
+   * (skipped as conflicts) and the survivors go in as one more multi-row
+   * INSERT — a dense-duplicate chunk is three statements, never O(rows). Only
+   * if that INSERT still collides (a concurrent writer raced in, or a
+   * collation-equal value the exact-match pre-check missed) are the survivors
+   * bisected: each half is retried, recursively, and a single row that still
+   * collides is skipped. A failed statement is rolled back by InnoDB alone, so
+   * the transaction stays usable. A chunk mixing explicit and generated
+   * auto-increment ids is processed as one such sequence per consecutive run of a kind. Deliberately
+   * NOT `INSERT IGNORE` (it would downgrade NOT NULL / FK / truncation errors
+   * to warnings) and not `ON DUPLICATE KEY UPDATE` (a no-op update is
+   * indistinguishable from an insert in the affected-rows count).
+   */
+  insertManyIgnore(data: Array<Record<string, unknown>>): Promise<TDbInsertIgnoreSlot[]>;
+  /**
+   * Indices of `rows` whose primary / unique-index key tuple is already stored
+   * (a row with a null / missing key component never collides). One SELECT
+   * covers every key set; it is split only to stay under the parameter limit.
+   * Skipped entirely when no row carries a key value (generated PK, no unique
+   * index values).
+   */
+  private _findStoredKeyConflicts;
+  /** Optimistic INSERT of a group, then pre-check + survivor INSERT (+ bisect on a race). */
+  private _insertIgnoringGroup;
+  /** Retries the halves of a group whose one INSERT is known to collide; a lone colliding row is skipped. */
+  private _bisectGroup;
+  /** ONE INSERT of a group's rows; `undefined` on a duplicate key (errno 1062 / 1586). */
+  private _tryInsertGroup;
   findOne(query: DbQuery): Promise<Record<string, unknown> | null>;
   findMany(query: DbQuery): Promise<Array<Record<string, unknown>>>;
+  /**
+   * `$skip` / `$limit` per partition in one statement: a `ROW_NUMBER()`
+   * window over `partitionBy` (the generic `$with` loader's per-parent page).
+   */
+  findManyPerPartition(query: DbQuery, partitionBy: readonly string[]): Promise<Array<Record<string, unknown>>>;
   count(query: DbQuery): Promise<number>;
   aggregate(query: DbQuery): Promise<Array<Record<string, unknown>>>;
   /**
@@ -186,6 +273,26 @@ declare class MysqlAdapter extends BaseDbAdapter {
    * expression skips `CONVERT_TZ`. Successes are cached per driver.
    */
   private _ensureBucketZone;
+  /**
+   * The WHERE of an UPDATE / DELETE on this table. MySQL rejects a statement
+   * whose WHERE reads the mutated table in a subquery (error 1093,
+   * `ER_UPDATE_TABLE_USED`) — what a relational predicate (`$some` / `$none`)
+   * does when its target or junction table, at any nesting level, is this
+   * table (a self relation such as `parent`). Such a filter is re-keyed on the
+   * primary key through a materialized derived table:
+   *
+   * ```sql
+   * WHERE (<pk…>) IN (SELECT * FROM (SELECT DISTINCT <pk…> FROM t WHERE <where>) AS `_rfm`)
+   * ```
+   *
+   * `DISTINCT` keeps the optimizer from merging the derived table back into
+   * the statement. Every other filter renders as-is.
+   *
+   * @since 0.1.147
+   */
+  private _mutationWhere;
+  /** `true` when a relational predicate of `filter` (nested ones included) reads this table. */
+  private _filterReadsOwnTable;
   updateOne(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps, expectedVersion?: number): Promise<TDbUpdateResult>;
   updateMany(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps): Promise<TDbUpdateResult>;
   replaceOne(filter: FilterExpr, data: Record<string, unknown>, expectedVersion?: number): Promise<TDbUpdateResult>;
@@ -284,6 +391,18 @@ declare class MysqlAdapter extends BaseDbAdapter {
 }
 //#endregion
 //#region src/mysql2-driver.d.ts
+/** Options of {@link Mysql2Driver}. */
+interface TMysql2DriverOptions {
+  /**
+   * Add `STRICT_TRANS_TABLES` to the session `sql_mode` of every new pool
+   * connection (default `true`, since 0.1.148). The server's own modes are
+   * kept — the mode is appended, never replaced. A non-strict server (Amazon
+   * RDS defaults to `NO_ENGINE_SUBSTITUTION`) otherwise coerces a `NOT NULL`,
+   * out-of-range or too-long value instead of failing the write. Pass `false`
+   * to keep the server's `sql_mode` untouched.
+   */
+  strictMode?: boolean;
+}
 /**
  * {@link TMysqlDriver} implementation backed by `mysql2/promise`.
  *
@@ -311,6 +430,11 @@ declare class MysqlAdapter extends BaseDbAdapter {
  * const driver = new Mysql2Driver(pool)
  * ```
  *
+ * Every new pool connection gets `STRICT_TRANS_TABLES` appended to its session
+ * `sql_mode` (since 0.1.148); pass `{ strictMode: false }` as the second
+ * argument to opt out. A pre-created `Pool` is covered too: connections it
+ * opened earlier get the statement when they are first acquired through it.
+ *
  * Requires `mysql2` to be installed:
  * ```bash
  * pnpm add mysql2
@@ -319,13 +443,15 @@ declare class MysqlAdapter extends BaseDbAdapter {
 declare class Mysql2Driver implements TMysqlDriver {
   private pool;
   private poolInit;
-  constructor(poolOrConfig: string | import("mysql2/promise").Pool | import("mysql2/promise").PoolOptions);
+  constructor(poolOrConfig: string | import("mysql2/promise").Pool | import("mysql2/promise").PoolOptions, options?: TMysql2DriverOptions);
   private getPool;
   run(sql: string, params?: unknown[]): Promise<TMysqlRunResult>;
   all<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
   get<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null>;
   exec(sql: string): Promise<void>;
   getConnection(): Promise<TMysqlConnection>;
+  private _closing?;
+  /** Idempotent: every call returns the first call's promise. */
   close(): Promise<void>;
 }
 //#endregion
@@ -335,17 +461,24 @@ declare class Mysql2Driver implements TMysqlDriver {
  *
  * @returns `{ sql, params }` — the WHERE clause (without "WHERE") and bound params.
  *          Returns `{ sql: '1=1', params: [] }` for empty/null filters.
+ *
+ * Relational predicates (`$some` / `$none`) render as correlated `EXISTS`
+ * subqueries referencing the outer table by `opts.qualifier` (default: the
+ * source table) — a statement with an aliased FROM must pass its alias.
+ *
+ * @param opts - since 0.1.147
  */
-declare function buildWhere(filter: FilterExpr$1): TSqlFragment$1;
+declare function buildWhere(filter: FilterExpr$1, opts?: TFilterVisitorOptions): TSqlFragment$1;
 //#endregion
 //#region src/index.d.ts
 /**
  * Creates a {@link DbSpace} backed by a MySQL connection pool.
  *
  * @param uri - MySQL connection URI (e.g., `mysql://root@localhost:3306/mydb`)
- * @param options - Additional pool options passed to mysql2.
+ * @param options - Additional pool options passed to mysql2. `strictMode: false`
+ *   (not a pool option) opts out of the per-session `STRICT_TRANS_TABLES` ({@link Mysql2Driver}).
  * @returns A `DbSpace` that creates `MysqlAdapter` instances per table.
  */
 declare function createAdapter(uri: string, options?: Record<string, unknown>): DbSpace;
 //#endregion
-export { Mysql2Driver, MysqlAdapter, type TMysqlConnection, type TMysqlDriver, type TMysqlRunResult, type TSqlFragment, buildWhere, createAdapter };
+export { Mysql2Driver, MysqlAdapter, type TMysql2DriverOptions, type TMysqlConnection, type TMysqlDriver, type TMysqlRunResult, type TSqlFragment, buildWhere, createAdapter };