@atscript/db-mysql 0.1.169 → 0.1.171

package/dist/index.cjs

@@ -1,4 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_annotation_values = require("./annotation-values-DS1rF0tw.cjs");
 let _atscript_db = require("@atscript/db");
 let _atscript_db_agg = require("@atscript/db/agg");
 let _atscript_db_sql_tools = require("@atscript/db-sql-tools");
@@ -110,7 +111,8 @@ function mysqlIndexPrefix(mappedType, bytesPerChar) {
 *    default of a nullable column, and `NOT NULL DEFAULT NULL` is ER 1067);
 *    expression form for TEXT/BLOB/JSON/GEOMETRY; invented type default for a
 *    required default-less column on `add`;
-* 5. COLLATE (native `@db.mysql.collate` or portable `@db.column.collate`);
+* 5. COLLATE (native `@db.mysql.collate` or portable `@db.column.collate`;
+*    a foreign-key column's is the referenced column's);
 * 6. ON UPDATE.
 *
 * A `@db.column.derived` field (since 0.1.141) renders as a VIRTUAL generated
@@ -119,12 +121,13 @@ function mysqlIndexPrefix(mappedType, bytesPerChar) {
 */
 function buildColumnDefinition(field, ctx) {
 	const sqlType = ctx.typeMapper?.(field) ?? mysqlTypeFromField(field);
+	const { charsetClause, collateClause } = mysqlColumnCharsetClauses(field, sqlType, ctx);
 	if (field.derived) return {
-		def: `${qi(field.physicalName)} ${sqlType}${mysqlCollateClause(field)} GENERATED ALWAYS AS (${(0, _atscript_db_sql_tools.derivedColumnExpr)(mysqlDialect, field)}) VIRTUAL`,
+		def: `${qi(field.physicalName)} ${sqlType}${charsetClause}${collateClause} GENERATED ALWAYS AS (${(0, _atscript_db_sql_tools.derivedColumnExpr)(mysqlDialect, field)}) VIRTUAL`,
 		inventedDefault: false
 	};
 	const increment = ctx.purpose !== "add" && (ctx.incrementFields?.has(field.path) ?? false);
-	let def = `${qi(field.physicalName)} ${sqlType}`;
+	let def = `${qi(field.physicalName)} ${sqlType}${charsetClause}`;
 	if (increment) def += " AUTO_INCREMENT";
 	if (ctx.purpose === "create") {
 		if (!field.optional && !field.isPrimaryKey && !increment) def += " NOT NULL";
@@ -138,14 +141,53 @@ function buildColumnDefinition(field, ctx) {
 		def += ` DEFAULT ${mysqlTypeDefault(sqlType, field)}`;
 		inventedDefault = true;
 	}
-	def += mysqlCollateClause(field);
-	const onUpdate = ctx.onUpdateFields?.get(field.physicalName);
-	if (onUpdate) def += ` ON UPDATE ${/^current_timestamp(\(\))?$/i.test(onUpdate) ? currentTimestampFor(sqlType) : onUpdate}`;
+	def += collateClause;
+	const onUpdate = ctx.onUpdateFields?.get(field.path);
+	if (onUpdate) def += ` ON UPDATE ${require_annotation_values.mysqlOnUpdateExpr(onUpdate, currentTimestampFor(sqlType))}`;
 	return {
 		def,
 		inventedDefault
 	};
 }
+/** Whether a column declares its own collation (`@db.mysql.collate` or `@db.column.collate`). */
+function declaresCollation(field) {
+	return field.collate !== void 0 || (field.type?.metadata?.has("db.mysql.collate") ?? false);
+}
+/**
+* The character set a column declares (`undefined`: the table's). A
+* foreign-key column takes the referenced column's, as MySQL requires of a
+* string foreign key: the referenced field's own `@db.mysql.charset`, else
+* its table's (`ctx.keyTableCharsets`); its own declarations are not used.
+*/
+function mysqlColumnCharset(field, ctx) {
+	const keyTarget = field.fkTargetField;
+	if (!keyTarget) return ctx.charsetFields?.get(field.path);
+	return keyTarget.type?.metadata?.get("db.mysql.charset") ?? ctx.keyTableCharsets?.get(field.path)?.charset;
+}
+/**
+* The ` CHARACTER SET …` and ` COLLATE …` of a column (see
+* {@link mysqlColumnCharset}); a foreign-key column's collation is the
+* referenced field's own, else its table's.
+*/
+function mysqlColumnCharsetClauses(field, sqlType, ctx) {
+	const charset = mysqlColumnCharset(field, ctx);
+	const charsetClause = mysqlCharsetClause(sqlType, charset);
+	const keyTarget = field.fkTargetField;
+	if (!keyTarget) return {
+		charsetClause,
+		collateClause: mysqlCollateClause(field, charset)
+	};
+	const ownCharset = keyTarget.type?.metadata?.get("db.mysql.charset");
+	if (declaresCollation(keyTarget)) return {
+		charsetClause,
+		collateClause: mysqlCollateClause(keyTarget, ownCharset)
+	};
+	const tableCollation = ownCharset === void 0 ? ctx.keyTableCharsets?.get(field.path)?.collation : void 0;
+	return {
+		charsetClause,
+		collateClause: tableCollation && CHARACTER_TYPE_RE.test(sqlType) ? ` COLLATE ${require_annotation_values.mysqlName("@db.mysql.collate", tableCollation)}` : ""
+	};
+}
 /** Escapes a MySQL identifier by doubling backticks. */
 function esc(name) {
 	return name.replace(/`/g, "``");
@@ -433,18 +475,39 @@ function buildAggregateSelect(table, where, controls) {
 function buildAggregateCount(table, where, controls) {
 	return (0, _atscript_db_sql_tools.buildAggregateCount)(mysqlDialect, table, where, controls);
 }
+/** Character-typed columns (the ones a `CHARACTER SET` applies to). */
+const CHARACTER_TYPE_RE = /^(VAR)?CHAR\b|^(TINY|MEDIUM|LONG)?TEXT\b|^(ENUM|SET)\b/i;
 /**
-* Maps portable collation values to MySQL collation names.
+* ` CHARACTER SET <charset>` for a character-typed column with a field-level
+* `@db.mysql.charset`, else `""`.
 */
+function mysqlCharsetClause(sqlType, charset) {
+	return charset && CHARACTER_TYPE_RE.test(sqlType) ? ` CHARACTER SET ${require_annotation_values.mysqlName("@db.mysql.charset", charset)}` : "";
+}
 /**
-* The `COLLATE` clause of a column (native `@db.mysql.collate`, else the
-* portable `@db.column.collate` mapping) — `""` when none applies.
+* The column's ` COLLATE …`: a native `@db.mysql.collate`, else the portable
+* `@db.column.collate` — in the column's `charset` when it sets one
+* (`nocase` → `<charset>_general_ci`, `binary` → `<charset>_bin`,
+* `unicode` → `<charset>_unicode_ci`), else in `utf8mb4`.
 */
-function mysqlCollateClause(field) {
+function mysqlCollateClause(field, charset) {
 	const nativeCollate = field.type?.metadata?.get("db.mysql.collate");
 	if (nativeCollate) return ` COLLATE ${nativeCollate}`;
-	return field.collate ? ` COLLATE ${collationToMysql(field.collate)}` : "";
+	if (!field.collate) return "";
+	const collation = collationToMysql(field.collate);
+	return ` COLLATE ${charset ? collation.replace(/^utf8mb4_/, `${charset}_`) : collation}`;
 }
+/**
+* The collation a table gets when only its character set is declared:
+* `utf8mb4_unicode_ci` for `utf8mb4` (the adapter's default), else none —
+* MySQL then applies the set's own default collation.
+*/
+function mysqlDefaultCollation(charset) {
+	return charset.toLowerCase() === "utf8mb4" ? "utf8mb4_unicode_ci" : void 0;
+}
+/**
+* Maps portable collation values to MySQL collation names.
+*/
 function collationToMysql(collation) {
 	switch (collation) {
 		case "binary": return "utf8mb4_bin";
@@ -453,15 +516,6 @@ function collationToMysql(collation) {
 		default: return "utf8mb4_unicode_ci";
 	}
 }
-/**
-* Maps an Atscript field descriptor to a MySQL column type.
-*
-* Reads `designType`, primitive tags (via `type.type.tags`), and annotations
-* from field metadata to produce the most specific MySQL type.
-*
-* For FK fields, delegates to the target PK's type via `field.fkTargetField`
-* so the FK column type always matches the referenced column.
-*/
 /** Maps integer primitive tags to MySQL integer types. */
 function intTypeFromTags(tags, unsigned) {
 	if (tags?.has("int8")) return unsigned ? "TINYINT UNSIGNED" : "TINYINT";
@@ -474,8 +528,19 @@ function intTypeFromTags(tags, unsigned) {
 	if (tags?.has("uint64")) return "BIGINT UNSIGNED";
 	return unsigned ? "INT UNSIGNED" : "INT";
 }
-function mysqlTypeFromField(field) {
-	if (field.fkTargetField) return mysqlTypeFromField(field.fkTargetField);
+/**
+* Maps an Atscript field descriptor to a MySQL column type.
+*
+* Reads `designType`, primitive tags (via `type.type.tags`), and annotations
+* from field metadata to produce the most specific MySQL type.
+*
+* `keyed` marks a column a foreign key references (the adapter knows it
+* from its space); a referencing column takes its type through
+* `field.fkTargetField`. A keyed string is never TEXT: a foreign key needs
+* both sides indexed in full, and MySQL indexes TEXT only by a prefix.
+*/
+function mysqlTypeFromField(field, keyed = false) {
+	if (field.fkTargetField) return mysqlTypeFromField(field.fkTargetField, true);
 	const tags = field.type?.type?.tags;
 	const metadata = field.type?.metadata;
 	const mysqlTypeOverride = metadata?.get("db.mysql.type");
@@ -500,14 +565,15 @@ function mysqlTypeFromField(field) {
 			const maxLen = (metadata?.get("expect.maxLength"))?.length;
 			if (maxLen !== void 0 && maxLen <= 65535) return `VARCHAR(${maxLen})`;
 			if (maxLen !== void 0 && maxLen > 65535) return "LONGTEXT";
-			if (field.isPrimaryKey || field.defaultValue || field.derived) return "VARCHAR(255)";
+			if (field.defaultValue?.kind === "fn" && field.defaultValue.fn === "uuid") return "CHAR(36)";
+			if (keyed || field.isPrimaryKey || field.defaultValue || field.derived) return "VARCHAR(255)";
 			return "TEXT";
 		}
 		case "json":
 		case "object":
 		case "array": return "JSON";
 		default:
-			if (field.isPrimaryKey || field.defaultValue) return "VARCHAR(255)";
+			if (keyed || field.isPrimaryKey || field.defaultValue) return "VARCHAR(255)";
 			return "TEXT";
 	}
 }
@@ -519,6 +585,8 @@ function buildCreateTable(table, fields, foreignKeys, options) {
 	const ctx = {
 		incrementFields: options?.incrementFields,
 		onUpdateFields: options?.onUpdateFields,
+		charsetFields: options?.charsetFields,
+		keyTableCharsets: options?.keyTableCharsets,
 		typeMapper: options?.typeMapper,
 		purpose: "create"
 	};
@@ -542,8 +610,9 @@ function buildCreateTable(table, fields, foreignKeys, options) {
 	let sql = `CREATE TABLE IF NOT EXISTS ${quoteTableName(table)} (${body})`;
 	const engine = options?.engine ?? "InnoDB";
 	const charset = options?.charset ?? "utf8mb4";
-	const collation = options?.collation ?? "utf8mb4_unicode_ci";
-	sql += ` ENGINE=${engine} DEFAULT CHARSET=${charset} COLLATE=${collation}`;
+	const collation = options?.collation ?? mysqlDefaultCollation(charset);
+	sql += ` ENGINE=${engine} DEFAULT CHARSET=${charset}`;
+	if (collation) sql += ` COLLATE=${collation}`;
 	if (options?.autoIncrementStart !== void 0) sql += ` AUTO_INCREMENT=${options.autoIncrementStart}`;
 	return sql;
 }
@@ -566,6 +635,14 @@ function buildWhere(filter, opts) {
 }
 //#endregion
 //#region src/mysql-adapter.ts
+/** A column's own `@db.mysql.charset`, `@db.mysql.collate` and `@db.column.collate` (lowercased, `""` when absent). */
+function declaredCharsetCollation(field) {
+	return [
+		field.type?.metadata?.get("db.mysql.charset"),
+		field.type?.metadata?.get("db.mysql.collate"),
+		field.collate
+	].map((v) => typeof v === "string" ? v.toLowerCase() : "");
+}
 /**
 * Parses a MySQL UTC datetime string (`'YYYY-MM-DD HH:MM:SS[.ffffff]'`) to
 * epoch ms — fractional seconds included (truncated to milliseconds; since
@@ -628,6 +705,33 @@ const nonStrictChecked = /* @__PURE__ */ new WeakSet();
 * loading the time zone tables fixes a running server without a restart.
 */
 const convertibleZones = /* @__PURE__ */ new WeakMap();
+/** The `ALTER TABLE` that re-creates `fks`, all on `table`, as they were. */
+function addForeignKeysSql(table, fks) {
+	return `ALTER TABLE ${table} ${fks.map((fk) => `ADD CONSTRAINT ${qi(fk.name)} FOREIGN KEY (${fk.columns.map(qi).join(", ")}) REFERENCES ${fk.refTable} (${fk.refColumns.map(qi).join(", ")}) ON DELETE ${fk.onDelete} ON UPDATE ${fk.onUpdate}`).join(", ")}`;
+}
+/** A map key of a live column. */
+const columnKey = (c) => `${c.schema}\0${c.table}\0${c.column}`;
+/** Which ends of `fk`'s `i`-th column pair are among `columns` (of the adapter's table). */
+function touchedEnds(fk, i, columns) {
+	return {
+		child: fk.own && columns.has(fk.columns[i]),
+		parent: fk.ref && columns.has(fk.refColumns[i])
+	};
+}
+const INTEGER_TYPE_RE = /^(tinyint|smallint|mediumint|int|integer|bigint)(?:\(\d+\))?(\s+unsigned)?(?:\s+zerofill)?$/;
+const CHAR_TYPE_RE = /^(?:var)?char\(\d+\)$/i;
+/**
+* What the two sides of a foreign key must share: an integer's type and
+* signedness (display width aside), a `CHAR` / `VARCHAR`'s collation (any
+* length), anything else the type.
+*/
+function fkTypeKey(column) {
+	const type = column.type.trim().toLowerCase().replace(/\s+/g, " ");
+	const int = INTEGER_TYPE_RE.exec(type);
+	if (int) return `int:${int[1] === "integer" ? "int" : int[1]}:${!!int[2]}`;
+	if (CHAR_TYPE_RE.test(type)) return `char:${(column.collation ?? "").toLowerCase()}`;
+	return type;
+}
 /**
 * MySQL adapter for {@link AtscriptDbTable}.
 *
@@ -650,7 +754,8 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 	static NATIVE_DEFAULT_FNS = new Set(["now", "increment"]);
 	_engine = "InnoDB";
 	_charset = "utf8mb4";
-	_collation = "utf8mb4_unicode_ci";
+	/** `@db.mysql.collate` on the table; none → the charset's default (see `mysqlDefaultCollation`). */
+	_collation;
 	_autoIncrementStart;
 	_incrementFields = /* @__PURE__ */ new Set();
 	/**
@@ -666,6 +771,11 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 	*/
 	_epochAfterRekey = /* @__PURE__ */ new Map();
 	_onUpdateFields = /* @__PURE__ */ new Map();
+	/** Field path → `@db.mysql.charset` of the column. */
+	_charsetFields = /* @__PURE__ */ new Map();
+	_space;
+	/** Memo of {@link _keyTableCharsets} — it also makes its warning fire once. */
+	_keyTableCharsetsMemo;
 	/** Whether the connected MySQL instance supports native VECTOR type (MySQL 9.0+). */
 	_supportsVector;
 	/** Vector fields: physical field name → { dimensions, similarity, indexName }. */
@@ -849,11 +959,11 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 	onBeforeFlatten(_type) {
 		const meta = _type.metadata;
 		const engine = meta.get("db.mysql.engine");
-		if (engine) this._engine = engine;
+		if (engine) this._engine = require_annotation_values.mysqlName("@db.mysql.engine", engine);
 		const charset = meta.get("db.mysql.charset");
-		if (charset) this._charset = charset;
+		if (charset) this._charset = require_annotation_values.mysqlName("@db.mysql.charset", charset);
 		const collate = meta.get("db.mysql.collate");
-		if (collate) this._collation = collate;
+		if (collate) this._collation = require_annotation_values.mysqlName("@db.mysql.collate", collate);
 	}
 	onFieldScanned(field, _type, metadata) {
 		if (metadata.has("db.default.increment")) {
@@ -863,6 +973,8 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 		}
 		const onUpdate = metadata.get("db.mysql.onUpdate");
 		if (onUpdate) this._onUpdateFields.set(field, onUpdate);
+		const charset = metadata.get("db.mysql.charset");
+		if (charset) this._charsetFields.set(field, require_annotation_values.mysqlName("@db.mysql.charset", charset));
 		const vectorMeta = metadata.get("db.search.vector");
 		if (vectorMeta) {
 			const indexName = vectorMeta.indexName || field;
@@ -876,6 +988,7 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 		}
 	}
 	getDesiredTableOptions() {
+		const collation = this._tableCollation();
 		return [
 			{
 				key: "engine",
@@ -885,10 +998,10 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 				key: "charset",
 				value: this._charset
 			},
-			{
+			...collation === void 0 ? [] : [{
 				key: "collation",
-				value: this._collation
-			}
+				value: collation
+			}]
 		];
 	}
 	async getExistingTableOptions(tableName) {
@@ -897,18 +1010,23 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
        WHERE TABLE_NAME = ? AND TABLE_SCHEMA = COALESCE(?, DATABASE())`, [tableName ?? this._table.tableName, this._schema]);
 		if (!row) return [];
 		const charset = row.TABLE_COLLATION?.split("_")[0] ?? "utf8mb4";
+		const desired = new Map(this.getDesiredTableOptions().map((o) => [o.key, o.value]));
+		const asDesired = (key, value) => {
+			const want = desired.get(key);
+			return want !== void 0 && want.toLowerCase() === value.toLowerCase() ? want : value;
+		};
 		return [
 			{
 				key: "engine",
-				value: row.ENGINE ?? "InnoDB"
+				value: asDesired("engine", row.ENGINE ?? "InnoDB")
 			},
 			{
 				key: "charset",
-				value: charset
+				value: asDesired("charset", charset)
 			},
 			{
 				key: "collation",
-				value: row.TABLE_COLLATION ?? "utf8mb4_unicode_ci"
+				value: asDesired("collation", row.TABLE_COLLATION ?? "utf8mb4_unicode_ci")
 			}
 		];
 	}
@@ -1633,15 +1751,64 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 		this._log(sql);
 		await this._exec().exec(sql);
 	}
+	/** The table's collation: `@db.mysql.collate`, else the charset's default one (`utf8mb4_unicode_ci` for `utf8mb4`). */
+	_tableCollation() {
+		return this._collation ?? mysqlDefaultCollation(this._charset);
+	}
+	/**
+	* Foreign-key column path → the referenced table's character set and
+	* collation, where they differ from this table's (see
+	* `mysqlColumnCharset`). Warns about a foreign-key column whose own
+	* `@db.mysql.charset` / collation is replaced by the referenced column's.
+	*/
+	_keyTableCharsets() {
+		return this._keyTableCharsetsMemo ??= this._buildKeyTableCharsets();
+	}
+	_buildKeyTableCharsets() {
+		const out = /* @__PURE__ */ new Map();
+		const own = `${this._charset}\0${this._tableCollation() ?? ""}`.toLowerCase();
+		for (const fk of this._table.foreignKeys.values()) {
+			const meta = fk.targetTypeRef?.()?.metadata;
+			const declaredCollation = meta?.get("db.mysql.collate");
+			const charset = meta?.get("db.mysql.charset") ?? declaredCollation?.split("_")[0] ?? "utf8mb4";
+			const collation = declaredCollation ?? mysqlDefaultCollation(charset);
+			if (`${charset}\0${collation ?? ""}`.toLowerCase() === own) continue;
+			for (const path of fk.fields) out.set(path, {
+				charset,
+				collation
+			});
+		}
+		for (const field of this._table.fieldDescriptors) {
+			const target = field.fkTargetField;
+			if (!target) continue;
+			const mine = declaredCharsetCollation(field);
+			if (mine.some(Boolean) && mine.join("\0") !== declaredCharsetCollation(target).join("\0")) this.logger.warn?.(`[mysql] "${this._table.tableName}.${field.path}": its own character set / collation is not used — a foreign-key column takes the referenced column's ("${target.path}"), as MySQL requires`);
+		}
+		return out;
+	}
+	/**
+	* The key-length prefix an index needs on `field`'s column: a function of
+	* its MAPPED type and its character set (`mysqlColumnCharset`, else the
+	* table's).
+	*/
+	_indexPrefix(field) {
+		const charset = mysqlColumnCharset(field, {
+			charsetFields: this._charsetFields,
+			keyTableCharsets: this._keyTableCharsets()
+		});
+		return mysqlIndexPrefix(this.typeMapper(field), mysqlBytesPerChar(charset ?? this._charset));
+	}
 	/** The CREATE TABLE options (engine/charset/collation/increment/ON UPDATE/type mapper). */
 	_tableOptions(opts) {
 		return {
 			engine: this._engine,
 			charset: this._charset,
-			collation: this._collation,
+			collation: this._tableCollation(),
 			autoIncrementStart: this._autoIncrementStart,
 			incrementFields: this._incrementFields,
 			onUpdateFields: this._onUpdateFields,
+			charsetFields: this._charsetFields,
+			keyTableCharsets: this._keyTableCharsets(),
 			typeMapper: (field) => this.typeMapper(field),
 			deferForeignKeysTo: opts?.deferForeignKeysTo
 		};
@@ -1651,6 +1818,8 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 		return {
 			incrementFields: this._incrementFields,
 			onUpdateFields: this._onUpdateFields,
+			charsetFields: this._charsetFields,
+			keyTableCharsets: this._keyTableCharsets(),
 			typeMapper: (field) => this.typeMapper(field),
 			purpose
 		};
@@ -1835,6 +2004,7 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 				return entering.has(field.physicalName);
 			};
 			const modified = /* @__PURE__ */ new Map();
+			const retyped = [];
 			for (const { field, existingType } of diff.typeChanged ?? []) {
 				const epoch = epochSource(field, existingType);
 				if (epoch) {
@@ -1852,6 +2022,7 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 					continue;
 				}
 				modified.set(field.physicalName, field);
+				retyped.push(field);
 			}
 			for (const { field } of diff.nullableChanged ?? []) {
 				if (rekeyed(field)) continue;
@@ -1865,17 +2036,285 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 				modified.set(field.physicalName, field);
 			}
 			for (const { field } of diff.defaultChanged ?? []) if (!rekeyed(field)) modified.set(field.physicalName, field);
-			for (const field of modified.values()) {
-				const ddl = `ALTER TABLE ${quotedTable} MODIFY COLUMN ${buildColumnDefinition(field, this._columnCtx("modify")).def}`;
-				this._log(ddl);
-				await conn.exec(ddl);
-			}
+			await this._dropIndexesOutgrown(conn, [...modified.values()]);
+			await this._withForeignKeysLifted(conn, retyped, async () => {
+				for (const field of modified.values()) {
+					const ddl = `ALTER TABLE ${quotedTable} MODIFY COLUMN ${buildColumnDefinition(field, this._columnCtx("modify")).def}`;
+					this._log(ddl);
+					await conn.exec(ddl);
+				}
+			});
 			return {
 				added,
 				renamed
 			};
 		});
 	}
+	/**
+	* Runs `fn` (the MODIFYs of `fields`) with the live foreign keys over those
+	* columns dropped — this table's own and those of any table referencing
+	* them, its own included — and re-creates them, as they were, after: also
+	* when `fn` throws. Nothing is dropped when a constraint could not be
+	* re-created over the new types (see {@link _liftable}): MySQL then refuses
+	* the MODIFY as it always did. A constraint that cannot be re-created is
+	* named, with its DDL, in the error (after `fn`'s own).
+	*/
+	async _withForeignKeysLifted(conn, fields, fn) {
+		if (fields.length === 0) return fn();
+		const found = await this._foreignKeysOver(conn, fields.map((f) => f.physicalName));
+		const lifted = found.length > 0 && await this._liftable(conn, found, fields) ? found : [];
+		const dropped = [];
+		let failure;
+		try {
+			for (const fk of lifted) {
+				const ddl = `ALTER TABLE ${fk.table} DROP FOREIGN KEY ${qi(fk.name)}`;
+				this._log(ddl);
+				await conn.exec(ddl);
+				dropped.push(fk);
+				this.logger.info(`[mysql] foreign key ${qi(fk.name)} on ${fk.table} dropped for the type change of ${quoteTableName(this.resolveTableName())}`);
+			}
+			await fn();
+		} catch (error) {
+			failure = error;
+		}
+		const lost = await this._restoreForeignKeys(conn, dropped);
+		if (lost.length > 0) {
+			const named = lost.map((fk) => `${qi(fk.name)} on ${fk.table} (re-create it with: ${addForeignKeysSql(fk.table, [fk])})`).join("; ");
+			const message = failure ? `${failure.message} — and foreign keys not restored: ${named}` : `Foreign keys not restored after the type change: ${named}`;
+			throw new Error(message, { cause: failure });
+		}
+		if (failure) throw failure;
+	}
+	/**
+	* Re-creates `fks` (dropped by {@link _withForeignKeysLifted}) — one
+	* `ALTER TABLE` per table, with `foreign_key_checks` off on this connection
+	* so MySQL adds them in place instead of rebuilding the table (the rows
+	* met them before the change). A table whose statement fails has its
+	* constraints re-tried one by one. Returns those that could not be
+	* re-created.
+	*/
+	async _restoreForeignKeys(conn, fks) {
+		if (fks.length === 0) return [];
+		const byTable = /* @__PURE__ */ new Map();
+		for (const fk of fks) {
+			const group = byTable.get(fk.table);
+			if (group) group.push(fk);
+			else byTable.set(fk.table, [fk]);
+		}
+		const add = async (table, group) => {
+			const ddl = addForeignKeysSql(table, group);
+			this._log(ddl);
+			try {
+				await conn.exec(ddl);
+			} catch (error) {
+				return error;
+			}
+			for (const fk of group) this.logger.info(`[mysql] foreign key ${qi(fk.name)} on ${fk.table} restored`);
+		};
+		const lost = [];
+		await conn.exec("SET @atscript_fk_checks = @@SESSION.foreign_key_checks, SESSION foreign_key_checks = 0");
+		try {
+			for (const [table, group] of byTable) {
+				const error = await add(table, group);
+				if (!error) continue;
+				for (const fk of group) {
+					const single = group.length === 1 ? error : await add(table, [fk]);
+					if (single) {
+						this.logger.error(`[mysql] foreign key ${qi(fk.name)} on ${table} could not be re-created: ${single.message}`);
+						lost.push(fk);
+					}
+				}
+			}
+		} finally {
+			await conn.exec("SET SESSION foreign_key_checks = @atscript_fk_checks");
+		}
+		return lost;
+	}
+	/**
+	* Whether every constraint of `fks` can be re-created once `fields` have
+	* their new types: each column pair of a constraint that the change touches
+	* stays compatible — the new type against the other side's live column (or
+	* its new type, on this table): integers of the same type and signedness,
+	* `CHAR` / `VARCHAR` either way with the same collation, anything else the
+	* same type. Otherwise nothing is lifted (and MySQL refuses the change, as
+	* it did before foreign keys were lifted) — a dropped constraint must
+	* never be lost to a column outside this run.
+	*/
+	async _liftable(conn, fks, fields) {
+		const changed = new Map(fields.map((f) => [f.physicalName, f]));
+		const columns = new Set(changed.keys());
+		const pairs = [];
+		for (const fk of fks) fk.columns.forEach((column, i) => {
+			const { child, parent } = touchedEnds(fk, i, columns);
+			if (!child && !parent) return;
+			pairs.push([{
+				schema: fk.schema,
+				table: fk.tableName,
+				column,
+				ours: child
+			}, {
+				schema: fk.refSchema,
+				table: fk.refTableName,
+				column: fk.refColumns[i],
+				ours: parent
+			}]);
+		});
+		const liveEnds = /* @__PURE__ */ new Map();
+		for (const end of pairs.flat()) if (!end.ours) liveEnds.set(columnKey(end), end);
+		const live = [...liveEnds.values()];
+		const liveRows = live.length === 0 ? [] : await conn.all(`SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, COLUMN_TYPE, COLLATION_NAME
+             FROM INFORMATION_SCHEMA.COLUMNS
+             WHERE ${live.map(() => "(TABLE_SCHEMA = ? AND TABLE_NAME = ? AND COLUMN_NAME = ?)").join(" OR ")}`, live.flatMap((end) => [
+			end.schema,
+			end.table,
+			end.column
+		]));
+		const liveOf = new Map(liveRows.map((r) => [columnKey({
+			schema: r.TABLE_SCHEMA,
+			table: r.TABLE_NAME,
+			column: r.COLUMN_NAME
+		}), {
+			type: r.COLUMN_TYPE,
+			collation: r.COLLATION_NAME ?? void 0
+		}]));
+		const collations = await this._newCollations(conn, [...new Set(pairs.flat().flatMap((end) => end.ours ? [changed.get(end.column)] : []).filter((field) => CHAR_TYPE_RE.test(this.typeMapper(field).trim())))]);
+		const typeOf = (end) => {
+			if (!end.ours) return liveOf.get(columnKey(end));
+			const field = changed.get(end.column);
+			return {
+				type: this.typeMapper(field),
+				collation: collations.get(field.physicalName)
+			};
+		};
+		for (const [child, parent] of pairs) {
+			const a = typeOf(child);
+			const b = typeOf(parent);
+			if (!a || !b || fkTypeKey(a) !== fkTypeKey(b)) {
+				this.logger.warn(`[mysql] ${qi(child.table)}.${qi(child.column)} → ${qi(parent.table)}.${qi(parent.column)} would not match after the type change (${a?.type ?? "?"} / ${b?.type ?? "?"}) — its foreign key stays in place, and MySQL decides on the change`);
+				return false;
+			}
+		}
+		return true;
+	}
+	/**
+	* The collation each of `fields` (string columns) has after its MODIFY:
+	* the definition's own `COLLATE`, else the default of its `CHARACTER SET`,
+	* else the table's.
+	*/
+	async _newCollations(conn, fields) {
+		const out = /* @__PURE__ */ new Map();
+		if (fields.length === 0) return out;
+		const ctx = this._columnCtx("modify");
+		const charsetDefaults = /* @__PURE__ */ new Map();
+		let tableCollation = null;
+		for (const field of fields) {
+			const { charsetClause, collateClause } = mysqlColumnCharsetClauses(field, this.typeMapper(field), ctx);
+			const collate = /COLLATE\s+`?(\w+)`?/i.exec(collateClause)?.[1];
+			const charset = /CHARACTER SET\s+`?(\w+)`?/i.exec(charsetClause)?.[1];
+			if (collate) out.set(field.physicalName, collate);
+			else if (charset) {
+				if (!charsetDefaults.has(charset)) {
+					const row = await conn.get(`SELECT COLLATION_NAME FROM INFORMATION_SCHEMA.COLLATIONS
+             WHERE CHARACTER_SET_NAME = ? AND IS_DEFAULT = 'Yes'`, [charset]);
+					charsetDefaults.set(charset, row?.COLLATION_NAME);
+				}
+				out.set(field.physicalName, charsetDefaults.get(charset));
+			} else {
+				if (tableCollation === null) tableCollation = (await conn.get(`SELECT TABLE_COLLATION FROM INFORMATION_SCHEMA.TABLES
+             WHERE TABLE_NAME = ? AND TABLE_SCHEMA = COALESCE(?, DATABASE())`, [this._table.tableName, this._schema]))?.TABLE_COLLATION ?? void 0;
+				out.set(field.physicalName, tableCollation);
+			}
+		}
+		return out;
+	}
+	/**
+	* The live foreign keys over any of `columns` of this table: its own (by
+	* their columns) and those referencing them (by the referenced columns),
+	* each with every column, in key order.
+	*/
+	async _foreignKeysOver(conn, columns) {
+		const target = [this._schema, this._table.tableName];
+		const rows = await conn.all(`SELECT k.TABLE_SCHEMA, k.TABLE_NAME, k.CONSTRAINT_NAME, k.COLUMN_NAME,
+              k.REFERENCED_TABLE_SCHEMA, k.REFERENCED_TABLE_NAME, k.REFERENCED_COLUMN_NAME,
+              r.UPDATE_RULE, r.DELETE_RULE,
+              (k.TABLE_SCHEMA = COALESCE(?, DATABASE()) AND k.TABLE_NAME = ?) AS IS_OWN,
+              (k.REFERENCED_TABLE_SCHEMA = COALESCE(?, DATABASE()) AND k.REFERENCED_TABLE_NAME = ?) AS IS_REF
+       FROM INFORMATION_SCHEMA.KEY_COLUMN_USAGE k
+       JOIN INFORMATION_SCHEMA.REFERENTIAL_CONSTRAINTS r
+         ON r.CONSTRAINT_SCHEMA = k.CONSTRAINT_SCHEMA AND r.CONSTRAINT_NAME = k.CONSTRAINT_NAME
+        AND r.TABLE_NAME = k.TABLE_NAME
+       WHERE k.REFERENCED_TABLE_NAME IS NOT NULL
+         AND ((k.TABLE_SCHEMA = COALESCE(?, DATABASE()) AND k.TABLE_NAME = ?)
+          OR (k.REFERENCED_TABLE_SCHEMA = COALESCE(?, DATABASE()) AND k.REFERENCED_TABLE_NAME = ?))
+       ORDER BY k.TABLE_SCHEMA, k.TABLE_NAME, k.CONSTRAINT_NAME, k.ORDINAL_POSITION`, [
+			...target,
+			...target,
+			...target,
+			...target
+		]);
+		const byConstraint = /* @__PURE__ */ new Map();
+		for (const r of rows) {
+			const key = `${r.TABLE_SCHEMA}\0${r.TABLE_NAME}\0${r.CONSTRAINT_NAME}`;
+			let fk = byConstraint.get(key);
+			if (!fk) {
+				fk = {
+					schema: r.TABLE_SCHEMA,
+					tableName: r.TABLE_NAME,
+					table: `${qi(r.TABLE_SCHEMA)}.${qi(r.TABLE_NAME)}`,
+					name: r.CONSTRAINT_NAME,
+					columns: [],
+					refSchema: r.REFERENCED_TABLE_SCHEMA,
+					refTableName: r.REFERENCED_TABLE_NAME,
+					refTable: `${qi(r.REFERENCED_TABLE_SCHEMA)}.${qi(r.REFERENCED_TABLE_NAME)}`,
+					refColumns: [],
+					onDelete: r.DELETE_RULE,
+					onUpdate: r.UPDATE_RULE,
+					own: Boolean(Number(r.IS_OWN)),
+					ref: Boolean(Number(r.IS_REF))
+				};
+				byConstraint.set(key, fk);
+			}
+			fk.columns.push(r.COLUMN_NAME);
+			fk.refColumns.push(r.REFERENCED_COLUMN_NAME);
+		}
+		const over = new Set(columns);
+		return [...byConstraint.values()].filter((fk) => fk.columns.some((_, i) => {
+			const { child, parent } = touchedEnds(fk, i, over);
+			return child || parent;
+		}));
+	}
+	/**
+	* Before `fields` are modified: drops the managed indexes that key more of
+	* a column than its new type allows — a full key on a column becoming
+	* TEXT (ER 1170), or on a VARCHAR growing past the key-part limit (ER
+	* 1071). Index sync re-creates them with the prefix the new type needs.
+	* Primary keys, FULLTEXT and unmanaged indexes are left alone.
+	*/
+	async _dropIndexesOutgrown(conn, fields) {
+		const limits = /* @__PURE__ */ new Map();
+		for (const field of fields) {
+			const prefix = this._indexPrefix(field);
+			if (prefix !== void 0) limits.set(field.physicalName, prefix);
+		}
+		if (limits.size === 0) return;
+		const columns = [...limits.keys()];
+		const rows = await conn.all(`SELECT INDEX_NAME, COLUMN_NAME, SUB_PART, INDEX_TYPE FROM INFORMATION_SCHEMA.STATISTICS
+       WHERE TABLE_NAME = ? AND TABLE_SCHEMA = COALESCE(?, DATABASE())
+         AND COLUMN_NAME IN (${columns.map(() => "?").join(", ")})`, [
+			this._table.tableName,
+			this._schema,
+			...columns
+		]);
+		const outgrown = /* @__PURE__ */ new Set();
+		for (const r of rows) if (r.INDEX_TYPE !== "FULLTEXT" && r.INDEX_NAME.startsWith("atscript__") && (r.SUB_PART === null || r.SUB_PART > limits.get(r.COLUMN_NAME))) outgrown.add(r.INDEX_NAME);
+		for (const name of outgrown) await this._dropIndex(name, conn);
+	}
+	/** `DROP INDEX name` on this table (logged). */
+	async _dropIndex(name, conn = this._exec()) {
+		const ddl = `DROP INDEX ${qi(name)} ON ${quoteTableName(this.resolveTableName())}`;
+		this._log(ddl);
+		await conn.exec(ddl);
+	}
 	async recreateTable() {
 		const tableName = this.resolveTableName();
 		const tempName = `${this._table.tableName}__tmp_${Date.now()}`;
@@ -1950,11 +2389,7 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 			this._schema,
 			...columns
 		]);
-		for (const row of rows) {
-			const sql = `DROP INDEX ${qi(row.name)} ON ${quoteTableName(this.resolveTableName())}`;
-			this._log(sql);
-			await this._exec().exec(sql);
-		}
+		for (const row of rows) await this._dropIndex(row.name);
 	}
 	async dropTableByName(tableName) {
 		const ddl = `DROP TABLE IF EXISTS ${quoteTableName(tableName)}`;
@@ -1980,13 +2415,17 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 		this._log(ddl);
 		await this._exec().exec(ddl);
 	}
+	/** Keeps the space: {@link typeMapper} asks it which fields a foreign key references. */
+	registerSpace(space) {
+		this._space = space;
+	}
 	typeMapper(field) {
 		if (field.encrypted) return "TEXT";
 		if (this._vectorFields.has(field.path)) {
 			const vec = this._vectorFields.get(field.path);
 			return this._supportsVector ? `VECTOR(${vec.dimensions})` : "JSON";
 		}
-		return mysqlTypeFromField(field);
+		return mysqlTypeFromField(field, !field.fkTargetField && this._space !== void 0 && this._table !== void 0 && this._space.getReferencedFields(this._table.tableName, this._table.schema).has(field.path));
 	}
 	async _syncIndexes(dryRun) {
 		const tableName = this._table.tableName;
@@ -1994,15 +2433,14 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 		if (!dryRun) {
 			for (const index of this._table.indexes.values()) if (index.type === "fulltext" && index.language !== void 0) this.logger.warn(`[mysql] fulltext index "${index.name}": @db.index.fulltext.language "${index.language}" is ignored — MySQL FULLTEXT has no per-index language`);
 		}
-		const bytesPerChar = mysqlBytesPerChar(this._charset);
 		const fields = new Map(this._table.fieldDescriptors.map((f) => [f.physicalName, f]));
 		const mappedType = (column) => {
 			const field = fields.get(column);
 			return field ? this.typeMapper(field) : void 0;
 		};
 		const desiredPrefix = (column) => {
-			const type = mappedType(column);
-			return type === void 0 ? void 0 : mysqlIndexPrefix(type, bytesPerChar);
+			const field = fields.get(column);
+			return field && this._indexPrefix(field);
 		};
 		const renderPart = (column, prefix) => prefix === void 0 ? column : `${column}(${prefix})`;
 		return this.syncIndexesWithDiff({
@@ -2054,11 +2492,7 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 				this._log(sql);
 				await this._exec().exec(sql);
 			},
-			dropIndex: async (name) => {
-				const sql = `DROP INDEX ${qi(name)} ON ${quoteTableName(this.resolveTableName())}`;
-				this._log(sql);
-				await this._exec().exec(sql);
-			}
+			dropIndex: (name) => this._dropIndex(name)
 		});
 	}
 	async syncForeignKeys() {
@@ -2069,10 +2503,11 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 		return this._syncForeignKeys(true);
 	}
 	_syncForeignKeys(dryRun) {
+		let existing;
 		return this.syncForeignKeysWithDiff({
 			dryRun,
-			listExisting: () => this._getExistingFkConstraints(),
-			dropConstraint: (name) => this._dropFkConstraint(name),
+			listExisting: async () => existing = await this._getExistingFkConstraints(),
+			dropConstraint: (name) => this._dropFkConstraint(name, existing.get(name)),
 			addConstraint: async (fk) => {
 				const ddl = `ALTER TABLE ${quoteTableName(this.resolveTableName())} ADD ${(0, _atscript_db_sql_tools.foreignKeySql)(qi, fk)}`;
 				this._log(ddl);
@@ -2083,19 +2518,40 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 	async dropForeignKeys(fkFieldKeys) {
 		if (fkFieldKeys.length === 0) return;
 		const keySet = new Set(fkFieldKeys);
-		for (const [constraintName, cols] of await this._getExistingFkConstraints()) if (keySet.has((0, _atscript_db.fkKey)(cols))) await this._dropFkConstraint(constraintName);
+		for (const [constraintName, cols] of await this._getExistingFkConstraints()) if (keySet.has((0, _atscript_db.fkKey)(cols))) await this._dropFkConstraint(constraintName, cols);
 	}
-	async _dropFkConstraint(name) {
+	/**
+	* Drops a foreign-key constraint over `columns` (in key order), then the
+	* index InnoDB created for it: an unnamed constraint gets an index named
+	* after its first column, which outlives the constraint — and would block
+	* that column from becoming TEXT once it no longer references anything
+	* (ER 1170). An index another constraint still needs is kept (ER 1553).
+	*/
+	async _dropFkConstraint(name, columns) {
 		const ddl = `ALTER TABLE ${quoteTableName(this.resolveTableName())} DROP FOREIGN KEY ${qi(name)}`;
 		this._log(ddl);
 		await this._exec().exec(ddl);
+		if (columns.length === 0) return;
+		if ((await this._exec().all(`SELECT COLUMN_NAME FROM INFORMATION_SCHEMA.STATISTICS
+         WHERE TABLE_NAME = ? AND TABLE_SCHEMA = COALESCE(?, DATABASE()) AND INDEX_NAME = ?
+         ORDER BY SEQ_IN_INDEX`, [
+			this._table.tableName,
+			this._schema,
+			columns[0]
+		])).map((r) => r.COLUMN_NAME).join("\0") !== columns.join("\0")) return;
+		try {
+			await this._dropIndex(columns[0]);
+		} catch (error) {
+			if (error.errno !== 1553) throw error;
+		}
 	}
 	/** Queries INFORMATION_SCHEMA for existing FK constraints, grouped by constraint name → column names. */
 	async _getExistingFkConstraints() {
 		const rows = await this._exec().all(`SELECT kcu.CONSTRAINT_NAME, kcu.COLUMN_NAME
        FROM INFORMATION_SCHEMA.KEY_COLUMN_USAGE kcu
        WHERE kcu.TABLE_NAME = ? AND kcu.TABLE_SCHEMA = COALESCE(?, DATABASE())
-         AND kcu.REFERENCED_TABLE_NAME IS NOT NULL`, [this._table.tableName, this._schema]);
+         AND kcu.REFERENCED_TABLE_NAME IS NOT NULL
+       ORDER BY kcu.CONSTRAINT_NAME, kcu.ORDINAL_POSITION`, [this._table.tableName, this._schema]);
 		const byName = /* @__PURE__ */ new Map();
 		for (const row of rows) {
 			let cols = byName.get(row.CONSTRAINT_NAME);