@nextlyhq/adapter-mysql 0.0.1

package/dist/index.mjs

@@ -0,0 +1,603 @@
+import { DrizzleAdapter } from '@nextlyhq/adapter-drizzle';
+import { createDatabaseError, isDatabaseError } from '@nextlyhq/adapter-drizzle/types';
+import { checkDialectVersion } from '@nextlyhq/adapter-drizzle/version-check';
+import { drizzle } from 'drizzle-orm/mysql2';
+import mysql from 'mysql2/promise';
+
+// src/index.ts
+var VERSION = "0.1.0";
+var DEFAULT_POOL_CONFIG = {
+  max: 10,
+  idleTimeoutMs: 3e4,
+  connectionTimeoutMs: 1e4
+};
+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
+};
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+var MySqlAdapter = class extends DrizzleAdapter {
+  /**
+   * The database dialect - always 'mysql' for this adapter.
+   */
+  dialect = "mysql";
+  /**
+   * Adapter configuration.
+   */
+  config;
+  /**
+   * Connection pool instance.
+   */
+  pool = null;
+  /**
+   * Connection state flag.
+   */
+  connected = false;
+  /**
+   * 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");
+        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.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() {
+    if (!this.pool) {
+      return;
+    }
+    try {
+      await this.pool.end();
+      if (this.config.logger?.info) {
+        this.config.logger.info("MySQL connection closed");
+      }
+    } finally {
+      this.pool = null;
+      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) {
+    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();
+      try {
+        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(() => {
+        });
+        lastError = 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 {
+        connection.release();
+      }
+    }
+    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
+    };
+  }
+  /**
+   * 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
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  getDrizzle(schema) {
+    if (typeof window !== "undefined") {
+      throw new Error("getDrizzle() is server-only");
+    }
+    const pool = this.ensurePool();
+    return schema ? drizzle({ client: pool, schema, mode: "default" }) : drizzle(pool);
+  }
+  /**
+   * 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.
+   */
+  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 timeoutSeconds = Math.ceil(options.timeoutMs / 1e3);
+      await connection.query(
+        `SET SESSION innodb_lock_wait_timeout = ${timeoutSeconds}`
+      );
+    }
+  }
+  /**
+   * 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.
+   */
+  createTransactionContext(connection) {
+    return {
+      execute: async (sql, params = []) => {
+        const [rows] = await connection.query(
+          sql,
+          params
+        );
+        return rows;
+      },
+      insert: async (table, data, _options) => {
+        const columns = Object.keys(data);
+        const values = Object.values(data);
+        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);
+        if (result.insertId) {
+          const [rows2] = await connection.query(
+            `SELECT * FROM ${this.escapeIdentifier(table)} WHERE id = ?`,
+            [result.insertId]
+          );
+          return rows2[0];
+        }
+        const whereClauses = columns.map(
+          (c) => `${this.escapeIdentifier(c)} = ?`
+        );
+        const [rows] = await connection.query(
+          `SELECT * FROM ${this.escapeIdentifier(table)} WHERE ${whereClauses.join(" AND ")} LIMIT 1`,
+          values
+        );
+        return rows[0];
+      },
+      insertMany: async (table, data, _options) => {
+        if (data.length === 0) return [];
+        const columns = Object.keys(data[0]);
+        const allValues = [];
+        const valuesClauses = [];
+        for (const record of data) {
+          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 (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 [rows] = await connection.query(
+            `SELECT * FROM ${this.escapeIdentifier(table)} WHERE id IN (${placeholders})`,
+            ids
+          );
+          return rows;
+        }
+        return [];
+      },
+      // TransactionContext CRUD methods delegate to the adapter's CRUD
+      // which uses Drizzle query API via the TableResolver.
+      select: async (table, options) => {
+        return this.select(table, options);
+      },
+      selectOne: async (table, options) => {
+        return this.selectOne(table, options);
+      },
+      update: async (table, data, where, options) => {
+        return this.update(table, data, where, options);
+      },
+      delete: async (table, where, _options) => {
+        return this.delete(table, where);
+      },
+      upsert: async (table, data, options) => {
+        return this.upsert(table, data, options);
+      },
+      // 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 = error;
+    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
+    });
+  }
+  /**
+   * Override handleQueryError to use MySQL-specific classification.
+   */
+  handleQueryError(error, operation, table) {
+    const dbError = this.classifyError(error);
+    if (!dbError.message.includes(operation)) {
+      dbError.message = `${operation} operation failed on table '${table}': ${dbError.message}`;
+    }
+    if (!dbError.table) {
+      dbError.table = table;
+    }
+    return dbError;
+  }
+};
+function createMySqlAdapter(config) {
+  return new MySqlAdapter(config);
+}
+function isMySqlAdapter(value) {
+  return value instanceof MySqlAdapter;
+}
+
+export { MySqlAdapter, VERSION, createMySqlAdapter, isMySqlAdapter };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map