@nextlyhq/adapter-mysql 0.0.2-alpha.73 → 0.0.2-alpha.75

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.
@@ -294,8 +312,14 @@ 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();
@@ -378,6 +402,59 @@ var MySqlAdapter = class extends _nextlyhq_adapter_drizzle.DrizzleAdapter {
 		};
 	}
 	/**
+	* The connection as a health check reads it, on one pooled connection: the
+	* server's version, timed for the round trip, then that session's
+	* `Ssl_cipher` status, which names the cipher when the session's connection
+	* is encrypted and is empty when it is not.
+	*
+	* @remarks
+	* The status and the connection's own socket are weighed by
+	* `encryptionOf`: behind a proxy the status can describe the proxy's own
+	* connection to the server, while this connection's socket is TLS. The
+	* socket is read as it is, never inferred from the `ssl` setting.
+	*
+	* Whether the database is on this machine is judged from the configured
+	* address, which never leaves this method. Any failure answers `"unknown"`.
+	*/
+	async inspectConnection() {
+		const local = this.isLocalHost(this.connectionHost());
+		let connection;
+		try {
+			connection = await this.ensurePool().getConnection();
+			const started = performance.now();
+			const [versionRows] = await connection.query("SELECT VERSION() AS version");
+			const roundTripMs = Math.max(0, Math.round(performance.now() - started));
+			const [statusRows] = await connection.query("SHOW SESSION STATUS LIKE 'Ssl_cipher'");
+			const cipher = statusRows[0]?.Value;
+			const version = versionRows[0]?.version;
+			return {
+				encryption: this.encryptionOf({
+					session: typeof cipher === "string" ? cipher !== "" : void 0,
+					ownSocketTls: this.ownSocketIsTls(connection)
+				}),
+				local,
+				roundTripMs,
+				...typeof version === "string" && version !== "" ? { serverVersion: version.split("-")[0] } : {}
+			};
+		} catch {
+			return {
+				encryption: "unknown",
+				local
+			};
+		} finally {
+			connection?.release();
+		}
+	}
+	/**
+	* The host this adapter connects to, as mysql2 resolves it: the connection
+	* string's when one is set, else the `host` option, else `localhost`.
+	* `undefined` when the connection string cannot be read.
+	*/
+	connectionHost() {
+		const configured = this.config.url ? this.hostOfUrl(this.config.url) : this.config.host ?? "";
+		return configured === "" ? "localhost" : configured;
+	}
+	/**
 	* Execute a raw SQL query.
 	*
 	* @param sql - SQL query string with ? placeholders
@@ -414,9 +491,29 @@ 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
+		});
 	}
 	/**
 	* Runs `work` on a connection of its own, opened for it with the pool's
@@ -458,6 +555,7 @@ var MySqlAdapter = class extends _nextlyhq_adapter_drizzle.DrizzleAdapter {
 		try {
 			try {
 				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) {
 				throw this.classifyError(error);
@@ -476,50 +574,48 @@ var MySqlAdapter = class extends _nextlyhq_adapter_drizzle.DrizzleAdapter {
 			connection.destroy();
 		}
 	}
-	/** The attempts `transaction` makes, each on a connection of its own. */
-	async runTransactionAttempts(work, options) {
+	/** One attempt at an outermost transaction, on a connection of its own. */
+	async runAttempt(work, options, openedAt) {
 		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 = {};
-			try {
-				await this.beginTransaction(connection, options, restore);
-				const result = await work(this.createTransactionContext(connection));
+		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");
-				if (this.config.logger?.debug) {
-					const durationMs = Date.now() - startTime;
-					this.config.logger.debug("Transaction committed", {
-						attempt,
-						durationMs
-					});
-				}
-				return result;
-			} catch (error) {
-				await connection.query("ROLLBACK").catch(() => {
+			},
+			rollback: async () => {
+				await connection.query("ROLLBACK").catch((rollbackError) => {
 					rollbackFailed = true;
+					throw rollbackError;
 				});
-				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);
 			}
-		}
-		throw this.classifyError(lastError);
+		}, 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.
@@ -630,17 +726,36 @@ 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.
@@ -661,7 +776,7 @@ var MySqlAdapter = class extends _nextlyhq_adapter_drizzle.DrizzleAdapter {
 		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);
-		if (this.config.timezone) config.timezone = this.config.timezone;
+		config.timezone = "Z";
 		if (this.config.charset) config.charset = this.config.charset;
 		config.multipleStatements = false;
 		config.dateStrings = false;
@@ -924,7 +1039,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);
@@ -932,7 +1048,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(", ");
@@ -950,7 +1065,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 = [];