@nextlyhq/adapter-mysql 0.0.2-alpha.72 → 0.0.2-alpha.74

package/dist/index.cjs

@@ -168,6 +168,16 @@ async function returnTransactionConnection(connection, rollbackFailed, restore)
 	else connection.destroy();
 }
 /**
+* mysql2 accepts only `local`, `Z` and `±HH:MM` spellings for its driver
+* zone, and the ones that resolve to UTC are exactly these. `local` resolves
+* to the Node process's own zone, so it agrees with a UTC session only on a
+* UTC host.
+*/
+function isUtcDriverZone(zone) {
+	if (zone === "local") return (/* @__PURE__ */ new Date()).getTimezoneOffset() === 0;
+	return zone === "Z" || zone === "+00:00" || zone === "-00:00";
+}
+/**
 * Package version
 */
 const VERSION = "0.1.0";
@@ -214,11 +224,19 @@ const MYSQL_ERROR_CODES = {
 	1146: "query",
 	1054: "query"
 };
+/** ER_LOCK_DEADLOCK: the transaction lost a race, and running it again may succeed. */
+const DEADLOCK = 1213;
 /**
-* Delay helper for retry logic.
+* The MySQL error number an error carries: its own, or that of the driver
+* error it wraps, as a classified or a Drizzle query error does.
 */
-function delay(ms) {
-	return new Promise((resolve) => setTimeout(resolve, ms));
+function errnoOf(error) {
+	for (let at = error, hops = 0; hops < 4; hops++) {
+		if (typeof at !== "object" || at === null) return void 0;
+		const errno = Reflect.get(at, "errno");
+		if (typeof errno === "number") return errno;
+		at = Reflect.get(at, "cause");
+	}
 }
 /**
 * MySQL database adapter for Nextly.
@@ -259,6 +277,8 @@ var MySqlAdapter = class extends _nextlyhq_adapter_drizzle.DrizzleAdapter {
 	* Connection pool instance.
 	*/
 	pool = null;
+	/** The `withSession` calls running, each on a connection of its own, for `disconnect` to wait for. */
+	sessions = /* @__PURE__ */ new Set();
 	/**
 	* Connection state flag.
 	*/
@@ -268,6 +288,7 @@ var MySqlAdapter = class extends _nextlyhq_adapter_drizzle.DrizzleAdapter {
 	* string at connect. Undefined until then, which callers treat as not known.
 	*/
 	sharedRowLock;
+	functionalIndexes;
 	/**
 	* Creates a new MySQL adapter instance.
 	*
@@ -291,15 +312,22 @@ var MySqlAdapter = class extends _nextlyhq_adapter_drizzle.DrizzleAdapter {
 	async connect() {
 		if (this.connected && this.pool) return;
 		try {
+			this.warnOnDriverZoneDisagreement();
 			const poolConfig = this.buildPoolConfig();
 			const pool = mysql2_promise.default.createPool(poolConfig);
+			pool.pool.on("connection", (connection) => {
+				connection.query("SET SESSION time_zone = '+00:00'", (error) => {
+					if (error) connection.destroy();
+				});
+			});
 			boundPoolWait(pool.pool, poolConfig.connectTimeout ?? 0);
 			this.pool = pool;
 			const connection = await this.pool.getConnection();
 			try {
 				await connection.query("SELECT 1");
-				const { variant } = await (0, _nextlyhq_adapter_drizzle_version_check.checkDialectVersion)(connection, "mysql", { onWarning: (msg) => this.config.logger?.warn?.(msg) });
+				const { variant, functionalIndexes } = await (0, _nextlyhq_adapter_drizzle_version_check.checkDialectVersion)(connection, "mysql", { onWarning: (msg) => this.config.logger?.warn?.(msg) });
 				this.sharedRowLock = (0, _nextlyhq_adapter_drizzle_version_check.acceptsForShare)(variant);
+				this.functionalIndexes = functionalIndexes;
 				this.connected = true;
 				if (this.config.logger?.info) this.config.logger.info("MySQL connection established", {
 					host: this.config.host ?? "from URL",
@@ -322,7 +350,8 @@ var MySqlAdapter = class extends _nextlyhq_adapter_drizzle.DrizzleAdapter {
 	*
 	* @remarks
 	* This method is idempotent - calling it multiple times is safe.
-	* It waits for all connections to be released before shutting down.
+	* It waits for all connections to be released before shutting down,
+	* including each running `withSession`'s connection of its own.
 	*/
 	async disconnect() {
 		const pool = this.pool;
@@ -331,6 +360,7 @@ var MySqlAdapter = class extends _nextlyhq_adapter_drizzle.DrizzleAdapter {
 		this.drizzleByRelations = /* @__PURE__ */ new WeakMap();
 		if (!pool) return;
 		try {
+			await Promise.allSettled([...this.sessions]);
 			await pool.end();
 			if (this.config.logger?.info) this.config.logger.info("MySQL connection closed");
 		} finally {
@@ -408,54 +438,131 @@ var MySqlAdapter = class extends _nextlyhq_adapter_drizzle.DrizzleAdapter {
 	*
 	* Note: Savepoints are disabled in this adapter for safety due to
 	* MySQL's quirks with nested transactions.
+	*
+	* A call made inside another transaction's work therefore joins it flat,
+	* on its connection: its statements are the outer's. Its failure cannot be
+	* undone alone, so it fails the whole transaction, even when the outer
+	* catches it: the outer's COMMIT is refused, it rolls back, and it rejects
+	* with the error that failed the joined call; any later joined call fails
+	* with that error at once. A joined call keeps the outer's options and is
+	* never retried itself. `retryWhen` is asked first, of every error that
+	* ends an attempt, application ones included.
 	*/
-	async transaction(work, options) {
-		return this.runInFlowTransaction(() => this.runTransactionAttempts(work, options));
+	transaction(work, options) {
+		return this.openOrJoin(work, options, {
+			run: (_attempt, openedAt) => this.runAttempt(work, options, openedAt),
+			retryable: (error) => errnoOf(error) === DEADLOCK,
+			describe: (error) => {
+				const errno = errnoOf(error);
+				return {
+					label: errno === DEADLOCK ? "deadlock" : "a retryable error",
+					detail: { errno }
+				};
+			},
+			logger: this.config.logger
+		});
 	}
-	/** The attempts `transaction` makes, each on a connection of its own. */
-	async runTransactionAttempts(work, options) {
-		const pool = this.ensurePool();
-		const maxAttempts = (options?.retryCount ?? 0) + 1;
-		const retryDelayMs = options?.retryDelayMs ?? 100;
-		let lastError;
-		for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-			const connection = await this.connectFlowTransaction(() => pool.getConnection());
-			const startTime = Date.now();
-			let rollbackFailed = false;
-			const restore = {};
+	/**
+	* Runs `work` on a connection of its own, opened for it with the pool's
+	* connection settings, outside a transaction, each statement committing as
+	* it runs.
+	*
+	* @remarks
+	* Not a pooled connection: on a server whose sessions start with autocommit
+	* off, one can hold a transaction an earlier caller left open, and turning
+	* autocommit on would commit that caller's writes. A new connection holds
+	* nothing. It does not count against `pool.max`.
+	*
+	* Each statement commits as it runs, whatever the server's own autocommit
+	* default. With `strictSqlMode` the session runs in strict mode, as a
+	* transaction given the same option does, so a statement that would cut a
+	* value short fails and changes nothing. The connection is closed
+	* afterwards, whether `work` finished or threw, so whatever `work` set on
+	* its session (a temporary table, a session variable, a lock) ends with it.
+	*/
+	async withSession(work, options) {
+		this.refuseSessionInTransaction();
+		this.ensurePool();
+		const running = this.runSession(work, options);
+		this.sessions.add(running);
+		try {
+			return await running;
+		} finally {
+			this.sessions.delete(running);
+		}
+	}
+	/** `withSession`'s work, on a connection it opens and closes. */
+	async runSession(work, options) {
+		let connection;
+		try {
+			connection = await mysql2_promise.default.createConnection(this.buildConnectionConfig());
+		} catch (error) {
+			throw this.classifyError(error);
+		}
+		try {
 			try {
-				await this.beginTransaction(connection, options, restore);
-				const result = await work(this.createTransactionContext(connection));
-				await connection.query("COMMIT");
-				if (this.config.logger?.debug) {
-					const durationMs = Date.now() - startTime;
-					this.config.logger.debug("Transaction committed", {
-						attempt,
-						durationMs
-					});
-				}
-				return result;
+				await connection.query("SET SESSION autocommit = 1");
+				await connection.query("SET SESSION time_zone = '+00:00'");
+				if (options?.strictSqlMode) await this.enterStrictMode(connection, {});
 			} catch (error) {
-				await connection.query("ROLLBACK").catch(() => {
-					rollbackFailed = true;
-				});
-				lastError = error;
-				if ((0, _nextlyhq_adapter_drizzle_types.isApplicationError)(error)) throw error;
-				const mysqlError = error;
-				if (mysqlError.errno === 1213 && attempt < maxAttempts) {
-					if (this.config.logger?.warn) this.config.logger.warn(`Transaction failed with deadlock, retrying (${attempt}/${maxAttempts})`, {
-						errno: mysqlError.errno,
-						attempt
-					});
-					await delay(retryDelayMs * attempt);
-					continue;
-				}
 				throw this.classifyError(error);
-			} finally {
-				await returnTransactionConnection(connection, rollbackFailed, restore);
 			}
+			return await work({ execute: async (statement, params = []) => {
+				const startTime = Date.now();
+				try {
+					const [rows] = await connection.query(statement, params);
+					if (this.config.logger?.query) this.config.logger.query(statement, params, Date.now() - startTime);
+					return rows;
+				} catch (error) {
+					throw this.classifyError(error, statement);
+				}
+			} });
+		} finally {
+			connection.destroy();
 		}
-		throw this.classifyError(lastError);
+	}
+	/** One attempt at an outermost transaction, on a connection of its own. */
+	async runAttempt(work, options, openedAt) {
+		const pool = this.ensurePool();
+		this.notePoolAccess();
+		const connection = await pool.getConnection();
+		let rollbackFailed = false;
+		const restore = {};
+		const settled = await this.settleOutermost({
+			context: this.createTransactionContext(connection),
+			join: this.joinSteps(connection),
+			openedAt,
+			begin: () => this.beginTransaction(connection, options, restore),
+			commit: async () => {
+				await connection.query("COMMIT");
+			},
+			rollback: async () => {
+				await connection.query("ROLLBACK").catch((rollbackError) => {
+					rollbackFailed = true;
+					throw rollbackError;
+				});
+			}
+		}, work, options);
+		await returnTransactionConnection(connection, rollbackFailed, restore);
+		return settled;
+	}
+	/**
+	* How a call made inside a transaction on `connection` joins it: flat, on
+	* the same connection, with nothing to send. Any failure inside it fails
+	* the whole transaction, since no savepoint can undo the part alone.
+	*/
+	joinSteps(connection) {
+		const callbackConnection = connection.connection;
+		return this.joinStepsOn(() => this.createTransactionContext(connection), (relations) => relations ? (0, drizzle_orm_mysql2.drizzle)({
+			client: callbackConnection,
+			relations
+		}) : (0, drizzle_orm_mysql2.drizzle)({ client: callbackConnection }), (context) => ({
+			context,
+			begin() {},
+			commit() {},
+			rollback() {},
+			dooms: () => true
+		}));
 	}
 	/**
 	* Get MySQL database capabilities.
@@ -482,7 +589,8 @@ var MySqlAdapter = class extends _nextlyhq_adapter_drizzle.DrizzleAdapter {
 			supportsOnConflict: true,
 			maxParamsPerQuery: 65535,
 			maxIdentifierLength: 64,
-			sharedRowLock: this.sharedRowLock
+			sharedRowLock: this.sharedRowLock,
+			functionalIndexes: this.functionalIndexes
 		};
 	}
 	/**
@@ -565,51 +673,86 @@ var MySqlAdapter = class extends _nextlyhq_adapter_drizzle.DrizzleAdapter {
 			"execute",
 			"getConnection"
 		]);
-		return this.trackFlowTransactions(this.pinDrizzleTransactions(onClient(callbackPool), async () => {
-			const connection = await this.connectFlowTransaction(() => pool.getConnection());
+		return this.joiningHandle(onClient(callbackPool), async () => {
+			const connection = await pool.getConnection();
 			return {
 				drizzle: onClient(connection.connection),
 				rollback: () => connection.query("ROLLBACK"),
 				release: (dirty) => {
 					if (dirty) connection.destroy();
 					else connection.release();
-				}
+				},
+				join: this.joinSteps(connection)
 			};
-		}));
+		}, relations);
+	}
+	/**
+	* Warns when a caller's configured driver zone does not agree with the
+	* pinned UTC session.
+	*
+	* mysql2's driver-level `timezone` decides how it parses the date strings
+	* the pinned session answers with and how it binds raw Date parameters, so
+	* a non-UTC spelling there would shift values a round-trip fails to
+	* cancel. The configuration is aligned to the pin (`buildConnectionConfig`
+	* sets UTC unconditionally, for pooled and standalone connections alike),
+	* never rewritten silently: the caller configured a reading, and this is
+	* where that reading is named as lost. Runs from `connect`, once per pool
+	* build — the configuration cannot change between calls.
+	*/
+	warnOnDriverZoneDisagreement() {
+		const requestedZone = this.config.timezone ?? "local";
+		if (isUtcDriverZone(requestedZone)) return;
+		this.config.logger?.warn?.(`Driver timezone "${requestedZone}" is not UTC; it is aligned to the pinned UTC session and no longer shifts reads or writes.`);
 	}
 	/**
 	* Builds mysql2 Pool configuration from adapter config.
 	*/
 	buildPoolConfig() {
-		const config = {};
-		if (this.config.url) config.uri = this.config.url;
-		else {
-			if (this.config.host) config.host = this.config.host;
-			if (this.config.port) config.port = this.config.port;
-			if (this.config.database) config.database = this.config.database;
-			if (this.config.user) config.user = this.config.user;
-			if (this.config.password) config.password = this.config.password;
-		}
+		const config = this.buildConnectionConfig();
 		config.connectionLimit = this.config.pool?.max ?? DEFAULT_POOL_CONFIG.max;
 		config.idleTimeout = this.config.pool?.idleTimeoutMs ?? DEFAULT_POOL_CONFIG.idleTimeoutMs;
-		config.connectTimeout = this.config.pool?.connectionTimeoutMs ?? DEFAULT_POOL_CONFIG.connectionTimeoutMs;
 		config.waitForConnections = true;
 		config.queueLimit = 0;
-		if (this.config.ssl) {
-			if (typeof this.config.ssl === "boolean") config.ssl = this.config.ssl ? {} : void 0;
-			else config.ssl = {
-				rejectUnauthorized: this.config.ssl.rejectUnauthorized,
-				ca: this.config.ssl.ca,
-				cert: this.config.ssl.cert,
-				key: this.config.ssl.key
-			};
-		}
-		if (this.config.timezone) config.timezone = this.config.timezone;
+		return config;
+	}
+	/**
+	* Builds the settings every connection opens with, pooled or not, from
+	* adapter config.
+	*/
+	buildConnectionConfig() {
+		const config = this.buildAddressConfig();
+		config.connectTimeout = this.config.pool?.connectionTimeoutMs ?? DEFAULT_POOL_CONFIG.connectionTimeoutMs;
+		if (this.config.ssl) config.ssl = this.buildSslConfig(this.config.ssl);
+		config.timezone = "Z";
 		if (this.config.charset) config.charset = this.config.charset;
 		config.multipleStatements = false;
 		config.dateStrings = false;
 		return config;
 	}
+	/** Where to connect: the connection string, or the explicit options. */
+	buildAddressConfig() {
+		if (this.config.url) return { uri: this.config.url };
+		const { host, port, database, user, password } = this.config;
+		const config = {
+			host,
+			port,
+			database,
+			user,
+			password
+		};
+		for (const key of Object.keys(config)) if (!config[key]) delete config[key];
+		return config;
+	}
+	/** mysql2's `ssl` option for the adapter's `ssl` setting. */
+	buildSslConfig(ssl) {
+		if (typeof ssl === "boolean") return ssl ? {} : void 0;
+		return {
+			rejectUnauthorized: ssl.rejectUnauthorized,
+			ca: ssl.ca,
+			cert: ssl.cert,
+			key: ssl.key
+		};
+	}
 	/**
 	* Begins a transaction with the specified options, recording in `changed`
 	* each session setting it changes, as it changes it, for `restoreSession`
@@ -634,12 +777,20 @@ var MySqlAdapter = class extends _nextlyhq_adapter_drizzle.DrizzleAdapter {
 			await connection.query(`SET SESSION innodb_lock_wait_timeout = ${timeoutSeconds}`);
 			changed.lockWaitTimeout = Number.isInteger(previous) ? previous : null;
 		}
-		if (options?.strictSqlMode) {
-			const [rows] = await connection.query("SELECT @@SESSION.sql_mode AS mode");
-			const previous = rows[0]?.mode;
-			await connection.query("SET SESSION sql_mode = TRIM(BOTH ',' FROM CONCAT(@@SESSION.sql_mode, ',STRICT_ALL_TABLES'))");
-			changed.sqlMode = typeof previous === "string" ? previous : null;
-		}
+		if (options?.strictSqlMode) await this.enterStrictMode(connection, changed);
+	}
+	/**
+	* Strict mode for the rest of this connection's session: an INSERT, UPDATE
+	* or ALTER that would cut a string to its column's length, or clamp a
+	* number to its range, fails instead of applying with a warning. Added to
+	* the session's own mode, so every other flag it had still holds, and
+	* recorded in `changed` for `restoreSession` to put back.
+	*/
+	async enterStrictMode(connection, changed) {
+		const [rows] = await connection.query("SELECT @@SESSION.sql_mode AS mode");
+		const previous = rows[0]?.mode;
+		changed.sqlMode = typeof previous === "string" ? previous : null;
+		await connection.query("SET SESSION sql_mode = TRIM(BOTH ',' FROM CONCAT(@@SESSION.sql_mode, ',STRICT_ALL_TABLES'))");
 	}
 	/**
 	* Creates a TransactionContext for the given connection.
@@ -835,7 +986,8 @@ var MySqlAdapter = class extends _nextlyhq_adapter_drizzle.DrizzleAdapter {
 				await connection.query(`SELECT ${idColumn} FROM ${this.escapeIdentifier(table)} WHERE ${idColumn} = ? FOR UPDATE`, [id]);
 			},
 			insert: async (table, data, options) => {
-				const mapped = this.mapRowToRawSql(this.getTableObject(table), data);
+				const insertTableObj = this.resolvedTableObject(table);
+				const mapped = this.mapRowToRawSql(insertTableObj, data);
 				const columns = Object.keys(mapped);
 				const values = Object.values(mapped);
 				const placeholders = this.buildPlaceholders(values.length, 0);
@@ -843,7 +995,6 @@ var MySqlAdapter = class extends _nextlyhq_adapter_drizzle.DrizzleAdapter {
 				const [result] = await connection.query(sql, values);
 				const ret = options?.returning;
 				if (Array.isArray(ret) && ret.length === 0) return;
-				const insertTableObj = this.getTableObject(table);
 				const aliases = this.dateWallClockAliases(insertTableObj, ret ?? "*");
 				const spelled = aliases.map((a) => `DATE_FORMAT(${this.escapeIdentifier(a.sqlName)}, '%Y-%m-%dT%H:%i:%s.%f') AS ${this.escapeIdentifier(a.alias)}`).join(", ");
 				const projected = !ret || ret === "*" ? "*" : this.mapColumnNamesToSql(insertTableObj, ret).map((c) => this.escapeIdentifier(c)).join(", ");
@@ -861,7 +1012,7 @@ var MySqlAdapter = class extends _nextlyhq_adapter_drizzle.DrizzleAdapter {
 				if (data.length === 0) return [];
 				const retMany = options?.returning;
 				const skipReread = Array.isArray(retMany) && retMany.length === 0;
-				const tableObj = this.getTableObject(table);
+				const tableObj = this.resolvedTableObject(table);
 				const mappedRecords = data.map((r) => this.mapRowToRawSql(tableObj, r));
 				const columns = Object.keys(mappedRecords[0]);
 				const allValues = [];