@nextlyhq/adapter-mysql 0.0.2-alpha.68 → 0.0.2-alpha.69

package/dist/index.mjs

@@ -1,957 +1,980 @@
-import { DrizzleAdapter } from '@nextlyhq/adapter-drizzle';
-import { isApplicationError, createDatabaseError, isDatabaseError } from '@nextlyhq/adapter-drizzle/types';
-import { checkDialectVersion, acceptsForShare } from '@nextlyhq/adapter-drizzle/version-check';
-import { and, eq, getColumns } from 'drizzle-orm';
-import { getTableConfig } from 'drizzle-orm/mysql-core';
-import { drizzle } from 'drizzle-orm/mysql2';
-import mysql from 'mysql2/promise';
-
+import { DrizzleAdapter } from "@nextlyhq/adapter-drizzle";
+import { createDatabaseError, isApplicationError, isDatabaseError, poolWaitTimeoutError } from "@nextlyhq/adapter-drizzle/types";
+import { acceptsForShare, checkDialectVersion } from "@nextlyhq/adapter-drizzle/version-check";
+import { and, eq, getColumns } from "drizzle-orm";
+import { getTableConfig } from "drizzle-orm/mysql-core";
+import { drizzle } from "drizzle-orm/mysql2";
+import mysql from "mysql2/promise";
+// src/pool-wait.ts
+/**
+* The bounded wait for a pooled connection.
+*
+* mysql2 has no such bound. A request that finds every connection in use is
+* queued until one is released, however long that takes, so a database that
+* stays busy holds every request behind it indefinitely. This bounds the wait
+* the way pg-pool's `connectionTimeoutMillis` does: past the bound, the
+* request fails with the adapters' own pool-wait timeout error, which core
+* answers with "database busy".
+*
+* Only the wait in the queue: a request that opens a new connection is bounded
+* by mysql2's `connectTimeout` instead, set from the same setting, and a
+* connection that cannot be opened is a database that cannot be reached
+* rather than one that is busy.
+*/
+/**
+* Takes a request that gave up out of the pool's queue, so a pool that stays
+* saturated does not collect every request that has already failed, and a
+* released connection goes to one still waiting. Returns whether it was
+* there: with diagnostics tracing on, mysql2 queues a wrapper of the
+* callback rather than the callback itself, and then it stays queued until a
+* connection reaches it.
+*/
+function leaveQueue(pool, waiting) {
+	const queue = pool._connectionQueue;
+	if (!queue) return false;
+	for (let at = 0; at < queue.length; at++) if (queue.peekAt(at) === waiting) {
+		queue.removeOne(at);
+		return true;
+	}
+	return false;
+}
+/**
+* Makes `pool` fail a request that has waited `boundMs` in its queue for a
+* connection, and returns it. A bound of 0 leaves the wait unbounded, as
+* pg-pool reads a `connectionTimeoutMillis` of 0.
+*
+* Replaces the pool's own `getConnection`, which its `query` and `execute`
+* go through, so every path to a connection is bounded: the adapter's
+* statements, its transactions, and the Drizzle handle core services query
+* through.
+*
+* A request that gives up leaves the queue. Where mysql2 cannot be asked to
+* drop it, the connection it is eventually handed is released straight back
+* rather than held by a request that has already failed.
+*/
+function boundPoolWait(pool, boundMs) {
+	if (boundMs <= 0) return pool;
+	const getConnection = pool.getConnection.bind(pool);
+	const bounded = (callback) => {
+		let answered = false;
+		const wait = {};
+		let queued = false;
+		const onEnqueue = () => queued = true;
+		pool.once("enqueue", onEnqueue);
+		const waiting = (err, connection) => {
+			if (answered) {
+				connection?.release();
+				return;
+			}
+			answered = true;
+			clearTimeout(wait.timer);
+			callback(err, connection);
+		};
+		getConnection(waiting);
+		pool.removeListener("enqueue", onEnqueue);
+		if (!queued || answered) return;
+		wait.timer = setTimeout(() => {
+			answered = true;
+			leaveQueue(pool, waiting);
+			callback(poolWaitTimeoutError(boundMs));
+		}, boundMs);
+	};
+	pool.getConnection = bounded;
+	return pool;
+}
 // src/index.ts
+/**
+* @nextlyhq/adapter-mysql
+*
+* MySQL database adapter for Nextly.
+* Extends DrizzleAdapter from @nextlyhq/adapter-drizzle to provide MySQL-specific functionality.
+*
+* @remarks
+* This adapter uses the mysql2 package for database connectivity and provides:
+* - Connection pooling via mysql2 Pool
+* - Full transaction support with isolation levels
+* - CRUD operations with workarounds for missing RETURNING clause
+* - MySQL-specific error classification
+* - Automatic retry for deadlocks (error 1213)
+*
+* @example
+* ```typescript
+* import { createMySqlAdapter } from '@nextlyhq/adapter-mysql';
+*
+* const adapter = createMySqlAdapter({
+*   url: process.env.DATABASE_URL!,
+* });
+*
+* await adapter.connect();
+*
+* // Query data
+* const users = await adapter.select('users', {
+*   where: { and: [{ column: 'status', op: '=', value: 'active' }] },
+*   limit: 10,
+* });
+*
+* await adapter.disconnect();
+* ```
+*
+* @packageDocumentation
+*/
+/**
+* Puts back what a transaction changed on its connection's session. False
+* when that could not be done, and the connection must not be pooled.
+*/
 async function restoreSession(connection, restore) {
-  if (restore === null) return true;
-  if (restore.lockWaitTimeout === null) return false;
-  try {
-    await connection.query(
-      `SET SESSION innodb_lock_wait_timeout = ${restore.lockWaitTimeout}`
-    );
-    return true;
-  } catch {
-    return false;
-  }
+	if (restore === null) return true;
+	if (restore.lockWaitTimeout === null || restore.sqlMode === null) return false;
+	try {
+		if (restore.lockWaitTimeout !== void 0) await connection.query(`SET SESSION innodb_lock_wait_timeout = ${restore.lockWaitTimeout}`);
+		if (restore.sqlMode !== void 0) await connection.query("SET SESSION sql_mode = ?", [restore.sqlMode]);
+		return true;
+	} catch {
+		return false;
+	}
 }
+/**
+* Ends a transaction's hold on its connection: back to the pool once its
+* session is as the transaction found it, or closed when it is not. A
+* connection whose ROLLBACK failed (`rollbackFailed`) may still be inside
+* the transaction, and the next request handed it would write into a
+* transaction nobody commits.
+*/
 async function returnTransactionConnection(connection, rollbackFailed, restore) {
-  if (!rollbackFailed && await restoreSession(connection, restore)) {
-    connection.release();
-  } else {
-    connection.destroy();
-  }
+	if (!rollbackFailed && await restoreSession(connection, restore)) connection.release();
+	else connection.destroy();
 }
-var VERSION = "0.1.0";
-var DEFAULT_POOL_CONFIG = {
-  max: 10,
-  idleTimeoutMs: 3e4,
-  connectionTimeoutMs: 1e4
+/**
+* Package version
+*/
+const VERSION = "0.1.0";
+/**
+* Default pool configuration values.
+*/
+const DEFAULT_POOL_CONFIG = {
+	min: 2,
+	max: 10,
+	idleTimeoutMs: 3e4,
+	connectionTimeoutMs: 15e3
 };
-var MYSQL_ERROR_CODES = {
-  // Unique/Duplicate key violations
-  1022: "unique_violation",
-  // ER_DUP_KEY
-  1062: "unique_violation",
-  // ER_DUP_ENTRY
-  1169: "unique_violation",
-  // ER_DUP_UNIQUE
-  1586: "unique_violation",
-  // ER_DUP_ENTRY_WITH_KEY_NAME
-  // Foreign key violations
-  1216: "foreign_key_violation",
-  // ER_NO_REFERENCED_ROW
-  1217: "foreign_key_violation",
-  // ER_ROW_IS_REFERENCED
-  1451: "foreign_key_violation",
-  // ER_ROW_IS_REFERENCED_2
-  1452: "foreign_key_violation",
-  // ER_NO_REFERENCED_ROW_2
-  // Not null violations
-  1048: "not_null_violation",
-  // ER_BAD_NULL_ERROR
-  1364: "not_null_violation",
-  // ER_NO_DEFAULT_FOR_FIELD
-  // Check constraint violations (MySQL 8.0.16+)
-  3819: "check_violation",
-  // ER_CHECK_CONSTRAINT_VIOLATED
-  // Deadlock
-  1213: "deadlock",
-  // ER_LOCK_DEADLOCK
-  // Timeout
-  1205: "timeout",
-  // ER_LOCK_WAIT_TIMEOUT
-  // Connection errors
-  1040: "connection",
-  // ER_CON_COUNT_ERROR - Too many connections
-  1042: "connection",
-  // ER_BAD_HOST_ERROR
-  1043: "connection",
-  // ER_HANDSHAKE_ERROR
-  1044: "connection",
-  // ER_DBACCESS_DENIED_ERROR
-  1045: "connection",
-  // ER_ACCESS_DENIED_ERROR
-  1129: "connection",
-  // ER_HOST_IS_BLOCKED
-  1130: "connection",
-  // ER_HOST_NOT_PRIVILEGED
-  2002: "connection",
-  // CR_CONNECTION_ERROR
-  2003: "connection",
-  // CR_CONN_HOST_ERROR
-  2006: "connection",
-  // CR_SERVER_GONE_ERROR
-  2013: "connection",
-  // CR_SERVER_LOST
-  // Query errors
-  1064: "query",
-  // ER_PARSE_ERROR
-  1146: "query",
-  // ER_NO_SUCH_TABLE
-  1054: "query"
-  // ER_BAD_FIELD_ERROR
+/**
+* MySQL error codes mapping to DatabaseErrorKind.
+*
+* @see https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html
+*/
+const MYSQL_ERROR_CODES = {
+	1022: "unique_violation",
+	1062: "unique_violation",
+	1169: "unique_violation",
+	1586: "unique_violation",
+	1216: "foreign_key_violation",
+	1217: "foreign_key_violation",
+	1451: "foreign_key_violation",
+	1452: "foreign_key_violation",
+	1048: "not_null_violation",
+	1364: "not_null_violation",
+	3819: "check_violation",
+	1213: "deadlock",
+	1205: "timeout",
+	1040: "connection",
+	1042: "connection",
+	1043: "connection",
+	1044: "connection",
+	1045: "connection",
+	1129: "connection",
+	1130: "connection",
+	2002: "connection",
+	2003: "connection",
+	2006: "connection",
+	2013: "connection",
+	1064: "query",
+	1146: "query",
+	1054: "query"
 };
+/**
+* Delay helper for retry logic.
+*/
 function delay(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+	return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/**
+* MySQL database adapter for Nextly.
+*
+* Extends the base DrizzleAdapter to provide MySQL-specific functionality
+* using the mysql2 package.
+*
+* @remarks
+* MySQL has some limitations compared to PostgreSQL:
+* - No native RETURNING clause (requires INSERT then SELECT)
+* - No native ILIKE (uses LOWER() LIKE workaround)
+* - No native JSONB (uses JSON type)
+* - No array types
+* - Savepoints disabled for safety (MySQL has nested transaction quirks)
+*
+* @example
+* ```typescript
+* const adapter = new MySqlAdapter({
+*   url: 'mysql://user:pass@localhost:3306/mydb',
+*   pool: { max: 20 },
+* });
+*
+* await adapter.connect();
+* ```
+*/
 var MySqlAdapter = class extends DrizzleAdapter {
-  // getDrizzle memoization: drizzle v1's constructor builds a relational
-  // query builder per table in the relations config (~40 tables), and the
-  // service layer resolves an instance on every db access — construct once
-  // per relations object (identity-stable: the schema registry caches it
-  // and hands out a NEW object on invalidation, which naturally misses
-  // this cache and produces a fresh instance).
-  drizzleByRelations = /* @__PURE__ */ new WeakMap();
-  drizzleBare;
-  /**
-   * The database dialect - always 'mysql' for this adapter.
-   */
-  dialect = "mysql";
-  /**
-   * Adapter configuration.
-   */
-  config;
-  /**
-   * Connection pool instance.
-   */
-  pool = null;
-  /**
-   * Connection state flag.
-   */
-  connected = false;
-  /**
-   * Whether the server accepts `SELECT ... FOR SHARE`, read from its version
-   * string at connect. Undefined until then, which callers treat as not known.
-   */
-  sharedRowLock;
-  /**
-   * Creates a new MySQL adapter instance.
-   *
-   * @param config - Adapter configuration
-   */
-  constructor(config) {
-    super();
-    this.config = config;
-  }
-  /**
-   * Connect to the MySQL database.
-   * Creates a connection pool using mysql2.
-   *
-   * @remarks
-   * This method initializes the connection pool and verifies connectivity
-   * by executing a simple query. It is idempotent - calling it multiple
-   * times will not create multiple pools.
-   *
-   * @throws {DatabaseError} If connection fails
-   */
-  async connect() {
-    if (this.connected && this.pool) {
-      return;
-    }
-    try {
-      const poolConfig = this.buildPoolConfig();
-      this.pool = mysql.createPool(poolConfig);
-      const connection = await this.pool.getConnection();
-      try {
-        await connection.query("SELECT 1");
-        const { variant } = await checkDialectVersion(connection, "mysql", {
-          // Why: route variant warnings through the adapter's logger so
-          // users see a single, consistent log surface.
-          onWarning: (msg) => this.config.logger?.warn?.(msg)
-        });
-        this.sharedRowLock = acceptsForShare(variant);
-        this.connected = true;
-        if (this.config.logger?.info) {
-          this.config.logger.info("MySQL connection established", {
-            host: this.config.host ?? "from URL",
-            database: this.config.database ?? "from URL"
-          });
-        }
-      } finally {
-        connection.release();
-      }
-    } catch (error) {
-      if (this.pool) {
-        await this.pool.end().catch(() => {
-        });
-        this.pool = null;
-      }
-      throw this.classifyError(error);
-    }
-  }
-  /**
-   * Disconnect from the MySQL database.
-   * Gracefully closes the connection pool.
-   *
-   * @remarks
-   * This method is idempotent - calling it multiple times is safe.
-   * It waits for all connections to be released before shutting down.
-   */
-  async disconnect() {
-    const pool = this.pool;
-    this.pool = null;
-    this.drizzleBare = void 0;
-    this.drizzleByRelations = /* @__PURE__ */ new WeakMap();
-    if (!pool) {
-      return;
-    }
-    try {
-      await pool.end();
-      if (this.config.logger?.info) {
-        this.config.logger.info("MySQL connection closed");
-      }
-    } finally {
-      this.connected = false;
-    }
-  }
-  /**
-   * Check if connected to the database.
-   */
-  isConnected() {
-    return this.connected && this.pool !== null;
-  }
-  /**
-   * Get connection pool statistics.
-   * Returns null if not connected.
-   *
-   * @remarks
-   * MySQL2 pool exposes different stats than pg:
-   * - _allConnections: all connections
-   * - _freeConnections: idle connections
-   * - _connectionQueue: waiting requests
-   */
-  getPoolStats() {
-    if (!this.pool) {
-      return null;
-    }
-    const poolInternal = this.pool;
-    const internal = poolInternal.pool;
-    if (!internal) {
-      return {
-        total: 0,
-        idle: 0,
-        waiting: 0,
-        active: 0
-      };
-    }
-    const total = internal._allConnections?.length ?? 0;
-    const idle = internal._freeConnections?.length ?? 0;
-    const waiting = internal._connectionQueue?.length ?? 0;
-    return {
-      total,
-      idle,
-      waiting,
-      active: total - idle
-    };
-  }
-  /**
-   * Execute a raw SQL query.
-   *
-   * @param sql - SQL query string with ? placeholders
-   * @param params - Query parameters
-   * @returns Query results
-   *
-   * @throws {DatabaseError} If query execution fails
-   */
-  async executeQuery(sql, params = []) {
-    const pool = this.ensurePool();
-    const startTime = Date.now();
-    try {
-      const [rows] = await pool.query(
-        sql,
-        params
-      );
-      if (this.config.logger?.query) {
-        const durationMs = Date.now() - startTime;
-        this.config.logger.query(sql, params, durationMs);
-      }
-      return rows;
-    } catch (error) {
-      throw this.classifyError(error, sql);
-    }
-  }
-  /**
-   * Execute work within a transaction.
-   *
-   * @param work - Function containing transactional operations
-   * @param options - Transaction options (isolation level, timeout, retry)
-   * @returns Result of the work function
-   *
-   * @remarks
-   * MySQL transactions support isolation levels. Automatic retry is
-   * implemented for deadlocks (error 1213) when `retryCount` is specified.
-   *
-   * Note: Savepoints are disabled in this adapter for safety due to
-   * MySQL's quirks with nested transactions.
-   */
-  async transaction(work, options) {
-    return this.runInFlowTransaction(
-      () => this.runTransactionAttempts(work, options)
-    );
-  }
-  /** 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 pool.getConnection();
-      const startTime = Date.now();
-      let rollbackFailed = false;
-      let restore = null;
-      try {
-        restore = await this.beginTransaction(connection, options);
-        const ctx = this.createTransactionContext(connection);
-        const result = await work(ctx);
-        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(() => {
-          rollbackFailed = true;
-        });
-        lastError = error;
-        if (isApplicationError(error)) throw error;
-        const mysqlError = error;
-        const isRetryable = mysqlError.errno === 1213;
-        if (isRetryable && 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);
-  }
-  /**
-   * Get MySQL database capabilities.
-   *
-   * @remarks
-   * MySQL has some limitations:
-   * - No JSONB (uses JSON)
-   * - No arrays
-   * - No native ILIKE
-   * - No RETURNING clause
-   * - Savepoints disabled for safety
-   */
-  getCapabilities() {
-    return {
-      dialect: "mysql",
-      supportsJsonb: false,
-      // MySQL uses JSON, not JSONB
-      supportsJson: true,
-      supportsArrays: false,
-      // MySQL doesn't support array types
-      supportsGeneratedColumns: true,
-      // MySQL 5.7.6+
-      supportsFts: true,
-      // MySQL has FULLTEXT indexes
-      supportsIlike: false,
-      // No native ILIKE, use LOWER() LIKE
-      supportsReturning: false,
-      // No RETURNING clause in MySQL
-      supportsSavepoints: false,
-      // Disabled for safety per approved approach
-      supportsOnConflict: true,
-      // ON DUPLICATE KEY UPDATE
-      maxParamsPerQuery: 65535,
-      // MySQL limit
-      maxIdentifierLength: 64,
-      // MySQL limit
-      sharedRowLock: this.sharedRowLock
-      // Known once connected
-    };
-  }
-  /**
-   * Build a placeholder for MySQL (uses ? instead of $1, $2, etc.)
-   *
-   * @param _index - Parameter index (ignored for MySQL)
-   * @returns The ? placeholder
-   */
-  buildPlaceholder(_index) {
-    return "?";
-  }
-  /**
-   * Build multiple placeholders for MySQL.
-   *
-   * @param count - Number of placeholders needed
-   * @param _startIndex - Starting index (ignored for MySQL)
-   * @returns Comma-separated ? placeholders
-   */
-  buildPlaceholders(count, _startIndex = 0) {
-    return Array(count).fill("?").join(", ");
-  }
-  /**
-   * Escape an identifier for MySQL (uses backticks instead of double quotes).
-   *
-   * @param identifier - The identifier to escape
-   * @returns Escaped identifier with backticks
-   */
-  escapeIdentifier(identifier) {
-    return `\`${identifier.replace(/`/g, "``")}\``;
-  }
-  // ============================================================
-  // Protected Helper Methods
-  // ============================================================
-  /**
-   * Ensures pool is connected and returns it.
-   *
-   * @throws {DatabaseError} If not connected
-   */
-  ensurePool() {
-    if (!this.pool) {
-      throw createDatabaseError({
-        kind: "connection",
-        message: "MySqlAdapter is not connected. Call connect() first."
-      });
-    }
-    return this.pool;
-  }
-  /**
-   * Return the typed Drizzle instance for MySQL.
-   * Guarded for server-only usage and requires an active connection.
-   *
-   * @param schema - Optional schema for relational queries (db.query.*)
-   * @returns Drizzle ORM instance wrapping the mysql2 pool connection
-   * @throws {Error} If called in browser or not connected
-   */
-  getDrizzle(relations) {
-    if (typeof window !== "undefined") {
-      throw new Error("getDrizzle() is server-only");
-    }
-    const pool = this.ensurePool();
-    if (!relations) {
-      this.drizzleBare ??= this.poolDrizzle(pool);
-      return this.drizzleBare;
-    }
-    let cached = this.drizzleByRelations.get(relations);
-    if (!cached) {
-      cached = this.poolDrizzle(pool, relations);
-      this.drizzleByRelations.set(relations, cached);
-    }
-    return cached;
-  }
-  /**
-   * A Drizzle handle on the pool, for `getDrizzle`.
-   *
-   * Its `transaction` runs on a connection this adapter checks out and
-   * returns itself (`pinDrizzleTransactions`): destroyed rather than pooled
-   * when no ROLLBACK could be confirmed on it. And it counts for
-   * `transactionOpenInFlow`, as the adapter's does.
-   */
-  poolDrizzle(pool, relations) {
-    const onClient = (client) => relations ? drizzle({ client, relations }) : drizzle({ client });
-    const callbackPool = pool.pool;
-    return this.trackFlowTransactions(
-      this.pinDrizzleTransactions(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();
-          }
-        };
-      })
-    );
-  }
-  /**
-   * 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;
-    }
-    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;
-    }
-    if (this.config.charset) {
-      config.charset = this.config.charset;
-    }
-    config.multipleStatements = false;
-    config.dateStrings = false;
-    return config;
-  }
-  /**
-   * Begins a transaction with the specified options, and returns what it
-   * changed on the session for `restoreSession` to put back.
-   */
-  async beginTransaction(connection, options) {
-    if (options?.isolationLevel) {
-      const isolationMap = {
-        "read uncommitted": "READ UNCOMMITTED",
-        "read committed": "READ COMMITTED",
-        "repeatable read": "REPEATABLE READ",
-        serializable: "SERIALIZABLE"
-      };
-      const level = isolationMap[options.isolationLevel];
-      if (level) {
-        await connection.query(`SET TRANSACTION ISOLATION LEVEL ${level}`);
-      }
-    }
-    if (options?.readOnly) {
-      await connection.query("SET TRANSACTION READ ONLY");
-    }
-    await connection.query("START TRANSACTION");
-    if (options?.timeoutMs) {
-      const [rows] = await connection.query(
-        "SELECT @@SESSION.innodb_lock_wait_timeout AS timeout"
-      );
-      const previous = Number(rows[0]?.timeout);
-      const timeoutSeconds = Math.ceil(options.timeoutMs / 1e3);
-      await connection.query(
-        `SET SESSION innodb_lock_wait_timeout = ${timeoutSeconds}`
-      );
-      return { lockWaitTimeout: Number.isInteger(previous) ? previous : null };
-    }
-    return null;
-  }
-  /**
-   * Creates a TransactionContext for the given connection.
-   *
-   * @remarks
-   * Note: Savepoint methods are not implemented (set to undefined)
-   * as savepoints are disabled in this adapter per approved approach.
-   */
-  /**
-   * Upsert with the meaning `INSERT … ON CONFLICT (target)` has on PostgreSQL
-   * and SQLite, on the tables where MySQL can keep that promise.
-   *
-   * MySQL cannot limit a duplicate to one key: `ON DUPLICATE KEY UPDATE`
-   * fires on a collision with ANY unique key, and a failed insert does not
-   * say reliably which one. So the conflict target must be the table's only
-   * unique key apart from its primary key, and any other table is refused
-   * before anything is written. On such a table the row is inserted first —
-   * its validation and triggers apply, as they do before `ON CONFLICT`
-   * elsewhere — and a duplicate is resolved by a locking read of the target
-   * key, which sees the latest committed row rather than the transaction's
-   * snapshot. The row found is kept as it is when there is nothing to update
-   * (a no-op assignment would still run its update triggers), or updated by
-   * its key. No row there means the collision was on the primary key, and it
-   * is refused as `ON CONFLICT (target)` refuses it.
-   *
-   * The steps run in the caller's transaction, or in one of their own, since a
-   * locking read locks nothing past its statement under autocommit. Rows are
-   * read back by their primary key, so a trigger that rewrites the conflict
-   * value still returns the row stored. The conflict columns must also be
-   * given values: MySQL cannot look a row up by a key the database would only
-   * fill in itself. A conflict is resolved on the caller's key value: a
-   * BEFORE INSERT trigger that moves the key onto another row's value is
-   * refused as a unique violation rather than resolved onto that row. A failed insert rolls back only itself on MySQL, so a
-   * caller's transaction stays usable.
-   */
-  async upsert(table, data, options, executor) {
-    const tableObj = this.getTableObject(table);
-    if (!tableObj) return super.upsert(table, data, options, executor);
-    let target;
-    try {
-      target = this.upsertTarget(tableObj, table, data, options);
-    } catch (error) {
-      throw this.handleQueryError(error, "upsert", table);
-    }
-    if (executor === void 0) {
-      return this.transaction((tx) => tx.upsert(table, data, options));
-    }
-    try {
-      const db = executor;
-      if (target.nullKey) {
-        return await this.insertRow(db, tableObj, data) ?? data;
-      }
-      return await this.insertOrResolve(
-        db,
-        tableObj,
-        data,
-        options,
-        target.where
-      );
-    } catch (error) {
-      throw this.handleQueryError(error, "upsert", table);
-    }
-  }
-  /**
-   * What an upsert is keyed on: the target's condition, and whether its key
-   * holds a NULL. Refuses a target this dialect cannot keep to, and a conflict
-   * column left for the database to fill — MySQL cannot look a row up by a key
-   * value only the database would supply.
-   */
-  upsertTarget(tableObj, table, data, options) {
-    this.assertUpsertTarget(table, data, options, true);
-    const key = this.conflictKey(tableObj, table, options.conflictColumns);
-    const values = options.conflictColumns.map((column) => data[column]);
-    return {
-      where: and(...key.map((column, i) => eq(column, values[i]))),
-      nullKey: values.some((value) => value === null)
-    };
-  }
-  /**
-   * The table's columns for a conflict target, refusing a target MySQL cannot
-   * keep to: one that is not a primary or unique key, which an update could
-   * spread over several rows, and one beside which the table has another
-   * unique key, a collision on which MySQL would not tell apart.
-   */
-  conflictKey(tableObj, table, conflictColumns) {
-    const record = tableObj;
-    const columns = conflictColumns.map((name) => record[name]);
-    const names = new Set(columns.map((column) => column?.name));
-    const isTarget = (key) => key.length === names.size && key.every((name) => names.has(name));
-    const { primary, unique } = keysOf(tableObj);
-    if (primary.length === 0) {
-      throw createDatabaseError({
-        kind: "query",
-        message: `upsert on ${table}: MySQL upserts need a table with a primary key, to read back the row they write.`
-      });
-    }
-    const known = columns.every((column) => column !== void 0);
-    if (!known || !(isTarget(primary) || unique.some((k) => isTarget(k.columns)))) {
-      throw createDatabaseError({
-        kind: "query",
-        message: `upsert on ${table}: the conflict columns (${conflictColumns.join(", ")}) are not a primary or unique key of the table.`
-      });
-    }
-    const others = unique.filter((key) => !isTarget(key.columns));
-    if (others.length > 0) {
-      throw createDatabaseError({
-        kind: "query",
-        message: `upsert on ${table}: MySQL cannot limit a duplicate to the conflict columns (${conflictColumns.join(", ")}) while the table has other unique keys (${others.map((key) => key.name).join(", ")}). Upsert only on a table whose one unique key besides the primary key is the conflict target, or insert and update inside a transaction.`
-      });
-    }
-    return columns;
-  }
-  /** The update an upsert applies to an existing row: never its key. */
-  updateValues(data, options) {
-    const key = new Set(options.conflictColumns);
-    const update = {};
-    for (const column of options.updateColumns ?? Object.keys(data)) {
-      if (!key.has(column) && column in data) update[column] = data[column];
-    }
-    return update;
-  }
-  /** The row matching `where`, by a locking (current) read. */
-  async lockedRow(db, tableObj, where) {
-    const rows = await db.select().from(tableObj).where(where).limit(1).for("update");
-    return rows[0];
-  }
-  /**
-   * Insert the row, or resolve a duplicate on the target key. The insert is
-   * read back by the primary key it reports, not by the conflict key: a
-   * BEFORE INSERT trigger may have rewritten the conflict value, and the row
-   * stored is the one to return.
-   *
-   * A duplicate is resolved when a row holds the TARGET key, whichever unique
-   * key MySQL names in its error. PostgreSQL checks the target's index before
-   * any other, so a row colliding on the target and on another key resolves
-   * on the target there too; refusing it here because MySQL happened to check
-   * the other index first would answer that case differently. A target row
-   * committed by another transaction after this insert failed is the order in
-   * which that transaction ran first, where PostgreSQL also resolves on it.
-   */
-  async insertOrResolve(db, tableObj, data, options, where) {
-    let failure;
-    try {
-      const stored = await this.insertRow(db, tableObj, data);
-      return stored ?? await this.lockedRow(db, tableObj, where);
-    } catch (error) {
-      if (this.classifyError(error).kind !== "unique_violation") throw error;
-      failure = error;
-    }
-    const existing = await this.lockedRow(db, tableObj, where);
-    if (existing === void 0) throw failure;
-    const update = this.updateValues(data, options);
-    if (Object.keys(update).length === 0) return existing;
-    await db.update(tableObj).set(update).where(where);
-    const identity = this.byIdentity(tableObj, {
-      ...existing,
-      ...update
-    });
-    const updated = identity === void 0 ? void 0 : await this.lockedRow(db, tableObj, identity);
-    return updated ?? this.lockedRow(db, tableObj, where);
-  }
-  /**
-   * Insert a row and read it back by its primary key: the value the caller
-   * gave, or the one MySQL or the model generated, which `$returningId()`
-   * reports and a given value it does not. Undefined when the table has no
-   * primary key to read by.
-   */
-  async insertRow(db, tableObj, data) {
-    const [generated] = await db.insert(tableObj).values(data).$returningId();
-    const given = Object.fromEntries(
-      Object.entries(data).filter(
-        ([, value]) => value !== void 0 && value !== null
-      )
-    );
-    const identity = this.byIdentity(tableObj, { ...generated, ...given });
-    return identity === void 0 ? void 0 : this.lockedRow(db, tableObj, identity);
-  }
-  /**
-   * A row's primary key as a condition, from a record keyed as the model's
-   * properties are. Undefined when the table has no primary key or the record
-   * lacks part of it.
-   */
-  byIdentity(tableObj, record) {
-    const primary = new Set(keysOf(tableObj).primary);
-    const parts = Object.entries(getColumns(tableObj)).filter(
-      ([, column]) => primary.has(column.name)
-    );
-    if (parts.length === 0 || parts.some(
-      ([name]) => record[name] === void 0 || record[name] === null
-    )) {
-      return void 0;
-    }
-    return and(
-      ...parts.map(([name, column]) => eq(column, record[name]))
-    );
-  }
-  /** A table-level `primaryKey({ columns })`, read through the MySQL table config. */
-  compositePrimaryKey(tableObj) {
-    return getTableConfig(
-      tableObj
-    ).primaryKeys.flatMap((key) => key.columns);
-  }
-  createTransactionContext(connection) {
-    const txConnection = connection.connection;
-    const txHandles = this.transactionDrizzleHandles(
-      (relations) => relations ? drizzle({ client: txConnection, relations }) : drizzle({ client: txConnection })
-    );
-    const txDb = txHandles.bare;
-    return {
-      drizzleWithRelations: txHandles.withRelations,
-      execute: async (sql, params = []) => {
-        const [rows] = await connection.query(
-          sql,
-          params
-        );
-        return rows;
-      },
-      // Run on the transaction-bound Drizzle instance rather than the pool, so
-      // the statement is part of this transaction and sees its uncommitted rows.
-      runStatement: async (statement) => {
-        await txDb().execute(statement);
-      },
-      // mysql2 answers a `[rows, fields]` tuple; the transaction-bound instance
-      // keeps the read inside this transaction so it sees its uncommitted writes.
-      queryStatement: async (statement) => {
-        const result = await txDb().execute(statement);
-        if (!Array.isArray(result)) {
-          throw this.createDatabaseError(
-            "query",
-            "Drizzle statement returned a result shape this adapter does not recognise; refusing to report it as an empty result.",
-            void 0
-          );
-        }
-        return result[0];
-      },
-      lockRow: async (table, id) => {
-        const idColumn = this.escapeIdentifier("id");
-        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 columns = Object.keys(mapped);
-        const values = Object.values(mapped);
-        const placeholders = this.buildPlaceholders(values.length, 0);
-        const sql = `INSERT INTO ${this.escapeIdentifier(table)} (${columns.map((c) => this.escapeIdentifier(c)).join(", ")}) VALUES (${placeholders})`;
-        const [result] = await connection.query(sql, values);
-        const ret = options?.returning;
-        if (Array.isArray(ret) && ret.length === 0) {
-          return void 0;
-        }
-        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(", ");
-        const selectList = spelled ? `${projected}, ${spelled}` : projected;
-        const idValue = result.insertId ? result.insertId : mapped.id;
-        if (idValue !== void 0) {
-          const [rows2] = await connection.query(
-            `SELECT ${selectList} FROM ${this.escapeIdentifier(table)} WHERE id = ?`,
-            [idValue]
-          );
-          return this.mapRowFromRawSql(insertTableObj, rows2[0], aliases);
-        }
-        const whereClauses = columns.map(
-          (c) => `${this.escapeIdentifier(c)} = ?`
-        );
-        const [rows] = await connection.query(
-          `SELECT ${selectList} FROM ${this.escapeIdentifier(table)} WHERE ${whereClauses.join(" AND ")} LIMIT 1`,
-          values
-        );
-        return this.mapRowFromRawSql(insertTableObj, rows[0], aliases);
-      },
-      insertMany: async (table, data, options) => {
-        if (data.length === 0) return [];
-        const retMany = options?.returning;
-        const skipReread = Array.isArray(retMany) && retMany.length === 0;
-        const tableObj = this.getTableObject(table);
-        const mappedRecords = data.map((r) => this.mapRowToRawSql(tableObj, r));
-        const columns = Object.keys(mappedRecords[0]);
-        const allValues = [];
-        const valuesClauses = [];
-        for (const record of mappedRecords) {
-          const placeholders = [];
-          for (const col of columns) {
-            allValues.push(record[col]);
-            placeholders.push("?");
-          }
-          valuesClauses.push(`(${placeholders.join(", ")})`);
-        }
-        const sql = `INSERT INTO ${this.escapeIdentifier(table)} (${columns.map((c) => this.escapeIdentifier(c)).join(", ")}) VALUES ${valuesClauses.join(", ")}`;
-        const [result] = await connection.query(
-          sql,
-          allValues
-        );
-        if (!skipReread && result.insertId && result.affectedRows > 0) {
-          const ids = [];
-          for (let i = 0; i < result.affectedRows; i++) {
-            ids.push(result.insertId + i);
-          }
-          const placeholders = ids.map(() => "?").join(", ");
-          const bulkAliases = this.dateWallClockAliases(tableObj, "*");
-          const bulkSpelled = bulkAliases.map(
-            (a) => `DATE_FORMAT(${this.escapeIdentifier(a.sqlName)}, '%Y-%m-%dT%H:%i:%s.%f') AS ${this.escapeIdentifier(a.alias)}`
-          ).join(", ");
-          const [rows] = await connection.query(
-            `SELECT *${bulkSpelled ? `, ${bulkSpelled}` : ""} FROM ${this.escapeIdentifier(table)} WHERE id IN (${placeholders})`,
-            ids
-          );
-          return rows.map(
-            (r) => this.mapRowFromRawSql(tableObj, r, bulkAliases)
-          );
-        }
-        return [];
-      },
-      // Adapter-built, as `insert` above is; `transactionUpdate` says why.
-      // A column the model does not declare binds natively, as every value
-      // on this path's insert does.
-      update: this.transactionUpdate(
-        txDb,
-        async (statement) => {
-          await txDb().execute(statement);
-          return void 0;
-        },
-        // Structured values as JSON text: mysql2's formatter spells an object
-        // as `key = value` pairs and an array as a value list, neither JSON.
-        (value) => this.bindUnmodeledStructuredAsJson(value)
-      ),
-      ...this.createTransactionForwarders(txDb),
-      // Savepoints disabled per approved approach
-      savepoint: void 0,
-      rollbackToSavepoint: void 0,
-      releaseSavepoint: void 0
-    };
-  }
-  /**
-   * Classifies a MySQL error into a DatabaseError.
-   *
-   * @param error - Original error from mysql2
-   * @param sql - SQL statement that caused the error (optional)
-   * @returns DatabaseError with proper classification
-   */
-  classifyError(error, sql) {
-    if (isDatabaseError(error)) return error;
-    const mysqlError = this.driverErrorIn(error, (candidate) => typeof candidate.errno === "number");
-    const kind = mysqlError.errno && MYSQL_ERROR_CODES[mysqlError.errno] || "unknown";
-    let message = mysqlError.message ?? String(error);
-    if (sql && kind === "query") {
-      message = `Query failed: ${message}`;
-    }
-    return createDatabaseError({
-      kind,
-      message,
-      code: mysqlError.code ?? mysqlError.errno?.toString(),
-      detail: mysqlError.sql,
-      cause: error instanceof Error ? error : void 0
-    });
-  }
+	drizzleByRelations = /* @__PURE__ */ new WeakMap();
+	drizzleBare;
+	/**
+	* The database dialect - always 'mysql' for this adapter.
+	*/
+	dialect = "mysql";
+	/**
+	* Adapter configuration.
+	*/
+	config;
+	/**
+	* Connection pool instance.
+	*/
+	pool = null;
+	/**
+	* Connection state flag.
+	*/
+	connected = false;
+	/**
+	* Whether the server accepts `SELECT ... FOR SHARE`, read from its version
+	* string at connect. Undefined until then, which callers treat as not known.
+	*/
+	sharedRowLock;
+	/**
+	* Creates a new MySQL adapter instance.
+	*
+	* @param config - Adapter configuration
+	*/
+	constructor(config) {
+		super();
+		this.config = config;
+	}
+	/**
+	* Connect to the MySQL database.
+	* Creates a connection pool using mysql2.
+	*
+	* @remarks
+	* This method initializes the connection pool and verifies connectivity
+	* by executing a simple query. It is idempotent - calling it multiple
+	* times will not create multiple pools.
+	*
+	* @throws {DatabaseError} If connection fails
+	*/
+	async connect() {
+		if (this.connected && this.pool) return;
+		try {
+			const poolConfig = this.buildPoolConfig();
+			const pool = mysql.createPool(poolConfig);
+			boundPoolWait(pool.pool, poolConfig.connectTimeout ?? 0);
+			this.pool = pool;
+			const connection = await this.pool.getConnection();
+			try {
+				await connection.query("SELECT 1");
+				const { variant } = await checkDialectVersion(connection, "mysql", { onWarning: (msg) => this.config.logger?.warn?.(msg) });
+				this.sharedRowLock = acceptsForShare(variant);
+				this.connected = true;
+				if (this.config.logger?.info) this.config.logger.info("MySQL connection established", {
+					host: this.config.host ?? "from URL",
+					database: this.config.database ?? "from URL"
+				});
+			} finally {
+				connection.release();
+			}
+		} catch (error) {
+			if (this.pool) {
+				await this.pool.end().catch(() => {});
+				this.pool = null;
+			}
+			throw this.classifyError(error);
+		}
+	}
+	/**
+	* Disconnect from the MySQL database.
+	* Gracefully closes the connection pool.
+	*
+	* @remarks
+	* This method is idempotent - calling it multiple times is safe.
+	* It waits for all connections to be released before shutting down.
+	*/
+	async disconnect() {
+		const pool = this.pool;
+		this.pool = null;
+		this.drizzleBare = void 0;
+		this.drizzleByRelations = /* @__PURE__ */ new WeakMap();
+		if (!pool) return;
+		try {
+			await pool.end();
+			if (this.config.logger?.info) this.config.logger.info("MySQL connection closed");
+		} finally {
+			this.connected = false;
+		}
+	}
+	/**
+	* Check if connected to the database.
+	*/
+	isConnected() {
+		return this.connected && this.pool !== null;
+	}
+	/**
+	* Get connection pool statistics.
+	* Returns null if not connected.
+	*
+	* @remarks
+	* MySQL2 pool exposes different stats than pg:
+	* - _allConnections: all connections
+	* - _freeConnections: idle connections
+	* - _connectionQueue: waiting requests
+	*/
+	getPoolStats() {
+		if (!this.pool) return null;
+		const internal = this.pool.pool;
+		if (!internal) return {
+			total: 0,
+			idle: 0,
+			waiting: 0,
+			active: 0
+		};
+		const total = internal._allConnections?.length ?? 0;
+		const idle = internal._freeConnections?.length ?? 0;
+		return {
+			total,
+			idle,
+			waiting: internal._connectionQueue?.length ?? 0,
+			active: total - idle
+		};
+	}
+	/**
+	* Execute a raw SQL query.
+	*
+	* @param sql - SQL query string with ? placeholders
+	* @param params - Query parameters
+	* @returns Query results
+	*
+	* @throws {DatabaseError} If query execution fails
+	*/
+	async executeQuery(sql, params = []) {
+		const pool = this.ensurePool();
+		const startTime = Date.now();
+		try {
+			this.notePoolAccess(sql);
+			const [rows] = await pool.query(sql, params);
+			if (this.config.logger?.query) {
+				const durationMs = Date.now() - startTime;
+				this.config.logger.query(sql, params, durationMs);
+			}
+			return rows;
+		} catch (error) {
+			throw this.classifyError(error, sql);
+		}
+	}
+	/**
+	* Execute work within a transaction.
+	*
+	* @param work - Function containing transactional operations
+	* @param options - Transaction options (isolation level, timeout, retry)
+	* @returns Result of the work function
+	*
+	* @remarks
+	* MySQL transactions support isolation levels. Automatic retry is
+	* implemented for deadlocks (error 1213) when `retryCount` is specified.
+	*
+	* Note: Savepoints are disabled in this adapter for safety due to
+	* MySQL's quirks with nested transactions.
+	*/
+	async transaction(work, options) {
+		return this.runInFlowTransaction(() => this.runTransactionAttempts(work, options));
+	}
+	/** 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 = {};
+			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;
+			} catch (error) {
+				await connection.query("ROLLBACK").catch(() => {
+					rollbackFailed = true;
+				});
+				lastError = error;
+				if (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);
+	}
+	/**
+	* Get MySQL database capabilities.
+	*
+	* @remarks
+	* MySQL has some limitations:
+	* - No JSONB (uses JSON)
+	* - No arrays
+	* - No native ILIKE
+	* - No RETURNING clause
+	* - Savepoints disabled for safety
+	*/
+	getCapabilities() {
+		return {
+			dialect: "mysql",
+			supportsJsonb: false,
+			supportsJson: true,
+			supportsArrays: false,
+			supportsGeneratedColumns: true,
+			supportsFts: true,
+			supportsIlike: false,
+			supportsReturning: false,
+			supportsSavepoints: false,
+			supportsOnConflict: true,
+			maxParamsPerQuery: 65535,
+			maxIdentifierLength: 64,
+			sharedRowLock: this.sharedRowLock
+		};
+	}
+	/**
+	* Build a placeholder for MySQL (uses ? instead of $1, $2, etc.)
+	*
+	* @param _index - Parameter index (ignored for MySQL)
+	* @returns The ? placeholder
+	*/
+	buildPlaceholder(_index) {
+		return "?";
+	}
+	/**
+	* Build multiple placeholders for MySQL.
+	*
+	* @param count - Number of placeholders needed
+	* @param _startIndex - Starting index (ignored for MySQL)
+	* @returns Comma-separated ? placeholders
+	*/
+	buildPlaceholders(count, _startIndex = 0) {
+		return Array(count).fill("?").join(", ");
+	}
+	/**
+	* Escape an identifier for MySQL (uses backticks instead of double quotes).
+	*
+	* @param identifier - The identifier to escape
+	* @returns Escaped identifier with backticks
+	*/
+	escapeIdentifier(identifier) {
+		return `\`${identifier.replace(/`/g, "``")}\``;
+	}
+	/**
+	* Ensures pool is connected and returns it.
+	*
+	* @throws {DatabaseError} If not connected
+	*/
+	ensurePool() {
+		if (!this.pool) throw createDatabaseError({
+			kind: "connection",
+			message: "MySqlAdapter is not connected. Call connect() first."
+		});
+		return this.pool;
+	}
+	/**
+	* Return the typed Drizzle instance for MySQL.
+	* Guarded for server-only usage and requires an active connection.
+	*
+	* @param schema - Optional schema for relational queries (db.query.*)
+	* @returns Drizzle ORM instance wrapping the mysql2 pool connection
+	* @throws {Error} If called in browser or not connected
+	*/
+	getDrizzle(relations) {
+		if (typeof window !== "undefined") throw new Error("getDrizzle() is server-only");
+		const pool = this.ensurePool();
+		if (!relations) {
+			this.drizzleBare ??= this.poolDrizzle(pool);
+			return this.drizzleBare;
+		}
+		let cached = this.drizzleByRelations.get(relations);
+		if (!cached) {
+			cached = this.poolDrizzle(pool, relations);
+			this.drizzleByRelations.set(relations, cached);
+		}
+		return cached;
+	}
+	/**
+	* A Drizzle handle on the pool, for `getDrizzle`.
+	*
+	* Its `transaction` runs on a connection this adapter checks out and
+	* returns itself (`pinDrizzleTransactions`): destroyed rather than pooled
+	* when no ROLLBACK could be confirmed on it. And it counts for
+	* `transactionOpenInFlow`, as the adapter's does.
+	*/
+	poolDrizzle(pool, relations) {
+		const onClient = (client) => relations ? drizzle({
+			client,
+			relations
+		}) : drizzle({ client });
+		const callbackPool = this.observedPool(pool.pool, [
+			"query",
+			"execute",
+			"getConnection"
+		]);
+		return this.trackFlowTransactions(this.pinDrizzleTransactions(onClient(callbackPool), async () => {
+			const connection = await this.connectFlowTransaction(() => pool.getConnection());
+			return {
+				drizzle: onClient(connection.connection),
+				rollback: () => connection.query("ROLLBACK"),
+				release: (dirty) => {
+					if (dirty) connection.destroy();
+					else connection.release();
+				}
+			};
+		}));
+	}
+	/**
+	* 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;
+		}
+		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;
+		if (this.config.charset) config.charset = this.config.charset;
+		config.multipleStatements = false;
+		config.dateStrings = false;
+		return config;
+	}
+	/**
+	* Begins a transaction with the specified options, recording in `changed`
+	* each session setting it changes, as it changes it, for `restoreSession`
+	* to put back.
+	*/
+	async beginTransaction(connection, options, changed) {
+		if (options?.isolationLevel) {
+			const level = {
+				"read uncommitted": "READ UNCOMMITTED",
+				"read committed": "READ COMMITTED",
+				"repeatable read": "REPEATABLE READ",
+				serializable: "SERIALIZABLE"
+			}[options.isolationLevel];
+			if (level) await connection.query(`SET TRANSACTION ISOLATION LEVEL ${level}`);
+		}
+		if (options?.readOnly) await connection.query("SET TRANSACTION READ ONLY");
+		await connection.query("START TRANSACTION");
+		if (options?.timeoutMs) {
+			const [rows] = await connection.query("SELECT @@SESSION.innodb_lock_wait_timeout AS timeout");
+			const previous = Number(rows[0]?.timeout);
+			const timeoutSeconds = Math.ceil(options.timeoutMs / 1e3);
+			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;
+		}
+	}
+	/**
+	* Creates a TransactionContext for the given connection.
+	*
+	* @remarks
+	* Note: Savepoint methods are not implemented (set to undefined)
+	* as savepoints are disabled in this adapter per approved approach.
+	*/
+	/**
+	* Upsert with the meaning `INSERT … ON CONFLICT (target)` has on PostgreSQL
+	* and SQLite, on the tables where MySQL can keep that promise.
+	*
+	* MySQL cannot limit a duplicate to one key: `ON DUPLICATE KEY UPDATE`
+	* fires on a collision with ANY unique key, and a failed insert does not
+	* say reliably which one. So the conflict target must be the table's only
+	* unique key apart from its primary key, and any other table is refused
+	* before anything is written. On such a table the row is inserted first —
+	* its validation and triggers apply, as they do before `ON CONFLICT`
+	* elsewhere — and a duplicate is resolved by a locking read of the target
+	* key, which sees the latest committed row rather than the transaction's
+	* snapshot. The row found is kept as it is when there is nothing to update
+	* (a no-op assignment would still run its update triggers), or updated by
+	* its key. No row there means the collision was on the primary key, and it
+	* is refused as `ON CONFLICT (target)` refuses it.
+	*
+	* The steps run in the caller's transaction, or in one of their own, since a
+	* locking read locks nothing past its statement under autocommit. Rows are
+	* read back by their primary key, so a trigger that rewrites the conflict
+	* value still returns the row stored. The conflict columns must also be
+	* given values: MySQL cannot look a row up by a key the database would only
+	* fill in itself. A conflict is resolved on the caller's key value: a
+	* BEFORE INSERT trigger that moves the key onto another row's value is
+	* refused as a unique violation rather than resolved onto that row. A failed insert rolls back only itself on MySQL, so a
+	* caller's transaction stays usable.
+	*/
+	async upsert(table, data, options, executor) {
+		const tableObj = this.getTableObject(table);
+		if (!tableObj) return super.upsert(table, data, options, executor);
+		let target;
+		try {
+			target = this.upsertTarget(tableObj, table, data, options);
+		} catch (error) {
+			throw this.handleQueryError(error, "upsert", table);
+		}
+		if (executor === void 0) return this.transaction((tx) => tx.upsert(table, data, options));
+		try {
+			const db = executor;
+			if (target.nullKey) return await this.insertRow(db, tableObj, data) ?? data;
+			return await this.insertOrResolve(db, tableObj, data, options, target.where);
+		} catch (error) {
+			throw this.handleQueryError(error, "upsert", table);
+		}
+	}
+	/**
+	* What an upsert is keyed on: the target's condition, and whether its key
+	* holds a NULL. Refuses a target this dialect cannot keep to, and a conflict
+	* column left for the database to fill — MySQL cannot look a row up by a key
+	* value only the database would supply.
+	*/
+	upsertTarget(tableObj, table, data, options) {
+		this.assertUpsertTarget(table, data, options, true);
+		const key = this.conflictKey(tableObj, table, options.conflictColumns);
+		const values = options.conflictColumns.map((column) => data[column]);
+		return {
+			where: and(...key.map((column, i) => eq(column, values[i]))),
+			nullKey: values.some((value) => value === null)
+		};
+	}
+	/**
+	* The table's columns for a conflict target, refusing a target MySQL cannot
+	* keep to: one that is not a primary or unique key, which an update could
+	* spread over several rows, and one beside which the table has another
+	* unique key, a collision on which MySQL would not tell apart.
+	*/
+	conflictKey(tableObj, table, conflictColumns) {
+		const record = tableObj;
+		const columns = conflictColumns.map((name) => record[name]);
+		const names = new Set(columns.map((column) => column?.name));
+		const isTarget = (key) => key.length === names.size && key.every((name) => names.has(name));
+		const { primary, unique } = keysOf(tableObj);
+		if (primary.length === 0) throw createDatabaseError({
+			kind: "query",
+			message: `upsert on ${table}: MySQL upserts need a table with a primary key, to read back the row they write.`
+		});
+		if (!columns.every((column) => column !== void 0) || !(isTarget(primary) || unique.some((k) => isTarget(k.columns)))) throw createDatabaseError({
+			kind: "query",
+			message: `upsert on ${table}: the conflict columns (${conflictColumns.join(", ")}) are not a primary or unique key of the table.`
+		});
+		const others = unique.filter((key) => !isTarget(key.columns));
+		if (others.length > 0) throw createDatabaseError({
+			kind: "query",
+			message: `upsert on ${table}: MySQL cannot limit a duplicate to the conflict columns (${conflictColumns.join(", ")}) while the table has other unique keys (${others.map((key) => key.name).join(", ")}). Upsert only on a table whose one unique key besides the primary key is the conflict target, or insert and update inside a transaction.`
+		});
+		return columns;
+	}
+	/** The update an upsert applies to an existing row: never its key. */
+	updateValues(data, options) {
+		const key = new Set(options.conflictColumns);
+		const update = {};
+		for (const column of options.updateColumns ?? Object.keys(data)) if (!key.has(column) && column in data) update[column] = data[column];
+		return update;
+	}
+	/** The row matching `where`, by a locking (current) read. */
+	async lockedRow(db, tableObj, where) {
+		return (await db.select().from(tableObj).where(where).limit(1).for("update"))[0];
+	}
+	/**
+	* Insert the row, or resolve a duplicate on the target key. The insert is
+	* read back by the primary key it reports, not by the conflict key: a
+	* BEFORE INSERT trigger may have rewritten the conflict value, and the row
+	* stored is the one to return.
+	*
+	* A duplicate is resolved when a row holds the TARGET key, whichever unique
+	* key MySQL names in its error. PostgreSQL checks the target's index before
+	* any other, so a row colliding on the target and on another key resolves
+	* on the target there too; refusing it here because MySQL happened to check
+	* the other index first would answer that case differently. A target row
+	* committed by another transaction after this insert failed is the order in
+	* which that transaction ran first, where PostgreSQL also resolves on it.
+	*/
+	async insertOrResolve(db, tableObj, data, options, where) {
+		let failure;
+		try {
+			return await this.insertRow(db, tableObj, data) ?? await this.lockedRow(db, tableObj, where);
+		} catch (error) {
+			if (this.classifyError(error).kind !== "unique_violation") throw error;
+			failure = error;
+		}
+		const existing = await this.lockedRow(db, tableObj, where);
+		if (existing === void 0) throw failure;
+		const update = this.updateValues(data, options);
+		if (Object.keys(update).length === 0) return existing;
+		await db.update(tableObj).set(update).where(where);
+		const identity = this.byIdentity(tableObj, {
+			...existing,
+			...update
+		});
+		return (identity === void 0 ? void 0 : await this.lockedRow(db, tableObj, identity)) ?? this.lockedRow(db, tableObj, where);
+	}
+	/**
+	* Insert a row and read it back by its primary key: the value the caller
+	* gave, or the one MySQL or the model generated, which `$returningId()`
+	* reports and a given value it does not. Undefined when the table has no
+	* primary key to read by.
+	*/
+	async insertRow(db, tableObj, data) {
+		const [generated] = await db.insert(tableObj).values(data).$returningId();
+		const given = Object.fromEntries(Object.entries(data).filter(([, value]) => value !== void 0 && value !== null));
+		const identity = this.byIdentity(tableObj, {
+			...generated,
+			...given
+		});
+		return identity === void 0 ? void 0 : this.lockedRow(db, tableObj, identity);
+	}
+	/**
+	* A row's primary key as a condition, from a record keyed as the model's
+	* properties are. Undefined when the table has no primary key or the record
+	* lacks part of it.
+	*/
+	byIdentity(tableObj, record) {
+		const primary = new Set(keysOf(tableObj).primary);
+		const parts = Object.entries(getColumns(tableObj)).filter(([, column]) => primary.has(column.name));
+		if (parts.length === 0 || parts.some(([name]) => record[name] === void 0 || record[name] === null)) return;
+		return and(...parts.map(([name, column]) => eq(column, record[name])));
+	}
+	/** A table-level `primaryKey({ columns })`, read through the MySQL table config. */
+	compositePrimaryKey(tableObj) {
+		return getTableConfig(tableObj).primaryKeys.flatMap((key) => key.columns);
+	}
+	createTransactionContext(connection) {
+		const txConnection = connection.connection;
+		const txHandles = this.transactionDrizzleHandles((relations) => relations ? drizzle({
+			client: txConnection,
+			relations
+		}) : drizzle({ client: txConnection }));
+		const txDb = txHandles.bare;
+		return {
+			drizzleWithRelations: txHandles.withRelations,
+			execute: async (sql, params = []) => {
+				const [rows] = await connection.query(sql, params);
+				return rows;
+			},
+			runStatement: async (statement) => {
+				await txDb().execute(statement);
+			},
+			queryStatement: async (statement) => {
+				const result = await txDb().execute(statement);
+				if (!Array.isArray(result)) throw this.createDatabaseError("query", "Drizzle statement returned a result shape this adapter does not recognise; refusing to report it as an empty result.", void 0);
+				return result[0];
+			},
+			lockRow: async (table, id) => {
+				const idColumn = this.escapeIdentifier("id");
+				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 columns = Object.keys(mapped);
+				const values = Object.values(mapped);
+				const placeholders = this.buildPlaceholders(values.length, 0);
+				const sql = `INSERT INTO ${this.escapeIdentifier(table)} (${columns.map((c) => this.escapeIdentifier(c)).join(", ")}) VALUES (${placeholders})`;
+				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(", ");
+				const selectList = spelled ? `${projected}, ${spelled}` : projected;
+				const idValue = result.insertId ? result.insertId : mapped.id;
+				if (idValue !== void 0) {
+					const [rows] = await connection.query(`SELECT ${selectList} FROM ${this.escapeIdentifier(table)} WHERE id = ?`, [idValue]);
+					return this.mapRowFromRawSql(insertTableObj, rows[0], aliases);
+				}
+				const whereClauses = columns.map((c) => `${this.escapeIdentifier(c)} = ?`);
+				const [rows] = await connection.query(`SELECT ${selectList} FROM ${this.escapeIdentifier(table)} WHERE ${whereClauses.join(" AND ")} LIMIT 1`, values);
+				return this.mapRowFromRawSql(insertTableObj, rows[0], aliases);
+			},
+			insertMany: async (table, data, options) => {
+				if (data.length === 0) return [];
+				const retMany = options?.returning;
+				const skipReread = Array.isArray(retMany) && retMany.length === 0;
+				const tableObj = this.getTableObject(table);
+				const mappedRecords = data.map((r) => this.mapRowToRawSql(tableObj, r));
+				const columns = Object.keys(mappedRecords[0]);
+				const allValues = [];
+				const valuesClauses = [];
+				for (const record of mappedRecords) {
+					const placeholders = [];
+					for (const col of columns) {
+						allValues.push(record[col]);
+						placeholders.push("?");
+					}
+					valuesClauses.push(`(${placeholders.join(", ")})`);
+				}
+				const sql = `INSERT INTO ${this.escapeIdentifier(table)} (${columns.map((c) => this.escapeIdentifier(c)).join(", ")}) VALUES ${valuesClauses.join(", ")}`;
+				const [result] = await connection.query(sql, allValues);
+				if (!skipReread && result.insertId && result.affectedRows > 0) {
+					const ids = [];
+					for (let i = 0; i < result.affectedRows; i++) ids.push(result.insertId + i);
+					const placeholders = ids.map(() => "?").join(", ");
+					const bulkAliases = this.dateWallClockAliases(tableObj, "*");
+					const bulkSpelled = bulkAliases.map((a) => `DATE_FORMAT(${this.escapeIdentifier(a.sqlName)}, '%Y-%m-%dT%H:%i:%s.%f') AS ${this.escapeIdentifier(a.alias)}`).join(", ");
+					const [rows] = await connection.query(`SELECT *${bulkSpelled ? `, ${bulkSpelled}` : ""} FROM ${this.escapeIdentifier(table)} WHERE id IN (${placeholders})`, ids);
+					return rows.map((r) => this.mapRowFromRawSql(tableObj, r, bulkAliases));
+				}
+				return [];
+			},
+			update: this.transactionUpdate(txDb, async (statement) => {
+				await txDb().execute(statement);
+			}, (value) => this.bindUnmodeledStructuredAsJson(value)),
+			...this.createTransactionForwarders(txDb),
+			savepoint: void 0,
+			rollbackToSavepoint: void 0,
+			releaseSavepoint: void 0
+		};
+	}
+	/**
+	* Classifies a MySQL error into a DatabaseError.
+	*
+	* @param error - Original error from mysql2
+	* @param sql - SQL statement that caused the error (optional)
+	* @returns DatabaseError with proper classification
+	*/
+	classifyError(error, sql) {
+		if (isDatabaseError(error)) return error;
+		const mysqlError = this.driverErrorIn(error, (candidate) => typeof candidate.errno === "number");
+		const kind = mysqlError.errno && MYSQL_ERROR_CODES[mysqlError.errno] || "unknown";
+		let message = mysqlError.message ?? String(error);
+		if (sql && kind === "query") message = `Query failed: ${message}`;
+		return createDatabaseError({
+			kind,
+			message,
+			code: mysqlError.code ?? mysqlError.errno?.toString(),
+			detail: mysqlError.sql,
+			cause: error instanceof Error ? error : void 0
+		});
+	}
 };
-var TABLE_KEYS = /* @__PURE__ */ new WeakMap();
+const TABLE_KEYS = /* @__PURE__ */ new WeakMap();
+/**
+* A table's primary key and its unique keys other than the primary key, read
+* from its model once and kept for the table's lifetime: a model is not
+* changed in place, a new schema brings new table objects.
+*/
 function keysOf(tableObj) {
-  const cached = TABLE_KEYS.get(tableObj);
-  if (cached) return cached;
-  const config = getTableConfig(tableObj);
-  const primary = [
-    ...config.columns.filter((column) => column.primary),
-    ...config.primaryKeys.flatMap((key) => key.columns)
-  ].map((column) => column.name);
-  const unique = [
-    ...config.columns.filter((column) => column.isUnique && !column.primary).map((column) => ({
-      // Drizzle's own name for an unnamed column-level unique key.
-      name: column.uniqueName ?? `${config.name}_${column.name}_unique`,
-      columns: [column.name]
-    })),
-    ...config.uniqueConstraints.map((constraint) => ({
-      name: constraint.name,
-      columns: constraint.columns.map((column) => column.name)
-    })),
-    ...config.indexes.filter((index) => index.config.unique === true).map((index) => ({
-      name: index.config.name,
-      columns: index.config.columns.map(
-        (column) => column.name
-      )
-    }))
-  ];
-  const keys = { primary, unique };
-  TABLE_KEYS.set(tableObj, keys);
-  return keys;
+	const cached = TABLE_KEYS.get(tableObj);
+	if (cached) return cached;
+	const config = getTableConfig(tableObj);
+	const keys = {
+		primary: [...config.columns.filter((column) => column.primary), ...config.primaryKeys.flatMap((key) => key.columns)].map((column) => column.name),
+		unique: [
+			...config.columns.filter((column) => column.isUnique && !column.primary).map((column) => ({
+				name: column.uniqueName ?? `${config.name}_${column.name}_unique`,
+				columns: [column.name]
+			})),
+			...config.uniqueConstraints.map((constraint) => ({
+				name: constraint.name,
+				columns: constraint.columns.map((column) => column.name)
+			})),
+			...config.indexes.filter((index) => index.config.unique === true).map((index) => ({
+				name: index.config.name,
+				columns: index.config.columns.map((column) => column.name)
+			}))
+		]
+	};
+	TABLE_KEYS.set(tableObj, keys);
+	return keys;
 }
+/**
+* Create a MySQL database adapter.
+*
+* @param config - MySQL adapter configuration
+* @returns A new MySqlAdapter instance
+*
+* @example
+* ```typescript
+* // Simple usage with URL
+* const adapter = createMySqlAdapter({
+*   url: 'mysql://user:pass@localhost:3306/mydb',
+* });
+*
+* // Full configuration
+* const adapter = createMySqlAdapter({
+*   url: process.env.DATABASE_URL!,
+*   pool: {
+*     min: 2,
+*     max: 20,
+*     idleTimeoutMs: 30000,
+*     connectionTimeoutMs: 10000,
+*   },
+*   ssl: {
+*     rejectUnauthorized: true,
+*   },
+* });
+*
+* await adapter.connect();
+* ```
+*/
 function createMySqlAdapter(config) {
-  return new MySqlAdapter(config);
+	return new MySqlAdapter(config);
 }
+/**
+* Type guard to check if a value is a MySqlAdapter.
+*
+* @param value - Value to check
+* @returns True if value is a MySqlAdapter instance
+*
+* @example
+* ```typescript
+* if (isMySqlAdapter(adapter)) {
+*   // TypeScript knows adapter is MySqlAdapter
+*   console.log('Using MySQL');
+* }
+* ```
+*/
 function isMySqlAdapter(value) {
-  return value instanceof MySqlAdapter;
+	return value instanceof MySqlAdapter;
 }
-
 export { MySqlAdapter, VERSION, createMySqlAdapter, isMySqlAdapter };
-//# sourceMappingURL=index.mjs.map
+
 //# sourceMappingURL=index.mjs.map