@atscript/db-mysql 0.1.161 → 0.1.163

package/dist/index.cjs

@@ -4,6 +4,16 @@ let _atscript_db_agg = require("@atscript/db/agg");
 let _atscript_db_sql_tools = require("@atscript/db-sql-tools");
 let _uniqu_core = require("@uniqu/core");
 //#region src/sql-builder.ts
+/**
+* A MySQL string literal: quotes doubled and backslashes escaped — MySQL
+* reads `\` as an escape in a string literal (unless the server runs with
+* `NO_BACKSLASH_ESCAPES`), so the shared `sqlStringLiteral` would drop or
+* reinterpret them (`'a\b'` stores a backspace, `'x\'` is unterminated).
+* @since 0.1.162
+*/
+function mysqlStringLiteral(value) {
+	return `'${value.replace(/\\/g, "\\\\").replace(/'/g, "''")}'`;
+}
 /** TEXT / BLOB families (`TINYTEXT` … `LONGBLOB`). */
 const TEXT_BLOB_RE = /^(TINY|MEDIUM|LONG)?(TEXT|BLOB)\b/i;
 /** Spatial types (`POINT SRID 4326`, `GEOMETRY`, `MULTI*`, …). */
@@ -13,11 +23,19 @@ function needsExpressionDefault(sqlType) {
 	return TEXT_BLOB_RE.test(sqlType) || /^JSON\b/i.test(sqlType) || GEOMETRY_RE.test(sqlType);
 }
 /**
+* `defaultValueToSqlLiteral` for MySQL: a string literal also escapes
+* backslashes, which MySQL reads as escapes (unless `NO_BACKSLASH_ESCAPES`) —
+* `'a\\b'` would store `a\b` minus one backslash otherwise.
+*/
+function mysqlValueLiteral(designType, value) {
+	return (0, _atscript_db_sql_tools.defaultValueToSqlLiteral)(designType, value, mysqlStringLiteral);
+}
+/**
 * Renders a model value default for a column of `sqlType`: the SQL literal,
 * wrapped in the expression form for the types that require it.
 */
 function mysqlDefaultLiteral(sqlType, designType, value) {
-	const literal = (0, _atscript_db_sql_tools.defaultValueToSqlLiteral)(designType, value);
+	const literal = mysqlValueLiteral(designType, value);
 	return needsExpressionDefault(sqlType) ? `(${literal})` : literal;
 }
 /**
@@ -153,6 +171,7 @@ const mysqlDialect = {
 		return quoteTableName(name);
 	},
 	unlimitedLimit: "18446744073709551615",
+	stringLiteral: mysqlStringLiteral,
 	derivedMergeHint(alias) {
 		return `/*+ MERGE(${qi(alias)}) */`;
 	},
@@ -184,11 +203,11 @@ const mysqlDialect = {
 	bucketAliasInHaving: true,
 	jsonExtract: mysqlJsonExtract,
 	jsonExtractText: (quotedCol, path) => {
-		const e = `JSON_EXTRACT(${quotedCol}, ${(0, _atscript_db_sql_tools.jsonDollarPath)(path)})`;
+		const e = `JSON_EXTRACT(${quotedCol}, ${(0, _atscript_db_sql_tools.jsonDollarPath)(path, mysqlStringLiteral)})`;
 		return `CASE WHEN JSON_TYPE(${e}) = 'NULL' THEN NULL ELSE JSON_UNQUOTE(${e}) END`;
 	},
 	jsonExtractValue: (quotedCol, path) => {
-		const e = `JSON_EXTRACT(${quotedCol}, ${(0, _atscript_db_sql_tools.jsonDollarPath)(path)})`;
+		const e = `JSON_EXTRACT(${quotedCol}, ${(0, _atscript_db_sql_tools.jsonDollarPath)(path, mysqlStringLiteral)})`;
 		return `CASE WHEN JSON_TYPE(${e}) = 'NULL' THEN NULL ELSE ${e} END`;
 	},
 	jsonFromText: (quotedCol) => `IF(JSON_VALID(${quotedCol}), ${quotedCol}, JSON_QUOTE(${quotedCol}))`,
@@ -206,7 +225,7 @@ const MYSQL_JSON_NUMBER_TYPES = "'INTEGER', 'UNSIGNED INTEGER', 'DOUBLE', 'DECIM
 * `CAST(… AS JSON)` (not in MariaDB).
 */
 function mysqlJsonExtract(quotedCol, path, type) {
-	const e = `JSON_EXTRACT(${quotedCol}, ${(0, _atscript_db_sql_tools.jsonDollarPath)(path)})`;
+	const e = `JSON_EXTRACT(${quotedCol}, ${(0, _atscript_db_sql_tools.jsonDollarPath)(path, mysqlStringLiteral)})`;
 	const t = `JSON_TYPE(${e})`;
 	switch (type) {
 		case "string": return `CASE ${t} WHEN 'STRING' THEN JSON_UNQUOTE(${e}) END`;
@@ -372,21 +391,28 @@ function buildInsertMany(table, rows, columns) {
 /**
 * Builds a SELECT statement with optional sort, limit, offset, projection.
 */
-function buildSelect(table, where, controls) {
-	return (0, _atscript_db_sql_tools.buildSelect)(mysqlDialect, table, where, controls);
+function buildSelect(table, where, controls, lock) {
+	return (0, _atscript_db_sql_tools.buildSelect)(mysqlDialect, table, where, controls, lock);
 }
 /**
-* Builds an UPDATE ... SET ... WHERE statement with optional LIMIT.
+* Builds an UPDATE ... SET ... WHERE statement with optional [ORDER BY …] LIMIT.
 */
 function buildUpdate(table, data, where, limit, ops, versionColumn, expectedVersion) {
 	return (0, _atscript_db_sql_tools.buildUpdate)(mysqlDialect, table, data, where, limit, ops, versionColumn, expectedVersion);
 }
 /**
-* Builds a DELETE ... WHERE statement with optional LIMIT.
+* Builds a DELETE ... WHERE statement with optional [ORDER BY …] LIMIT.
 */
 function buildDelete(table, where, limit) {
 	return (0, _atscript_db_sql_tools.buildDelete)(mysqlDialect, table, where, limit);
 }
+/** `ORDER BY … LIMIT n` of a bounded write (since 0.1.162), `undefined` when unbounded. */
+function writeLimitClause(bound) {
+	return bound && {
+		count: (0, _atscript_db_sql_tools.writeLimitCount)(bound),
+		orderBy: (0, _atscript_db_sql_tools.orderByList)(mysqlDialect, bound.sort, bound.nulls)
+	};
+}
 /**
 * Builds a CREATE OR REPLACE VIEW statement from a view plan and column mappings.
 */
@@ -680,11 +706,24 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 	_txConnection() {
 		return this._getTransactionState();
 	}
-	async _beginTransaction() {
+	async _beginTransaction(opts) {
 		const conn = await this.driver.getConnection();
-		await conn.exec("START TRANSACTION");
-		this._log("START TRANSACTION");
-		return conn;
+		let levelPending = false;
+		try {
+			if (opts?.isolation) {
+				const sql = `SET TRANSACTION ISOLATION LEVEL ${opts.isolation.toUpperCase()}`;
+				this._log(sql);
+				await conn.exec(sql);
+				levelPending = true;
+			}
+			await conn.exec("START TRANSACTION");
+			this._log("START TRANSACTION");
+			return conn;
+		} catch (err) {
+			if (levelPending && conn.destroy) conn.destroy();
+			else conn.release();
+			throw err;
+		}
 	}
 	async _commitTransaction(state) {
 		const conn = state;
@@ -776,6 +815,18 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 	supportsNullsPlacement() {
 		return true;
 	}
+	/**
+	* Locking reads: `SELECT … FOR UPDATE` / `FOR SHARE` [`NOWAIT` /
+	* `SKIP LOCKED`] (MySQL 8). A locking read is a current read — it sees the
+	* latest committed row even under REPEATABLE READ. @since 0.1.162
+	*/
+	supportsReadLocks() {
+		return true;
+	}
+	/** Every level, set by `SET TRANSACTION ISOLATION LEVEL` before `START TRANSACTION`. @since 0.1.162 */
+	isolationLevels() {
+		return _atscript_db.ALL_ISOLATION_LEVELS;
+	}
 	/** Computed view columns and first-row joins. */
 	viewCapabilities() {
 		return _atscript_db.ALL_VIEW_CAPABILITIES;
@@ -913,7 +964,7 @@ 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", [{
+			if (err.errno === 1213 || err.errno === 1205 || err.errno === 3572) throw new _atscript_db.DbError(err.errno === 1213 ? "DEADLOCK" : "LOCK_TIMEOUT", [{
 				path: "",
 				message: err.sqlMessage ?? err.message
 			}]);
@@ -1258,7 +1309,7 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 				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));
+				await this._exec().all(sql, params).catch((error) => this._mapConstraintError(error));
 			}
 		}
 	}
@@ -1348,15 +1399,15 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 			...query.controls,
 			$limit: 1
 		};
-		const { sql, params } = buildSelect(this._readSource(query, "rows"), where, controls);
+		const { sql, params } = buildSelect(this._readSource(query, "rows"), where, controls, query.lock);
 		this._log(sql, params);
-		return this._exec().get(sql, params);
+		return this._exec().get(sql, params).catch((error) => this._mapConstraintError(error));
 	}
 	async findMany(query) {
 		const where = buildWhere(query.filter);
-		const { sql, params } = buildSelect(this._readSource(query, "rows"), where, query.controls);
+		const { sql, params } = buildSelect(this._readSource(query, "rows"), where, query.controls, query.lock);
 		this._log(sql, params);
-		return this._exec().all(sql, params);
+		return this._exec().all(sql, params).catch((error) => this._mapConstraintError(error));
 	}
 	/**
 	* `$skip` / `$limit` per partition in one statement: a `ROW_NUMBER()`
@@ -1466,10 +1517,18 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 			modifiedCount: result.changedRows
 		};
 	}
+	/** Native `UPDATE/DELETE … ORDER BY … LIMIT n` (since 0.1.162). */
+	supportsWriteLimit() {
+		return true;
+	}
+	/** The `ORDER BY … LIMIT` scan locks as it goes and skips rows gone meanwhile. */
+	writeLimitIsAtomic() {
+		return true;
+	}
 	async updateMany(filter, data, ops, opts) {
 		const where = this._mutationWhere(filter);
 		const versionColumn = this._versionColumnFor(opts);
-		const { sql, params } = buildUpdate(this.resolveTableName(), data, where, void 0, ops, versionColumn);
+		const { sql, params } = buildUpdate(this.resolveTableName(), data, where, writeLimitClause(opts?.limit), ops, versionColumn);
 		this._log(sql, params);
 		const result = await this._wrapConstraintError(() => this._exec().run(sql, params));
 		return {
@@ -1480,8 +1539,8 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 	async replaceOne(filter, data, expectedVersion) {
 		const where = this._mutationWhere(filter);
 		const versionColumn = this._table.versionColumnPhysical;
-		const full = (0, _atscript_db_sql_tools.fillReplacePayload)(data, this._replaceColumns(), versionColumn);
-		const { sql, params } = buildUpdate(this.resolveTableName(), full, where, 1, void 0, versionColumn, expectedVersion);
+		const full = (0, _atscript_db_sql_tools.fillReplacePayload)(data, this._replaceColumns(), versionColumn, this._table.onUpdateIncPhysical);
+		const { sql, params } = buildUpdate(this.resolveTableName(), full, where, 1, this._onUpdateIncOps(), versionColumn, expectedVersion);
 		this._log(sql, params);
 		const result = await this._wrapConstraintError(() => this._exec().run(sql, params));
 		return {
@@ -1502,7 +1561,7 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 	async replaceMany(filter, data) {
 		const where = this._mutationWhere(filter);
 		const versionColumn = this._table.versionColumnPhysical;
-		const { sql, params } = buildUpdate(this.resolveTableName(), data, where, void 0, void 0, versionColumn);
+		const { sql, params } = buildUpdate(this.resolveTableName(), data, where, void 0, this._onUpdateIncOps(), versionColumn);
 		this._log(sql, params);
 		const result = await this._wrapConstraintError(() => this._exec().run(sql, params));
 		return {
@@ -1516,9 +1575,9 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 		this._log(sql, params);
 		return { deletedCount: (await this._wrapConstraintError(() => this._exec().run(sql, params))).affectedRows };
 	}
-	async deleteMany(filter) {
+	async deleteMany(filter, opts) {
 		const where = this._mutationWhere(filter);
-		const { sql, params } = buildDelete(this.resolveTableName(), where);
+		const { sql, params } = buildDelete(this.resolveTableName(), where, writeLimitClause(opts?.limit));
 		this._log(sql, params);
 		return { deletedCount: (await this._wrapConstraintError(() => this._exec().run(sql, params))).affectedRows };
 	}
@@ -1660,6 +1719,13 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 		this._log(sql);
 		await this._exec().exec(sql);
 	}
+	/**
+	* INFORMATION_SCHEMA reports a 4-byte character (an emoji) of a literal
+	* default as `?` — the column stores it intact.
+	*/
+	reportedDefault(desired) {
+		return desired.replace(/[\u{10000}-\u{10FFFF}]/gu, "?");
+	}
 	async getExistingColumns() {
 		return this.getExistingColumnsForTable(this._table.tableName);
 	}
@@ -1681,7 +1747,7 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 				type: r.SRS_ID == null ? r.COLUMN_TYPE.toUpperCase() : `${r.COLUMN_TYPE.toUpperCase()} SRID ${r.SRS_ID}`,
 				notnull: r.IS_NULLABLE === "NO",
 				pk: Boolean(Number(r.IS_PK ?? 0)),
-				dflt_value: normalizeMysqlDefault(r.COLUMN_DEFAULT)
+				dflt_value: normalizeMysqlDefault(r.COLUMN_DEFAULT, r.EXTRA)
 			};
 			if (/\b(VIRTUAL|STORED) GENERATED\b/i.test(r.EXTRA ?? "")) column.generated = true;
 			return column;
@@ -1789,7 +1855,7 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 					const selectExprs = commonCols.map((c) => {
 						const field = fieldsByName.get(c);
 						if (field && !field.optional && !field.isPrimaryKey) {
-							const fallback = field.defaultValue?.kind === "value" ? (0, _atscript_db_sql_tools.defaultValueToSqlLiteral)(field.designType, field.defaultValue.value) : (0, _atscript_db_sql_tools.defaultValueForType)(field.designType);
+							const fallback = field.defaultValue?.kind === "value" ? mysqlValueLiteral(field.designType, field.defaultValue.value) : (0, _atscript_db_sql_tools.defaultValueForType)(field.designType);
 							return `COALESCE(${qi(c)}, ${fallback}) AS ${qi(c)}`;
 						}
 						return qi(c);
@@ -1880,7 +1946,7 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 		}
 		return mysqlTypeFromField(field);
 	}
-	async syncIndexes() {
+	async _syncIndexes(dryRun) {
 		const tableName = this._table.tableName;
 		const schema = this._schema;
 		const bytesPerChar = mysqlBytesPerChar(this._charset);
@@ -1894,7 +1960,13 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 			return type === void 0 ? void 0 : mysqlIndexPrefix(type, bytesPerChar);
 		};
 		const renderPart = (column, prefix) => prefix === void 0 ? column : `${column}(${prefix})`;
-		await this.syncIndexesWithDiff({
+		return this.syncIndexesWithDiff({
+			dryRun,
+			skipIndex: (index) => {
+				if (index.type !== "geo") return void 0;
+				const fieldMeta = this._table.fieldDescriptors.find((f) => f.physicalName === index.fields[0]?.name);
+				return fieldMeta?.optional ? `[mysql] geo index "${index.name}" skipped — SPATIAL indexes require a NOT NULL column; make "${fieldMeta.path}" required to index it` : void 0;
+			},
 			listExisting: async () => {
 				const rows = await this._exec().all(`SELECT INDEX_NAME, COLUMN_NAME, SUB_PART, SEQ_IN_INDEX
            FROM INFORMATION_SCHEMA.STATISTICS
@@ -1917,11 +1989,6 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 			renderDesiredColumn: (_index, f) => renderPart(f.name, desiredPrefix(f.name)),
 			createIndex: async (index) => {
 				if (index.type === "geo") {
-					const fieldMeta = this._table.fieldDescriptors.find((f) => f.physicalName === index.fields[0]?.name);
-					if (fieldMeta?.optional) {
-						this.logger.warn(`[mysql] geo index "${index.name}" skipped — SPATIAL indexes require a NOT NULL column; make "${fieldMeta.path}" required to index it`);
-						return;
-					}
 					const sql = `CREATE SPATIAL INDEX ${qi(index.key)} ON ${quoteTableName(this.resolveTableName())} (${qi(index.fields[0].name)})`;
 					this._log(sql);
 					await this._exec().exec(sql);
@@ -1950,39 +2017,33 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 		});
 	}
 	async syncForeignKeys() {
-		const existingByName = await this._getExistingFkConstraints();
-		const desiredFkKeys = /* @__PURE__ */ new Set();
-		for (const fk of this._table.foreignKeys.values()) desiredFkKeys.add([...(0, _atscript_db.fkColumns)(fk).fields].toSorted().join(","));
-		for (const [constraintName, columns] of existingByName) {
-			const key = columns.toSorted().join(",");
-			if (!desiredFkKeys.has(key)) {
-				const ddl = `ALTER TABLE ${quoteTableName(this.resolveTableName())} DROP FOREIGN KEY ${qi(constraintName)}`;
-				this._log(ddl);
-				await this._exec().exec(ddl);
-			}
-		}
-		const existingKeys = new Set([...existingByName.values()].map((cols) => cols.toSorted().join(",")));
-		for (const fk of this._table.foreignKeys.values()) {
-			const key = [...(0, _atscript_db.fkColumns)(fk).fields].toSorted().join(",");
-			if (!existingKeys.has(key)) {
+		return this._syncForeignKeys(false);
+	}
+	/** The FK changes {@link syncForeignKeys} would make — no DDL. */
+	async planForeignKeys() {
+		return this._syncForeignKeys(true);
+	}
+	_syncForeignKeys(dryRun) {
+		return this.syncForeignKeysWithDiff({
+			dryRun,
+			listExisting: () => this._getExistingFkConstraints(),
+			dropConstraint: (name) => this._dropFkConstraint(name),
+			addConstraint: async (fk) => {
 				const ddl = `ALTER TABLE ${quoteTableName(this.resolveTableName())} ADD ${(0, _atscript_db_sql_tools.foreignKeySql)(qi, fk)}`;
 				this._log(ddl);
 				await this._exec().exec(ddl);
 			}
-		}
+		});
 	}
 	async dropForeignKeys(fkFieldKeys) {
 		if (fkFieldKeys.length === 0) return;
 		const keySet = new Set(fkFieldKeys);
-		const existingByName = await this._getExistingFkConstraints();
-		for (const [constraintName, cols] of existingByName) {
-			const key = cols.toSorted().join(",");
-			if (keySet.has(key)) {
-				const ddl = `ALTER TABLE ${quoteTableName(this.resolveTableName())} DROP FOREIGN KEY ${qi(constraintName)}`;
-				this._log(ddl);
-				await this._exec().exec(ddl);
-			}
-		}
+		for (const [constraintName, cols] of await this._getExistingFkConstraints()) if (keySet.has((0, _atscript_db.fkKey)(cols))) await this._dropFkConstraint(constraintName);
+	}
+	async _dropFkConstraint(name) {
+		const ddl = `ALTER TABLE ${quoteTableName(this.resolveTableName())} DROP FOREIGN KEY ${qi(name)}`;
+		this._log(ddl);
+		await this._exec().exec(ddl);
 	}
 	/** Queries INFORMATION_SCHEMA for existing FK constraints, grouped by constraint name → column names. */
 	async _getExistingFkConstraints() {
@@ -2320,14 +2381,46 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 * `uuid()`), but the diff engine compares against serialized form (`fn:now`,
 * `fn:uuid`). Without normalization, every table with function defaults
 * produces phantom ALTER diffs on re-plan.
+*
+* An expression default (`EXTRA` has `DEFAULT_GENERATED` — the form TEXT /
+* BLOB / JSON / GEOMETRY columns require) is reported as the printed
+* expression: possibly parenthesised, a string literal with a charset
+* introducer, escaped once more as a whole (`_utf8mb4\'it\\\'s\'` for
+* `'it''s'`). It is unwrapped to the literal's value. The value is compared type-aware by
+* `sameDefaultValue` (core), so `1` / `0.00` need no rewriting here.
 */
-function normalizeMysqlDefault(value) {
+function normalizeMysqlDefault(value, extra) {
 	if (value === null) return;
-	const lower = value.toLowerCase();
+	let v = value;
+	const expression = /\bDEFAULT_GENERATED\b/i.test(extra ?? "");
+	if (expression) while (v.startsWith("(") && v.endsWith(")")) v = v.slice(1, -1).trim();
+	const lower = v.toLowerCase();
 	if (/^current_timestamp(?:\(\d?\))?$/.test(lower)) return "fn:now";
 	if (lower === "uuid()") return "fn:uuid";
-	if (value.startsWith("'") && value.endsWith("'")) return value.slice(1, -1).replace(/''/g, "'");
-	return value;
+	if (expression) {
+		v = decodeLatin1Utf8(v);
+		const printed = /^(?:_\w+)?\\'/.test(v) ? v.replace(/\\([\s\S])/g, "$1") : v;
+		const literal = /^(?:_\w+)?'([\s\S]*)'$/.exec(printed);
+		return literal ? unescapeMysqlString(literal[1]) : printed;
+	}
+	return (0, _atscript_db_sql_tools.unquoteSqlStringLiteral)(v) ?? v;
+}
+/** `value`'s code units (all ≤ U+00FF) as bytes, decoded as UTF-8 — `value` unchanged otherwise. */
+function decodeLatin1Utf8(value) {
+	if (!/[\u0080-\u00ff]/.test(value) || /[^\u0000-\u00ff]/.test(value)) return value;
+	const decoded = Buffer.from(value, "latin1").toString("utf8");
+	return decoded.includes("�") ? value : decoded;
+}
+const MYSQL_ESCAPES = {
+	n: "\n",
+	r: "\r",
+	t: "	",
+	"0": "\0",
+	Z: ""
+};
+/** The body of a printed MySQL string literal: `\x` escapes and doubled `''` resolved. */
+function unescapeMysqlString(body) {
+	return body.replace(/\\([\s\S])|''/g, (match, ch) => ch === void 0 ? "'" : MYSQL_ESCAPES[ch] ?? ch);
 }
 /** Maps generic similarity metric to MySQL 9+ distance function name. */
 function similarityToMysqlFn(similarity) {
@@ -2511,6 +2604,9 @@ var Mysql2Driver = class {
 			},
 			release() {
 				conn.release();
+			},
+			destroy() {
+				conn.destroy();
 			}
 		};
 	}

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDefaultFn, TDbDeleteResult, TDbFieldMeta, TDbInsertIgnoreOptions, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateOptions, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TExistingTableOption, TFieldOps, TJsonCopyTarget, TPrimaryKeyChange, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TTableOptionDiff, TValueFormatterPair, TViewCapability } from "@atscript/db";
+import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDefaultFn, TDbDeleteManyOptions, TDbDeleteResult, TDbFieldMeta, TDbInsertIgnoreOptions, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbIsolationLevel, TDbObjectKind, TDbUpdateOptions, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TExistingTableOption, TFieldOps, TForeignKeyChange, TIndexChange, TJsonCopyTarget, TPrimaryKeyChange, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TTableOptionDiff, TTransactionOptions, 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";
@@ -72,6 +72,13 @@ interface TMysqlConnection {
   exec(sql: string): Promise<void>;
   /** Release this connection back to the pool. */
   release(): void;
+  /**
+   * Close this connection instead of returning it to the pool (since
+   * 0.1.162) — used when its session state cannot be trusted, e.g. a
+   * one-shot `SET TRANSACTION` left pending by a failed
+   * `START TRANSACTION`. Optional: a driver without it gets `release()`.
+   */
+  destroy?(): void;
 }
 /**
  * `MysqlAdapter` options.
@@ -154,7 +161,7 @@ declare class MysqlAdapter extends BaseDbAdapter {
   protected _transactionOwner(): unknown;
   /** The dedicated connection of this pool's open transaction, if any. */
   private _txConnection;
-  protected _beginTransaction(): Promise<TMysqlConnection>;
+  protected _beginTransaction(opts?: TTransactionOptions): Promise<TMysqlConnection>;
   protected _commitTransaction(state: unknown): Promise<void>;
   protected _rollbackTransaction(state: unknown): Promise<void>;
   /**
@@ -196,6 +203,14 @@ declare class MysqlAdapter extends BaseDbAdapter {
   supportsAggregateExpressions(): boolean;
   /** `$nulls` / `@db.sort.nulls` NULL placement — a leading `(col IS NULL)` key where the native order differs. */
   supportsNullsPlacement(): boolean;
+  /**
+   * Locking reads: `SELECT … FOR UPDATE` / `FOR SHARE` [`NOWAIT` /
+   * `SKIP LOCKED`] (MySQL 8). A locking read is a current read — it sees the
+   * latest committed row even under REPEATABLE READ. @since 0.1.162
+   */
+  supportsReadLocks(): boolean;
+  /** Every level, set by `SET TRANSACTION ISOLATION LEVEL` before `START TRANSACTION`. @since 0.1.162 */
+  isolationLevels(): ReadonlySet<TDbIsolationLevel>;
   /** Computed view columns and first-row joins. */
   viewCapabilities(): ReadonlySet<TViewCapability>;
   onBeforeFlatten(_type: unknown): void;
@@ -385,13 +400,17 @@ declare class MysqlAdapter extends BaseDbAdapter {
   /** `true` when a relational predicate of `filter` (nested ones included) reads this table. */
   private _filterReadsOwnTable;
   updateOne(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps, expectedVersion?: number, opts?: TDbUpdateOptions): Promise<TDbUpdateResult>;
+  /** Native `UPDATE/DELETE … ORDER BY … LIMIT n` (since 0.1.162). */
+  supportsWriteLimit(): boolean;
+  /** The `ORDER BY … LIMIT` scan locks as it goes and skips rows gone meanwhile. */
+  writeLimitIsAtomic(): boolean;
   updateMany(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps, opts?: TDbUpdateOptions): Promise<TDbUpdateResult>;
   replaceOne(filter: FilterExpr, data: Record<string, unknown>, expectedVersion?: number): Promise<TDbUpdateResult>;
   /** The columns a full replace assigns (`replaceColumnsFor`), built once per table. */
   private _replaceColumns;
   replaceMany(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
   deleteOne(filter: FilterExpr): Promise<TDbDeleteResult>;
-  deleteMany(filter: FilterExpr): Promise<TDbDeleteResult>;
+  deleteMany(filter: FilterExpr, opts?: TDbDeleteManyOptions): Promise<TDbDeleteResult>;
   prepareTypeMapper(): Promise<void>;
   ensureTable(opts?: TEnsureTableOptions): Promise<void>;
   /** The CREATE TABLE options (engine/charset/collation/increment/ON UPDATE/type mapper). */
@@ -419,6 +438,11 @@ declare class MysqlAdapter extends BaseDbAdapter {
    */
   rebuildPrimaryKey(change: TPrimaryKeyChange): Promise<void>;
   private _ensureView;
+  /**
+   * INFORMATION_SCHEMA reports a 4-byte character (an emoji) of a literal
+   * default as `?` — the column stores it intact.
+   */
+  reportedDefault(desired: string): string;
   getExistingColumns(): Promise<TExistingColumn[]>;
   getExistingColumnsForTable(tableName: string): Promise<TExistingColumn[]>;
   /** Live columns of `tableName`, read through `exec` (a held connection, or the pool). */
@@ -434,9 +458,13 @@ declare class MysqlAdapter extends BaseDbAdapter {
   dropViewByName(viewName: string): Promise<void>;
   renameTable(oldName: string): Promise<void>;
   typeMapper(field: TDbFieldMeta): string;
-  syncIndexes(): Promise<void>;
-  syncForeignKeys(): Promise<void>;
+  protected _syncIndexes(dryRun: boolean): Promise<TIndexChange[]>;
+  syncForeignKeys(): Promise<TForeignKeyChange[]>;
+  /** The FK changes {@link syncForeignKeys} would make — no DDL. */
+  planForeignKeys(): Promise<TForeignKeyChange[]>;
+  private _syncForeignKeys;
   dropForeignKeys(fkFieldKeys: string[]): Promise<void>;
+  private _dropFkConstraint;
   /** Queries INFORMATION_SCHEMA for existing FK constraints, grouped by constraint name → column names. */
   private _getExistingFkConstraints;
   getSearchIndexes(): TSearchIndexInfo[];

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDefaultFn, TDbDeleteResult, TDbFieldMeta, TDbInsertIgnoreOptions, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateOptions, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TExistingTableOption, TFieldOps, TJsonCopyTarget, TPrimaryKeyChange, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TTableOptionDiff, TValueFormatterPair, TViewCapability } from "@atscript/db";
+import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDefaultFn, TDbDeleteManyOptions, TDbDeleteResult, TDbFieldMeta, TDbInsertIgnoreOptions, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbIsolationLevel, TDbObjectKind, TDbUpdateOptions, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TExistingTableOption, TFieldOps, TForeignKeyChange, TIndexChange, TJsonCopyTarget, TPrimaryKeyChange, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TTableOptionDiff, TTransactionOptions, 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";
@@ -72,6 +72,13 @@ interface TMysqlConnection {
   exec(sql: string): Promise<void>;
   /** Release this connection back to the pool. */
   release(): void;
+  /**
+   * Close this connection instead of returning it to the pool (since
+   * 0.1.162) — used when its session state cannot be trusted, e.g. a
+   * one-shot `SET TRANSACTION` left pending by a failed
+   * `START TRANSACTION`. Optional: a driver without it gets `release()`.
+   */
+  destroy?(): void;
 }
 /**
  * `MysqlAdapter` options.
@@ -154,7 +161,7 @@ declare class MysqlAdapter extends BaseDbAdapter {
   protected _transactionOwner(): unknown;
   /** The dedicated connection of this pool's open transaction, if any. */
   private _txConnection;
-  protected _beginTransaction(): Promise<TMysqlConnection>;
+  protected _beginTransaction(opts?: TTransactionOptions): Promise<TMysqlConnection>;
   protected _commitTransaction(state: unknown): Promise<void>;
   protected _rollbackTransaction(state: unknown): Promise<void>;
   /**
@@ -196,6 +203,14 @@ declare class MysqlAdapter extends BaseDbAdapter {
   supportsAggregateExpressions(): boolean;
   /** `$nulls` / `@db.sort.nulls` NULL placement — a leading `(col IS NULL)` key where the native order differs. */
   supportsNullsPlacement(): boolean;
+  /**
+   * Locking reads: `SELECT … FOR UPDATE` / `FOR SHARE` [`NOWAIT` /
+   * `SKIP LOCKED`] (MySQL 8). A locking read is a current read — it sees the
+   * latest committed row even under REPEATABLE READ. @since 0.1.162
+   */
+  supportsReadLocks(): boolean;
+  /** Every level, set by `SET TRANSACTION ISOLATION LEVEL` before `START TRANSACTION`. @since 0.1.162 */
+  isolationLevels(): ReadonlySet<TDbIsolationLevel>;
   /** Computed view columns and first-row joins. */
   viewCapabilities(): ReadonlySet<TViewCapability>;
   onBeforeFlatten(_type: unknown): void;
@@ -385,13 +400,17 @@ declare class MysqlAdapter extends BaseDbAdapter {
   /** `true` when a relational predicate of `filter` (nested ones included) reads this table. */
   private _filterReadsOwnTable;
   updateOne(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps, expectedVersion?: number, opts?: TDbUpdateOptions): Promise<TDbUpdateResult>;
+  /** Native `UPDATE/DELETE … ORDER BY … LIMIT n` (since 0.1.162). */
+  supportsWriteLimit(): boolean;
+  /** The `ORDER BY … LIMIT` scan locks as it goes and skips rows gone meanwhile. */
+  writeLimitIsAtomic(): boolean;
   updateMany(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps, opts?: TDbUpdateOptions): Promise<TDbUpdateResult>;
   replaceOne(filter: FilterExpr, data: Record<string, unknown>, expectedVersion?: number): Promise<TDbUpdateResult>;
   /** The columns a full replace assigns (`replaceColumnsFor`), built once per table. */
   private _replaceColumns;
   replaceMany(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
   deleteOne(filter: FilterExpr): Promise<TDbDeleteResult>;
-  deleteMany(filter: FilterExpr): Promise<TDbDeleteResult>;
+  deleteMany(filter: FilterExpr, opts?: TDbDeleteManyOptions): Promise<TDbDeleteResult>;
   prepareTypeMapper(): Promise<void>;
   ensureTable(opts?: TEnsureTableOptions): Promise<void>;
   /** The CREATE TABLE options (engine/charset/collation/increment/ON UPDATE/type mapper). */
@@ -419,6 +438,11 @@ declare class MysqlAdapter extends BaseDbAdapter {
    */
   rebuildPrimaryKey(change: TPrimaryKeyChange): Promise<void>;
   private _ensureView;
+  /**
+   * INFORMATION_SCHEMA reports a 4-byte character (an emoji) of a literal
+   * default as `?` — the column stores it intact.
+   */
+  reportedDefault(desired: string): string;
   getExistingColumns(): Promise<TExistingColumn[]>;
   getExistingColumnsForTable(tableName: string): Promise<TExistingColumn[]>;
   /** Live columns of `tableName`, read through `exec` (a held connection, or the pool). */
@@ -434,9 +458,13 @@ declare class MysqlAdapter extends BaseDbAdapter {
   dropViewByName(viewName: string): Promise<void>;
   renameTable(oldName: string): Promise<void>;
   typeMapper(field: TDbFieldMeta): string;
-  syncIndexes(): Promise<void>;
-  syncForeignKeys(): Promise<void>;
+  protected _syncIndexes(dryRun: boolean): Promise<TIndexChange[]>;
+  syncForeignKeys(): Promise<TForeignKeyChange[]>;
+  /** The FK changes {@link syncForeignKeys} would make — no DDL. */
+  planForeignKeys(): Promise<TForeignKeyChange[]>;
+  private _syncForeignKeys;
   dropForeignKeys(fkFieldKeys: string[]): Promise<void>;
+  private _dropFkConstraint;
   /** Queries INFORMATION_SCHEMA for existing FK constraints, grouped by constraint name → column names. */
   private _getExistingFkConstraints;
   getSearchIndexes(): TSearchIndexInfo[];

package/dist/index.mjs

@@ -1,8 +1,18 @@
-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 { ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_ISOLATION_LEVELS, ALL_VIEW_CAPABILITIES, BaseDbAdapter, DbError, DbSpace, NoopLogger, bucketTimeZoneUnavailable, containsRelationFilter, defaultFulltextIndex, describeFulltext, fkKey, 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, buildJsonColumnCopy, buildJsonifyText, buildKeyViolationCount, 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 { EMPTY_OR, SEARCH_SOURCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildJsonColumnCopy, buildJsonifyText, buildKeyViolationCount, buildPartitionedSelect, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere as buildWhere$1, chunkInsertRows, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, foreignKeySql, fromSourceHint, fromSourceSql, geoWindowFromControls, jsonDollarPath, mapQueryErrors, normalizeGeoPointValue, numericOutOfRangeError, orFragment, orderByList, parseRegexString, renameGeoDistance, replaceColumnsFor, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, unquoteSqlStringLiteral, vectorDistanceSource, viewReadSource, writeLimitCount } from "@atscript/db-sql-tools";
 import { BUCKET_MAX_INSTANT, BUCKET_MIN_INSTANT } from "@uniqu/core";
 //#region src/sql-builder.ts
+/**
+* A MySQL string literal: quotes doubled and backslashes escaped — MySQL
+* reads `\` as an escape in a string literal (unless the server runs with
+* `NO_BACKSLASH_ESCAPES`), so the shared `sqlStringLiteral` would drop or
+* reinterpret them (`'a\b'` stores a backspace, `'x\'` is unterminated).
+* @since 0.1.162
+*/
+function mysqlStringLiteral(value) {
+	return `'${value.replace(/\\/g, "\\\\").replace(/'/g, "''")}'`;
+}
 /** TEXT / BLOB families (`TINYTEXT` … `LONGBLOB`). */
 const TEXT_BLOB_RE = /^(TINY|MEDIUM|LONG)?(TEXT|BLOB)\b/i;
 /** Spatial types (`POINT SRID 4326`, `GEOMETRY`, `MULTI*`, …). */
@@ -12,11 +22,19 @@ function needsExpressionDefault(sqlType) {
 	return TEXT_BLOB_RE.test(sqlType) || /^JSON\b/i.test(sqlType) || GEOMETRY_RE.test(sqlType);
 }
 /**
+* `defaultValueToSqlLiteral` for MySQL: a string literal also escapes
+* backslashes, which MySQL reads as escapes (unless `NO_BACKSLASH_ESCAPES`) —
+* `'a\\b'` would store `a\b` minus one backslash otherwise.
+*/
+function mysqlValueLiteral(designType, value) {
+	return defaultValueToSqlLiteral(designType, value, mysqlStringLiteral);
+}
+/**
 * Renders a model value default for a column of `sqlType`: the SQL literal,
 * wrapped in the expression form for the types that require it.
 */
 function mysqlDefaultLiteral(sqlType, designType, value) {
-	const literal = defaultValueToSqlLiteral(designType, value);
+	const literal = mysqlValueLiteral(designType, value);
 	return needsExpressionDefault(sqlType) ? `(${literal})` : literal;
 }
 /**
@@ -152,6 +170,7 @@ const mysqlDialect = {
 		return quoteTableName(name);
 	},
 	unlimitedLimit: "18446744073709551615",
+	stringLiteral: mysqlStringLiteral,
 	derivedMergeHint(alias) {
 		return `/*+ MERGE(${qi(alias)}) */`;
 	},
@@ -183,11 +202,11 @@ const mysqlDialect = {
 	bucketAliasInHaving: true,
 	jsonExtract: mysqlJsonExtract,
 	jsonExtractText: (quotedCol, path) => {
-		const e = `JSON_EXTRACT(${quotedCol}, ${jsonDollarPath(path)})`;
+		const e = `JSON_EXTRACT(${quotedCol}, ${jsonDollarPath(path, mysqlStringLiteral)})`;
 		return `CASE WHEN JSON_TYPE(${e}) = 'NULL' THEN NULL ELSE JSON_UNQUOTE(${e}) END`;
 	},
 	jsonExtractValue: (quotedCol, path) => {
-		const e = `JSON_EXTRACT(${quotedCol}, ${jsonDollarPath(path)})`;
+		const e = `JSON_EXTRACT(${quotedCol}, ${jsonDollarPath(path, mysqlStringLiteral)})`;
 		return `CASE WHEN JSON_TYPE(${e}) = 'NULL' THEN NULL ELSE ${e} END`;
 	},
 	jsonFromText: (quotedCol) => `IF(JSON_VALID(${quotedCol}), ${quotedCol}, JSON_QUOTE(${quotedCol}))`,
@@ -205,7 +224,7 @@ const MYSQL_JSON_NUMBER_TYPES = "'INTEGER', 'UNSIGNED INTEGER', 'DOUBLE', 'DECIM
 * `CAST(… AS JSON)` (not in MariaDB).
 */
 function mysqlJsonExtract(quotedCol, path, type) {
-	const e = `JSON_EXTRACT(${quotedCol}, ${jsonDollarPath(path)})`;
+	const e = `JSON_EXTRACT(${quotedCol}, ${jsonDollarPath(path, mysqlStringLiteral)})`;
 	const t = `JSON_TYPE(${e})`;
 	switch (type) {
 		case "string": return `CASE ${t} WHEN 'STRING' THEN JSON_UNQUOTE(${e}) END`;
@@ -371,21 +390,28 @@ function buildInsertMany$1(table, rows, columns) {
 /**
 * Builds a SELECT statement with optional sort, limit, offset, projection.
 */
-function buildSelect$1(table, where, controls) {
-	return buildSelect(mysqlDialect, table, where, controls);
+function buildSelect$1(table, where, controls, lock) {
+	return buildSelect(mysqlDialect, table, where, controls, lock);
 }
 /**
-* Builds an UPDATE ... SET ... WHERE statement with optional LIMIT.
+* Builds an UPDATE ... SET ... WHERE statement with optional [ORDER BY …] LIMIT.
 */
 function buildUpdate$1(table, data, where, limit, ops, versionColumn, expectedVersion) {
 	return buildUpdate(mysqlDialect, table, data, where, limit, ops, versionColumn, expectedVersion);
 }
 /**
-* Builds a DELETE ... WHERE statement with optional LIMIT.
+* Builds a DELETE ... WHERE statement with optional [ORDER BY …] LIMIT.
 */
 function buildDelete$1(table, where, limit) {
 	return buildDelete(mysqlDialect, table, where, limit);
 }
+/** `ORDER BY … LIMIT n` of a bounded write (since 0.1.162), `undefined` when unbounded. */
+function writeLimitClause(bound) {
+	return bound && {
+		count: writeLimitCount(bound),
+		orderBy: orderByList(mysqlDialect, bound.sort, bound.nulls)
+	};
+}
 /**
 * Builds a CREATE OR REPLACE VIEW statement from a view plan and column mappings.
 */
@@ -679,11 +705,24 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 	_txConnection() {
 		return this._getTransactionState();
 	}
-	async _beginTransaction() {
+	async _beginTransaction(opts) {
 		const conn = await this.driver.getConnection();
-		await conn.exec("START TRANSACTION");
-		this._log("START TRANSACTION");
-		return conn;
+		let levelPending = false;
+		try {
+			if (opts?.isolation) {
+				const sql = `SET TRANSACTION ISOLATION LEVEL ${opts.isolation.toUpperCase()}`;
+				this._log(sql);
+				await conn.exec(sql);
+				levelPending = true;
+			}
+			await conn.exec("START TRANSACTION");
+			this._log("START TRANSACTION");
+			return conn;
+		} catch (err) {
+			if (levelPending && conn.destroy) conn.destroy();
+			else conn.release();
+			throw err;
+		}
 	}
 	async _commitTransaction(state) {
 		const conn = state;
@@ -775,6 +814,18 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 	supportsNullsPlacement() {
 		return true;
 	}
+	/**
+	* Locking reads: `SELECT … FOR UPDATE` / `FOR SHARE` [`NOWAIT` /
+	* `SKIP LOCKED`] (MySQL 8). A locking read is a current read — it sees the
+	* latest committed row even under REPEATABLE READ. @since 0.1.162
+	*/
+	supportsReadLocks() {
+		return true;
+	}
+	/** Every level, set by `SET TRANSACTION ISOLATION LEVEL` before `START TRANSACTION`. @since 0.1.162 */
+	isolationLevels() {
+		return ALL_ISOLATION_LEVELS;
+	}
 	/** Computed view columns and first-row joins. */
 	viewCapabilities() {
 		return ALL_VIEW_CAPABILITIES;
@@ -912,7 +963,7 @@ 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", [{
+			if (err.errno === 1213 || err.errno === 1205 || err.errno === 3572) throw new DbError(err.errno === 1213 ? "DEADLOCK" : "LOCK_TIMEOUT", [{
 				path: "",
 				message: err.sqlMessage ?? err.message
 			}]);
@@ -1257,7 +1308,7 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 				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));
+				await this._exec().all(sql, params).catch((error) => this._mapConstraintError(error));
 			}
 		}
 	}
@@ -1347,15 +1398,15 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 			...query.controls,
 			$limit: 1
 		};
-		const { sql, params } = buildSelect$1(this._readSource(query, "rows"), where, controls);
+		const { sql, params } = buildSelect$1(this._readSource(query, "rows"), where, controls, query.lock);
 		this._log(sql, params);
-		return this._exec().get(sql, params);
+		return this._exec().get(sql, params).catch((error) => this._mapConstraintError(error));
 	}
 	async findMany(query) {
 		const where = buildWhere(query.filter);
-		const { sql, params } = buildSelect$1(this._readSource(query, "rows"), where, query.controls);
+		const { sql, params } = buildSelect$1(this._readSource(query, "rows"), where, query.controls, query.lock);
 		this._log(sql, params);
-		return this._exec().all(sql, params);
+		return this._exec().all(sql, params).catch((error) => this._mapConstraintError(error));
 	}
 	/**
 	* `$skip` / `$limit` per partition in one statement: a `ROW_NUMBER()`
@@ -1465,10 +1516,18 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 			modifiedCount: result.changedRows
 		};
 	}
+	/** Native `UPDATE/DELETE … ORDER BY … LIMIT n` (since 0.1.162). */
+	supportsWriteLimit() {
+		return true;
+	}
+	/** The `ORDER BY … LIMIT` scan locks as it goes and skips rows gone meanwhile. */
+	writeLimitIsAtomic() {
+		return true;
+	}
 	async updateMany(filter, data, ops, opts) {
 		const where = this._mutationWhere(filter);
 		const versionColumn = this._versionColumnFor(opts);
-		const { sql, params } = buildUpdate$1(this.resolveTableName(), data, where, void 0, ops, versionColumn);
+		const { sql, params } = buildUpdate$1(this.resolveTableName(), data, where, writeLimitClause(opts?.limit), ops, versionColumn);
 		this._log(sql, params);
 		const result = await this._wrapConstraintError(() => this._exec().run(sql, params));
 		return {
@@ -1479,8 +1538,8 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 	async replaceOne(filter, data, expectedVersion) {
 		const where = this._mutationWhere(filter);
 		const versionColumn = this._table.versionColumnPhysical;
-		const full = fillReplacePayload(data, this._replaceColumns(), versionColumn);
-		const { sql, params } = buildUpdate$1(this.resolveTableName(), full, where, 1, void 0, versionColumn, expectedVersion);
+		const full = fillReplacePayload(data, this._replaceColumns(), versionColumn, this._table.onUpdateIncPhysical);
+		const { sql, params } = buildUpdate$1(this.resolveTableName(), full, where, 1, this._onUpdateIncOps(), versionColumn, expectedVersion);
 		this._log(sql, params);
 		const result = await this._wrapConstraintError(() => this._exec().run(sql, params));
 		return {
@@ -1501,7 +1560,7 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 	async replaceMany(filter, data) {
 		const where = this._mutationWhere(filter);
 		const versionColumn = this._table.versionColumnPhysical;
-		const { sql, params } = buildUpdate$1(this.resolveTableName(), data, where, void 0, void 0, versionColumn);
+		const { sql, params } = buildUpdate$1(this.resolveTableName(), data, where, void 0, this._onUpdateIncOps(), versionColumn);
 		this._log(sql, params);
 		const result = await this._wrapConstraintError(() => this._exec().run(sql, params));
 		return {
@@ -1515,9 +1574,9 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 		this._log(sql, params);
 		return { deletedCount: (await this._wrapConstraintError(() => this._exec().run(sql, params))).affectedRows };
 	}
-	async deleteMany(filter) {
+	async deleteMany(filter, opts) {
 		const where = this._mutationWhere(filter);
-		const { sql, params } = buildDelete$1(this.resolveTableName(), where);
+		const { sql, params } = buildDelete$1(this.resolveTableName(), where, writeLimitClause(opts?.limit));
 		this._log(sql, params);
 		return { deletedCount: (await this._wrapConstraintError(() => this._exec().run(sql, params))).affectedRows };
 	}
@@ -1659,6 +1718,13 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 		this._log(sql);
 		await this._exec().exec(sql);
 	}
+	/**
+	* INFORMATION_SCHEMA reports a 4-byte character (an emoji) of a literal
+	* default as `?` — the column stores it intact.
+	*/
+	reportedDefault(desired) {
+		return desired.replace(/[\u{10000}-\u{10FFFF}]/gu, "?");
+	}
 	async getExistingColumns() {
 		return this.getExistingColumnsForTable(this._table.tableName);
 	}
@@ -1680,7 +1746,7 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 				type: r.SRS_ID == null ? r.COLUMN_TYPE.toUpperCase() : `${r.COLUMN_TYPE.toUpperCase()} SRID ${r.SRS_ID}`,
 				notnull: r.IS_NULLABLE === "NO",
 				pk: Boolean(Number(r.IS_PK ?? 0)),
-				dflt_value: normalizeMysqlDefault(r.COLUMN_DEFAULT)
+				dflt_value: normalizeMysqlDefault(r.COLUMN_DEFAULT, r.EXTRA)
 			};
 			if (/\b(VIRTUAL|STORED) GENERATED\b/i.test(r.EXTRA ?? "")) column.generated = true;
 			return column;
@@ -1788,7 +1854,7 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 					const selectExprs = commonCols.map((c) => {
 						const field = fieldsByName.get(c);
 						if (field && !field.optional && !field.isPrimaryKey) {
-							const fallback = field.defaultValue?.kind === "value" ? defaultValueToSqlLiteral(field.designType, field.defaultValue.value) : defaultValueForType(field.designType);
+							const fallback = field.defaultValue?.kind === "value" ? mysqlValueLiteral(field.designType, field.defaultValue.value) : defaultValueForType(field.designType);
 							return `COALESCE(${qi(c)}, ${fallback}) AS ${qi(c)}`;
 						}
 						return qi(c);
@@ -1879,7 +1945,7 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 		}
 		return mysqlTypeFromField(field);
 	}
-	async syncIndexes() {
+	async _syncIndexes(dryRun) {
 		const tableName = this._table.tableName;
 		const schema = this._schema;
 		const bytesPerChar = mysqlBytesPerChar(this._charset);
@@ -1893,7 +1959,13 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 			return type === void 0 ? void 0 : mysqlIndexPrefix(type, bytesPerChar);
 		};
 		const renderPart = (column, prefix) => prefix === void 0 ? column : `${column}(${prefix})`;
-		await this.syncIndexesWithDiff({
+		return this.syncIndexesWithDiff({
+			dryRun,
+			skipIndex: (index) => {
+				if (index.type !== "geo") return void 0;
+				const fieldMeta = this._table.fieldDescriptors.find((f) => f.physicalName === index.fields[0]?.name);
+				return fieldMeta?.optional ? `[mysql] geo index "${index.name}" skipped — SPATIAL indexes require a NOT NULL column; make "${fieldMeta.path}" required to index it` : void 0;
+			},
 			listExisting: async () => {
 				const rows = await this._exec().all(`SELECT INDEX_NAME, COLUMN_NAME, SUB_PART, SEQ_IN_INDEX
            FROM INFORMATION_SCHEMA.STATISTICS
@@ -1916,11 +1988,6 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 			renderDesiredColumn: (_index, f) => renderPart(f.name, desiredPrefix(f.name)),
 			createIndex: async (index) => {
 				if (index.type === "geo") {
-					const fieldMeta = this._table.fieldDescriptors.find((f) => f.physicalName === index.fields[0]?.name);
-					if (fieldMeta?.optional) {
-						this.logger.warn(`[mysql] geo index "${index.name}" skipped — SPATIAL indexes require a NOT NULL column; make "${fieldMeta.path}" required to index it`);
-						return;
-					}
 					const sql = `CREATE SPATIAL INDEX ${qi(index.key)} ON ${quoteTableName(this.resolveTableName())} (${qi(index.fields[0].name)})`;
 					this._log(sql);
 					await this._exec().exec(sql);
@@ -1949,39 +2016,33 @@ 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([...fkColumns(fk).fields].toSorted().join(","));
-		for (const [constraintName, columns] of existingByName) {
-			const key = columns.toSorted().join(",");
-			if (!desiredFkKeys.has(key)) {
-				const ddl = `ALTER TABLE ${quoteTableName(this.resolveTableName())} DROP FOREIGN KEY ${qi(constraintName)}`;
-				this._log(ddl);
-				await this._exec().exec(ddl);
-			}
-		}
-		const existingKeys = new Set([...existingByName.values()].map((cols) => cols.toSorted().join(",")));
-		for (const fk of this._table.foreignKeys.values()) {
-			const key = [...fkColumns(fk).fields].toSorted().join(",");
-			if (!existingKeys.has(key)) {
+		return this._syncForeignKeys(false);
+	}
+	/** The FK changes {@link syncForeignKeys} would make — no DDL. */
+	async planForeignKeys() {
+		return this._syncForeignKeys(true);
+	}
+	_syncForeignKeys(dryRun) {
+		return this.syncForeignKeysWithDiff({
+			dryRun,
+			listExisting: () => this._getExistingFkConstraints(),
+			dropConstraint: (name) => this._dropFkConstraint(name),
+			addConstraint: async (fk) => {
 				const ddl = `ALTER TABLE ${quoteTableName(this.resolveTableName())} ADD ${foreignKeySql(qi, fk)}`;
 				this._log(ddl);
 				await this._exec().exec(ddl);
 			}
-		}
+		});
 	}
 	async dropForeignKeys(fkFieldKeys) {
 		if (fkFieldKeys.length === 0) return;
 		const keySet = new Set(fkFieldKeys);
-		const existingByName = await this._getExistingFkConstraints();
-		for (const [constraintName, cols] of existingByName) {
-			const key = cols.toSorted().join(",");
-			if (keySet.has(key)) {
-				const ddl = `ALTER TABLE ${quoteTableName(this.resolveTableName())} DROP FOREIGN KEY ${qi(constraintName)}`;
-				this._log(ddl);
-				await this._exec().exec(ddl);
-			}
-		}
+		for (const [constraintName, cols] of await this._getExistingFkConstraints()) if (keySet.has(fkKey(cols))) await this._dropFkConstraint(constraintName);
+	}
+	async _dropFkConstraint(name) {
+		const ddl = `ALTER TABLE ${quoteTableName(this.resolveTableName())} DROP FOREIGN KEY ${qi(name)}`;
+		this._log(ddl);
+		await this._exec().exec(ddl);
 	}
 	/** Queries INFORMATION_SCHEMA for existing FK constraints, grouped by constraint name → column names. */
 	async _getExistingFkConstraints() {
@@ -2319,14 +2380,46 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 * `uuid()`), but the diff engine compares against serialized form (`fn:now`,
 * `fn:uuid`). Without normalization, every table with function defaults
 * produces phantom ALTER diffs on re-plan.
+*
+* An expression default (`EXTRA` has `DEFAULT_GENERATED` — the form TEXT /
+* BLOB / JSON / GEOMETRY columns require) is reported as the printed
+* expression: possibly parenthesised, a string literal with a charset
+* introducer, escaped once more as a whole (`_utf8mb4\'it\\\'s\'` for
+* `'it''s'`). It is unwrapped to the literal's value. The value is compared type-aware by
+* `sameDefaultValue` (core), so `1` / `0.00` need no rewriting here.
 */
-function normalizeMysqlDefault(value) {
+function normalizeMysqlDefault(value, extra) {
 	if (value === null) return;
-	const lower = value.toLowerCase();
+	let v = value;
+	const expression = /\bDEFAULT_GENERATED\b/i.test(extra ?? "");
+	if (expression) while (v.startsWith("(") && v.endsWith(")")) v = v.slice(1, -1).trim();
+	const lower = v.toLowerCase();
 	if (/^current_timestamp(?:\(\d?\))?$/.test(lower)) return "fn:now";
 	if (lower === "uuid()") return "fn:uuid";
-	if (value.startsWith("'") && value.endsWith("'")) return value.slice(1, -1).replace(/''/g, "'");
-	return value;
+	if (expression) {
+		v = decodeLatin1Utf8(v);
+		const printed = /^(?:_\w+)?\\'/.test(v) ? v.replace(/\\([\s\S])/g, "$1") : v;
+		const literal = /^(?:_\w+)?'([\s\S]*)'$/.exec(printed);
+		return literal ? unescapeMysqlString(literal[1]) : printed;
+	}
+	return unquoteSqlStringLiteral(v) ?? v;
+}
+/** `value`'s code units (all ≤ U+00FF) as bytes, decoded as UTF-8 — `value` unchanged otherwise. */
+function decodeLatin1Utf8(value) {
+	if (!/[\u0080-\u00ff]/.test(value) || /[^\u0000-\u00ff]/.test(value)) return value;
+	const decoded = Buffer.from(value, "latin1").toString("utf8");
+	return decoded.includes("�") ? value : decoded;
+}
+const MYSQL_ESCAPES = {
+	n: "\n",
+	r: "\r",
+	t: "	",
+	"0": "\0",
+	Z: ""
+};
+/** The body of a printed MySQL string literal: `\x` escapes and doubled `''` resolved. */
+function unescapeMysqlString(body) {
+	return body.replace(/\\([\s\S])|''/g, (match, ch) => ch === void 0 ? "'" : MYSQL_ESCAPES[ch] ?? ch);
 }
 /** Maps generic similarity metric to MySQL 9+ distance function name. */
 function similarityToMysqlFn(similarity) {
@@ -2510,6 +2603,9 @@ var Mysql2Driver = class {
 			},
 			release() {
 				conn.release();
+			},
+			destroy() {
+				conn.destroy();
 			}
 		};
 	}

package/package.json

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