@atscript/db-mysql 0.1.131 → 0.1.132

package/dist/index.cjs

@@ -2,6 +2,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let _atscript_db = require("@atscript/db");
 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
 /** TEXT / BLOB families (`TINYTEXT` … `LONGBLOB`). */
 const TEXT_BLOB_RE = /^(TINY|MEDIUM|LONG)?(TEXT|BLOB)\b/i;
@@ -165,9 +166,74 @@ const mysqlDialect = {
 			params: [...dist.params, circle.radius]
 		};
 	},
+	calendarBucket: mysqlCalendarBucket,
+	bucketAliasInHaving: true,
 	createViewPrefix: "CREATE OR REPLACE VIEW"
 };
 /**
+* Whether a field is stored as a native MySQL `TIMESTAMP`: a `number` with
+* `@db.default.now`. The adapter writes such values as UTC
+* `'YYYY-MM-DD HH:MM:SS'` strings and reads them back as epoch ms; every other
+* numeric timestamp is a DOUBLE / BIGINT epoch-ms column.
+*/
+function isMysqlTimestampColumn(fd) {
+	return fd.designType === "number" && fd.defaultValue?.kind === "fn" && fd.defaultValue.fn === "now";
+}
+/** `'1970-01-01 00:00:00'` as a DATETIME: the base for epoch arithmetic free of the session zone. */
+const MYSQL_EPOCH = "CAST('1970-01-01 00:00:00' AS DATETIME)";
+/**
+* Calendar-bucket label: TEXT `'YYYY-MM-DD'` — the local date of the
+* bucket's first day in `b.tz` — or NULL for a NULL source or one outside
+* `[BUCKET_MIN_INSTANT, BUCKET_MAX_INSTANT)`.
+*
+* The source's UTC wall time `U` (a DATETIME) depends on storage:
+* - DOUBLE / BIGINT epoch ms: `epoch + INTERVAL FLOOR(col / 1000) SECOND`
+*   (never `FROM_UNIXTIME`, which converts to the session zone);
+* - native `TIMESTAMP` ({@link isMysqlTimestampColumn}): `CAST(col AS DATETIME)`
+*   — the session-zone rendering, which is exactly the UTC string the adapter
+*   wrote and parses back on read, so the label agrees with the value reads
+*   return whatever the server's session zone is (`UNIX_TIMESTAMP(col)` would
+*   agree only under a UTC session zone).
+*
+* The local date is `DATE(CONVERT_TZ(U, '+00:00', '<tz>'))`, or `DATE(U)` for
+* `UTC` (no time zone tables needed). Truncation is calendar arithmetic on
+* that date. `CONVERT_TZ` returns NULL when the zone is unknown to the
+* server and its input unchanged outside its range — `MysqlAdapter` probes
+* each zone before running the query (`BUCKET_TZ_UNAVAILABLE`).
+*
+* Parameter-free (the zone is an inlined, charset-checked literal), so the
+* SELECT and GROUP BY renderings are identical (`ONLY_FULL_GROUP_BY`).
+*/
+function mysqlCalendarBucket(quotedCol, b) {
+	let utc;
+	let inRange;
+	if (isMysqlTimestampColumn(b.fd)) {
+		utc = `CAST(${quotedCol} AS DATETIME)`;
+		inRange = `${utc} >= '1970-01-02 00:00:00'`;
+	} else {
+		utc = `(${MYSQL_EPOCH} + INTERVAL FLOOR(${quotedCol} / 1000) SECOND)`;
+		inRange = `${quotedCol} >= ${_uniqu_core.BUCKET_MIN_INSTANT} AND ${quotedCol} < ${_uniqu_core.BUCKET_MAX_INSTANT}`;
+	}
+	const local = b.tz === "UTC" ? `DATE(${utc})` : `DATE(CONVERT_TZ(${utc}, '+00:00', ${(0, _atscript_db_sql_tools.sqlTimeZoneLiteral)(b.tz)}))`;
+	let first;
+	switch (b.unit) {
+		case "day":
+			first = local;
+			break;
+		case "week":
+			first = `DATE_SUB(${local}, INTERVAL ((WEEKDAY(${local}) + 1 - ${b.weekStartIso} + 7) % 7) DAY)`;
+			break;
+		case "month":
+			first = `DATE_SUB(${local}, INTERVAL DAYOFMONTH(${local}) - 1 DAY)`;
+			break;
+		case "quarter":
+			first = `(MAKEDATE(YEAR(${local}), 1) + INTERVAL (QUARTER(${local}) - 1) QUARTER)`;
+			break;
+		default: first = `MAKEDATE(YEAR(${local}), 1)`;
+	}
+	return `CASE WHEN ${inRange} THEN DATE_FORMAT(${first}, '%Y-%m-%d') END`;
+}
+/**
 * Spherical distance in meters from a POINT column to a query point.
 * Used as the `distExpr` of the shared geo search builder.
 */
@@ -210,6 +276,10 @@ function mysqlGeoValueToPoint(value) {
 function buildInsert(table, data) {
 	return (0, _atscript_db_sql_tools.buildInsert)(mysqlDialect, table, data);
 }
+/** Multi-row INSERT over `columns` (a missing column → `DEFAULT`). */
+function buildInsertMany(table, rows, columns) {
+	return (0, _atscript_db_sql_tools.buildInsertMany)(mysqlDialect, table, rows, columns);
+}
 /**
 * Builds a SELECT statement with optional sort, limit, offset, projection.
 */
@@ -291,7 +361,7 @@ function mysqlTypeFromField(field) {
 		case "number":
 			if (precision) return `DECIMAL(${precision.precision},${precision.scale})`;
 			if (field.defaultValue?.kind === "fn" && field.defaultValue.fn === "increment") return unsigned ? "BIGINT UNSIGNED" : "BIGINT";
-			if (field.defaultValue?.kind === "fn" && field.defaultValue.fn === "now") return "TIMESTAMP";
+			if (isMysqlTimestampColumn(field)) return "TIMESTAMP";
 			if (tags?.has("int")) return intTypeFromTags(tags, unsigned);
 			return "DOUBLE";
 		case "integer": return intTypeFromTags(tags, unsigned);
@@ -385,6 +455,25 @@ function epochMsToUtcDatetime(ms) {
 	return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, "0")}-${String(d.getUTCDate()).padStart(2, "0")} ${String(d.getUTCHours()).padStart(2, "0")}:${String(d.getUTCMinutes()).padStart(2, "0")}:${String(d.getUTCSeconds()).padStart(2, "0")}`;
 }
 /**
+* One statement answers both questions `CONVERT_TZ` never raises an error
+* for: `missing` — the named zone (bound as `?`) converts to NULL, i.e. the
+* time zone tables are not loaded or lack it; `shift` — a fixed `+01:00`
+* conversion after 2038 is not applied (0 instead of 60 minutes), i.e. the
+* server's `CONVERT_TZ` range ends in 2038 (before 8.0.28, or 32-bit).
+*
+* The range half deliberately uses a fixed offset, not the named zone: MySQL
+* tz tables hold no transitions after 2037, so a zone such as `Europe/London`
+* legitimately converts to +00:00 in June 2040 on a current server — an
+* "unchanged" named-zone result is not evidence of a limited range.
+*/
+const TZ_PROBE_SQL = "SELECT CONVERT_TZ('2040-06-01 12:00:00', '+00:00', ?) IS NULL AS missing, TIMESTAMPDIFF(MINUTE, '2040-06-01 12:00:00', CONVERT_TZ('2040-06-01 12:00:00', '+00:00', '+01:00')) AS shift";
+/**
+* Zones `CONVERT_TZ` is known to handle, per driver (adapters are per table
+* and share a driver). Positives only: a failed zone is probed again, so
+* loading the time zone tables fixes a running server without a restart.
+*/
+const convertibleZones = /* @__PURE__ */ new WeakMap();
+/**
 * MySQL adapter for {@link AtscriptDbTable}.
 *
 * Accepts any {@link TMysqlDriver} implementation — the actual MySQL driver
@@ -481,6 +570,13 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 	nativeDefaultFns() {
 		return MysqlAdapter.NATIVE_DEFAULT_FNS;
 	}
+	/**
+	* Every unit: `mysqlCalendarBucket` renders them all; named zones need the
+	* server's time zone tables (probed per zone in `aggregate()`).
+	*/
+	calendarBucketUnits() {
+		return _atscript_db.ALL_BUCKET_UNITS;
+	}
 	onBeforeFlatten(_type) {
 		const meta = _type.metadata;
 		const engine = meta.get("db.mysql.engine");
@@ -573,7 +669,7 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 	* converts epoch ms to a UTC datetime string for the wire protocol.
 	*/
 	formatValue(field) {
-		if (field.designType === "number" && field.defaultValue?.kind === "fn" && field.defaultValue.fn === "now") return {
+		if (isMysqlTimestampColumn(field)) return {
 			toStorage: (value) => typeof value === "number" ? epochMsToUtcDatetime(value) : value,
 			fromStorage: utcDatetimeToEpochMs
 		};
@@ -636,26 +732,16 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 		};
 		return this.withTransaction(async () => {
 			const tableName = this.resolveTableName();
-			const keys = Object.keys(data[0]);
-			const colsClause = keys.map((k) => qi(k)).join(", ");
-			const paramsPerRow = keys.length;
-			const maxRowsPerBatch = paramsPerRow > 0 ? Math.floor(6e4 / paramsPerRow) : data.length;
+			const columns = (0, _atscript_db_sql_tools.insertManyColumns)(data);
+			const maxRowsPerBatch = columns.length > 0 ? Math.floor(6e4 / columns.length) : data.length;
 			const allIds = [];
-			const rowPlaceholderClause = `(${keys.map(() => "?").join(", ")})`;
 			for (let offset = 0; offset < data.length; offset += maxRowsPerBatch) {
-				const batchEnd = Math.min(offset + maxRowsPerBatch, data.length);
-				const batchSize = batchEnd - offset;
-				const params = [];
-				for (let i = offset; i < batchEnd; i++) {
-					const row = data[i];
-					for (const k of keys) params.push(mysqlDialect.toValue(row[k]));
-				}
-				const valuesClause = Array(batchSize).fill(rowPlaceholderClause).join(", ");
-				const sql = `INSERT INTO ${quoteTableName(tableName)} (${colsClause}) VALUES ${valuesClause}`;
+				const batch = data.slice(offset, offset + maxRowsPerBatch);
+				const { sql, params } = buildInsertMany(tableName, batch, columns);
 				this._log(sql, params);
 				const result = await this._wrapConstraintError(() => this._exec().run(sql, params));
 				const firstId = Number(result.insertId);
-				for (let i = 0; i < batchSize; i++) allIds.push(this._resolveInsertedId(data[offset + i], firstId > 0 ? firstId + i : 0));
+				for (let i = 0; i < batch.length; i++) allIds.push(this._resolveInsertedId(batch[i], firstId > 0 ? firstId + i : 0));
 			}
 			return {
 				insertedCount: allIds.length,
@@ -689,6 +775,7 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 		const search = (0, _atscript_db_agg.resolveAggregateSearch)(query.controls);
 		const where = search ? this._buildSearchWhere(search.text, query, search.indexName) : buildWhere(query.filter);
 		const tableName = this.resolveTableName();
+		for (const bucket of query.controls.$select?.buckets ?? []) await this._ensureBucketZone(bucket.tz);
 		if (query.controls.$count) {
 			const { sql, params } = buildAggregateCount(tableName, where, query.controls);
 			this._log(sql, params);
@@ -698,6 +785,30 @@ var MysqlAdapter = class MysqlAdapter extends _atscript_db.BaseDbAdapter {
 		this._log(sql, params);
 		return this._exec().all(sql, params);
 	}
+	/**
+	* Verifies that `CONVERT_TZ` can convert to a calendar bucket's zone before
+	* any bucket SQL runs — MySQL never fails loudly here: it returns NULL when
+	* the time zone tables are not loaded (or lack the zone) and its input
+	* unchanged outside its supported range (before 8.0.28 that range ends in
+	* 2038). One probe ({@link TZ_PROBE_SQL}) detects both and raises
+	* `BUCKET_TZ_UNAVAILABLE` with the fix. `UTC` needs no probe — its
+	* expression skips `CONVERT_TZ`. Successes are cached per driver.
+	*/
+	async _ensureBucketZone(tz) {
+		if (tz === "UTC" || convertibleZones.get(this.driver)?.has(tz)) return;
+		this._log(TZ_PROBE_SQL, [tz]);
+		const row = await this._exec().get(TZ_PROBE_SQL, [tz]);
+		let problem;
+		if (!row || Number(row.missing) !== 0) problem = "its time zone tables are not loaded or lack this zone — load them with mysql_tzinfo_to_sql";
+		else if (Number(row.shift) !== 60) problem = "its CONVERT_TZ does not convert instants after 2038 — MySQL 8.0.28 or later (64-bit) is required";
+		if (problem) throw (0, _atscript_db.bucketTimeZoneUnavailable)(`MySQL cannot convert to time zone "${tz}": ${problem}`);
+		let zones = convertibleZones.get(this.driver);
+		if (!zones) {
+			zones = /* @__PURE__ */ new Set();
+			convertibleZones.set(this.driver, zones);
+		}
+		zones.add(tz);
+	}
 	async updateOne(filter, data, ops, expectedVersion) {
 		const where = buildWhere(filter);
 		const versionColumn = this._table.versionColumn;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { BaseDbAdapter, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDefaultFn, TDbDeleteResult, TDbFieldMeta, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TExistingTableOption, TFieldOps, TPrimaryKeyChange, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TTableOptionDiff, TValueFormatterPair } from "@atscript/db";
+import { BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDefaultFn, TDbDeleteResult, TDbFieldMeta, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TExistingTableOption, TFieldOps, TPrimaryKeyChange, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TTableOptionDiff, TValueFormatterPair } from "@atscript/db";
 import { TMetadataMap } from "@atscript/typescript/utils";
 import { FilterExpr as FilterExpr$1 } from "@uniqu/core";
 import { TSqlFragment, TSqlFragment as TSqlFragment$1 } from "@atscript/db-sql-tools";
@@ -132,6 +132,11 @@ declare class MysqlAdapter extends BaseDbAdapter {
   prepareId(id: unknown, _fieldType: unknown): unknown;
   supportsNativeValueDefaults(): boolean;
   nativeDefaultFns(): ReadonlySet<TDbDefaultFn>;
+  /**
+   * Every unit: `mysqlCalendarBucket` renders them all; named zones need the
+   * server's time zone tables (probed per zone in `aggregate()`).
+   */
+  calendarBucketUnits(): ReadonlySet<BucketUnit>;
   onBeforeFlatten(_type: unknown): void;
   onFieldScanned(field: string, _type: unknown, metadata: TMetadataMap<AtscriptMetadata>): void;
   getDesiredTableOptions(): TExistingTableOption[];
@@ -160,6 +165,16 @@ declare class MysqlAdapter extends BaseDbAdapter {
   findMany(query: DbQuery): Promise<Array<Record<string, unknown>>>;
   count(query: DbQuery): Promise<number>;
   aggregate(query: DbQuery): Promise<Array<Record<string, unknown>>>;
+  /**
+   * Verifies that `CONVERT_TZ` can convert to a calendar bucket's zone before
+   * any bucket SQL runs — MySQL never fails loudly here: it returns NULL when
+   * the time zone tables are not loaded (or lack the zone) and its input
+   * unchanged outside its supported range (before 8.0.28 that range ends in
+   * 2038). One probe ({@link TZ_PROBE_SQL}) detects both and raises
+   * `BUCKET_TZ_UNAVAILABLE` with the fix. `UTC` needs no probe — its
+   * expression skips `CONVERT_TZ`. Successes are cached per driver.
+   */
+  private _ensureBucketZone;
   updateOne(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps, expectedVersion?: number): Promise<TDbUpdateResult>;
   updateMany(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps): Promise<TDbUpdateResult>;
   replaceOne(filter: FilterExpr, data: Record<string, unknown>, expectedVersion?: number): Promise<TDbUpdateResult>;

package/dist/index.d.mts

@@ -1,7 +1,7 @@
-import { BaseDbAdapter, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDefaultFn, TDbDeleteResult, TDbFieldMeta, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TExistingTableOption, TFieldOps, TPrimaryKeyChange, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TTableOptionDiff, TValueFormatterPair } from "@atscript/db";
+import { BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDefaultFn, TDbDeleteResult, TDbFieldMeta, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TExistingTableOption, TFieldOps, TPrimaryKeyChange, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TTableOptionDiff, TValueFormatterPair } from "@atscript/db";
 import { TSqlFragment, TSqlFragment as TSqlFragment$1 } from "@atscript/db-sql-tools";
-import { TMetadataMap } from "@atscript/typescript/utils";
 import { FilterExpr as FilterExpr$1 } from "@uniqu/core";
+import { TMetadataMap } from "@atscript/typescript/utils";
 
 //#region src/types.d.ts
 /**
@@ -132,6 +132,11 @@ declare class MysqlAdapter extends BaseDbAdapter {
   prepareId(id: unknown, _fieldType: unknown): unknown;
   supportsNativeValueDefaults(): boolean;
   nativeDefaultFns(): ReadonlySet<TDbDefaultFn>;
+  /**
+   * Every unit: `mysqlCalendarBucket` renders them all; named zones need the
+   * server's time zone tables (probed per zone in `aggregate()`).
+   */
+  calendarBucketUnits(): ReadonlySet<BucketUnit>;
   onBeforeFlatten(_type: unknown): void;
   onFieldScanned(field: string, _type: unknown, metadata: TMetadataMap<AtscriptMetadata>): void;
   getDesiredTableOptions(): TExistingTableOption[];
@@ -160,6 +165,16 @@ declare class MysqlAdapter extends BaseDbAdapter {
   findMany(query: DbQuery): Promise<Array<Record<string, unknown>>>;
   count(query: DbQuery): Promise<number>;
   aggregate(query: DbQuery): Promise<Array<Record<string, unknown>>>;
+  /**
+   * Verifies that `CONVERT_TZ` can convert to a calendar bucket's zone before
+   * any bucket SQL runs — MySQL never fails loudly here: it returns NULL when
+   * the time zone tables are not loaded (or lack the zone) and its input
+   * unchanged outside its supported range (before 8.0.28 that range ends in
+   * 2038). One probe ({@link TZ_PROBE_SQL}) detects both and raises
+   * `BUCKET_TZ_UNAVAILABLE` with the fix. `UTC` needs no probe — its
+   * expression skips `CONVERT_TZ`. Successes are cached per driver.
+   */
+  private _ensureBucketZone;
   updateOne(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps, expectedVersion?: number): Promise<TDbUpdateResult>;
   updateMany(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps): Promise<TDbUpdateResult>;
   replaceOne(filter: FilterExpr, data: Record<string, unknown>, expectedVersion?: number): Promise<TDbUpdateResult>;

package/dist/index.mjs

@@ -1,6 +1,7 @@
-import { BaseDbAdapter, DbError, DbSpace } from "@atscript/db";
+import { ALL_BUCKET_UNITS, BaseDbAdapter, DbError, DbSpace, bucketTimeZoneUnavailable } from "@atscript/db";
 import { resolveAggregateSearch } from "@atscript/db/agg";
-import { buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildSelect, buildUpdate, buildWhere as buildWhere$1, defaultValueForType, defaultValueToSqlLiteral, fillReplacePayload, geoWindowFromControls, normalizeGeoPointValue, parseRegexString, refActionToSql, renameGeoDistance, replaceColumnsFor, toSqlValue } from "@atscript/db-sql-tools";
+import { buildAggregateCount, buildAggregateSelect, buildCreateView, buildDelete, buildGeoSearchCount, buildGeoSearchSelect, buildInsert, buildInsertMany, buildSelect, buildUpdate, buildWhere as buildWhere$1, defaultValueForType, defaultValueToSqlLiteral, fillReplacePayload, geoWindowFromControls, insertManyColumns, normalizeGeoPointValue, parseRegexString, refActionToSql, renameGeoDistance, replaceColumnsFor, sqlTimeZoneLiteral, toSqlValue } 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`). */
 const TEXT_BLOB_RE = /^(TINY|MEDIUM|LONG)?(TEXT|BLOB)\b/i;
@@ -164,9 +165,74 @@ const mysqlDialect = {
 			params: [...dist.params, circle.radius]
 		};
 	},
+	calendarBucket: mysqlCalendarBucket,
+	bucketAliasInHaving: true,
 	createViewPrefix: "CREATE OR REPLACE VIEW"
 };
 /**
+* Whether a field is stored as a native MySQL `TIMESTAMP`: a `number` with
+* `@db.default.now`. The adapter writes such values as UTC
+* `'YYYY-MM-DD HH:MM:SS'` strings and reads them back as epoch ms; every other
+* numeric timestamp is a DOUBLE / BIGINT epoch-ms column.
+*/
+function isMysqlTimestampColumn(fd) {
+	return fd.designType === "number" && fd.defaultValue?.kind === "fn" && fd.defaultValue.fn === "now";
+}
+/** `'1970-01-01 00:00:00'` as a DATETIME: the base for epoch arithmetic free of the session zone. */
+const MYSQL_EPOCH = "CAST('1970-01-01 00:00:00' AS DATETIME)";
+/**
+* Calendar-bucket label: TEXT `'YYYY-MM-DD'` — the local date of the
+* bucket's first day in `b.tz` — or NULL for a NULL source or one outside
+* `[BUCKET_MIN_INSTANT, BUCKET_MAX_INSTANT)`.
+*
+* The source's UTC wall time `U` (a DATETIME) depends on storage:
+* - DOUBLE / BIGINT epoch ms: `epoch + INTERVAL FLOOR(col / 1000) SECOND`
+*   (never `FROM_UNIXTIME`, which converts to the session zone);
+* - native `TIMESTAMP` ({@link isMysqlTimestampColumn}): `CAST(col AS DATETIME)`
+*   — the session-zone rendering, which is exactly the UTC string the adapter
+*   wrote and parses back on read, so the label agrees with the value reads
+*   return whatever the server's session zone is (`UNIX_TIMESTAMP(col)` would
+*   agree only under a UTC session zone).
+*
+* The local date is `DATE(CONVERT_TZ(U, '+00:00', '<tz>'))`, or `DATE(U)` for
+* `UTC` (no time zone tables needed). Truncation is calendar arithmetic on
+* that date. `CONVERT_TZ` returns NULL when the zone is unknown to the
+* server and its input unchanged outside its range — `MysqlAdapter` probes
+* each zone before running the query (`BUCKET_TZ_UNAVAILABLE`).
+*
+* Parameter-free (the zone is an inlined, charset-checked literal), so the
+* SELECT and GROUP BY renderings are identical (`ONLY_FULL_GROUP_BY`).
+*/
+function mysqlCalendarBucket(quotedCol, b) {
+	let utc;
+	let inRange;
+	if (isMysqlTimestampColumn(b.fd)) {
+		utc = `CAST(${quotedCol} AS DATETIME)`;
+		inRange = `${utc} >= '1970-01-02 00:00:00'`;
+	} else {
+		utc = `(${MYSQL_EPOCH} + INTERVAL FLOOR(${quotedCol} / 1000) SECOND)`;
+		inRange = `${quotedCol} >= ${BUCKET_MIN_INSTANT} AND ${quotedCol} < ${BUCKET_MAX_INSTANT}`;
+	}
+	const local = b.tz === "UTC" ? `DATE(${utc})` : `DATE(CONVERT_TZ(${utc}, '+00:00', ${sqlTimeZoneLiteral(b.tz)}))`;
+	let first;
+	switch (b.unit) {
+		case "day":
+			first = local;
+			break;
+		case "week":
+			first = `DATE_SUB(${local}, INTERVAL ((WEEKDAY(${local}) + 1 - ${b.weekStartIso} + 7) % 7) DAY)`;
+			break;
+		case "month":
+			first = `DATE_SUB(${local}, INTERVAL DAYOFMONTH(${local}) - 1 DAY)`;
+			break;
+		case "quarter":
+			first = `(MAKEDATE(YEAR(${local}), 1) + INTERVAL (QUARTER(${local}) - 1) QUARTER)`;
+			break;
+		default: first = `MAKEDATE(YEAR(${local}), 1)`;
+	}
+	return `CASE WHEN ${inRange} THEN DATE_FORMAT(${first}, '%Y-%m-%d') END`;
+}
+/**
 * Spherical distance in meters from a POINT column to a query point.
 * Used as the `distExpr` of the shared geo search builder.
 */
@@ -209,6 +275,10 @@ function mysqlGeoValueToPoint(value) {
 function buildInsert$1(table, data) {
 	return buildInsert(mysqlDialect, table, data);
 }
+/** Multi-row INSERT over `columns` (a missing column → `DEFAULT`). */
+function buildInsertMany$1(table, rows, columns) {
+	return buildInsertMany(mysqlDialect, table, rows, columns);
+}
 /**
 * Builds a SELECT statement with optional sort, limit, offset, projection.
 */
@@ -290,7 +360,7 @@ function mysqlTypeFromField(field) {
 		case "number":
 			if (precision) return `DECIMAL(${precision.precision},${precision.scale})`;
 			if (field.defaultValue?.kind === "fn" && field.defaultValue.fn === "increment") return unsigned ? "BIGINT UNSIGNED" : "BIGINT";
-			if (field.defaultValue?.kind === "fn" && field.defaultValue.fn === "now") return "TIMESTAMP";
+			if (isMysqlTimestampColumn(field)) return "TIMESTAMP";
 			if (tags?.has("int")) return intTypeFromTags(tags, unsigned);
 			return "DOUBLE";
 		case "integer": return intTypeFromTags(tags, unsigned);
@@ -384,6 +454,25 @@ function epochMsToUtcDatetime(ms) {
 	return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, "0")}-${String(d.getUTCDate()).padStart(2, "0")} ${String(d.getUTCHours()).padStart(2, "0")}:${String(d.getUTCMinutes()).padStart(2, "0")}:${String(d.getUTCSeconds()).padStart(2, "0")}`;
 }
 /**
+* One statement answers both questions `CONVERT_TZ` never raises an error
+* for: `missing` — the named zone (bound as `?`) converts to NULL, i.e. the
+* time zone tables are not loaded or lack it; `shift` — a fixed `+01:00`
+* conversion after 2038 is not applied (0 instead of 60 minutes), i.e. the
+* server's `CONVERT_TZ` range ends in 2038 (before 8.0.28, or 32-bit).
+*
+* The range half deliberately uses a fixed offset, not the named zone: MySQL
+* tz tables hold no transitions after 2037, so a zone such as `Europe/London`
+* legitimately converts to +00:00 in June 2040 on a current server — an
+* "unchanged" named-zone result is not evidence of a limited range.
+*/
+const TZ_PROBE_SQL = "SELECT CONVERT_TZ('2040-06-01 12:00:00', '+00:00', ?) IS NULL AS missing, TIMESTAMPDIFF(MINUTE, '2040-06-01 12:00:00', CONVERT_TZ('2040-06-01 12:00:00', '+00:00', '+01:00')) AS shift";
+/**
+* Zones `CONVERT_TZ` is known to handle, per driver (adapters are per table
+* and share a driver). Positives only: a failed zone is probed again, so
+* loading the time zone tables fixes a running server without a restart.
+*/
+const convertibleZones = /* @__PURE__ */ new WeakMap();
+/**
 * MySQL adapter for {@link AtscriptDbTable}.
 *
 * Accepts any {@link TMysqlDriver} implementation — the actual MySQL driver
@@ -480,6 +569,13 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 	nativeDefaultFns() {
 		return MysqlAdapter.NATIVE_DEFAULT_FNS;
 	}
+	/**
+	* Every unit: `mysqlCalendarBucket` renders them all; named zones need the
+	* server's time zone tables (probed per zone in `aggregate()`).
+	*/
+	calendarBucketUnits() {
+		return ALL_BUCKET_UNITS;
+	}
 	onBeforeFlatten(_type) {
 		const meta = _type.metadata;
 		const engine = meta.get("db.mysql.engine");
@@ -572,7 +668,7 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 	* converts epoch ms to a UTC datetime string for the wire protocol.
 	*/
 	formatValue(field) {
-		if (field.designType === "number" && field.defaultValue?.kind === "fn" && field.defaultValue.fn === "now") return {
+		if (isMysqlTimestampColumn(field)) return {
 			toStorage: (value) => typeof value === "number" ? epochMsToUtcDatetime(value) : value,
 			fromStorage: utcDatetimeToEpochMs
 		};
@@ -635,26 +731,16 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 		};
 		return this.withTransaction(async () => {
 			const tableName = this.resolveTableName();
-			const keys = Object.keys(data[0]);
-			const colsClause = keys.map((k) => qi(k)).join(", ");
-			const paramsPerRow = keys.length;
-			const maxRowsPerBatch = paramsPerRow > 0 ? Math.floor(6e4 / paramsPerRow) : data.length;
+			const columns = insertManyColumns(data);
+			const maxRowsPerBatch = columns.length > 0 ? Math.floor(6e4 / columns.length) : data.length;
 			const allIds = [];
-			const rowPlaceholderClause = `(${keys.map(() => "?").join(", ")})`;
 			for (let offset = 0; offset < data.length; offset += maxRowsPerBatch) {
-				const batchEnd = Math.min(offset + maxRowsPerBatch, data.length);
-				const batchSize = batchEnd - offset;
-				const params = [];
-				for (let i = offset; i < batchEnd; i++) {
-					const row = data[i];
-					for (const k of keys) params.push(mysqlDialect.toValue(row[k]));
-				}
-				const valuesClause = Array(batchSize).fill(rowPlaceholderClause).join(", ");
-				const sql = `INSERT INTO ${quoteTableName(tableName)} (${colsClause}) VALUES ${valuesClause}`;
+				const batch = data.slice(offset, offset + maxRowsPerBatch);
+				const { sql, params } = buildInsertMany$1(tableName, batch, columns);
 				this._log(sql, params);
 				const result = await this._wrapConstraintError(() => this._exec().run(sql, params));
 				const firstId = Number(result.insertId);
-				for (let i = 0; i < batchSize; i++) allIds.push(this._resolveInsertedId(data[offset + i], firstId > 0 ? firstId + i : 0));
+				for (let i = 0; i < batch.length; i++) allIds.push(this._resolveInsertedId(batch[i], firstId > 0 ? firstId + i : 0));
 			}
 			return {
 				insertedCount: allIds.length,
@@ -688,6 +774,7 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 		const search = resolveAggregateSearch(query.controls);
 		const where = search ? this._buildSearchWhere(search.text, query, search.indexName) : buildWhere(query.filter);
 		const tableName = this.resolveTableName();
+		for (const bucket of query.controls.$select?.buckets ?? []) await this._ensureBucketZone(bucket.tz);
 		if (query.controls.$count) {
 			const { sql, params } = buildAggregateCount$1(tableName, where, query.controls);
 			this._log(sql, params);
@@ -697,6 +784,30 @@ var MysqlAdapter = class MysqlAdapter extends BaseDbAdapter {
 		this._log(sql, params);
 		return this._exec().all(sql, params);
 	}
+	/**
+	* Verifies that `CONVERT_TZ` can convert to a calendar bucket's zone before
+	* any bucket SQL runs — MySQL never fails loudly here: it returns NULL when
+	* the time zone tables are not loaded (or lack the zone) and its input
+	* unchanged outside its supported range (before 8.0.28 that range ends in
+	* 2038). One probe ({@link TZ_PROBE_SQL}) detects both and raises
+	* `BUCKET_TZ_UNAVAILABLE` with the fix. `UTC` needs no probe — its
+	* expression skips `CONVERT_TZ`. Successes are cached per driver.
+	*/
+	async _ensureBucketZone(tz) {
+		if (tz === "UTC" || convertibleZones.get(this.driver)?.has(tz)) return;
+		this._log(TZ_PROBE_SQL, [tz]);
+		const row = await this._exec().get(TZ_PROBE_SQL, [tz]);
+		let problem;
+		if (!row || Number(row.missing) !== 0) problem = "its time zone tables are not loaded or lack this zone — load them with mysql_tzinfo_to_sql";
+		else if (Number(row.shift) !== 60) problem = "its CONVERT_TZ does not convert instants after 2038 — MySQL 8.0.28 or later (64-bit) is required";
+		if (problem) throw bucketTimeZoneUnavailable(`MySQL cannot convert to time zone "${tz}": ${problem}`);
+		let zones = convertibleZones.get(this.driver);
+		if (!zones) {
+			zones = /* @__PURE__ */ new Set();
+			convertibleZones.set(this.driver, zones);
+		}
+		zones.add(tz);
+	}
 	async updateOne(filter, data, ops, expectedVersion) {
 		const where = buildWhere(filter);
 		const versionColumn = this._table.versionColumn;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-mysql",
-  "version": "0.1.131",
+  "version": "0.1.132",
   "description": "MySQL adapter for @atscript/db with mysql2 driver support.",
   "keywords": [
     "atscript",
@@ -43,17 +43,17 @@
   "devDependencies": {
     "@atscript/core": "^0.1.92",
     "@atscript/typescript": "^0.1.92",
-    "@uniqu/core": "^0.1.8",
+    "@uniqu/core": "^0.1.9",
     "mysql2": "^3.11.0",
     "unplugin-atscript": "^0.1.92"
   },
   "peerDependencies": {
     "@atscript/core": "^0.1.92",
     "@atscript/typescript": "^0.1.92",
-    "@uniqu/core": "^0.1.8",
+    "@uniqu/core": "^0.1.9",
     "mysql2": ">=3.0.0",
-    "@atscript/db": "^0.1.131",
-    "@atscript/db-sql-tools": "^0.1.131"
+    "@atscript/db": "^0.1.132",
+    "@atscript/db-sql-tools": "^0.1.132"
   },
   "peerDependenciesMeta": {
     "mysql2": {