@atscript/db-mysql 0.1.151 → 0.1.153

package/dist/index.cjs

@@ -153,6 +153,9 @@ const mysqlDialect = {
 		return quoteTableName(name);
 	},
 	unlimitedLimit: "18446744073709551615",
+	derivedMergeHint(alias) {
+		return `/*+ MERGE(${qi(alias)}) */`;
+	},
 	toValue: _atscript_db_sql_tools.toSqlValue,
 	toParam(value) {
 		if (value === void 0) return null;
@@ -618,9 +621,21 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 	get _schema() {
 		return this._table?.schema ?? null;
 	}
-	constructor(driver) {
+	constructor(driver, options) {
 		super();
 		this.driver = driver;
+		this.viewJoinPruning = options?.viewJoinPruning !== false;
+	}
+	/**
+	* The FROM source of a read of this adapter's table or view: a managed
+	* view read that needs only some of its LEFT joins reads an inline,
+	* pruned definition (`viewReadSource`, since 0.1.153) — MySQL has no
+	* outer-join elimination, so every LEFT JOIN of a view is otherwise probed
+	* per row, even for a `COUNT(*)`. Off with `viewJoinPruning: false`.
+	*/
+	_readSource(query, kind, partitionBy) {
+		const name = this.resolveTableName();
+		return this.viewJoinPruning ? (0, _atscript_db_sql_tools.viewReadSource)(mysqlDialect, this._table, name, query, kind, partitionBy) : name;
 	}
 	/** Every adapter over this pool shares one transaction (since 0.1.128). */
 	_transactionOwner() {
@@ -722,6 +737,10 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 	supportsAggregateExpressions() {
 		return true;
 	}
+	/** `$nulls` / `@db.sort.nulls` NULL placement — a leading `(col IS NULL)` key where the native order differs. */
+	supportsNullsPlacement() {
+		return true;
+	}
 	/** Computed view columns and first-row joins. */
 	viewCapabilities() {
 		return _atscript_db.ALL_VIEW_CAPABILITIES;
@@ -850,7 +869,7 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 			return this._mapConstraintError(error);
 		}
 	}
-	/** Rethrows `error` as a structured `DbError` when it is a unique / FK violation, else as is. */
+	/** Rethrows `error` as a structured `DbError` when it is a unique / FK violation or a deadlock / lock wait timeout, else as is. */
 	_mapConstraintError(error) {
 		if (error && typeof error === "object" && "errno" in error) {
 			const err = error;
@@ -859,6 +878,10 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 				message: err.sqlMessage ?? err.message
 			}]);
 			if (err.errno === 1451 || err.errno === 1452) throw new _atscript_db.DbError("FK_VIOLATION", this._mapFkError(err.message));
+			if (err.errno === 1213 || err.errno === 1205) throw new _atscript_db.DbError(err.errno === 1213 ? "DEADLOCK" : "LOCK_TIMEOUT", [{
+				path: "",
+				message: err.sqlMessage ?? err.message
+			}]);
 		}
 		throw error;
 	}
@@ -1059,27 +1082,49 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 		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).
+	* Standalone (no caller transaction): 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).
+	*
+	* Inside a CALLER's transaction (`opts.inCallerTransaction`, else
+	* `isInTransaction()` on entry) the key SELECT runs FIRST and only the
+	* missing rows are inserted, in primary-key order: a failed duplicate INSERT
+	* leaves InnoDB's shared lock on the duplicate record until COMMIT, and a
+	* later UPDATE of that row in two such transactions would deadlock (S→X).
+	* The SELECT is a non-locking consistent read, so the common case takes no
+	* lock on a stored row at all. `opts.lockConflicts` then locks the stored
+	* conflicting rows exclusively — `SELECT … WHERE pk IN (found) ORDER BY pk
+	* FOR UPDATE` (by the unique key a row collided on when that was not the
+	* primary key), existing keys only, so record locks and no gap locks —
+	* before inserting the rest.
+	*
+	* Either way, only if an INSERT still collides (a concurrent writer raced in
+	* — committed after the transaction's snapshot or still uncommitted — or a
+	* collation-equal value the exact-match pre-check missed) are the rows
+	* bisected in input order: each half is retried, recursively, and a single
+	* row that still collides is skipped (holding the failed INSERT's shared
+	* lock). 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) {
+	async insertManyIgnore(data, opts) {
 		if (data.length === 0) return [];
 		await this._warnNonStrictMode();
 		const { columns, batches } = (0, _atscript_db_sql_tools.chunkInsertRows)(data);
-		const single = data.length === 1 && !this._txConnection() ? this._uniformIdGroup(data) : void 0;
-		if (single) return this._insertIgnoringGroup(this.resolveTableName(), columns, single, this._incrementStep());
+		const inTx = this._txConnection() !== void 0;
+		const mode = {
+			precheck: opts?.inCallerTransaction ?? inTx,
+			lock: opts?.lockConflicts === true
+		};
+		const single = data.length === 1 && !inTx ? this._uniformIdGroup(data) : void 0;
+		if (single) return this._insertIgnoringGroup(this.resolveTableName(), columns, single, this._incrementStep(), mode);
 		return this.withTransaction(async () => {
 			const tableName = this.resolveTableName();
 			const slots = [];
@@ -1087,7 +1132,7 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 			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) => {
+				for (const group of await this._idGroups(batch, zero)) (await this._insertIgnoringGroup(tableName, columns, group, step, mode)).forEach((slot, k) => {
 					out[group.at[k]] = slot;
 				});
 				slots.push(...out);
@@ -1097,20 +1142,21 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 	}
 	/**
 	* 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).
+	* (a row with a null / missing key component never collides), each mapped
+	* to the index (in `uniqueKeySets` order — the primary key first) of the
+	* first key set it collides on. One non-locking 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) => (0, _atscript_db.uniqueKeyTuple)(row, fields)));
 		const used = keySets.map((_, k) => rowTuples.some((t) => t[k] !== void 0));
-		if (!used.includes(true)) return /* @__PURE__ */ new Set();
+		if (!used.includes(true)) return /* @__PURE__ */ new Map();
 		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());
+		const storedTuples = keySets.map(() => /* @__PURE__ */ new Set());
 		for (let offset = 0; offset < rows.length; offset += sliceSize) {
 			const end = Math.min(rows.length, offset + sliceSize);
 			const clauses = [];
@@ -1136,30 +1182,103 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 			const found = await this._exec().all(sql, params);
 			for (const doc of found) keySets.forEach((fields, k) => {
 				const tuple = (0, _atscript_db.uniqueKeyTuple)(doc, fields);
-				if (tuple !== void 0) stored[k].add(tuple);
+				if (tuple !== void 0) storedTuples[k].add(tuple);
 			});
 		}
-		const skipped = /* @__PURE__ */ new Set();
+		const skipped = /* @__PURE__ */ new Map();
 		rowTuples.forEach((tuples, i) => {
-			if (tuples.some((t, k) => t !== void 0 && stored[k].has(t))) skipped.add(i);
+			const k = tuples.findIndex((t, k) => t !== void 0 && storedTuples[k].has(t));
+			if (k >= 0) skipped.set(i, k);
 		});
 		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];
+	/**
+	* Exclusive locks on the stored rows the `skipped` input rows collide with
+	* (found by {@link _findStoredKeyConflicts}, so every key exists): `SELECT …
+	* FOR UPDATE` by the key set each row collided on — the primary key when it
+	* did — ascending, one statement per key set. The keys are the INPUT rows'
+	* own (write-form) values, which the pre-check matched exactly; a full
+	* unique-key equality on existing records takes record locks only, never a
+	* gap lock.
+	*/
+	async _lockStoredRows(tableName, rows, skipped) {
+		if (skipped.size === 0) return;
+		const keySets = this._table.uniqueKeySets.filter((f) => f.length > 0);
+		const byKeySet = /* @__PURE__ */ new Map();
+		for (const [i, k] of skipped) {
+			let keyed = byKeySet.get(k);
+			if (!keyed) byKeySet.set(k, keyed = /* @__PURE__ */ new Map());
+			keyed.set((0, _atscript_db.uniqueKeyTuple)(rows[i], keySets[k]), rows[i]);
+		}
+		for (const [k, keyed] of byKeySet) {
+			const fields = keySets[k];
+			const keyRows = [...keyed.values()];
+			const sliceSize = Math.max(1, Math.floor(6e4 / fields.length));
+			const cols = fields.map((f) => qi(f)).join(", ");
+			const tuple = fields.length === 1 ? "?" : `(${fields.map(() => "?").join(", ")})`;
+			for (let offset = 0; offset < keyRows.length; offset += sliceSize) {
+				const slice = keyRows.slice(offset, offset + sliceSize);
+				const params = [];
+				for (const row of slice) params.push(...fields.map((f) => mysqlDialect.toValue(row[f])));
+				const target = fields.length === 1 ? cols : `(${cols})`;
+				const sql = `SELECT ${cols} FROM ${quoteTableName(tableName)} WHERE ${target} IN (${slice.map(() => tuple).join(", ")}) ORDER BY ${cols} FOR UPDATE`;
+				this._log(sql, params);
+				await this._wrapConstraintError(() => this._exec().all(sql, params));
+			}
+		}
+	}
+	/** Input positions of `rows` in ascending primary-key order (input order without a complete key). */
+	_pkOrder(rows, at) {
+		const pkCols = this._table.primaryKeys.map((k) => this._table.physicalPath(k));
+		if (pkCols.length === 0 || at.length < 2) return at;
+		if (at.some((i) => pkCols.some((c) => rows[i][c] === void 0 || rows[i][c] === null))) return at;
+		return at.toSorted((a, b) => {
+			for (const c of pkCols) {
+				const x = rows[a][c];
+				const y = rows[b][c];
+				if (x === y) continue;
+				return x < y ? -1 : 1;
+			}
+			return a - b;
+		});
+	}
+	/**
+	* One {@link _idGroups} group. Standalone: optimistic INSERT, then pre-check
+	* + survivor INSERT (+ bisect on a race). `mode.precheck`: pre-check (and
+	* `mode.lock`: lock the stored conflicts) FIRST, then insert the survivors in
+	* primary-key order.
+	*/
+	async _insertIgnoringGroup(tableName, columns, group, step, mode) {
+		if (!mode.precheck && !mode.lock) {
+			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++]);
+		if (mode.lock) await this._lockStoredRows(tableName, group.rows, skipped);
+		if (skipped.size === 0 && !mode.precheck && !mode.lock) return this._bisectGroup(tableName, columns, group, step);
+		const keep = group.rows.map((_, i) => i).filter((i) => !skipped.has(i));
+		const ordered = mode.precheck && !group.generated ? this._pkOrder(group.rows, keep) : keep;
+		const inserted = /* @__PURE__ */ new Map();
+		if (ordered.length > 0) {
+			const sorted = {
+				rows: ordered.map((i) => group.rows[i]),
+				at: [],
+				generated: group.generated
+			};
+			let slots = await this._tryInsertGroup(tableName, columns, sorted, step);
+			if (slots) slots.forEach((slot, k) => inserted.set(ordered[k], slot));
+			else {
+				const survivors = {
+					rows: keep.map((i) => group.rows[i]),
+					at: [],
+					generated: group.generated
+				};
+				slots = keep.length === 1 ? [null] : await this._bisectGroup(tableName, columns, survivors, step);
+				slots.forEach((slot, k) => inserted.set(keep[k], slot));
+			}
+		}
+		return group.rows.map((_, i) => skipped.has(i) ? null : inserted.get(i));
 	}
 	/** 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) {
@@ -1194,13 +1313,13 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 			...query.controls,
 			$limit: 1
 		};
-		const { sql, params } = buildSelect(this.resolveTableName(), where, controls);
+		const { sql, params } = buildSelect(this._readSource(query, "rows"), where, controls);
 		this._log(sql, params);
 		return this._exec().get(sql, params);
 	}
 	async findMany(query) {
 		const where = buildWhere(query.filter);
-		const { sql, params } = buildSelect(this.resolveTableName(), where, query.controls);
+		const { sql, params } = buildSelect(this._readSource(query, "rows"), where, query.controls);
 		this._log(sql, params);
 		return this._exec().all(sql, params);
 	}
@@ -1210,20 +1329,21 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 	*/
 	async findManyPerPartition(query, partitionBy) {
 		const where = buildWhere(query.filter);
-		const { sql, params } = (0, _atscript_db_sql_tools.buildPartitionedSelect)(mysqlDialect, this.resolveTableName(), where, query.controls, partitionBy);
+		const { sql, params } = (0, _atscript_db_sql_tools.buildPartitionedSelect)(mysqlDialect, this._readSource(query, "rows", partitionBy), where, query.controls, partitionBy);
 		this._log(sql, params);
 		return (0, _atscript_db_sql_tools.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}`;
+		const source = this._readSource(query, "count");
+		const sql = `SELECT ${(0, _atscript_db_sql_tools.fromSourceHint)(source)}COUNT(*) as cnt FROM ${(0, _atscript_db_sql_tools.fromSourceSql)(mysqlDialect, source)} WHERE ${where.sql}`;
 		this._log(sql, where.params);
 		return (await this._exec().get(sql, where.params))?.cnt ?? 0;
 	}
 	async aggregate(query) {
 		const search = (0, _atscript_db_agg.resolveAggregateSearch)(query.controls);
 		const where = search ? this._buildSearchWhere(search.text, query, search.indexName) : buildWhere(query.filter);
-		const tableName = this.resolveTableName();
+		const tableName = search ? this.resolveTableName() : this._readSource(query, "aggregate");
 		for (const bucket of query.controls.$select?.buckets ?? []) await this._ensureBucketZone(bucket.tz);
 		if (query.controls.$count) {
 			const { sql, params } = buildAggregateCount(tableName, where, query.controls);
@@ -2269,16 +2389,19 @@ var Mysql2Driver = class {
 *
 * @param uri - MySQL connection URI (e.g., `mysql://root@localhost:3306/mydb`)
 * @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}).
+*   (not a pool option) opts out of the per-session `STRICT_TRANS_TABLES` ({@link Mysql2Driver});
+*   `viewJoinPruning: false` (not a pool option, since 0.1.153) reads managed views by name
+*   ({@link TMysqlAdapterOptions}).
 * @returns A `DbSpace` that creates `MysqlAdapter` instances per table.
 */
 function createAdapter(uri, options) {
-	const { strictMode, ...pool } = options ?? {};
+	const { strictMode, viewJoinPruning, ...pool } = options ?? {};
 	const driver = new Mysql2Driver({
 		uri,
 		...pool
 	}, { strictMode });
-	return new _atscript_db.DbSpace(() => new MysqlAdapter(driver), { onClose: () => driver.close() });
+	const adapterOptions = { viewJoinPruning };
+	return new _atscript_db.DbSpace(() => new MysqlAdapter(driver, adapterOptions), { onClose: () => driver.close() });
 }
 //#endregion
 exports.Mysql2Driver = Mysql2Driver;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDefaultFn, TDbDeleteResult, TDbFieldMeta, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateOptions, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TExistingTableOption, TFieldOps, TPrimaryKeyChange, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TTableOptionDiff, TValueFormatterPair, TViewCapability } from "@atscript/db";
+import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDefaultFn, TDbDeleteResult, TDbFieldMeta, TDbInsertIgnoreOptions, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateOptions, 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 { TFilterVisitorOptions, TSqlFragment, TSqlFragment as TSqlFragment$1 } from "@atscript/db-sql-tools";
@@ -73,6 +73,18 @@ interface TMysqlConnection {
   /** Release this connection back to the pool. */
   release(): void;
 }
+/**
+ * `MysqlAdapter` options.
+ * @since 0.1.153
+ */
+interface TMysqlAdapterOptions {
+  /**
+   * Read a managed view through an inline definition without the LEFT joins
+   * the query does not need (default `true`) — see the views guide,
+   * "Performance". `false` always reads the stored view by name.
+   */
+  viewJoinPruning?: boolean;
+}
 //#endregion
 //#region src/mysql-adapter.d.ts
 /**
@@ -117,7 +129,15 @@ declare class MysqlAdapter extends BaseDbAdapter {
    * (the name-taking schema-sync primitives run on such an adapter).
    */
   private get _schema();
-  constructor(driver: TMysqlDriver);
+  constructor(driver: TMysqlDriver, options?: TMysqlAdapterOptions);
+  /**
+   * The FROM source of a read of this adapter's table or view: a managed
+   * view read that needs only some of its LEFT joins reads an inline,
+   * pruned definition (`viewReadSource`, since 0.1.153) — MySQL has no
+   * outer-join elimination, so every LEFT JOIN of a view is otherwise probed
+   * per row, even for a `COUNT(*)`. Off with `viewJoinPruning: false`.
+   */
+  private _readSource;
   /** Every adapter over this pool shares one transaction (since 0.1.128). */
   protected _transactionOwner(): unknown;
   /** The dedicated connection of this pool's open transaction, if any. */
@@ -162,6 +182,8 @@ declare class MysqlAdapter extends BaseDbAdapter {
   aggregateFns(): ReadonlySet<AggregateFn>;
   /** Arithmetic in an aggregate `$select` (`{ $expr }`, `{ $fn, $expr }`). */
   supportsAggregateExpressions(): boolean;
+  /** `$nulls` / `@db.sort.nulls` NULL placement — a leading `(col IS NULL)` key where the native order differs. */
+  supportsNullsPlacement(): boolean;
   /** Computed view columns and first-row joins. */
   viewCapabilities(): ReadonlySet<TViewCapability>;
   onBeforeFlatten(_type: unknown): void;
@@ -188,7 +210,7 @@ declare class MysqlAdapter extends BaseDbAdapter {
    * - 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. */
+  /** Rethrows `error` as a structured `DbError` when it is a unique / FK violation or a deadlock / lock wait timeout, else as is. */
   private _mapConstraintError;
   private _mapFkError;
   insertOne(data: Record<string, unknown>): Promise<TDbInsertResult>;
@@ -246,31 +268,66 @@ declare class MysqlAdapter extends BaseDbAdapter {
   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[]>;
+   * Standalone (no caller transaction): 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).
+   *
+   * Inside a CALLER's transaction (`opts.inCallerTransaction`, else
+   * `isInTransaction()` on entry) the key SELECT runs FIRST and only the
+   * missing rows are inserted, in primary-key order: a failed duplicate INSERT
+   * leaves InnoDB's shared lock on the duplicate record until COMMIT, and a
+   * later UPDATE of that row in two such transactions would deadlock (S→X).
+   * The SELECT is a non-locking consistent read, so the common case takes no
+   * lock on a stored row at all. `opts.lockConflicts` then locks the stored
+   * conflicting rows exclusively — `SELECT … WHERE pk IN (found) ORDER BY pk
+   * FOR UPDATE` (by the unique key a row collided on when that was not the
+   * primary key), existing keys only, so record locks and no gap locks —
+   * before inserting the rest.
+   *
+   * Either way, only if an INSERT still collides (a concurrent writer raced in
+   * — committed after the transaction's snapshot or still uncommitted — or a
+   * collation-equal value the exact-match pre-check missed) are the rows
+   * bisected in input order: each half is retried, recursively, and a single
+   * row that still collides is skipped (holding the failed INSERT's shared
+   * lock). 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>>, opts?: TDbInsertIgnoreOptions): 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).
+   * (a row with a null / missing key component never collides), each mapped
+   * to the index (in `uniqueKeySets` order — the primary key first) of the
+   * first key set it collides on. One non-locking 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). */
+  /**
+   * Exclusive locks on the stored rows the `skipped` input rows collide with
+   * (found by {@link _findStoredKeyConflicts}, so every key exists): `SELECT …
+   * FOR UPDATE` by the key set each row collided on — the primary key when it
+   * did — ascending, one statement per key set. The keys are the INPUT rows'
+   * own (write-form) values, which the pre-check matched exactly; a full
+   * unique-key equality on existing records takes record locks only, never a
+   * gap lock.
+   */
+  private _lockStoredRows;
+  /** Input positions of `rows` in ascending primary-key order (input order without a complete key). */
+  private _pkOrder;
+  /**
+   * One {@link _idGroups} group. Standalone: optimistic INSERT, then pre-check
+   * + survivor INSERT (+ bisect on a race). `mode.precheck`: pre-check (and
+   * `mode.lock`: lock the stored conflicts) FIRST, then insert the survivors in
+   * primary-key order.
+   */
   private _insertIgnoringGroup;
   /** Retries the halves of a group whose one INSERT is known to collide; a lone colliding row is skipped. */
   private _bisectGroup;
@@ -503,9 +560,11 @@ declare function buildWhere(filter: FilterExpr$1, opts?: TFilterVisitorOptions):
  *
  * @param uri - MySQL connection URI (e.g., `mysql://root@localhost:3306/mydb`)
  * @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}).
+ *   (not a pool option) opts out of the per-session `STRICT_TRANS_TABLES` ({@link Mysql2Driver});
+ *   `viewJoinPruning: false` (not a pool option, since 0.1.153) reads managed views by name
+ *   ({@link TMysqlAdapterOptions}).
  * @returns A `DbSpace` that creates `MysqlAdapter` instances per table.
  */
 declare function createAdapter(uri: string, options?: Record<string, unknown>): DbSpace;
 //#endregion
-export { Mysql2Driver, MysqlAdapter, type TMysql2DriverOptions, type TMysqlConnection, type TMysqlDriver, type TMysqlRunResult, type TSqlFragment, buildWhere, createAdapter };
+export { Mysql2Driver, MysqlAdapter, type TMysql2DriverOptions, type TMysqlAdapterOptions, type TMysqlConnection, type TMysqlDriver, type TMysqlRunResult, type TSqlFragment, buildWhere, createAdapter };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDefaultFn, TDbDeleteResult, TDbFieldMeta, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateOptions, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TExistingTableOption, TFieldOps, TPrimaryKeyChange, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TTableOptionDiff, TValueFormatterPair, TViewCapability } from "@atscript/db";
+import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDefaultFn, TDbDeleteResult, TDbFieldMeta, TDbInsertIgnoreOptions, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateOptions, 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";
@@ -73,6 +73,18 @@ interface TMysqlConnection {
   /** Release this connection back to the pool. */
   release(): void;
 }
+/**
+ * `MysqlAdapter` options.
+ * @since 0.1.153
+ */
+interface TMysqlAdapterOptions {
+  /**
+   * Read a managed view through an inline definition without the LEFT joins
+   * the query does not need (default `true`) — see the views guide,
+   * "Performance". `false` always reads the stored view by name.
+   */
+  viewJoinPruning?: boolean;
+}
 //#endregion
 //#region src/mysql-adapter.d.ts
 /**
@@ -117,7 +129,15 @@ declare class MysqlAdapter extends BaseDbAdapter {
    * (the name-taking schema-sync primitives run on such an adapter).
    */
   private get _schema();
-  constructor(driver: TMysqlDriver);
+  constructor(driver: TMysqlDriver, options?: TMysqlAdapterOptions);
+  /**
+   * The FROM source of a read of this adapter's table or view: a managed
+   * view read that needs only some of its LEFT joins reads an inline,
+   * pruned definition (`viewReadSource`, since 0.1.153) — MySQL has no
+   * outer-join elimination, so every LEFT JOIN of a view is otherwise probed
+   * per row, even for a `COUNT(*)`. Off with `viewJoinPruning: false`.
+   */
+  private _readSource;
   /** Every adapter over this pool shares one transaction (since 0.1.128). */
   protected _transactionOwner(): unknown;
   /** The dedicated connection of this pool's open transaction, if any. */
@@ -162,6 +182,8 @@ declare class MysqlAdapter extends BaseDbAdapter {
   aggregateFns(): ReadonlySet<AggregateFn>;
   /** Arithmetic in an aggregate `$select` (`{ $expr }`, `{ $fn, $expr }`). */
   supportsAggregateExpressions(): boolean;
+  /** `$nulls` / `@db.sort.nulls` NULL placement — a leading `(col IS NULL)` key where the native order differs. */
+  supportsNullsPlacement(): boolean;
   /** Computed view columns and first-row joins. */
   viewCapabilities(): ReadonlySet<TViewCapability>;
   onBeforeFlatten(_type: unknown): void;
@@ -188,7 +210,7 @@ declare class MysqlAdapter extends BaseDbAdapter {
    * - 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. */
+  /** Rethrows `error` as a structured `DbError` when it is a unique / FK violation or a deadlock / lock wait timeout, else as is. */
   private _mapConstraintError;
   private _mapFkError;
   insertOne(data: Record<string, unknown>): Promise<TDbInsertResult>;
@@ -246,31 +268,66 @@ declare class MysqlAdapter extends BaseDbAdapter {
   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[]>;
+   * Standalone (no caller transaction): 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).
+   *
+   * Inside a CALLER's transaction (`opts.inCallerTransaction`, else
+   * `isInTransaction()` on entry) the key SELECT runs FIRST and only the
+   * missing rows are inserted, in primary-key order: a failed duplicate INSERT
+   * leaves InnoDB's shared lock on the duplicate record until COMMIT, and a
+   * later UPDATE of that row in two such transactions would deadlock (S→X).
+   * The SELECT is a non-locking consistent read, so the common case takes no
+   * lock on a stored row at all. `opts.lockConflicts` then locks the stored
+   * conflicting rows exclusively — `SELECT … WHERE pk IN (found) ORDER BY pk
+   * FOR UPDATE` (by the unique key a row collided on when that was not the
+   * primary key), existing keys only, so record locks and no gap locks —
+   * before inserting the rest.
+   *
+   * Either way, only if an INSERT still collides (a concurrent writer raced in
+   * — committed after the transaction's snapshot or still uncommitted — or a
+   * collation-equal value the exact-match pre-check missed) are the rows
+   * bisected in input order: each half is retried, recursively, and a single
+   * row that still collides is skipped (holding the failed INSERT's shared
+   * lock). 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>>, opts?: TDbInsertIgnoreOptions): 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).
+   * (a row with a null / missing key component never collides), each mapped
+   * to the index (in `uniqueKeySets` order — the primary key first) of the
+   * first key set it collides on. One non-locking 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). */
+  /**
+   * Exclusive locks on the stored rows the `skipped` input rows collide with
+   * (found by {@link _findStoredKeyConflicts}, so every key exists): `SELECT …
+   * FOR UPDATE` by the key set each row collided on — the primary key when it
+   * did — ascending, one statement per key set. The keys are the INPUT rows'
+   * own (write-form) values, which the pre-check matched exactly; a full
+   * unique-key equality on existing records takes record locks only, never a
+   * gap lock.
+   */
+  private _lockStoredRows;
+  /** Input positions of `rows` in ascending primary-key order (input order without a complete key). */
+  private _pkOrder;
+  /**
+   * One {@link _idGroups} group. Standalone: optimistic INSERT, then pre-check
+   * + survivor INSERT (+ bisect on a race). `mode.precheck`: pre-check (and
+   * `mode.lock`: lock the stored conflicts) FIRST, then insert the survivors in
+   * primary-key order.
+   */
   private _insertIgnoringGroup;
   /** Retries the halves of a group whose one INSERT is known to collide; a lone colliding row is skipped. */
   private _bisectGroup;
@@ -503,9 +560,11 @@ declare function buildWhere(filter: FilterExpr$1, opts?: TFilterVisitorOptions):
  *
  * @param uri - MySQL connection URI (e.g., `mysql://root@localhost:3306/mydb`)
  * @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}).
+ *   (not a pool option) opts out of the per-session `STRICT_TRANS_TABLES` ({@link Mysql2Driver});
+ *   `viewJoinPruning: false` (not a pool option, since 0.1.153) reads managed views by name
+ *   ({@link TMysqlAdapterOptions}).
  * @returns A `DbSpace` that creates `MysqlAdapter` instances per table.
  */
 declare function createAdapter(uri: string, options?: Record<string, unknown>): DbSpace;
 //#endregion
-export { Mysql2Driver, MysqlAdapter, type TMysql2DriverOptions, type TMysqlConnection, type TMysqlDriver, type TMysqlRunResult, type TSqlFragment, buildWhere, createAdapter };
+export { Mysql2Driver, MysqlAdapter, type TMysql2DriverOptions, type TMysqlAdapterOptions, type TMysqlConnection, type TMysqlDriver, type TMysqlRunResult, type TSqlFragment, buildWhere, createAdapter };

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_VIEW_CAPABILITIES, BaseDbAdapter, DbError, DbSpace, NoopLogger, bucketTimeZoneUnavailable, containsRelationFilter, defaultFulltextIndex, describeFulltext, fkColumns, forEachResolvedRelation, isConflict, searchTermInteger, splitFulltextFields, uniqueKeyTuple, vectorIndexNotFoundMessage } from "@atscript/db";
 import { resolveAggregateSearch } from "@atscript/db/agg";
-import { EMPTY_OR, 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, orFragment, parseRegexString, renameGeoDistance, replaceColumnsFor, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, vectorDistanceSource } from "@atscript/db-sql-tools";
+import { EMPTY_OR, 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, fromSourceHint, fromSourceSql, geoWindowFromControls, jsonDollarPath, mapQueryErrors, normalizeGeoPointValue, numericOutOfRangeError, orFragment, parseRegexString, renameGeoDistance, replaceColumnsFor, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, vectorDistanceSource, viewReadSource } 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`). */
@@ -152,6 +152,9 @@ const mysqlDialect = {
 		return quoteTableName(name);
 	},
 	unlimitedLimit: "18446744073709551615",
+	derivedMergeHint(alias) {
+		return `/*+ MERGE(${qi(alias)}) */`;
+	},
 	toValue: toSqlValue,
 	toParam(value) {
 		if (value === void 0) return null;
@@ -617,9 +620,21 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 	get _schema() {
 		return this._table?.schema ?? null;
 	}
-	constructor(driver) {
+	constructor(driver, options) {
 		super();
 		this.driver = driver;
+		this.viewJoinPruning = options?.viewJoinPruning !== false;
+	}
+	/**
+	* The FROM source of a read of this adapter's table or view: a managed
+	* view read that needs only some of its LEFT joins reads an inline,
+	* pruned definition (`viewReadSource`, since 0.1.153) — MySQL has no
+	* outer-join elimination, so every LEFT JOIN of a view is otherwise probed
+	* per row, even for a `COUNT(*)`. Off with `viewJoinPruning: false`.
+	*/
+	_readSource(query, kind, partitionBy) {
+		const name = this.resolveTableName();
+		return this.viewJoinPruning ? viewReadSource(mysqlDialect, this._table, name, query, kind, partitionBy) : name;
 	}
 	/** Every adapter over this pool shares one transaction (since 0.1.128). */
 	_transactionOwner() {
@@ -721,6 +736,10 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 	supportsAggregateExpressions() {
 		return true;
 	}
+	/** `$nulls` / `@db.sort.nulls` NULL placement — a leading `(col IS NULL)` key where the native order differs. */
+	supportsNullsPlacement() {
+		return true;
+	}
 	/** Computed view columns and first-row joins. */
 	viewCapabilities() {
 		return ALL_VIEW_CAPABILITIES;
@@ -849,7 +868,7 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 			return this._mapConstraintError(error);
 		}
 	}
-	/** Rethrows `error` as a structured `DbError` when it is a unique / FK violation, else as is. */
+	/** Rethrows `error` as a structured `DbError` when it is a unique / FK violation or a deadlock / lock wait timeout, else as is. */
 	_mapConstraintError(error) {
 		if (error && typeof error === "object" && "errno" in error) {
 			const err = error;
@@ -858,6 +877,10 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 				message: err.sqlMessage ?? err.message
 			}]);
 			if (err.errno === 1451 || err.errno === 1452) throw new DbError("FK_VIOLATION", this._mapFkError(err.message));
+			if (err.errno === 1213 || err.errno === 1205) throw new DbError(err.errno === 1213 ? "DEADLOCK" : "LOCK_TIMEOUT", [{
+				path: "",
+				message: err.sqlMessage ?? err.message
+			}]);
 		}
 		throw error;
 	}
@@ -1058,27 +1081,49 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 		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).
+	* Standalone (no caller transaction): 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).
+	*
+	* Inside a CALLER's transaction (`opts.inCallerTransaction`, else
+	* `isInTransaction()` on entry) the key SELECT runs FIRST and only the
+	* missing rows are inserted, in primary-key order: a failed duplicate INSERT
+	* leaves InnoDB's shared lock on the duplicate record until COMMIT, and a
+	* later UPDATE of that row in two such transactions would deadlock (S→X).
+	* The SELECT is a non-locking consistent read, so the common case takes no
+	* lock on a stored row at all. `opts.lockConflicts` then locks the stored
+	* conflicting rows exclusively — `SELECT … WHERE pk IN (found) ORDER BY pk
+	* FOR UPDATE` (by the unique key a row collided on when that was not the
+	* primary key), existing keys only, so record locks and no gap locks —
+	* before inserting the rest.
+	*
+	* Either way, only if an INSERT still collides (a concurrent writer raced in
+	* — committed after the transaction's snapshot or still uncommitted — or a
+	* collation-equal value the exact-match pre-check missed) are the rows
+	* bisected in input order: each half is retried, recursively, and a single
+	* row that still collides is skipped (holding the failed INSERT's shared
+	* lock). 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) {
+	async insertManyIgnore(data, opts) {
 		if (data.length === 0) return [];
 		await this._warnNonStrictMode();
 		const { columns, batches } = chunkInsertRows(data);
-		const single = data.length === 1 && !this._txConnection() ? this._uniformIdGroup(data) : void 0;
-		if (single) return this._insertIgnoringGroup(this.resolveTableName(), columns, single, this._incrementStep());
+		const inTx = this._txConnection() !== void 0;
+		const mode = {
+			precheck: opts?.inCallerTransaction ?? inTx,
+			lock: opts?.lockConflicts === true
+		};
+		const single = data.length === 1 && !inTx ? this._uniformIdGroup(data) : void 0;
+		if (single) return this._insertIgnoringGroup(this.resolveTableName(), columns, single, this._incrementStep(), mode);
 		return this.withTransaction(async () => {
 			const tableName = this.resolveTableName();
 			const slots = [];
@@ -1086,7 +1131,7 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 			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) => {
+				for (const group of await this._idGroups(batch, zero)) (await this._insertIgnoringGroup(tableName, columns, group, step, mode)).forEach((slot, k) => {
 					out[group.at[k]] = slot;
 				});
 				slots.push(...out);
@@ -1096,20 +1141,21 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 	}
 	/**
 	* 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).
+	* (a row with a null / missing key component never collides), each mapped
+	* to the index (in `uniqueKeySets` order — the primary key first) of the
+	* first key set it collides on. One non-locking 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();
+		if (!used.includes(true)) return /* @__PURE__ */ new Map();
 		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());
+		const storedTuples = keySets.map(() => /* @__PURE__ */ new Set());
 		for (let offset = 0; offset < rows.length; offset += sliceSize) {
 			const end = Math.min(rows.length, offset + sliceSize);
 			const clauses = [];
@@ -1135,30 +1181,103 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 			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);
+				if (tuple !== void 0) storedTuples[k].add(tuple);
 			});
 		}
-		const skipped = /* @__PURE__ */ new Set();
+		const skipped = /* @__PURE__ */ new Map();
 		rowTuples.forEach((tuples, i) => {
-			if (tuples.some((t, k) => t !== void 0 && stored[k].has(t))) skipped.add(i);
+			const k = tuples.findIndex((t, k) => t !== void 0 && storedTuples[k].has(t));
+			if (k >= 0) skipped.set(i, k);
 		});
 		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];
+	/**
+	* Exclusive locks on the stored rows the `skipped` input rows collide with
+	* (found by {@link _findStoredKeyConflicts}, so every key exists): `SELECT …
+	* FOR UPDATE` by the key set each row collided on — the primary key when it
+	* did — ascending, one statement per key set. The keys are the INPUT rows'
+	* own (write-form) values, which the pre-check matched exactly; a full
+	* unique-key equality on existing records takes record locks only, never a
+	* gap lock.
+	*/
+	async _lockStoredRows(tableName, rows, skipped) {
+		if (skipped.size === 0) return;
+		const keySets = this._table.uniqueKeySets.filter((f) => f.length > 0);
+		const byKeySet = /* @__PURE__ */ new Map();
+		for (const [i, k] of skipped) {
+			let keyed = byKeySet.get(k);
+			if (!keyed) byKeySet.set(k, keyed = /* @__PURE__ */ new Map());
+			keyed.set(uniqueKeyTuple(rows[i], keySets[k]), rows[i]);
+		}
+		for (const [k, keyed] of byKeySet) {
+			const fields = keySets[k];
+			const keyRows = [...keyed.values()];
+			const sliceSize = Math.max(1, Math.floor(6e4 / fields.length));
+			const cols = fields.map((f) => qi(f)).join(", ");
+			const tuple = fields.length === 1 ? "?" : `(${fields.map(() => "?").join(", ")})`;
+			for (let offset = 0; offset < keyRows.length; offset += sliceSize) {
+				const slice = keyRows.slice(offset, offset + sliceSize);
+				const params = [];
+				for (const row of slice) params.push(...fields.map((f) => mysqlDialect.toValue(row[f])));
+				const target = fields.length === 1 ? cols : `(${cols})`;
+				const sql = `SELECT ${cols} FROM ${quoteTableName(tableName)} WHERE ${target} IN (${slice.map(() => tuple).join(", ")}) ORDER BY ${cols} FOR UPDATE`;
+				this._log(sql, params);
+				await this._wrapConstraintError(() => this._exec().all(sql, params));
+			}
+		}
+	}
+	/** Input positions of `rows` in ascending primary-key order (input order without a complete key). */
+	_pkOrder(rows, at) {
+		const pkCols = this._table.primaryKeys.map((k) => this._table.physicalPath(k));
+		if (pkCols.length === 0 || at.length < 2) return at;
+		if (at.some((i) => pkCols.some((c) => rows[i][c] === void 0 || rows[i][c] === null))) return at;
+		return at.toSorted((a, b) => {
+			for (const c of pkCols) {
+				const x = rows[a][c];
+				const y = rows[b][c];
+				if (x === y) continue;
+				return x < y ? -1 : 1;
+			}
+			return a - b;
+		});
+	}
+	/**
+	* One {@link _idGroups} group. Standalone: optimistic INSERT, then pre-check
+	* + survivor INSERT (+ bisect on a race). `mode.precheck`: pre-check (and
+	* `mode.lock`: lock the stored conflicts) FIRST, then insert the survivors in
+	* primary-key order.
+	*/
+	async _insertIgnoringGroup(tableName, columns, group, step, mode) {
+		if (!mode.precheck && !mode.lock) {
+			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++]);
+		if (mode.lock) await this._lockStoredRows(tableName, group.rows, skipped);
+		if (skipped.size === 0 && !mode.precheck && !mode.lock) return this._bisectGroup(tableName, columns, group, step);
+		const keep = group.rows.map((_, i) => i).filter((i) => !skipped.has(i));
+		const ordered = mode.precheck && !group.generated ? this._pkOrder(group.rows, keep) : keep;
+		const inserted = /* @__PURE__ */ new Map();
+		if (ordered.length > 0) {
+			const sorted = {
+				rows: ordered.map((i) => group.rows[i]),
+				at: [],
+				generated: group.generated
+			};
+			let slots = await this._tryInsertGroup(tableName, columns, sorted, step);
+			if (slots) slots.forEach((slot, k) => inserted.set(ordered[k], slot));
+			else {
+				const survivors = {
+					rows: keep.map((i) => group.rows[i]),
+					at: [],
+					generated: group.generated
+				};
+				slots = keep.length === 1 ? [null] : await this._bisectGroup(tableName, columns, survivors, step);
+				slots.forEach((slot, k) => inserted.set(keep[k], slot));
+			}
+		}
+		return group.rows.map((_, i) => skipped.has(i) ? null : inserted.get(i));
 	}
 	/** 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) {
@@ -1193,13 +1312,13 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 			...query.controls,
 			$limit: 1
 		};
-		const { sql, params } = buildSelect$1(this.resolveTableName(), where, controls);
+		const { sql, params } = buildSelect$1(this._readSource(query, "rows"), where, controls);
 		this._log(sql, params);
 		return this._exec().get(sql, params);
 	}
 	async findMany(query) {
 		const where = buildWhere(query.filter);
-		const { sql, params } = buildSelect$1(this.resolveTableName(), where, query.controls);
+		const { sql, params } = buildSelect$1(this._readSource(query, "rows"), where, query.controls);
 		this._log(sql, params);
 		return this._exec().all(sql, params);
 	}
@@ -1209,20 +1328,21 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 	*/
 	async findManyPerPartition(query, partitionBy) {
 		const where = buildWhere(query.filter);
-		const { sql, params } = buildPartitionedSelect(mysqlDialect, this.resolveTableName(), where, query.controls, partitionBy);
+		const { sql, params } = buildPartitionedSelect(mysqlDialect, this._readSource(query, "rows", partitionBy), 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}`;
+		const source = this._readSource(query, "count");
+		const sql = `SELECT ${fromSourceHint(source)}COUNT(*) as cnt FROM ${fromSourceSql(mysqlDialect, source)} WHERE ${where.sql}`;
 		this._log(sql, where.params);
 		return (await this._exec().get(sql, where.params))?.cnt ?? 0;
 	}
 	async aggregate(query) {
 		const search = resolveAggregateSearch(query.controls);
 		const where = search ? this._buildSearchWhere(search.text, query, search.indexName) : buildWhere(query.filter);
-		const tableName = this.resolveTableName();
+		const tableName = search ? this.resolveTableName() : this._readSource(query, "aggregate");
 		for (const bucket of query.controls.$select?.buckets ?? []) await this._ensureBucketZone(bucket.tz);
 		if (query.controls.$count) {
 			const { sql, params } = buildAggregateCount$1(tableName, where, query.controls);
@@ -2268,16 +2388,19 @@ var Mysql2Driver = class {
 *
 * @param uri - MySQL connection URI (e.g., `mysql://root@localhost:3306/mydb`)
 * @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}).
+*   (not a pool option) opts out of the per-session `STRICT_TRANS_TABLES` ({@link Mysql2Driver});
+*   `viewJoinPruning: false` (not a pool option, since 0.1.153) reads managed views by name
+*   ({@link TMysqlAdapterOptions}).
 * @returns A `DbSpace` that creates `MysqlAdapter` instances per table.
 */
 function createAdapter(uri, options) {
-	const { strictMode, ...pool } = options ?? {};
+	const { strictMode, viewJoinPruning, ...pool } = options ?? {};
 	const driver = new Mysql2Driver({
 		uri,
 		...pool
 	}, { strictMode });
-	return new DbSpace(() => new MysqlAdapter(driver), { onClose: () => driver.close() });
+	const adapterOptions = { viewJoinPruning };
+	return new DbSpace(() => new MysqlAdapter(driver, adapterOptions), { onClose: () => driver.close() });
 }
 //#endregion
 export { Mysql2Driver, MysqlAdapter, buildWhere, createAdapter };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-mysql",
-  "version": "0.1.151",
+  "version": "0.1.153",
   "description": "MySQL adapter for @atscript/db with mysql2 driver support.",
   "keywords": [
     "atscript",
@@ -41,19 +41,19 @@
     "access": "public"
   },
   "devDependencies": {
-    "@atscript/core": "^0.1.102",
-    "@atscript/typescript": "^0.1.102",
-    "@uniqu/core": "^0.1.14",
+    "@atscript/core": "^0.1.103",
+    "@atscript/typescript": "^0.1.103",
+    "@uniqu/core": "^0.1.15",
     "mysql2": "^3.11.0",
-    "unplugin-atscript": "^0.1.102"
+    "unplugin-atscript": "^0.1.103"
   },
   "peerDependencies": {
-    "@atscript/core": "^0.1.102",
-    "@atscript/typescript": "^0.1.102",
-    "@uniqu/core": "^0.1.14",
+    "@atscript/core": "^0.1.103",
+    "@atscript/typescript": "^0.1.103",
+    "@uniqu/core": "^0.1.15",
     "mysql2": ">=3.0.0",
-    "@atscript/db": "^0.1.151",
-    "@atscript/db-sql-tools": "^0.1.151"
+    "@atscript/db": "^0.1.153",
+    "@atscript/db-sql-tools": "^0.1.153"
   },
   "peerDependenciesMeta": {
     "mysql2": {