@atscript/db-mysql 0.1.153 → 0.1.155

package/dist/index.cjs

@@ -183,6 +183,15 @@ const mysqlDialect = {
 	calendarBucket: mysqlCalendarBucket,
 	bucketAliasInHaving: true,
 	jsonExtract: mysqlJsonExtract,
+	jsonExtractText: (quotedCol, path) => {
+		const e = `JSON_EXTRACT(${quotedCol}, ${(0, _atscript_db_sql_tools.jsonDollarPath)(path)})`;
+		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)})`;
+		return `CASE WHEN JSON_TYPE(${e}) = 'NULL' THEN NULL ELSE ${e} END`;
+	},
+	jsonFromText: (quotedCol) => `IF(JSON_VALID(${quotedCol}), ${quotedCol}, JSON_QUOTE(${quotedCol}))`,
 	castDouble: (expr) => `CAST(${expr} AS DOUBLE)`,
 	createViewPrefix: "CREATE OR REPLACE VIEW"
 };
@@ -569,6 +578,20 @@ function epochMsToUtcDatetime(ms, fsp = 0) {
 */
 const TZ_PROBE_SQL = "SELECT CONVERT_TZ('2040-06-01 12:00:00', '+00:00', ?) IS NULL AS missing, TIMESTAMPDIFF(MINUTE, '2040-06-01 12:00:00', CONVERT_TZ('2040-06-01 12:00:00', '+00:00', '+01:00')) AS shift";
 const isZero = (v) => v === 0 || v === "0";
+/** A live numeric column type (`INFORMATION_SCHEMA.COLUMNS.COLUMN_TYPE`). */
+const NUMERIC_SQL_TYPE = /^(double|float|real|decimal|numeric|bigint|int|integer|mediumint|smallint|tinyint)\b/i;
+/** A live text column type — e.g. the column atscript-db <= 0.1.154 created for a `T | null` union. */
+const TEXT_SQL_TYPE = /^(tinytext|text|mediumtext|longtext|varchar|char)\b/i;
+/**
+* Whether the type change of `field` from the live `existingType` converts
+* epoch ms to a native TIMESTAMP / DATETIME (through a temp column, see
+* `_migrateEpochColumnToTemporal`); `fromText`: the live column is text.
+*/
+function epochSource(field, existingType) {
+	if (!isMysqlTimestampColumn(field)) return void 0;
+	const fromText = TEXT_SQL_TYPE.test(existingType);
+	return fromText || NUMERIC_SQL_TYPE.test(existingType) ? { fromText } : void 0;
+}
 /** Drivers whose session `sql_mode` was already checked for strictness (see `_warnNonStrictMode`). */
 const nonStrictChecked = /* @__PURE__ */ new WeakSet();
 /**
@@ -602,6 +625,18 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 	_collation = "utf8mb4_unicode_ci";
 	_autoIncrementStart;
 	_incrementFields = /* @__PURE__ */ new Set();
+	/**
+	* Changes of columns leaving a pending primary key that `syncColumns` left
+	* to the next `rebuildPrimaryKey` (re-declared in its swap statement).
+	*/
+	_leavingKeyColumns = /* @__PURE__ */ new Map();
+	/**
+	* Columns leaving a pending primary key that also convert from epoch ms to
+	* TIMESTAMP / DATETIME: the temp-column conversion drops the column, which
+	* a key column cannot be — the next `rebuildPrimaryKey` converts them
+	* after its swap.
+	*/
+	_epochAfterRekey = /* @__PURE__ */ new Map();
 	_onUpdateFields = /* @__PURE__ */ new Map();
 	/** Whether the connected MySQL instance supports native VECTOR type (MySQL 9.0+). */
 	_supportsVector;
@@ -1520,12 +1555,22 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 			purpose
 		};
 	}
+	/** The quoted table `tableName` of the adapter's schema, or the adapter's own. */
+	_quotedTable(tableName) {
+		return quoteTableName(tableName ? this._schema ? `${this._schema}.${tableName}` : tableName : this.resolveTableName());
+	}
 	async hasRows(tableName) {
-		const sql = `SELECT EXISTS(SELECT 1 FROM ${tableName ? quoteTableName(this._schema ? `${this._schema}.${tableName}` : tableName) : quoteTableName(this.resolveTableName())}) AS present`;
+		const sql = `SELECT EXISTS(SELECT 1 FROM ${this._quotedTable(tableName)}) AS present`;
 		this._log(sql);
 		const row = await this._exec().get(sql, []);
 		return Boolean(Number(row?.present ?? 0));
 	}
+	async countKeyViolations(columns, tableName) {
+		const sql = (0, _atscript_db_sql_tools.buildKeyViolationCount)(mysqlDialect, this._quotedTable(tableName), columns);
+		this._log(sql);
+		const row = await this._exec().get(sql, []);
+		return Number(row?.violations ?? 0);
+	}
 	/** Live foreign keys referencing `tableName` (any table of the schema). */
 	async getReferencingForeignKeys(tableName) {
 		const rows = await this._exec().all(`SELECT TABLE_NAME, CONSTRAINT_NAME, COLUMN_NAME, REFERENCED_COLUMN_NAME
@@ -1564,7 +1609,8 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 	* NOT NULL) together with the key swap — so an AUTO_INCREMENT column never
 	* exists without a key (ER 1075), in safe mode or otherwise. A demoted key
 	* column loses AUTO_INCREMENT in the same statement (pre-flight guarantees
-	* its model no longer declares increment). Called on an empty table only.
+	* its model no longer declares increment). Called on an empty table or one
+	* whose rows satisfy the new key (`countKeyViolations`).
 	*/
 	async rebuildPrimaryKey(change) {
 		const fields = new Map(this._table.fieldDescriptors.map((f) => [f.physicalName, f]));
@@ -1575,6 +1621,9 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 			if (field) clauses.push(`MODIFY COLUMN ${buildColumnDefinition(field, this._columnCtx("modify")).def}`);
 		}
 		if (change.from.length > 0) {
+			const leaving = this._leavingKeyColumns;
+			this._leavingKeyColumns = /* @__PURE__ */ new Map();
+			for (const field of leaving.values()) if (!to.has(field.physicalName) && !this._epochAfterRekey.has(field.physicalName)) clauses.push(`MODIFY COLUMN ${buildColumnDefinition(field, this._columnCtx("modify")).def}`);
 			const placeholders = change.from.map(() => "?").join(", ");
 			const live = await this._exec().all(`SELECT COLUMN_NAME, COLUMN_TYPE, EXTRA FROM INFORMATION_SCHEMA.COLUMNS
          WHERE TABLE_NAME = ? AND TABLE_SCHEMA = COALESCE(?, DATABASE())
@@ -1584,7 +1633,7 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 				...change.from
 			]);
 			for (const col of live) {
-				if (to.has(col.COLUMN_NAME) || !/auto_increment/i.test(col.EXTRA ?? "")) continue;
+				if (to.has(col.COLUMN_NAME) || leaving.has(col.COLUMN_NAME) || !/auto_increment/i.test(col.EXTRA ?? "")) continue;
 				const field = fields.get(col.COLUMN_NAME);
 				const def = field ? buildColumnDefinition(field, this._columnCtx("modify")).def : `${qi(col.COLUMN_NAME)} ${col.COLUMN_TYPE.toUpperCase()} NOT NULL`;
 				clauses.push(`MODIFY COLUMN ${def}`);
@@ -1592,10 +1641,18 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 			clauses.push("DROP PRIMARY KEY");
 		}
 		if (change.to.length > 0) clauses.push(`ADD PRIMARY KEY (${change.to.map((c) => qi(c)).join(", ")})`);
-		if (clauses.length === 0) return;
-		const ddl = `ALTER TABLE ${quoteTableName(this.resolveTableName())} ${clauses.join(", ")}`;
-		this._log(ddl);
-		await this._withStrictSession((conn) => conn.exec(ddl));
+		const epochAfter = this._epochAfterRekey;
+		this._epochAfterRekey = /* @__PURE__ */ new Map();
+		if (clauses.length === 0 && epochAfter.size === 0) return;
+		const tableName = this.resolveTableName();
+		const ddl = `ALTER TABLE ${quoteTableName(tableName)} ${clauses.join(", ")}`;
+		await this._withStrictSession(async (conn) => {
+			if (clauses.length > 0) {
+				this._log(ddl);
+				await conn.exec(ddl);
+			}
+			for (const { field, fromText } of epochAfter.values()) await this._migrateEpochColumnToTemporal(conn, tableName, field, this.typeMapper(field), fromText);
+		});
 	}
 	async _ensureView() {
 		const view = this._table;
@@ -1635,6 +1692,13 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 			const tableName = this.resolveTableName();
 			const added = [];
 			const renamed = [];
+			const keyChange = diff.primaryKeyChanged;
+			const entering = new Set(keyChange?.to ?? []);
+			const leaving = new Set(keyChange?.from.filter((c) => !entering.has(c)) ?? []);
+			for (const { field, existingType } of diff.typeChanged ?? []) {
+				const name = field.physicalName;
+				if ((keyChange ? keyChange.from.includes(name) && entering.has(name) : field.isPrimaryKey) && epochSource(field, existingType) !== void 0) throw new Error(`Cannot convert primary-key column "${name}" from epoch milliseconds to ${this.typeMapper(field)} — migrate it manually.`);
+			}
 			for (const { field, oldName } of diff.renamed ?? []) {
 				const ddl = `ALTER TABLE ${quoteTableName(tableName)} RENAME COLUMN ${qi(oldName)} TO ${qi(field.physicalName)}`;
 				this._log(ddl);
@@ -1654,10 +1718,27 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 				}
 				added.push(field.physicalName);
 			}
-			const enteringKey = new Set(diff.primaryKeyChanged?.to ?? []);
+			this._leavingKeyColumns = /* @__PURE__ */ new Map();
+			this._epochAfterRekey = /* @__PURE__ */ new Map();
+			const rekeyed = (field) => {
+				if (leaving.has(field.physicalName)) {
+					this._leavingKeyColumns.set(field.physicalName, field);
+					return true;
+				}
+				return entering.has(field.physicalName);
+			};
 			const modified = /* @__PURE__ */ new Map();
-			for (const { field } of diff.typeChanged ?? []) {
-				if (enteringKey.has(field.physicalName)) continue;
+			for (const { field, existingType } of diff.typeChanged ?? []) {
+				const epoch = epochSource(field, existingType);
+				if (epoch) {
+					if (leaving.has(field.physicalName)) this._epochAfterRekey.set(field.physicalName, {
+						field,
+						fromText: epoch.fromText
+					});
+					else await this._migrateEpochColumnToTemporal(conn, tableName, field, this.typeMapper(field), epoch.fromText);
+					continue;
+				}
+				if (rekeyed(field)) continue;
 				const sqlType = this.typeMapper(field);
 				if (field.isGeoPoint && !field.encrypted && sqlType.startsWith("POINT")) {
 					await this._migrateJsonColumnToPoint(conn, tableName, field);
@@ -1666,7 +1747,7 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 				modified.set(field.physicalName, field);
 			}
 			for (const { field } of diff.nullableChanged ?? []) {
-				if (enteringKey.has(field.physicalName)) continue;
+				if (rekeyed(field)) continue;
 				if (!field.optional) {
 					const sqlType = this.typeMapper(field);
 					const fallback = field.defaultValue?.kind === "value" ? mysqlDefaultLiteral(sqlType, field.designType, field.defaultValue.value) : mysqlTypeDefault(sqlType, field);
@@ -1676,7 +1757,7 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 				}
 				modified.set(field.physicalName, field);
 			}
-			for (const { field } of diff.defaultChanged ?? []) if (!enteringKey.has(field.physicalName)) 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);
@@ -1732,6 +1813,20 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 	async dropTable() {
 		return this.dropTableByName(this.resolveTableName());
 	}
+	async copyFromJsonColumn(source, targets) {
+		const temporal = targets.find((t) => mysqlTemporalFsp(t.field) !== void 0);
+		if (temporal) throw new Error(`"${temporal.column}" is a TIMESTAMP / DATETIME column — its epoch-ms JSON values cannot be copied into it`);
+		const sql = (0, _atscript_db_sql_tools.buildJsonColumnCopy)(mysqlDialect, this.resolveTableName(), source, targets);
+		await this._withStrictSession(async (conn) => {
+			this._log(sql);
+			await conn.exec(sql);
+		});
+	}
+	async jsonifyTextColumn(column) {
+		const sql = (0, _atscript_db_sql_tools.buildJsonifyText)(mysqlDialect, this.resolveTableName(), column);
+		this._log(sql);
+		await this._exec().exec(sql);
+	}
 	async dropColumns(columns) {
 		const tableName = this.resolveTableName();
 		const drops = columns.map((col) => `DROP COLUMN ${qi(col)}`).join(", ");
@@ -2162,6 +2257,41 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 		return (0, _atscript_db_sql_tools.buildGeoSearchSelect)(mysqlDialect, ctx.tableName, ctx.where, ctx.dist, ctx.window, ctx.controls);
 	}
 	/**
+	* Migrates an epoch-ms number column to a native `TIMESTAMP` / `DATETIME`
+	* via a temp column: each value becomes the UTC wall time the adapter would
+	* write for it (`formatValue`), truncated to the column's precision. A value
+	* the type cannot hold (before 1970 / after 2038 for `TIMESTAMP`) — or a
+	* column the drop is refused for (an index it would leave with duplicates,
+	* a foreign key) — fails the sync with the original column untouched (the
+	* temp column is dropped again). The column keeps its position. It must
+	* not be keyed (dropping it would shrink the key): `syncColumns` refuses a
+	* column keyed before and after, and defers one leaving the key to
+	* `rebuildPrimaryKey`. In a text column (`fromText`) only a numeric value is
+	* epoch ms; other text is read as a datetime, as a plain `MODIFY` would.
+	*/
+	async _migrateEpochColumnToTemporal(conn, tableName, field, sqlType, fromText = false) {
+		const col = qi(field.physicalName);
+		const tmp = qi(`${field.physicalName}__ts_mig`);
+		const quotedTable = quoteTableName(tableName);
+		const digits = Math.min(mysqlTemporalFsp(field) ?? 0, 3);
+		const epoch = `DATE_ADD(CAST('1970-01-01 00:00:00' AS DATETIME(6)), INTERVAL ${`FLOOR(${col} / ${10 ** (3 - digits)}) * ${10 ** (6 - digits)}`} MICROSECOND)`;
+		const value = fromText ? `CASE WHEN ${col} REGEXP '^[0-9]+([.][0-9]+)?$' THEN ${epoch} ELSE CAST(${col} AS DATETIME(6)) END` : epoch;
+		const run = async (ddl) => {
+			this._log(ddl);
+			await conn.exec(ddl);
+		};
+		await run(`ALTER TABLE ${quotedTable} ADD COLUMN ${tmp} ${sqlType} NULL AFTER ${col}`);
+		try {
+			await run(`UPDATE ${quotedTable} SET ${tmp} = ${value} WHERE ${col} IS NOT NULL`);
+			await run(`ALTER TABLE ${quotedTable} DROP COLUMN ${col}`);
+		} catch (error) {
+			await run(`ALTER TABLE ${quotedTable} DROP COLUMN ${tmp}`).catch(() => void 0);
+			throw error;
+		}
+		await run(`ALTER TABLE ${quotedTable} RENAME COLUMN ${tmp} TO ${col}`);
+		await run(`ALTER TABLE ${quotedTable} MODIFY COLUMN ${buildColumnDefinition(field, this._columnCtx("modify")).def}`);
+	}
+	/**
 	* Migrates a v1 JSON `[lng, lat]` column to native `POINT SRID 4326` via a
 	* temp column (MySQL has no JSON→geometry cast for MODIFY COLUMN).
 	*/
@@ -2228,8 +2358,14 @@ function sanitizeParams(params) {
 *
 * - TIMESTAMP/DATETIME → epoch milliseconds (number) instead of Date objects
 * - DECIMAL/NEWDECIMAL → number instead of string
+* - JSON → its text (since 0.1.155), as MariaDB's `LONGTEXT` JSON and SQLite
+*   return it: the relational mapper parses JSON text, so a JSON string value
+*   is not mistaken for JSON text. Done here as well as with `jsonStrings`:
+*   mysql2 caches compiled row parsers per process without keying them by
+*   `jsonStrings`, so another pool's parser could otherwise be reused.
 */
 function atscriptTypeCast(field, next) {
+	if (field.type === "JSON") return field.string("utf8");
 	if (field.type === "TIMESTAMP" || field.type === "DATETIME") {
 		const str = field.string();
 		if (str === null) return null;
@@ -2312,6 +2448,7 @@ var Mysql2Driver = class {
 				timezone: "+00:00",
 				supportBigNumbers: true,
 				bigNumberStrings: false,
+				jsonStrings: true,
 				typeCast: atscriptTypeCast
 			});
 			else this.pool = mysql.createPool({
@@ -2319,6 +2456,7 @@ var Mysql2Driver = class {
 				timezone: "+00:00",
 				supportBigNumbers: true,
 				bigNumberStrings: false,
+				jsonStrings: true,
 				typeCast: atscriptTypeCast
 			});
 			if (strict) ensureStrict(this.pool);

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, TPrimaryKeyChange, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TTableOptionDiff, TValueFormatterPair, TViewCapability } from "@atscript/db";
+import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDefaultFn, TDbDeleteResult, TDbFieldMeta, TDbInsertIgnoreOptions, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateOptions, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TExistingTableOption, TFieldOps, TJsonCopyTarget, TPrimaryKeyChange, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TTableOptionDiff, TValueFormatterPair, TViewCapability } from "@atscript/db";
 import { TMetadataMap } from "@atscript/typescript/utils";
 import { FilterExpr as FilterExpr$1 } from "@uniqu/core";
 import { TFilterVisitorOptions, TSqlFragment, TSqlFragment as TSqlFragment$1 } from "@atscript/db-sql-tools";
@@ -112,6 +112,18 @@ declare class MysqlAdapter extends BaseDbAdapter {
   private _collation;
   private _autoIncrementStart?;
   private _incrementFields;
+  /**
+   * Changes of columns leaving a pending primary key that `syncColumns` left
+   * to the next `rebuildPrimaryKey` (re-declared in its swap statement).
+   */
+  private _leavingKeyColumns;
+  /**
+   * Columns leaving a pending primary key that also convert from epoch ms to
+   * TIMESTAMP / DATETIME: the temp-column conversion drops the column, which
+   * a key column cannot be — the next `rebuildPrimaryKey` converts them
+   * after its swap.
+   */
+  private _epochAfterRekey;
   private _onUpdateFields;
   /** Whether the connected MySQL instance supports native VECTOR type (MySQL 9.0+). */
   private _supportsVector;
@@ -386,7 +398,10 @@ declare class MysqlAdapter extends BaseDbAdapter {
   private _tableOptions;
   /** The shared column-definition context for ADD/MODIFY statements. */
   private _columnCtx;
+  /** The quoted table `tableName` of the adapter's schema, or the adapter's own. */
+  private _quotedTable;
   hasRows(tableName?: string): Promise<boolean>;
+  countKeyViolations(columns: readonly string[], tableName?: string): Promise<number>;
   /** Live foreign keys referencing `tableName` (any table of the schema). */
   getReferencingForeignKeys(tableName: string): Promise<TReferencingForeignKey[]>;
   getObjectKind(name: string): Promise<TDbObjectKind | undefined>;
@@ -399,7 +414,8 @@ declare class MysqlAdapter extends BaseDbAdapter {
    * NOT NULL) together with the key swap — so an AUTO_INCREMENT column never
    * exists without a key (ER 1075), in safe mode or otherwise. A demoted key
    * column loses AUTO_INCREMENT in the same statement (pre-flight guarantees
-   * its model no longer declares increment). Called on an empty table only.
+   * its model no longer declares increment). Called on an empty table or one
+   * whose rows satisfy the new key (`countKeyViolations`).
    */
   rebuildPrimaryKey(change: TPrimaryKeyChange): Promise<void>;
   private _ensureView;
@@ -410,6 +426,8 @@ declare class MysqlAdapter extends BaseDbAdapter {
   syncColumns(diff: TColumnDiff): Promise<TSyncColumnResult>;
   recreateTable(): Promise<void>;
   dropTable(): Promise<void>;
+  copyFromJsonColumn(source: string, targets: readonly TJsonCopyTarget[]): Promise<void>;
+  jsonifyTextColumn(column: string): Promise<void>;
   dropColumns(columns: string[]): Promise<void>;
   dropIndexesForColumns(columns: string[]): Promise<void>;
   dropTableByName(tableName: string): Promise<void>;
@@ -467,6 +485,20 @@ declare class MysqlAdapter extends BaseDbAdapter {
   /** Resolves the shared parts of a geo search once (column, filter, distance, window). */
   private _prepareGeoSearch;
   private _buildGeoSearchSelect;
+  /**
+   * Migrates an epoch-ms number column to a native `TIMESTAMP` / `DATETIME`
+   * via a temp column: each value becomes the UTC wall time the adapter would
+   * write for it (`formatValue`), truncated to the column's precision. A value
+   * the type cannot hold (before 1970 / after 2038 for `TIMESTAMP`) — or a
+   * column the drop is refused for (an index it would leave with duplicates,
+   * a foreign key) — fails the sync with the original column untouched (the
+   * temp column is dropped again). The column keeps its position. It must
+   * not be keyed (dropping it would shrink the key): `syncColumns` refuses a
+   * column keyed before and after, and defers one leaving the key to
+   * `rebuildPrimaryKey`. In a text column (`fromText`) only a numeric value is
+   * epoch ms; other text is read as a datetime, as a plain `MODIFY` would.
+   */
+  private _migrateEpochColumnToTemporal;
   /**
    * Migrates a v1 JSON `[lng, lat]` column to native `POINT SRID 4326` via a
    * temp column (MySQL has no JSON→geometry cast for MODIFY COLUMN).

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, TPrimaryKeyChange, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TTableOptionDiff, TValueFormatterPair, TViewCapability } from "@atscript/db";
+import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDefaultFn, TDbDeleteResult, TDbFieldMeta, TDbInsertIgnoreOptions, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateOptions, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TExistingTableOption, TFieldOps, TJsonCopyTarget, TPrimaryKeyChange, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TTableOptionDiff, TValueFormatterPair, TViewCapability } from "@atscript/db";
 import { TFilterVisitorOptions, TSqlFragment, TSqlFragment as TSqlFragment$1 } from "@atscript/db-sql-tools";
 import { FilterExpr as FilterExpr$1 } from "@uniqu/core";
 import { TMetadataMap } from "@atscript/typescript/utils";
@@ -112,6 +112,18 @@ declare class MysqlAdapter extends BaseDbAdapter {
   private _collation;
   private _autoIncrementStart?;
   private _incrementFields;
+  /**
+   * Changes of columns leaving a pending primary key that `syncColumns` left
+   * to the next `rebuildPrimaryKey` (re-declared in its swap statement).
+   */
+  private _leavingKeyColumns;
+  /**
+   * Columns leaving a pending primary key that also convert from epoch ms to
+   * TIMESTAMP / DATETIME: the temp-column conversion drops the column, which
+   * a key column cannot be — the next `rebuildPrimaryKey` converts them
+   * after its swap.
+   */
+  private _epochAfterRekey;
   private _onUpdateFields;
   /** Whether the connected MySQL instance supports native VECTOR type (MySQL 9.0+). */
   private _supportsVector;
@@ -386,7 +398,10 @@ declare class MysqlAdapter extends BaseDbAdapter {
   private _tableOptions;
   /** The shared column-definition context for ADD/MODIFY statements. */
   private _columnCtx;
+  /** The quoted table `tableName` of the adapter's schema, or the adapter's own. */
+  private _quotedTable;
   hasRows(tableName?: string): Promise<boolean>;
+  countKeyViolations(columns: readonly string[], tableName?: string): Promise<number>;
   /** Live foreign keys referencing `tableName` (any table of the schema). */
   getReferencingForeignKeys(tableName: string): Promise<TReferencingForeignKey[]>;
   getObjectKind(name: string): Promise<TDbObjectKind | undefined>;
@@ -399,7 +414,8 @@ declare class MysqlAdapter extends BaseDbAdapter {
    * NOT NULL) together with the key swap — so an AUTO_INCREMENT column never
    * exists without a key (ER 1075), in safe mode or otherwise. A demoted key
    * column loses AUTO_INCREMENT in the same statement (pre-flight guarantees
-   * its model no longer declares increment). Called on an empty table only.
+   * its model no longer declares increment). Called on an empty table or one
+   * whose rows satisfy the new key (`countKeyViolations`).
    */
   rebuildPrimaryKey(change: TPrimaryKeyChange): Promise<void>;
   private _ensureView;
@@ -410,6 +426,8 @@ declare class MysqlAdapter extends BaseDbAdapter {
   syncColumns(diff: TColumnDiff): Promise<TSyncColumnResult>;
   recreateTable(): Promise<void>;
   dropTable(): Promise<void>;
+  copyFromJsonColumn(source: string, targets: readonly TJsonCopyTarget[]): Promise<void>;
+  jsonifyTextColumn(column: string): Promise<void>;
   dropColumns(columns: string[]): Promise<void>;
   dropIndexesForColumns(columns: string[]): Promise<void>;
   dropTableByName(tableName: string): Promise<void>;
@@ -467,6 +485,20 @@ declare class MysqlAdapter extends BaseDbAdapter {
   /** Resolves the shared parts of a geo search once (column, filter, distance, window). */
   private _prepareGeoSearch;
   private _buildGeoSearchSelect;
+  /**
+   * Migrates an epoch-ms number column to a native `TIMESTAMP` / `DATETIME`
+   * via a temp column: each value becomes the UTC wall time the adapter would
+   * write for it (`formatValue`), truncated to the column's precision. A value
+   * the type cannot hold (before 1970 / after 2038 for `TIMESTAMP`) — or a
+   * column the drop is refused for (an index it would leave with duplicates,
+   * a foreign key) — fails the sync with the original column untouched (the
+   * temp column is dropped again). The column keeps its position. It must
+   * not be keyed (dropping it would shrink the key): `syncColumns` refuses a
+   * column keyed before and after, and defers one leaving the key to
+   * `rebuildPrimaryKey`. In a text column (`fromText`) only a numeric value is
+   * epoch ms; other text is read as a datetime, as a plain `MODIFY` would.
+   */
+  private _migrateEpochColumnToTemporal;
   /**
    * Migrates a v1 JSON `[lng, lat]` column to native `POINT SRID 4326` via a
    * temp column (MySQL has no JSON→geometry cast for MODIFY COLUMN).

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_VIEW_CAPABILITIES, BaseDbAdapter, DbError, DbSpace, NoopLogger, bucketTimeZoneUnavailable, containsRelationFilter, defaultFulltextIndex, describeFulltext, fkColumns, forEachResolvedRelation, isConflict, searchTermInteger, splitFulltextFields, uniqueKeyTuple, vectorIndexNotFoundMessage } from "@atscript/db";
 import { resolveAggregateSearch } from "@atscript/db/agg";
-import { EMPTY_OR, SEARCH_SOURCE_ALIAS, arithOverflowError, buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildPartitionedSelect, buildSelect, buildUpdate, buildVectorSearchCount, buildVectorSearchSelect, buildWhere as buildWhere$1, chunkInsertRows, defaultValueForType, defaultValueToSqlLiteral, derivedColumnExpr, fillReplacePayload, foreignKeySql, 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, parseRegexString, renameGeoDistance, replaceColumnsFor, sqlTimeZoneLiteral, stripPartitionRowNumber, toSqlValue, vectorDistanceSource, viewReadSource } from "@atscript/db-sql-tools";
 import { BUCKET_MAX_INSTANT, BUCKET_MIN_INSTANT } from "@uniqu/core";
 //#region src/sql-builder.ts
 /** TEXT / BLOB families (`TINYTEXT` … `LONGBLOB`). */
@@ -182,6 +182,15 @@ const mysqlDialect = {
 	calendarBucket: mysqlCalendarBucket,
 	bucketAliasInHaving: true,
 	jsonExtract: mysqlJsonExtract,
+	jsonExtractText: (quotedCol, path) => {
+		const e = `JSON_EXTRACT(${quotedCol}, ${jsonDollarPath(path)})`;
+		return `CASE WHEN JSON_TYPE(${e}) = 'NULL' THEN NULL ELSE JSON_UNQUOTE(${e}) END`;
+	},
+	jsonExtractValue: (quotedCol, path) => {
+		const e = `JSON_EXTRACT(${quotedCol}, ${jsonDollarPath(path)})`;
+		return `CASE WHEN JSON_TYPE(${e}) = 'NULL' THEN NULL ELSE ${e} END`;
+	},
+	jsonFromText: (quotedCol) => `IF(JSON_VALID(${quotedCol}), ${quotedCol}, JSON_QUOTE(${quotedCol}))`,
 	castDouble: (expr) => `CAST(${expr} AS DOUBLE)`,
 	createViewPrefix: "CREATE OR REPLACE VIEW"
 };
@@ -568,6 +577,20 @@ function epochMsToUtcDatetime(ms, fsp = 0) {
 */
 const TZ_PROBE_SQL = "SELECT CONVERT_TZ('2040-06-01 12:00:00', '+00:00', ?) IS NULL AS missing, TIMESTAMPDIFF(MINUTE, '2040-06-01 12:00:00', CONVERT_TZ('2040-06-01 12:00:00', '+00:00', '+01:00')) AS shift";
 const isZero = (v) => v === 0 || v === "0";
+/** A live numeric column type (`INFORMATION_SCHEMA.COLUMNS.COLUMN_TYPE`). */
+const NUMERIC_SQL_TYPE = /^(double|float|real|decimal|numeric|bigint|int|integer|mediumint|smallint|tinyint)\b/i;
+/** A live text column type — e.g. the column atscript-db <= 0.1.154 created for a `T | null` union. */
+const TEXT_SQL_TYPE = /^(tinytext|text|mediumtext|longtext|varchar|char)\b/i;
+/**
+* Whether the type change of `field` from the live `existingType` converts
+* epoch ms to a native TIMESTAMP / DATETIME (through a temp column, see
+* `_migrateEpochColumnToTemporal`); `fromText`: the live column is text.
+*/
+function epochSource(field, existingType) {
+	if (!isMysqlTimestampColumn(field)) return void 0;
+	const fromText = TEXT_SQL_TYPE.test(existingType);
+	return fromText || NUMERIC_SQL_TYPE.test(existingType) ? { fromText } : void 0;
+}
 /** Drivers whose session `sql_mode` was already checked for strictness (see `_warnNonStrictMode`). */
 const nonStrictChecked = /* @__PURE__ */ new WeakSet();
 /**
@@ -601,6 +624,18 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 	_collation = "utf8mb4_unicode_ci";
 	_autoIncrementStart;
 	_incrementFields = /* @__PURE__ */ new Set();
+	/**
+	* Changes of columns leaving a pending primary key that `syncColumns` left
+	* to the next `rebuildPrimaryKey` (re-declared in its swap statement).
+	*/
+	_leavingKeyColumns = /* @__PURE__ */ new Map();
+	/**
+	* Columns leaving a pending primary key that also convert from epoch ms to
+	* TIMESTAMP / DATETIME: the temp-column conversion drops the column, which
+	* a key column cannot be — the next `rebuildPrimaryKey` converts them
+	* after its swap.
+	*/
+	_epochAfterRekey = /* @__PURE__ */ new Map();
 	_onUpdateFields = /* @__PURE__ */ new Map();
 	/** Whether the connected MySQL instance supports native VECTOR type (MySQL 9.0+). */
 	_supportsVector;
@@ -1519,12 +1554,22 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 			purpose
 		};
 	}
+	/** The quoted table `tableName` of the adapter's schema, or the adapter's own. */
+	_quotedTable(tableName) {
+		return quoteTableName(tableName ? this._schema ? `${this._schema}.${tableName}` : tableName : this.resolveTableName());
+	}
 	async hasRows(tableName) {
-		const sql = `SELECT EXISTS(SELECT 1 FROM ${tableName ? quoteTableName(this._schema ? `${this._schema}.${tableName}` : tableName) : quoteTableName(this.resolveTableName())}) AS present`;
+		const sql = `SELECT EXISTS(SELECT 1 FROM ${this._quotedTable(tableName)}) AS present`;
 		this._log(sql);
 		const row = await this._exec().get(sql, []);
 		return Boolean(Number(row?.present ?? 0));
 	}
+	async countKeyViolations(columns, tableName) {
+		const sql = buildKeyViolationCount(mysqlDialect, this._quotedTable(tableName), columns);
+		this._log(sql);
+		const row = await this._exec().get(sql, []);
+		return Number(row?.violations ?? 0);
+	}
 	/** Live foreign keys referencing `tableName` (any table of the schema). */
 	async getReferencingForeignKeys(tableName) {
 		const rows = await this._exec().all(`SELECT TABLE_NAME, CONSTRAINT_NAME, COLUMN_NAME, REFERENCED_COLUMN_NAME
@@ -1563,7 +1608,8 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 	* NOT NULL) together with the key swap — so an AUTO_INCREMENT column never
 	* exists without a key (ER 1075), in safe mode or otherwise. A demoted key
 	* column loses AUTO_INCREMENT in the same statement (pre-flight guarantees
-	* its model no longer declares increment). Called on an empty table only.
+	* its model no longer declares increment). Called on an empty table or one
+	* whose rows satisfy the new key (`countKeyViolations`).
 	*/
 	async rebuildPrimaryKey(change) {
 		const fields = new Map(this._table.fieldDescriptors.map((f) => [f.physicalName, f]));
@@ -1574,6 +1620,9 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 			if (field) clauses.push(`MODIFY COLUMN ${buildColumnDefinition(field, this._columnCtx("modify")).def}`);
 		}
 		if (change.from.length > 0) {
+			const leaving = this._leavingKeyColumns;
+			this._leavingKeyColumns = /* @__PURE__ */ new Map();
+			for (const field of leaving.values()) if (!to.has(field.physicalName) && !this._epochAfterRekey.has(field.physicalName)) clauses.push(`MODIFY COLUMN ${buildColumnDefinition(field, this._columnCtx("modify")).def}`);
 			const placeholders = change.from.map(() => "?").join(", ");
 			const live = await this._exec().all(`SELECT COLUMN_NAME, COLUMN_TYPE, EXTRA FROM INFORMATION_SCHEMA.COLUMNS
          WHERE TABLE_NAME = ? AND TABLE_SCHEMA = COALESCE(?, DATABASE())
@@ -1583,7 +1632,7 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 				...change.from
 			]);
 			for (const col of live) {
-				if (to.has(col.COLUMN_NAME) || !/auto_increment/i.test(col.EXTRA ?? "")) continue;
+				if (to.has(col.COLUMN_NAME) || leaving.has(col.COLUMN_NAME) || !/auto_increment/i.test(col.EXTRA ?? "")) continue;
 				const field = fields.get(col.COLUMN_NAME);
 				const def = field ? buildColumnDefinition(field, this._columnCtx("modify")).def : `${qi(col.COLUMN_NAME)} ${col.COLUMN_TYPE.toUpperCase()} NOT NULL`;
 				clauses.push(`MODIFY COLUMN ${def}`);
@@ -1591,10 +1640,18 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 			clauses.push("DROP PRIMARY KEY");
 		}
 		if (change.to.length > 0) clauses.push(`ADD PRIMARY KEY (${change.to.map((c) => qi(c)).join(", ")})`);
-		if (clauses.length === 0) return;
-		const ddl = `ALTER TABLE ${quoteTableName(this.resolveTableName())} ${clauses.join(", ")}`;
-		this._log(ddl);
-		await this._withStrictSession((conn) => conn.exec(ddl));
+		const epochAfter = this._epochAfterRekey;
+		this._epochAfterRekey = /* @__PURE__ */ new Map();
+		if (clauses.length === 0 && epochAfter.size === 0) return;
+		const tableName = this.resolveTableName();
+		const ddl = `ALTER TABLE ${quoteTableName(tableName)} ${clauses.join(", ")}`;
+		await this._withStrictSession(async (conn) => {
+			if (clauses.length > 0) {
+				this._log(ddl);
+				await conn.exec(ddl);
+			}
+			for (const { field, fromText } of epochAfter.values()) await this._migrateEpochColumnToTemporal(conn, tableName, field, this.typeMapper(field), fromText);
+		});
 	}
 	async _ensureView() {
 		const view = this._table;
@@ -1634,6 +1691,13 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 			const tableName = this.resolveTableName();
 			const added = [];
 			const renamed = [];
+			const keyChange = diff.primaryKeyChanged;
+			const entering = new Set(keyChange?.to ?? []);
+			const leaving = new Set(keyChange?.from.filter((c) => !entering.has(c)) ?? []);
+			for (const { field, existingType } of diff.typeChanged ?? []) {
+				const name = field.physicalName;
+				if ((keyChange ? keyChange.from.includes(name) && entering.has(name) : field.isPrimaryKey) && epochSource(field, existingType) !== void 0) throw new Error(`Cannot convert primary-key column "${name}" from epoch milliseconds to ${this.typeMapper(field)} — migrate it manually.`);
+			}
 			for (const { field, oldName } of diff.renamed ?? []) {
 				const ddl = `ALTER TABLE ${quoteTableName(tableName)} RENAME COLUMN ${qi(oldName)} TO ${qi(field.physicalName)}`;
 				this._log(ddl);
@@ -1653,10 +1717,27 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 				}
 				added.push(field.physicalName);
 			}
-			const enteringKey = new Set(diff.primaryKeyChanged?.to ?? []);
+			this._leavingKeyColumns = /* @__PURE__ */ new Map();
+			this._epochAfterRekey = /* @__PURE__ */ new Map();
+			const rekeyed = (field) => {
+				if (leaving.has(field.physicalName)) {
+					this._leavingKeyColumns.set(field.physicalName, field);
+					return true;
+				}
+				return entering.has(field.physicalName);
+			};
 			const modified = /* @__PURE__ */ new Map();
-			for (const { field } of diff.typeChanged ?? []) {
-				if (enteringKey.has(field.physicalName)) continue;
+			for (const { field, existingType } of diff.typeChanged ?? []) {
+				const epoch = epochSource(field, existingType);
+				if (epoch) {
+					if (leaving.has(field.physicalName)) this._epochAfterRekey.set(field.physicalName, {
+						field,
+						fromText: epoch.fromText
+					});
+					else await this._migrateEpochColumnToTemporal(conn, tableName, field, this.typeMapper(field), epoch.fromText);
+					continue;
+				}
+				if (rekeyed(field)) continue;
 				const sqlType = this.typeMapper(field);
 				if (field.isGeoPoint && !field.encrypted && sqlType.startsWith("POINT")) {
 					await this._migrateJsonColumnToPoint(conn, tableName, field);
@@ -1665,7 +1746,7 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 				modified.set(field.physicalName, field);
 			}
 			for (const { field } of diff.nullableChanged ?? []) {
-				if (enteringKey.has(field.physicalName)) continue;
+				if (rekeyed(field)) continue;
 				if (!field.optional) {
 					const sqlType = this.typeMapper(field);
 					const fallback = field.defaultValue?.kind === "value" ? mysqlDefaultLiteral(sqlType, field.designType, field.defaultValue.value) : mysqlTypeDefault(sqlType, field);
@@ -1675,7 +1756,7 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 				}
 				modified.set(field.physicalName, field);
 			}
-			for (const { field } of diff.defaultChanged ?? []) if (!enteringKey.has(field.physicalName)) 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);
@@ -1731,6 +1812,20 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 	async dropTable() {
 		return this.dropTableByName(this.resolveTableName());
 	}
+	async copyFromJsonColumn(source, targets) {
+		const temporal = targets.find((t) => mysqlTemporalFsp(t.field) !== void 0);
+		if (temporal) throw new Error(`"${temporal.column}" is a TIMESTAMP / DATETIME column — its epoch-ms JSON values cannot be copied into it`);
+		const sql = buildJsonColumnCopy(mysqlDialect, this.resolveTableName(), source, targets);
+		await this._withStrictSession(async (conn) => {
+			this._log(sql);
+			await conn.exec(sql);
+		});
+	}
+	async jsonifyTextColumn(column) {
+		const sql = buildJsonifyText(mysqlDialect, this.resolveTableName(), column);
+		this._log(sql);
+		await this._exec().exec(sql);
+	}
 	async dropColumns(columns) {
 		const tableName = this.resolveTableName();
 		const drops = columns.map((col) => `DROP COLUMN ${qi(col)}`).join(", ");
@@ -2161,6 +2256,41 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 		return buildGeoSearchSelect(mysqlDialect, ctx.tableName, ctx.where, ctx.dist, ctx.window, ctx.controls);
 	}
 	/**
+	* Migrates an epoch-ms number column to a native `TIMESTAMP` / `DATETIME`
+	* via a temp column: each value becomes the UTC wall time the adapter would
+	* write for it (`formatValue`), truncated to the column's precision. A value
+	* the type cannot hold (before 1970 / after 2038 for `TIMESTAMP`) — or a
+	* column the drop is refused for (an index it would leave with duplicates,
+	* a foreign key) — fails the sync with the original column untouched (the
+	* temp column is dropped again). The column keeps its position. It must
+	* not be keyed (dropping it would shrink the key): `syncColumns` refuses a
+	* column keyed before and after, and defers one leaving the key to
+	* `rebuildPrimaryKey`. In a text column (`fromText`) only a numeric value is
+	* epoch ms; other text is read as a datetime, as a plain `MODIFY` would.
+	*/
+	async _migrateEpochColumnToTemporal(conn, tableName, field, sqlType, fromText = false) {
+		const col = qi(field.physicalName);
+		const tmp = qi(`${field.physicalName}__ts_mig`);
+		const quotedTable = quoteTableName(tableName);
+		const digits = Math.min(mysqlTemporalFsp(field) ?? 0, 3);
+		const epoch = `DATE_ADD(CAST('1970-01-01 00:00:00' AS DATETIME(6)), INTERVAL ${`FLOOR(${col} / ${10 ** (3 - digits)}) * ${10 ** (6 - digits)}`} MICROSECOND)`;
+		const value = fromText ? `CASE WHEN ${col} REGEXP '^[0-9]+([.][0-9]+)?$' THEN ${epoch} ELSE CAST(${col} AS DATETIME(6)) END` : epoch;
+		const run = async (ddl) => {
+			this._log(ddl);
+			await conn.exec(ddl);
+		};
+		await run(`ALTER TABLE ${quotedTable} ADD COLUMN ${tmp} ${sqlType} NULL AFTER ${col}`);
+		try {
+			await run(`UPDATE ${quotedTable} SET ${tmp} = ${value} WHERE ${col} IS NOT NULL`);
+			await run(`ALTER TABLE ${quotedTable} DROP COLUMN ${col}`);
+		} catch (error) {
+			await run(`ALTER TABLE ${quotedTable} DROP COLUMN ${tmp}`).catch(() => void 0);
+			throw error;
+		}
+		await run(`ALTER TABLE ${quotedTable} RENAME COLUMN ${tmp} TO ${col}`);
+		await run(`ALTER TABLE ${quotedTable} MODIFY COLUMN ${buildColumnDefinition(field, this._columnCtx("modify")).def}`);
+	}
+	/**
 	* Migrates a v1 JSON `[lng, lat]` column to native `POINT SRID 4326` via a
 	* temp column (MySQL has no JSON→geometry cast for MODIFY COLUMN).
 	*/
@@ -2227,8 +2357,14 @@ function sanitizeParams(params) {
 *
 * - TIMESTAMP/DATETIME → epoch milliseconds (number) instead of Date objects
 * - DECIMAL/NEWDECIMAL → number instead of string
+* - JSON → its text (since 0.1.155), as MariaDB's `LONGTEXT` JSON and SQLite
+*   return it: the relational mapper parses JSON text, so a JSON string value
+*   is not mistaken for JSON text. Done here as well as with `jsonStrings`:
+*   mysql2 caches compiled row parsers per process without keying them by
+*   `jsonStrings`, so another pool's parser could otherwise be reused.
 */
 function atscriptTypeCast(field, next) {
+	if (field.type === "JSON") return field.string("utf8");
 	if (field.type === "TIMESTAMP" || field.type === "DATETIME") {
 		const str = field.string();
 		if (str === null) return null;
@@ -2311,6 +2447,7 @@ var Mysql2Driver = class {
 				timezone: "+00:00",
 				supportBigNumbers: true,
 				bigNumberStrings: false,
+				jsonStrings: true,
 				typeCast: atscriptTypeCast
 			});
 			else this.pool = mysql.createPool({
@@ -2318,6 +2455,7 @@ var Mysql2Driver = class {
 				timezone: "+00:00",
 				supportBigNumbers: true,
 				bigNumberStrings: false,
+				jsonStrings: true,
 				typeCast: atscriptTypeCast
 			});
 			if (strict) ensureStrict(this.pool);

package/package.json

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