@remix-run/data-table-mysql 0.4.0 → 0.5.1

package/src/lib/database.ts

@@ -0,0 +1,46 @@
+import { Database, type DatabaseOptions } from '@remix-run/data-table'
+
+import { MysqlDatabaseDriver, type MysqlDatabaseInput } from './driver.ts'
+
+/** Options for creating a MySQL database. */
+export interface MysqlDatabaseOptions extends DatabaseOptions {
+  /** Character set assigned to the recreated database. */
+  characterSet?: string
+  /** Collation assigned to the recreated database. */
+  collation?: string
+}
+
+/** A {@link Database} backed by MySQL. */
+export class MysqlDatabase extends Database<'mysql'> {
+  /**
+   * Creates a MySQL-backed database.
+   * @param input MySQL pool configuration, pool, connection, or URI.
+   * @param options Database runtime and recreation options.
+   */
+  constructor(input: MysqlDatabaseInput, options: MysqlDatabaseOptions = {}) {
+    super(new MysqlDatabaseDriver(input, options), options)
+  }
+}
+
+/**
+ * Creates a MySQL-backed database.
+ *
+ * @param input MySQL pool configuration, pool, connection, or URI.
+ * @param options Database runtime and recreation options.
+ * @returns A MySQL database.
+ * @example
+ * ```ts
+ * import { createMysqlDatabase } from 'remix/data-table/mysql'
+ *
+ * let db = createMysqlDatabase({
+ *   uri: process.env.DATABASE_URL,
+ *   multipleStatements: true,
+ * })
+ * ```
+ */
+export function createMysqlDatabase(
+  input: MysqlDatabaseInput,
+  options: MysqlDatabaseOptions = {},
+): MysqlDatabase {
+  return new MysqlDatabase(input, options)
+}

package/src/lib/{adapter.ts → driver.ts}

@@ -1,18 +1,22 @@
 import type {
+  DataManipulationOperation,
   DataManipulationRequest,
   DataManipulationResult,
-  DataManipulationOperation,
-  DatabaseAdapter,
+  DatabaseDriver,
   SqlStatement,
   TableRef,
   TransactionOptions,
   TransactionToken,
 } from '@remix-run/data-table'
+import { AsyncLocalStorage } from 'node:async_hooks'
+
 import { getTablePrimaryKey } from '@remix-run/data-table'
+import mysql from 'mysql2/promise'
 import type {
   Connection as MysqlConnection,
   Pool as MysqlPool,
   PoolConnection as MysqlPoolConnection,
+  PoolOptions as MysqlPoolOptions,
   ResultSetHeader,
   RowDataPacket,
 } from 'mysql2/promise'
@@ -32,33 +36,62 @@ type MysqlQueryResultHeader = {
 type MysqlTransactionConnection = MysqlConnection | MysqlPoolConnection
 type MysqlQueryable = MysqlPool | MysqlTransactionConnection
 
+export type MysqlDatabaseInput = string | MysqlPoolOptions | MysqlQueryable
+
+const mysqlCapabilities = Object.freeze({
+  returning: false,
+  savepoints: true,
+  upsert: true,
+  transactionalDdl: false,
+  migrationLock: true,
+})
+
+/** Database creation options used when wiping a config-backed MySQL driver. */
+export interface MysqlDatabaseDriverOptions {
+  /** Character set assigned to the recreated database. */
+  characterSet?: string
+  /** Collation assigned to the recreated database. */
+  collation?: string
+}
+
 /**
- * `DatabaseAdapter` implementation for mysql-compatible clients.
+ * MySQL database driver backed by a mysql-compatible client.
  */
-export class MysqlDatabaseAdapter implements DatabaseAdapter {
+export class MysqlDatabaseDriver implements DatabaseDriver<'mysql'> {
   /**
-   * The SQL dialect identifier reported by this adapter.
+   * The SQL dialect identifier reported by this database.
    */
-  dialect = 'mysql'
+  get dialect(): 'mysql' {
+    return 'mysql'
+  }
 
   /**
-   * Feature flags describing the mysql behaviors supported by this adapter.
+   * Feature flags describing the MySQL behaviors supported by this database.
    */
-  capabilities
+  get capabilities() {
+    return mysqlCapabilities
+  }
 
+  #config?: string | MysqlPoolOptions
   #client: MysqlQueryable
+  #characterSet?: string
+  #collation?: string
   #transactions = new Map<string, TransactionState>()
   #transactionCounter = 0
+  #migrationLockQueue = Promise.resolve()
+  #migrationLockStore = new AsyncLocalStorage<boolean>()
+  #poolClosed = false
 
-  constructor(client: MysqlQueryable) {
-    this.#client = client
-    this.capabilities = {
-      returning: false,
-      savepoints: true,
-      upsert: true,
-      transactionalDdl: false,
-      migrationLock: true,
+  constructor(config: MysqlDatabaseInput, options: MysqlDatabaseDriverOptions = {}) {
+    if (isMysqlQueryable(config)) {
+      this.#client = config
+    } else {
+      this.#config = config
+      this.#client = createMysqlPool(config)
     }
+
+    this.#characterSet = options.characterSet
+    this.#collation = options.collation
   }
 
   /**
@@ -187,17 +220,24 @@ export class MysqlDatabaseAdapter implements DatabaseAdapter {
       connection = this.#client
     }
 
-    if (options?.isolationLevel) {
-      await connection.query('set transaction isolation level ' + options.isolationLevel)
-    }
+    try {
+      if (options?.isolationLevel) {
+        await connection.query('set transaction isolation level ' + options.isolationLevel)
+      }
 
-    if (options?.readOnly !== undefined) {
-      await connection.query(
-        options.readOnly ? 'set transaction read only' : 'set transaction read write',
-      )
-    }
+      if (options?.readOnly !== undefined) {
+        await connection.query(
+          options.readOnly ? 'set transaction read only' : 'set transaction read write',
+        )
+      }
 
-    await connection.beginTransaction()
+      await connection.beginTransaction()
+    } catch (error) {
+      if (releaseOnClose) {
+        destroyMysqlConnection(connection)
+      }
+      throw error
+    }
 
     this.#transactionCounter += 1
     let token = { id: 'tx_' + String(this.#transactionCounter) }
@@ -222,13 +262,21 @@ export class MysqlDatabaseAdapter implements DatabaseAdapter {
       throw new Error('Unknown transaction token: ' + token.id)
     }
 
+    let failed = false
     try {
       await transaction.connection.commit()
+    } catch (error) {
+      failed = true
+      throw error
     } finally {
       this.#transactions.delete(token.id)
 
-      if (transaction.releaseOnClose && isMysqlPoolConnection(transaction.connection)) {
-        transaction.connection.release()
+      if (transaction.releaseOnClose) {
+        if (failed) {
+          destroyMysqlConnection(transaction.connection)
+        } else if (isMysqlPoolConnection(transaction.connection)) {
+          transaction.connection.release()
+        }
       }
     }
   }
@@ -245,13 +293,21 @@ export class MysqlDatabaseAdapter implements DatabaseAdapter {
       throw new Error('Unknown transaction token: ' + token.id)
     }
 
+    let failed = false
     try {
       await transaction.connection.rollback()
+    } catch (error) {
+      failed = true
+      throw error
     } finally {
       this.#transactions.delete(token.id)
 
-      if (transaction.releaseOnClose && isMysqlPoolConnection(transaction.connection)) {
-        transaction.connection.release()
+      if (transaction.releaseOnClose) {
+        if (failed) {
+          destroyMysqlConnection(transaction.connection)
+        } else if (isMysqlPoolConnection(transaction.connection)) {
+          transaction.connection.release()
+        }
       }
     }
   }
@@ -290,19 +346,144 @@ export class MysqlDatabaseAdapter implements DatabaseAdapter {
   }
 
   /**
-   * Acquires the mysql migration lock.
-   * @returns A promise that resolves when the lock is acquired.
+   * Destructively recreates the configured MySQL database.
+   * @returns A promise that resolves when the database is ready for use.
    */
-  async acquireMigrationLock(): Promise<void> {
-    await this.#client.query('select get_lock(?, 60)', ['data_table_migrations'])
+  async wipe(): Promise<void> {
+    let config = this.#configOrThrow('wipe')
+    this.#assertNoOpenTransactions('wipe')
+    let database = resolveMysqlDatabaseName(config)
+    await this.#closePool()
+    let connection: MysqlConnection | undefined
+
+    try {
+      connection = await createMysqlConnection(toMysqlServerConfig(config))
+      await connection.query('drop database if exists ' + quoteIdentifier(database))
+
+      let sql = 'create database ' + quoteIdentifier(database)
+
+      if (this.#characterSet) {
+        sql += ' character set ' + quoteIdentifier(this.#characterSet)
+      }
+
+      if (this.#collation) {
+        sql += ' collate ' + quoteIdentifier(this.#collation)
+      }
+
+      await connection.query(sql)
+    } finally {
+      try {
+        await connection?.end()
+      } finally {
+        await this.#replacePool()
+      }
+    }
+  }
+
+  /** Closes a pool created from configuration. Supplied connections and pools remain caller-owned. */
+  async close(): Promise<void> {
+    this.#assertNoOpenTransactions('close')
+    if (this.#config) {
+      await this.#closePool()
+    }
   }
 
   /**
-   * Releases the mysql migration lock.
-   * @returns A promise that resolves when the lock is released.
+   * Runs migration work on the mysql connection that owns the named lock.
+   *
+   * Lock acquisition waits up to 60 seconds and throws when the lock cannot
+   * be acquired. Re-entering this method from inside `run` throws instead of
+   * deadlocking, and a failed run destroys the reserved connection instead of
+   * returning it to the pool.
+   * @param name Logical migration lock name.
+   * @param run Migration work to run with a connection-bound driver.
+   * @returns The callback result.
    */
-  async releaseMigrationLock(): Promise<void> {
-    await this.#client.query('select release_lock(?)', ['data_table_migrations'])
+  async withMigrationLock<result>(
+    name: string,
+    run: (driver: DatabaseDriver<'mysql'>) => Promise<result>,
+  ): Promise<result> {
+    if (this.#migrationLockStore.getStore()) {
+      throw new Error('MySQL migration lock is already held by this database')
+    }
+
+    let waitForPreviousLock = this.#migrationLockQueue
+    let releaseQueue: () => void = () => undefined
+    this.#migrationLockQueue = new Promise((resolve) => {
+      releaseQueue = resolve
+    })
+
+    await waitForPreviousLock
+
+    try {
+      let releaseOnClose = false
+      let connection: MysqlTransactionConnection
+
+      if (isMysqlPool(this.#client)) {
+        connection = await this.#client.getConnection()
+        releaseOnClose = true
+      } else {
+        connection = this.#client
+      }
+
+      let driver = releaseOnClose ? new MysqlDatabaseDriver(connection) : this
+
+      try {
+        let value = await this.#migrationLockStore.run(true, () =>
+          runWithMysqlMigrationLock(connection, name, driver, run),
+        )
+
+        if (releaseOnClose && isMysqlPoolConnection(connection)) {
+          connection.release()
+        }
+
+        return value
+      } catch (error) {
+        // A failed run can leave the reserved connection dirty (open
+        // transaction, still-held named lock), so destroy the connection
+        // instead of returning it to the pool.
+        if (releaseOnClose) {
+          destroyMysqlConnection(connection)
+        }
+
+        throw error
+      }
+    } finally {
+      releaseQueue()
+    }
+  }
+
+  async #closePool(): Promise<void> {
+    this.#transactions.clear()
+    // mysql2 pools error on end() when called twice, so ending must be
+    // tracked to keep close() idempotent.
+    if (isMysqlPool(this.#client) && !this.#poolClosed) {
+      this.#poolClosed = true
+      await this.#client.end()
+    }
+  }
+
+  async #replacePool(): Promise<void> {
+    await this.#closePool().catch(() => undefined)
+
+    if (this.#config) {
+      this.#client = createMysqlPool(this.#config)
+      this.#poolClosed = false
+    }
+  }
+
+  #configOrThrow(method: string): string | MysqlPoolOptions {
+    if (!this.#config) {
+      throw new Error('MySQL database ' + method + '() requires config-based construction')
+    }
+
+    return this.#config
+  }
+
+  #assertNoOpenTransactions(method: string): void {
+    if (this.#transactions.size > 0) {
+      throw new Error('MySQL database cannot ' + method + ' while transactions are open')
+    }
   }
 
   #resolveClient(token: TransactionToken | undefined): MysqlQueryable {
@@ -324,36 +505,159 @@ export class MysqlDatabaseAdapter implements DatabaseAdapter {
   }
 }
 
-/**
- * Creates a mysql `DatabaseAdapter`.
- * @param client Mysql pool or connection.
- * @param options Optional adapter capability overrides.
- * @returns A configured mysql adapter.
- * @example
- * ```ts
- * import { createPool } from 'mysql2/promise'
- * import { createDatabase } from 'remix/data-table'
- * import { createMysqlDatabaseAdapter } from 'remix/data-table/mysql'
- *
- * let pool = createPool({ uri: process.env.DATABASE_URL })
- * let adapter = createMysqlDatabaseAdapter(pool)
- * let db = createDatabase(adapter)
- * ```
- */
-export function createMysqlDatabaseAdapter(client: MysqlQueryable): MysqlDatabaseAdapter {
-  return new MysqlDatabaseAdapter(client)
+function isMysqlQueryable(value: unknown): value is MysqlQueryable {
+  return typeof value === 'object' && value !== null && 'query' in value
+}
+
+function createMysqlPool(config: string | MysqlPoolOptions): MysqlPool {
+  return typeof config === 'string' ? mysql.createPool(config) : mysql.createPool(config)
+}
+
+function createMysqlConnection(config: string | MysqlPoolOptions): Promise<MysqlConnection> {
+  return typeof config === 'string'
+    ? mysql.createConnection(config)
+    : mysql.createConnection(config)
 }
 
 function isMysqlPool(client: MysqlQueryable): client is MysqlPool {
   return 'getConnection' in client && typeof client.getConnection === 'function'
 }
 
+function resolveMysqlDatabaseName(config: string | MysqlPoolOptions): string {
+  let database =
+    typeof config === 'string'
+      ? resolveDatabaseNameFromUrl(config)
+      : (config.database ?? resolveDatabaseNameFromUrl(config.uri ?? ''))
+
+  if (!database) {
+    throw new Error('MySQL database config requires a database name')
+  }
+
+  return database
+}
+
+function resolveDatabaseNameFromUrl(value: string): string | undefined {
+  try {
+    let url = new URL(value)
+    let database = decodeURIComponent(url.pathname.replace(/^\//, ''))
+    return database || undefined
+  } catch {
+    return undefined
+  }
+}
+
+function toMysqlServerConfig(config: string | MysqlPoolOptions): string | MysqlPoolOptions {
+  if (typeof config === 'string') {
+    try {
+      let url = new URL(config)
+      url.pathname = '/'
+      return url.toString()
+    } catch {
+      return config
+    }
+  }
+
+  // Pool-only options make mysql2's createConnection() log "Ignoring invalid
+  // configuration option" warnings, so strip them from the maintenance
+  // connection config.
+  let {
+    database: _database,
+    uri,
+    connectionLimit: _connectionLimit,
+    maxIdle: _maxIdle,
+    idleTimeout: _idleTimeout,
+    queueLimit: _queueLimit,
+    waitForConnections: _waitForConnections,
+    ...serverConfig
+  } = config
+
+  if (uri === undefined) {
+    return serverConfig
+  }
+
+  return { ...serverConfig, uri: removeDatabaseFromUrl(uri) }
+}
+
+function removeDatabaseFromUrl(value: string): string {
+  try {
+    let url = new URL(value)
+    url.pathname = '/'
+    return url.toString()
+  } catch {
+    return value
+  }
+}
+
 function isMysqlPoolConnection(
   connection: MysqlTransactionConnection,
 ): connection is MysqlPoolConnection {
   return 'release' in connection && typeof connection.release === 'function'
 }
 
+function destroyMysqlConnection(connection: MysqlTransactionConnection): void {
+  let destroy = (connection as { destroy?: () => void }).destroy
+
+  if (typeof destroy === 'function') {
+    destroy.call(connection)
+    return
+  }
+
+  void connection.end().catch(() => undefined)
+}
+
+async function runWithMysqlMigrationLock<result>(
+  connection: MysqlTransactionConnection,
+  name: string,
+  driver: MysqlDatabaseDriver,
+  run: (driver: DatabaseDriver<'mysql'>) => Promise<result>,
+): Promise<result> {
+  // sha2(..., 256) yields 64 hex characters, exactly GET_LOCK's 64-character
+  // lock name limit, so any additional prefix must go inside the hash input.
+  let [lockRows] = await connection.query(
+    "select lock_name, get_lock(lock_name, 60) as `acquired` from (select sha2(concat(coalesce(database(), ''), ':', ?), 256) as lock_name) as migration_lock",
+    [name],
+  )
+
+  let lockRow = isRowsResult(lockRows) ? lockRows[0] : undefined
+  let lockName = lockRow?.lock_name
+
+  if (typeof lockName !== 'string' || !toBooleanExists(lockRow?.acquired)) {
+    throw new Error('MySQL migration lock could not be acquired')
+  }
+
+  let outcome: { status: 'success'; value: result } | { status: 'failure'; error: unknown }
+
+  try {
+    outcome = { status: 'success', value: await run(driver) }
+  } catch (error) {
+    outcome = { status: 'failure', error }
+  }
+
+  let unlockFailed = false
+  let unlockError: unknown
+
+  try {
+    let [unlockRows] = await connection.query('select release_lock(?) as `released`', [lockName])
+
+    if (!isRowsResult(unlockRows) || !toBooleanExists(unlockRows[0]?.released)) {
+      throw new Error('MySQL migration lock was not held by the reserved connection')
+    }
+  } catch (error) {
+    unlockFailed = true
+    unlockError = error
+  }
+
+  if (outcome.status === 'failure') {
+    throw outcome.error
+  }
+
+  if (unlockFailed) {
+    throw unlockError
+  }
+
+  return outcome.value
+}
+
 function isRowsResult(result: unknown): result is MysqlQueryRows {
   return Array.isArray(result) && (result.length === 0 || !Array.isArray(result[0]))
 }

package/src/lib/sql-compiler.ts

@@ -1,5 +1,6 @@
 import { getTableName, getTablePrimaryKey } from '@remix-run/data-table'
-import type { DataManipulationOperation, Predicate, SqlStatement } from '@remix-run/data-table'
+import type { Predicate, SqlStatement } from '@remix-run/data-table'
+import type { DataManipulationOperation } from '@remix-run/data-table'
 import {
   collectColumns as collectColumnsHelper,
   normalizeJoinType as normalizeJoinTypeHelper,
@@ -43,8 +44,8 @@ export function compileMysqlOperation(operation: DataManipulationOperation): Sql
         compileGroupByClause(operation.groupBy) +
         compileHavingClause(operation.having, context) +
         compileOrderByClause(operation.orderBy) +
-        compileLimitClause(operation.limit) +
-        compileOffsetClause(operation.offset),
+        compileLimitClause(operation.limit, context) +
+        compileOffsetClause(operation.offset, context),
       values: context.values,
     }
   }
@@ -279,20 +280,20 @@ function compileOrderByClause(orderBy: { column: string; direction: 'asc' | 'des
   )
 }
 
-function compileLimitClause(limit: number | undefined): string {
+function compileLimitClause(limit: number | undefined, context: CompileContext): string {
   if (limit === undefined) {
     return ''
   }
 
-  return ' limit ' + String(limit)
+  return ' limit ' + pushValue(context, limit)
 }
 
-function compileOffsetClause(offset: number | undefined): string {
+function compileOffsetClause(offset: number | undefined, context: CompileContext): string {
   if (offset === undefined) {
     return ''
   }
 
-  return ' offset ' + String(offset)
+  return ' offset ' + pushValue(context, offset)
 }
 
 function compilePredicate(predicate: Predicate, context: CompileContext): string {

package/dist/lib/adapter.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/lib/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,uBAAuB,EACvB,sBAAsB,EACtB,yBAAyB,EACzB,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,uBAAuB,CAAA;AAE9B,OAAO,KAAK,EACV,UAAU,IAAI,eAAe,EAC7B,IAAI,IAAI,SAAS,EACjB,cAAc,IAAI,mBAAmB,EAGtC,MAAM,gBAAgB,CAAA;AAcvB,KAAK,0BAA0B,GAAG,eAAe,GAAG,mBAAmB,CAAA;AACvE,KAAK,cAAc,GAAG,SAAS,GAAG,0BAA0B,CAAA;AAE5D;;GAEG;AACH,qBAAa,oBAAqB,YAAW,eAAe;;IAC1D;;OAEG;IACH,OAAO,SAAU;IAEjB;;OAEG;IACH,YAAY;;;;;;MAAA;IAMZ,YAAY,MAAM,EAAE,cAAc,EASjC;IAED;;;;OAIG;IACH,UAAU,CAAC,SAAS,EAAE,yBAAyB,GAAG,YAAY,EAAE,CAG/D;IAED;;;;OAIG;IACG,OAAO,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CA8B/E;IAED;;;;;;;;OAQG;IACG,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAG9E;IAED;;;;;OAKG;IACG,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,WAAW,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAchF;IAED;;;;;;OAMG;IACG,SAAS,CACb,KAAK,EAAE,QAAQ,EACf,MAAM,EAAE,MAAM,EACd,WAAW,CAAC,EAAE,gBAAgB,GAC7B,OAAO,CAAC,OAAO,CAAC,CAclB;IAED;;;;OAIG;IACG,gBAAgB,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAgC9E;IAED;;;;OAIG;IACG,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB9D;IAED;;;;OAIG;IACG,mBAAmB,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBhE;IAED;;;;;OAKG;IACG,eAAe,CAAC,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG1E;IAED;;;;;OAKG;IACG,mBAAmB,CAAC,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG9E;IAED;;;;;OAKG;IACG,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG3E;IAED;;;OAGG;IACG,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAE1C;IAED;;;OAGG;IACG,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAE1C;CAmBF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,cAAc,GAAG,oBAAoB,CAEvF"}