@atscript/db-mysql 0.1.146 → 0.1.148

package/dist/index.mjs

@@ -1,6 +1,6 @@
-import { ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, BaseDbAdapter, DbError, DbSpace, bucketTimeZoneUnavailable, vectorIndexNotFoundMessage } from "@atscript/db";
+import { ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_VIEW_CAPABILITIES, BaseDbAdapter, DbError, DbSpace, NoopLogger, bucketTimeZoneUnavailable, containsRelationFilter, fkColumns, forEachResolvedRelation, isConflict, uniqueKeyTuple, vectorIndexNotFoundMessage } from "@atscript/db";
 import { resolveAggregateSearch } from "@atscript/db/agg";
-import { buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere as buildWhere$1, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, geoWindowFromControls, insertManyColumns, jsonDollarPath, normalizeGeoPointValue, parseRegexString, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlTimeZoneLiteral, toSqlValue, vectorDistanceSource } from "@atscript/db-sql-tools";
+import { SEARCH_SOURCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildPartitionedSelect, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere as buildWhere$1, chunkInsertRows, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, foreignKeySql, geoWindowFromControls, jsonDollarPath, mapQueryErrors, normalizeGeoPointValue, numericOutOfRangeError, parseRegexString, renameGeoDistance, replaceColumnsFor, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, vectorDistanceSource } from "@atscript/db-sql-tools";
 import { BUCKET_MAX_INSTANT, BUCKET_MIN_INSTANT } from "@uniqu/core";
 //#region src/sql-builder.ts
 /** TEXT / BLOB families (`TINYTEXT` … `LONGBLOB`). */
@@ -104,7 +104,7 @@ function buildColumnDefinition(field, ctx) {
 		def: `${qi(field.physicalName)} ${sqlType}${mysqlCollateClause(field)} GENERATED ALWAYS AS (${derivedColumnExpr(mysqlDialect, field)}) VIRTUAL`,
 		inventedDefault: false
 	};
-	const increment = ctx.purpose !== "add" && (ctx.incrementFields?.has(field.physicalName) ?? false);
+	const increment = ctx.purpose !== "add" && (ctx.incrementFields?.has(field.path) ?? false);
 	let def = `${qi(field.physicalName)} ${sqlType}`;
 	if (increment) def += " AUTO_INCREMENT";
 	if (ctx.purpose === "create") {
@@ -164,6 +164,10 @@ const mysqlDialect = {
 			params: [pattern]
 		};
 	},
+	mapQueryError(error, arithmetic) {
+		if (error?.errno !== 1690) return void 0;
+		return arithmetic ? arithOverflowError() : numericOutOfRangeError();
+	},
 	geoWithin(quotedCol, circle) {
 		const dist = mysqlGeoDistanceExpr(quotedCol, circle.center);
 		return {
@@ -174,6 +178,7 @@ const mysqlDialect = {
 	calendarBucket: mysqlCalendarBucket,
 	bucketAliasInHaving: true,
 	jsonExtract: mysqlJsonExtract,
+	castDouble: (expr) => `CAST(${expr} AS DOUBLE)`,
 	createViewPrefix: "CREATE OR REPLACE VIEW"
 };
 /** `JSON_TYPE()` names of JSON numbers (MariaDB reports only INTEGER / DOUBLE). */
@@ -209,7 +214,8 @@ function isMysqlTimestampColumn(fd) {
 const MYSQL_EPOCH = "CAST('1970-01-01 00:00:00' AS DATETIME)";
 /**
 * Calendar-bucket label: TEXT `'YYYY-MM-DD'` — the local date of the
-* bucket's first day in `b.tz` — or NULL for a NULL source or one outside
+* bucket's first day in `b.tz` — or, for `hour`, `'YYYY-MM-DDTHH:00'` — the
+* local wall-clock hour — or NULL for a NULL source or one outside
 * `[BUCKET_MIN_INSTANT, BUCKET_MAX_INSTANT)`.
 *
 * The source's UTC wall time `U` (a DATETIME) depends on storage:
@@ -221,9 +227,12 @@ const MYSQL_EPOCH = "CAST('1970-01-01 00:00:00' AS DATETIME)";
 *   return whatever the server's session zone is (`UNIX_TIMESTAMP(col)` would
 *   agree only under a UTC session zone).
 *
-* The local date is `DATE(CONVERT_TZ(U, '+00:00', '<tz>'))`, or `DATE(U)` for
-* `UTC` (no time zone tables needed). Truncation is calendar arithmetic on
-* that date. `CONVERT_TZ` returns NULL when the zone is unknown to the
+* The local wall time is `CONVERT_TZ(U, '+00:00', '<tz>')`, or `U` for `UTC`
+* (no time zone tables needed) — UTC → local is never ambiguous, so a
+* `+05:30` zone's hour starts at :30 UTC and a DST fall-back's repeated hour
+* is one label. The hour is formatted from it; the other units truncate
+* its `DATE()` with calendar arithmetic. `CONVERT_TZ`
+* returns NULL when the zone is unknown to the
 * server and its input unchanged outside its range — `MysqlAdapter` probes
 * each zone before running the query (`BUCKET_TZ_UNAVAILABLE`).
 *
@@ -240,24 +249,33 @@ function mysqlCalendarBucket(quotedCol, b) {
 		utc = `(${MYSQL_EPOCH} + INTERVAL FLOOR(${quotedCol} / 1000) SECOND)`;
 		inRange = `${quotedCol} >= ${BUCKET_MIN_INSTANT} AND ${quotedCol} < ${BUCKET_MAX_INSTANT}`;
 	}
-	const local = b.tz === "UTC" ? `DATE(${utc})` : `DATE(CONVERT_TZ(${utc}, '+00:00', ${sqlTimeZoneLiteral(b.tz)}))`;
-	let first;
+	const wall = b.tz === "UTC" ? utc : `CONVERT_TZ(${utc}, '+00:00', ${sqlTimeZoneLiteral(b.tz)})`;
+	const local = `DATE(${wall})`;
+	let value;
+	let format = "%Y-%m-%d";
 	switch (b.unit) {
+		case "hour":
+			value = wall;
+			format = "%Y-%m-%dT%H:00";
+			break;
 		case "day":
-			first = local;
+			value = local;
 			break;
 		case "week":
-			first = `DATE_SUB(${local}, INTERVAL ((WEEKDAY(${local}) + 1 - ${b.weekStartIso} + 7) % 7) DAY)`;
+			value = `DATE_SUB(${local}, INTERVAL ((WEEKDAY(${local}) + 1 - ${b.weekStartIso} + 7) % 7) DAY)`;
 			break;
 		case "month":
-			first = `DATE_SUB(${local}, INTERVAL DAYOFMONTH(${local}) - 1 DAY)`;
+			value = `DATE_SUB(${local}, INTERVAL DAYOFMONTH(${local}) - 1 DAY)`;
 			break;
 		case "quarter":
-			first = `(MAKEDATE(YEAR(${local}), 1) + INTERVAL (QUARTER(${local}) - 1) QUARTER)`;
+			value = `(MAKEDATE(YEAR(${local}), 1) + INTERVAL (QUARTER(${local}) - 1) QUARTER)`;
+			break;
+		case "year":
+			value = `MAKEDATE(YEAR(${local}), 1)`;
 			break;
-		default: first = `MAKEDATE(YEAR(${local}), 1)`;
+		default: throw new Error(`Unhandled calendar bucket unit "${String(b.unit)}"`);
 	}
-	return `CASE WHEN ${inRange} THEN DATE_FORMAT(${first}, '%Y-%m-%d') END`;
+	return `CASE WHEN ${inRange} THEN DATE_FORMAT(${value}, '${format}') END`;
 }
 /**
 * Spherical distance in meters from a POINT column to a query point.
@@ -445,12 +463,7 @@ function buildCreateTable(table, fields, foreignKeys, options) {
 	}
 	if (foreignKeys) for (const fk of foreignKeys.values()) {
 		if (options?.deferForeignKeysTo?.has(fk.targetTable)) continue;
-		const localCols = fk.fields.map((f) => qi(f)).join(", ");
-		const targetCols = fk.targetFields.map((f) => qi(f)).join(", ");
-		let constraint = `FOREIGN KEY (${localCols}) REFERENCES ${qi(fk.targetTable)} (${targetCols})`;
-		if (fk.onDelete) constraint += ` ON DELETE ${refActionToSql(fk.onDelete)}`;
-		if (fk.onUpdate) constraint += ` ON UPDATE ${refActionToSql(fk.onUpdate)}`;
-		constraints.push(constraint);
+		constraints.push(foreignKeySql(qi, fk));
 	}
 	const body = [...colDefs.map((c) => c.def), ...constraints].join(", ");
 	let sql = `CREATE TABLE IF NOT EXISTS ${quoteTableName(table)} (${body})`;
@@ -468,9 +481,15 @@ function buildCreateTable(table, fields, foreignKeys, options) {
 *
 * @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
 */
-function buildWhere(filter) {
-	return buildWhere$1(mysqlDialect, filter);
+function buildWhere(filter, opts) {
+	return buildWhere$1(mysqlDialect, filter, opts);
 }
 //#endregion
 //#region src/mysql-adapter.ts
@@ -502,6 +521,9 @@ function epochMsToUtcDatetime(ms) {
 * "unchanged" named-zone result is not evidence of a limited range.
 */
 const TZ_PROBE_SQL = "SELECT CONVERT_TZ('2040-06-01 12:00:00', '+00:00', ?) IS NULL AS missing, TIMESTAMPDIFF(MINUTE, '2040-06-01 12:00:00', CONVERT_TZ('2040-06-01 12:00:00', '+00:00', '+01:00')) AS shift";
+const isZero = (v) => v === 0 || v === "0";
+/** Drivers whose session `sql_mode` was already checked for strictness (see `_warnNonStrictMode`). */
+const nonStrictChecked = /* @__PURE__ */ new WeakSet();
 /**
 * Zones `CONVERT_TZ` is known to handle, per driver (adapters are per table
 * and share a driver). Positives only: a failed zone is probed again, so
@@ -614,6 +636,17 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 			if (!tx) conn.release();
 		}
 	}
+	/**
+	* 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) {
+		return true;
+	}
 	/** MySQL InnoDB enforces FK constraints natively. */
 	supportsNativeForeignKeys() {
 		return true;
@@ -634,10 +667,18 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 	calendarBucketUnits() {
 		return ALL_BUCKET_UNITS;
 	}
-	/** Every aggregate function, `countDistinct` included. */
+	/** Every aggregate function: `countDistinct`, `first` and `last` included. */
 	aggregateFns() {
 		return ALL_AGGREGATE_FNS;
 	}
+	/** Arithmetic in an aggregate `$select` (`{ $expr }`, `{ $fn, $expr }`). */
+	supportsAggregateExpressions() {
+		return true;
+	}
+	/** Computed view columns and first-row joins. */
+	viewCapabilities() {
+		return ALL_VIEW_CAPABILITIES;
+	}
 	onBeforeFlatten(_type) {
 		const meta = _type.metadata;
 		const engine = meta.get("db.mysql.engine");
@@ -748,6 +789,7 @@ var MysqlAdapter = 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)
 	*/
@@ -755,16 +797,20 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 		try {
 			return await fn();
 		} catch (error) {
-			if (error && typeof error === "object" && "errno" in error) {
-				const err = error;
-				if (err.errno === 1062) throw new DbError("CONFLICT", [{
-					path: (err.message?.match(/for key '(?:\w+\.)?(\w+)'/))?.[1] ?? "",
-					message: err.sqlMessage ?? err.message
-				}]);
-				if (err.errno === 1451 || err.errno === 1452) throw new DbError("FK_VIOLATION", this._mapFkError(err.message));
-			}
-			throw error;
+			return this._mapConstraintError(error);
+		}
+	}
+	/** Rethrows `error` as a structured `DbError` when it is a unique / FK violation, else as is. */
+	_mapConstraintError(error) {
+		if (error && typeof error === "object" && "errno" in error) {
+			const err = error;
+			if (err.errno === 1062 || err.errno === 1586) throw new DbError("CONFLICT", [{
+				path: (err.message?.match(/^[\s\S]*for key '(?:[^']*\.)?([^'.]+)'/))?.[1] ?? "",
+				message: err.sqlMessage ?? err.message
+			}]);
+			if (err.errno === 1451 || err.errno === 1452) throw new DbError("FK_VIOLATION", this._mapFkError(err.message));
 		}
+		throw error;
 	}
 	_mapFkError(message) {
 		const fkMatch = message.match(/FOREIGN KEY \(`(\w+)`\)/);
@@ -793,16 +839,21 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 		};
 		return this.withTransaction(async () => {
 			const tableName = this.resolveTableName();
-			const columns = insertManyColumns(data);
-			const maxRowsPerBatch = columns.length > 0 ? Math.floor(6e4 / columns.length) : data.length;
+			const { columns, batches } = chunkInsertRows(data);
 			const allIds = [];
-			for (let offset = 0; offset < data.length; offset += maxRowsPerBatch) {
-				const batch = data.slice(offset, offset + maxRowsPerBatch);
-				const { sql, params } = buildInsertMany$1(tableName, batch, columns);
-				this._log(sql, params);
-				const result = await this._wrapConstraintError(() => this._exec().run(sql, params));
-				const firstId = Number(result.insertId);
-				for (let i = 0; i < batch.length; i++) allIds.push(this._resolveInsertedId(batch[i], firstId > 0 ? firstId + i : 0));
+			const step = this._incrementStep();
+			const zero = this._zeroIsExplicit();
+			for (const batch of batches) {
+				const ids = Array.from({ length: batch.length });
+				for (const group of await this._idGroups(batch, zero)) {
+					const { sql, params } = buildInsertMany$1(tableName, group.rows, columns);
+					this._log(sql, params);
+					const result = await this._wrapConstraintError(() => this._exec().run(sql, params));
+					(await this._groupInsertedIds(group, result.insertId, step)).forEach((id, k) => {
+						ids[group.at[k]] = id;
+					});
+				}
+				allIds.push(...ids);
 			}
 			return {
 				insertedCount: allIds.length,
@@ -810,6 +861,230 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 			};
 		});
 	}
+	/** Physical column of the single-column AUTO_INCREMENT primary key, if the table has one. */
+	_autoIncrementPk() {
+		const pks = this._table.primaryKeys;
+		if (pks.length !== 1 || !this._incrementFields.has(pks[0])) return void 0;
+		return this._table.getMetadata().physicalPath(pks[0]);
+	}
+	/**
+	* 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.
+	*/
+	async _idGroups(rows, zeroIsExplicit) {
+		const col = this._autoIncrementPk();
+		if (!col) return [{
+			rows,
+			at: rows.map((_, i) => i),
+			generated: false
+		}];
+		const zeroExplicit = rows.some((r) => isZero(r[col])) && await zeroIsExplicit();
+		const groups = [];
+		rows.forEach((row, i) => {
+			const v = row[col];
+			const generated = v === void 0 || v === null || isZero(v) && !zeroExplicit;
+			let last = groups.at(-1);
+			if (!last || last.generated !== generated) {
+				last = {
+					rows: [],
+					at: [],
+					generated
+				};
+				groups.push(last);
+			}
+			last.rows.push(row);
+			last.at.push(i);
+		});
+		return groups;
+	}
+	/** The session `sql_mode` text on the current connection (`undefined` when the server returns no row). */
+	async _sessionSqlMode() {
+		const row = await this._exec().get("SELECT @@SESSION.sql_mode AS mode", []);
+		if (!row) return void 0;
+		return typeof row.mode === "string" ? row.mode : "";
+	}
+	/** The {@link TZeroIsExplicit} of one `insertMany` / `insertManyIgnore` call. */
+	_zeroIsExplicit() {
+		let mode;
+		return () => mode ??= this._sessionSqlMode().then((text) => (text ?? "").includes("NO_AUTO_VALUE_ON_ZERO"));
+	}
+	/**
+	* 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.
+	*/
+	async _warnNonStrictMode() {
+		if (this.logger === NoopLogger || nonStrictChecked.has(this.driver)) return;
+		nonStrictChecked.add(this.driver);
+		try {
+			const mode = await this._sessionSqlMode();
+			if (mode !== void 0 && !/STRICT_(TRANS|ALL)_TABLES/.test(mode)) this.logger.warn(`MySQL session sql_mode lacks STRICT_TRANS_TABLES / STRICT_ALL_TABLES (${mode}): writes assume a strict mode and a non-strict server silently coerces NOT NULL violations`);
+		} catch {
+			nonStrictChecked.delete(this.driver);
+		}
+	}
+	/** The {@link TIncrementStep} of one `insertMany` / `insertManyIgnore` call. */
+	_incrementStep() {
+		let step;
+		return () => step ??= (async () => {
+			const row = await this._exec().get("SELECT @@auto_increment_increment AS step", []);
+			const n = Number(row?.step);
+			return Number.isInteger(n) && n > 0 ? n : 1;
+		})();
+	}
+	/**
+	* 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.
+	*/
+	async _groupInsertedIds(group, insertId, step) {
+		const first = Number(insertId);
+		const stride = group.generated && group.rows.length > 1 && first > 0 ? await step() : 1;
+		return group.rows.map((row, i) => {
+			const generatedId = first > 0 ? first + i * stride : 0;
+			return group.generated ? generatedId : this._resolveInsertedId(row, generatedId);
+		});
+	}
+	supportsInsertIgnore() {
+		return true;
+	}
+	/**
+	* 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).
+	*/
+	async insertManyIgnore(data) {
+		if (data.length === 0) return [];
+		await this._warnNonStrictMode();
+		return this.withTransaction(async () => {
+			const tableName = this.resolveTableName();
+			const { columns, batches } = chunkInsertRows(data);
+			const slots = [];
+			const step = this._incrementStep();
+			const zero = this._zeroIsExplicit();
+			for (const batch of batches) {
+				const out = Array.from({ length: batch.length }, () => null);
+				for (const group of await this._idGroups(batch, zero)) (await this._insertIgnoringGroup(tableName, columns, group, step)).forEach((slot, k) => {
+					out[group.at[k]] = slot;
+				});
+				slots.push(...out);
+			}
+			return slots;
+		});
+	}
+	/**
+	* 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).
+	*/
+	async _findStoredKeyConflicts(tableName, rows) {
+		const keySets = this._table.uniqueKeySets.filter((f) => f.length > 0);
+		const rowTuples = rows.map((row) => keySets.map((fields) => uniqueKeyTuple(row, fields)));
+		const used = keySets.map((_, k) => rowTuples.some((t) => t[k] !== void 0));
+		if (!used.includes(true)) return /* @__PURE__ */ new Set();
+		const width = keySets.reduce((n, f, k) => n + (used[k] ? f.length : 0), 0);
+		const sliceSize = Math.max(1, Math.floor(6e4 / width));
+		const selectCols = [...new Set(keySets.flat())].map((c) => qi(c)).join(", ");
+		const stored = keySets.map(() => /* @__PURE__ */ new Set());
+		for (let offset = 0; offset < rows.length; offset += sliceSize) {
+			const end = Math.min(rows.length, offset + sliceSize);
+			const clauses = [];
+			const params = [];
+			keySets.forEach((fields, k) => {
+				if (!used[k]) return;
+				const group = [];
+				for (let i = offset; i < end; i++) if (rowTuples[i][k] !== void 0) group.push(rows[i]);
+				if (group.length === 0) return;
+				const values = (row) => fields.map((f) => mysqlDialect.toValue(row[f]));
+				if (fields.length === 1) {
+					clauses.push(`${qi(fields[0])} IN (${group.map(() => "?").join(", ")})`);
+					for (const row of group) params.push(...values(row));
+				} else {
+					const tuple = `(${fields.map(() => "?").join(", ")})`;
+					clauses.push(`(${fields.map((f) => qi(f)).join(", ")}) IN (${group.map(() => tuple).join(", ")})`);
+					for (const row of group) params.push(...values(row));
+				}
+			});
+			if (clauses.length === 0) continue;
+			const sql = `SELECT ${selectCols} FROM ${quoteTableName(tableName)} WHERE ${clauses.join(" OR ")}`;
+			this._log(sql, params);
+			const found = await this._exec().all(sql, params);
+			for (const doc of found) keySets.forEach((fields, k) => {
+				const tuple = uniqueKeyTuple(doc, fields);
+				if (tuple !== void 0) stored[k].add(tuple);
+			});
+		}
+		const skipped = /* @__PURE__ */ new Set();
+		rowTuples.forEach((tuples, i) => {
+			if (tuples.some((t, k) => t !== void 0 && stored[k].has(t))) skipped.add(i);
+		});
+		return skipped;
+	}
+	/** Optimistic INSERT of a group, then pre-check + survivor INSERT (+ bisect on a race). */
+	async _insertIgnoringGroup(tableName, columns, group, step) {
+		const direct = await this._tryInsertGroup(tableName, columns, group, step);
+		if (direct) return direct;
+		if (group.rows.length === 1) return [null];
+		const skipped = await this._findStoredKeyConflicts(tableName, group.rows);
+		if (skipped.size === 0) return this._bisectGroup(tableName, columns, group, step);
+		const survivors = {
+			rows: group.rows.filter((_, i) => !skipped.has(i)),
+			at: [],
+			generated: group.generated
+		};
+		const inserted = survivors.rows.length > 0 ? await this._tryInsertGroup(tableName, columns, survivors, step) ?? (survivors.rows.length === 1 ? [null] : await this._bisectGroup(tableName, columns, survivors, step)) : [];
+		let next = 0;
+		return group.rows.map((_, i) => skipped.has(i) ? null : inserted[next++]);
+	}
+	/** Retries the halves of a group whose one INSERT is known to collide; a lone colliding row is skipped. */
+	async _bisectGroup(tableName, columns, group, step) {
+		const mid = group.rows.length >> 1;
+		const out = [];
+		for (const rows of [group.rows.slice(0, mid), group.rows.slice(mid)]) {
+			const half = {
+				rows,
+				at: [],
+				generated: group.generated
+			};
+			out.push(...await this._tryInsertGroup(tableName, columns, half, step) ?? (rows.length === 1 ? [null] : await this._bisectGroup(tableName, columns, half, step)));
+		}
+		return out;
+	}
+	/** ONE INSERT of a group's rows; `undefined` on a duplicate key (errno 1062 / 1586). */
+	async _tryInsertGroup(tableName, columns, group, step) {
+		const { sql, params } = buildInsertMany$1(tableName, group.rows, columns);
+		this._log(sql, params);
+		try {
+			const result = await this._wrapConstraintError(() => this._exec().run(sql, params));
+			return (await this._groupInsertedIds(group, result.insertId, step)).map((insertedId) => ({ insertedId }));
+		} catch (error) {
+			if (!isConflict(error)) throw error;
+			if (group.generated && error.errors.some((e) => e.path === "PRIMARY")) throw error;
+			return;
+		}
+	}
 	async findOne(query) {
 		const where = buildWhere(query.filter);
 		const controls = {
@@ -826,6 +1101,16 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 		this._log(sql, params);
 		return this._exec().all(sql, params);
 	}
+	/**
+	* `$skip` / `$limit` per partition in one statement: a `ROW_NUMBER()`
+	* window over `partitionBy` (the generic `$with` loader's per-parent page).
+	*/
+	async findManyPerPartition(query, partitionBy) {
+		const where = buildWhere(query.filter);
+		const { sql, params } = buildPartitionedSelect(mysqlDialect, this.resolveTableName(), where, query.controls, partitionBy);
+		this._log(sql, params);
+		return stripPartitionRowNumber(await this._exec().all(sql, params));
+	}
 	async count(query) {
 		const where = buildWhere(query.filter);
 		const sql = `SELECT COUNT(*) as cnt FROM ${quoteTableName(this.resolveTableName())} WHERE ${where.sql}`;
@@ -840,11 +1125,11 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 		if (query.controls.$count) {
 			const { sql, params } = buildAggregateCount$1(tableName, where, query.controls);
 			this._log(sql, params);
-			return [{ count: (await this._exec().get(sql, params))?.count ?? 0 }];
+			return [{ count: (await mapQueryErrors(mysqlDialect, () => this._exec().get(sql, params), query.controls))?.count ?? 0 }];
 		}
 		const { sql, params } = buildAggregateSelect$1(tableName, where, query.controls);
 		this._log(sql, params);
-		return this._exec().all(sql, params);
+		return mapQueryErrors(mysqlDialect, () => this._exec().all(sql, params), query.controls);
 	}
 	/**
 	* Verifies that `CONVERT_TZ` can convert to a calendar bucket's zone before
@@ -870,8 +1155,50 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 		}
 		zones.add(tz);
 	}
-	async updateOne(filter, data, ops, expectedVersion) {
+	/**
+	* 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
+	*/
+	_mutationWhere(filter) {
 		const where = buildWhere(filter);
+		if (!this._filterReadsOwnTable(filter)) return where;
+		const tableName = this.resolveTableName();
+		const keys = this._table.primaryKeys.map((key) => this._table.physicalPath(key));
+		if (keys.length === 0) throw new DbError("REL_FILTER_NOT_SUPPORTED", [{
+			path: "",
+			message: "MySQL cannot update or delete by a relational predicate that reads the table itself when the table has no primary key"
+		}]);
+		const cols = keys.map((key) => qi(key)).join(", ");
+		return {
+			sql: `${keys.length === 1 ? cols : `(${cols})`} IN (SELECT * FROM (SELECT DISTINCT ${cols} FROM ${quoteTableName(tableName)} WHERE ${where.sql}) AS ${qi("_rfm")})`,
+			params: where.params
+		};
+	}
+	/** `true` when a relational predicate of `filter` (nested ones included) reads this table. */
+	_filterReadsOwnTable(filter) {
+		if (!containsRelationFilter(filter)) return false;
+		const own = this.resolveTableName();
+		let hit = false;
+		forEachResolvedRelation(filter, (node) => {
+			if (node.target.table === own || node.junction?.table === own) hit = true;
+		});
+		return hit;
+	}
+	async updateOne(filter, data, ops, expectedVersion) {
+		const where = this._mutationWhere(filter);
 		const versionColumn = this._table.versionColumnPhysical;
 		const { sql, params } = buildUpdate$1(this.resolveTableName(), data, where, 1, ops, versionColumn, expectedVersion);
 		this._log(sql, params);
@@ -882,7 +1209,7 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 		};
 	}
 	async updateMany(filter, data, ops) {
-		const where = buildWhere(filter);
+		const where = this._mutationWhere(filter);
 		const versionColumn = this._table.versionColumnPhysical;
 		const { sql, params } = buildUpdate$1(this.resolveTableName(), data, where, void 0, ops, versionColumn);
 		this._log(sql, params);
@@ -893,7 +1220,7 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 		};
 	}
 	async replaceOne(filter, data, expectedVersion) {
-		const where = buildWhere(filter);
+		const where = this._mutationWhere(filter);
 		const versionColumn = this._table.versionColumnPhysical;
 		const full = fillReplacePayload(data, replaceColumnsFor(this._table.fieldDescriptors, this.nativeDefaultFns()), versionColumn);
 		const { sql, params } = buildUpdate$1(this.resolveTableName(), full, where, 1, void 0, versionColumn, expectedVersion);
@@ -905,7 +1232,7 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 		};
 	}
 	async replaceMany(filter, data) {
-		const where = buildWhere(filter);
+		const where = this._mutationWhere(filter);
 		const versionColumn = this._table.versionColumnPhysical;
 		const { sql, params } = buildUpdate$1(this.resolveTableName(), data, where, void 0, void 0, versionColumn);
 		this._log(sql, params);
@@ -916,18 +1243,19 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 		};
 	}
 	async deleteOne(filter) {
-		const where = buildWhere(filter);
+		const where = this._mutationWhere(filter);
 		const { sql, params } = buildDelete$1(this.resolveTableName(), where, 1);
 		this._log(sql, params);
 		return { deletedCount: (await this._wrapConstraintError(() => this._exec().run(sql, params))).affectedRows };
 	}
 	async deleteMany(filter) {
-		const where = buildWhere(filter);
+		const where = this._mutationWhere(filter);
 		const { sql, params } = buildDelete$1(this.resolveTableName(), where);
 		this._log(sql, params);
 		return { deletedCount: (await this._wrapConstraintError(() => this._exec().run(sql, params))).affectedRows };
 	}
 	async prepareTypeMapper() {
+		await this._warnNonStrictMode();
 		if (this._supportsVector === void 0 && this._vectorFields.size > 0) await this._detectVectorSupport();
 	}
 	async ensureTable(opts) {
@@ -1294,7 +1622,7 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 	async syncForeignKeys() {
 		const existingByName = await this._getExistingFkConstraints();
 		const desiredFkKeys = /* @__PURE__ */ new Set();
-		for (const fk of this._table.foreignKeys.values()) desiredFkKeys.add([...fk.fields].toSorted().join(","));
+		for (const fk of this._table.foreignKeys.values()) desiredFkKeys.add([...fkColumns(fk).fields].toSorted().join(","));
 		for (const [constraintName, columns] of existingByName) {
 			const key = columns.toSorted().join(",");
 			if (!desiredFkKeys.has(key)) {
@@ -1305,13 +1633,9 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 		}
 		const existingKeys = new Set([...existingByName.values()].map((cols) => cols.toSorted().join(",")));
 		for (const fk of this._table.foreignKeys.values()) {
-			const key = [...fk.fields].toSorted().join(",");
+			const key = [...fkColumns(fk).fields].toSorted().join(",");
 			if (!existingKeys.has(key)) {
-				const localCols = fk.fields.map((f) => qi(f)).join(", ");
-				const targetCols = fk.targetFields.map((f) => qi(f)).join(", ");
-				let ddl = `ALTER TABLE ${quoteTableName(this.resolveTableName())} ADD FOREIGN KEY (${localCols}) REFERENCES ${qi(fk.targetTable)} (${targetCols})`;
-				if (fk.onDelete) ddl += ` ON DELETE ${refActionToSql(fk.onDelete)}`;
-				if (fk.onUpdate) ddl += ` ON UPDATE ${refActionToSql(fk.onUpdate)}`;
+				const ddl = `ALTER TABLE ${quoteTableName(this.resolveTableName())} ADD ${foreignKeySql(qi, fk)}`;
 				this._log(ddl);
 				await this._exec().exec(ddl);
 			}
@@ -1471,7 +1795,7 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 			vec = first.value[1];
 		}
 		const distanceFn = similarityToMysqlFn(vec.similarity);
-		const where = buildWhere(query.filter);
+		const where = buildWhere(query.filter, { qualifier: mysqlDialect.quoteTable(SEARCH_SOURCE_ALIAS) });
 		const controls = query.controls || {};
 		const threshold = this._resolveVectorThreshold(controls, vec.indexName);
 		return {
@@ -1549,7 +1873,7 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 		const controls = query.controls ?? {};
 		return {
 			tableName: this.resolveTableName(),
-			where: buildWhere(query.filter),
+			where: buildWhere(query.filter, { qualifier: mysqlDialect.quoteTable(SEARCH_SOURCE_ALIAS) }),
 			dist: mysqlGeoDistanceExpr(qi(column), point),
 			window: geoWindowFromControls(controls),
 			controls
@@ -1633,6 +1957,26 @@ function atscriptTypeCast(field, next) {
 	}
 	return next();
 }
+/** Appends `STRICT_TRANS_TABLES` to the session `sql_mode` unless a strict mode is already set. */
+const ENSURE_STRICT_SQL = "SET SESSION sql_mode = IF(FIND_IN_SET('STRICT_TRANS_TABLES', @@SESSION.sql_mode) OR FIND_IN_SET('STRICT_ALL_TABLES', @@SESSION.sql_mode), @@SESSION.sql_mode, CONCAT_WS(',', NULLIF(@@SESSION.sql_mode, ''), 'STRICT_TRANS_TABLES'))";
+/**
+* Runs {@link ENSURE_STRICT_SQL} once on every connection of the pool: on
+* `connection` for the ones the pool opens, and on `acquire` for a connection
+* opened before the driver was constructed (a pre-used pool). The statement is
+* queued on the connection before the pool hands it out, so it precedes every
+* query; a failure leaves the server's mode in place.
+*/
+function ensureStrict(pool) {
+	const raw = pool;
+	const seen = /* @__PURE__ */ new WeakSet();
+	const strict = (conn) => {
+		if (seen.has(conn)) return;
+		seen.add(conn);
+		conn.query(ENSURE_STRICT_SQL, () => {});
+	};
+	raw.on("connection", strict);
+	raw.on("acquire", strict);
+}
 /**
 * {@link TMysqlDriver} implementation backed by `mysql2/promise`.
 *
@@ -1660,6 +2004,11 @@ function atscriptTypeCast(field, next) {
 * 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
@@ -1668,9 +2017,12 @@ function atscriptTypeCast(field, next) {
 var Mysql2Driver = class {
 	pool;
 	poolInit;
-	constructor(poolOrConfig) {
-		if (typeof poolOrConfig === "object" && "execute" in poolOrConfig) this.pool = poolOrConfig;
-		else this.poolInit = import("mysql2/promise").then((mysql) => {
+	constructor(poolOrConfig, options = {}) {
+		const strict = options.strictMode !== false;
+		if (typeof poolOrConfig === "object" && "execute" in poolOrConfig) {
+			this.pool = poolOrConfig;
+			if (strict) ensureStrict(this.pool);
+		} else this.poolInit = import("mysql2/promise").then((mysql) => {
 			if (typeof poolOrConfig === "string") this.pool = mysql.createPool({
 				uri: poolOrConfig,
 				timezone: "+00:00",
@@ -1685,6 +2037,7 @@ var Mysql2Driver = class {
 				bigNumberStrings: false,
 				typeCast: atscriptTypeCast
 			});
+			if (strict) ensureStrict(this.pool);
 			return this.pool;
 		});
 	}
@@ -1739,8 +2092,10 @@ var Mysql2Driver = class {
 			}
 		};
 	}
-	async close() {
-		await (await this.getPool()).end();
+	_closing;
+	/** Idempotent: every call returns the first call's promise. */
+	close() {
+		return this._closing ??= Promise.resolve(this.getPool()).then((pool) => pool.end());
 	}
 };
 //#endregion
@@ -1749,15 +2104,17 @@ var Mysql2Driver = class {
 * 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.
 */
 function createAdapter(uri, options) {
+	const { strictMode, ...pool } = options ?? {};
 	const driver = new Mysql2Driver({
 		uri,
-		...options
-	});
-	return new DbSpace(() => new MysqlAdapter(driver));
+		...pool
+	}, { strictMode });
+	return new DbSpace(() => new MysqlAdapter(driver), { onClose: () => driver.close() });
 }
 //#endregion
 export { Mysql2Driver, MysqlAdapter, buildWhere, createAdapter };