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

package/README.md

@@ -1,13 +1,12 @@
 # data-table-mysql
 
-MySQL adapter for [`remix/data-table`](https://github.com/remix-run/remix/tree/main/packages/data-table).
-Use this package when you want `data-table` APIs backed by `mysql2`.
+MySQL database driver for [`remix/data-table`](https://github.com/remix-run/remix/tree/main/packages/data-table), backed by `mysql2`.
 
 ## Features
 
-- **Native `mysql2` Integration**: Works with `mysql2/promise` `Pool` and `PoolConnection` instances
+- **Native `mysql2` Integration**: Creates a pool from `mysql2` configuration or uses an existing pool or connection
 - **Full `data-table` API Support**: Queries, relations, writes, and transactions
-- **Adapter-Owned Compiler**: SQL compilation lives in this adapter, with optional shared pure helpers from `data-table`
+- **MySQL Compiler**: SQL compilation is handled automatically for MySQL
 - **Multi-Statement Migrations**: `executeScript()` runs `up.sql` / `down.sql` files via `mysql2` (requires `multipleStatements: true`)
 - **MySQL Capabilities Enabled By Default**:
   - `returning: false`
@@ -25,18 +24,17 @@ npm i remix mysql2
 ## Usage
 
 ```ts
-import { createPool } from 'mysql2/promise'
-import { createDatabase } from 'remix/data-table'
-import { createMysqlDatabaseAdapter } from 'remix/data-table/mysql'
+import { createMysqlDatabase } from 'remix/data-table/mysql'
 
-let pool = createPool(process.env.DATABASE_URL as string)
-let db = createDatabase(createMysqlDatabaseAdapter(pool))
+let db = createMysqlDatabase({
+  uri: process.env.DATABASE_URL,
+  multipleStatements: true,
+})
 ```
 
-Use `db.query(...)`, relation loading, and transactions from `remix/data-table`.
-Import any driver-specific types you need directly from `mysql2/promise`.
+Use `db.query(...)`, relation loading, and transactions from `remix/data-table`. Import any driver-specific types you need directly from `mysql2/promise`.
 
-## Adapter Capabilities
+## Database Capabilities
 
 `data-table-mysql` reports this capability set by default:
 
@@ -50,26 +48,26 @@ Import any driver-specific types you need directly from `mysql2/promise`.
 
 ### Multi-Statement Migrations
 
-`remix/data-table/migrations` sends each migration to the adapter as a single multi-statement SQL
-script. mysql2 only accepts multi-statement scripts when the connection is created with
-`multipleStatements: true`:
+`remix/data-table/migrations` sends each migration as a single multi-statement SQL script. mysql2 only accepts multi-statement scripts when the connection is created with `multipleStatements: true`:
 
 ```ts
-import { createPool } from 'mysql2/promise'
+import { createMysqlDatabase } from 'remix/data-table/mysql'
 
-let pool = createPool({
+let db = createMysqlDatabase({
   uri: process.env.DATABASE_URL,
   multipleStatements: true,
 })
 ```
 
+Config-backed databases support `db.wipe()` and `db.reset()`. Call `await db.close()` during application shutdown to close the internally created pool. You may pass an existing `mysql2` pool or connection when your application owns the driver lifecycle; `db.close()` leaves supplied clients alone, and destructive lifecycle methods are unavailable in that mode. `db.wipe()` requires a database name in the connection config (`database`, or the path of a connection URI) and throws when none is present.
+
+Migration runs reserve one connection for the MySQL named lock, migration SQL, and journal updates. Lock acquisition waits up to 60 seconds and fails with an error instead of allowing the migration to proceed. After a successful run the connection is unlocked and returned to the pool; if the migration or unlock fails, the reserved connection is destroyed instead of being reused, so a dirty session can never leak back into the pool. Nested migration lock acquisition throws instead of deadlocking.
+
 ### `returning` On MySQL
 
-MySQL does not natively support SQL `RETURNING`. In this adapter, using `returning` on write
-operations throws `DataTableQueryError`.
+MySQL does not natively support SQL `RETURNING`. Using `returning` on write operations therefore throws `DataTableQueryError`.
 
-Use write metadata (`affectedRows`, `insertId`) on MySQL, or switch adapters when returned rows
-are required.
+Use write metadata (`affectedRows`, `insertId`) on MySQL, or switch databases when returned rows are required.
 
 ```ts
 import { DataTableQueryError } from 'remix/data-table'
@@ -80,17 +78,42 @@ try {
     .insert({ email: 'a@example.com', status: 'active' }, { returning: ['id'] })
 } catch (error) {
   if (error instanceof DataTableQueryError) {
-    // insert() returning is not supported by this adapter
+    // insert() returning is not supported by MySQL
   }
 }
 ```
 
+## Running integration tests locally
+
+To start a local MySQL container matching CI:
+
+```sh
+podman run --name mysql \
+  -e MYSQL_ROOT_PASSWORD=root \
+  -e MYSQL_DATABASE=remix \
+  -p 3306:3306 \
+  -d mysql:8
+```
+
+Then run:
+
+```sh
+REMIX_DATA_TABLE_MYSQL_TEST_URL=mysql://root:root@127.0.0.1:3306/remix \
+pnpm test src/lib/driver.integration.test.ts
+```
+
+Remove the container when you are done:
+
+```sh
+podman rm -f mysql
+```
+
 ## Related Packages
 
 - [`data-table`](https://github.com/remix-run/remix/tree/main/packages/data-table) - Core query/relations API
 - [`data-schema`](https://github.com/remix-run/remix/tree/main/packages/data-schema) - Schema parsing and validation
-- [`data-table-postgres`](https://github.com/remix-run/remix/tree/main/packages/data-table-postgres) - PostgreSQL adapter
-- [`data-table-sqlite`](https://github.com/remix-run/remix/tree/main/packages/data-table-sqlite) - SQLite adapter
+- [`data-table-postgres`](https://github.com/remix-run/remix/tree/main/packages/data-table-postgres) - PostgreSQL database driver
+- [`data-table-sqlite`](https://github.com/remix-run/remix/tree/main/packages/data-table-sqlite) - SQLite database driver
 
 ## License
 

package/dist/index.d.ts

@@ -1,2 +1,4 @@
-export { createMysqlDatabaseAdapter, MysqlDatabaseAdapter } from './lib/adapter.ts';
+export { createMysqlDatabase, MysqlDatabase } from './lib/database.ts';
+export type { MysqlDatabaseOptions } from './lib/database.ts';
+export type { MysqlDatabaseInput } from './lib/driver.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACtE,YAAY,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AAC7D,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/index.js

@@ -1 +1 @@
-export { createMysqlDatabaseAdapter, MysqlDatabaseAdapter } from "./lib/adapter.js";
+export { createMysqlDatabase, MysqlDatabase } from './lib/database.js';

package/dist/lib/database.d.ts

@@ -0,0 +1,36 @@
+import { Database, type DatabaseOptions } from '@remix-run/data-table';
+import { 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 declare 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);
+}
+/**
+ * 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 declare function createMysqlDatabase(input: MysqlDatabaseInput, options?: MysqlDatabaseOptions): MysqlDatabase;
+//# sourceMappingURL=database.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/lib/database.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAEtE,OAAO,EAAuB,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAE1E,6CAA6C;AAC7C,MAAM,WAAW,oBAAqB,SAAQ,eAAe;IAC3D,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,0CAA0C;AAC1C,qBAAa,aAAc,SAAQ,QAAQ,CAAC,OAAO,CAAC;IAClD;;;;OAIG;IACH,YAAY,KAAK,EAAE,kBAAkB,EAAE,OAAO,GAAE,oBAAyB,EAExE;CACF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE,oBAAyB,GACjC,aAAa,CAEf"}

package/dist/lib/database.js

@@ -0,0 +1,32 @@
+import { Database } from '@remix-run/data-table';
+import { MysqlDatabaseDriver } from './driver.js';
+/** A {@link Database} backed by MySQL. */
+export class MysqlDatabase extends Database {
+    /**
+     * Creates a MySQL-backed database.
+     * @param input MySQL pool configuration, pool, connection, or URI.
+     * @param options Database runtime and recreation options.
+     */
+    constructor(input, options = {}) {
+        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, options = {}) {
+    return new MysqlDatabase(input, options);
+}

package/dist/lib/{adapter.d.ts → driver.d.ts}

@@ -1,27 +1,35 @@
-import type { DataManipulationRequest, DataManipulationResult, DataManipulationOperation, DatabaseAdapter, SqlStatement, TableRef, TransactionOptions, TransactionToken } from '@remix-run/data-table';
-import type { Connection as MysqlConnection, Pool as MysqlPool, PoolConnection as MysqlPoolConnection } from 'mysql2/promise';
+import type { DataManipulationOperation, DataManipulationRequest, DataManipulationResult, DatabaseDriver, SqlStatement, TableRef, TransactionOptions, TransactionToken } from '@remix-run/data-table';
+import type { Connection as MysqlConnection, Pool as MysqlPool, PoolConnection as MysqlPoolConnection, PoolOptions as MysqlPoolOptions } from 'mysql2/promise';
 type MysqlTransactionConnection = MysqlConnection | MysqlPoolConnection;
 type MysqlQueryable = MysqlPool | MysqlTransactionConnection;
+export type MysqlDatabaseInput = string | MysqlPoolOptions | MysqlQueryable;
+/** 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 declare class MysqlDatabaseAdapter implements DatabaseAdapter {
+export declare class MysqlDatabaseDriver implements DatabaseDriver<'mysql'> {
     #private;
     /**
-     * The SQL dialect identifier reported by this adapter.
+     * The SQL dialect identifier reported by this database.
      */
-    dialect: string;
+    get dialect(): 'mysql';
     /**
-     * Feature flags describing the mysql behaviors supported by this adapter.
+     * Feature flags describing the MySQL behaviors supported by this database.
      */
-    capabilities: {
-        returning: boolean;
-        savepoints: boolean;
-        upsert: boolean;
-        transactionalDdl: boolean;
-        migrationLock: boolean;
-    };
-    constructor(client: MysqlQueryable);
+    get capabilities(): Readonly<{
+        returning: false;
+        savepoints: true;
+        upsert: true;
+        transactionalDdl: false;
+        migrationLock: true;
+    }>;
+    constructor(config: MysqlDatabaseInput, options?: MysqlDatabaseDriverOptions);
     /**
      * Compiles a data-manipulation operation to mysql SQL statements.
      * @param operation Operation to compile.
@@ -99,32 +107,24 @@ export declare class MysqlDatabaseAdapter implements DatabaseAdapter {
      */
     releaseSavepoint(token: TransactionToken, name: string): Promise<void>;
     /**
-     * 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.
      */
-    acquireMigrationLock(): Promise<void>;
+    wipe(): Promise<void>;
+    /** Closes a pool created from configuration. Supplied connections and pools remain caller-owned. */
+    close(): Promise<void>;
     /**
-     * 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.
      */
-    releaseMigrationLock(): Promise<void>;
+    withMigrationLock<result>(name: string, run: (driver: DatabaseDriver<'mysql'>) => Promise<result>): Promise<result>;
 }
-/**
- * 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 declare function createMysqlDatabaseAdapter(client: MysqlQueryable): MysqlDatabaseAdapter;
 export {};
-//# sourceMappingURL=adapter.d.ts.map
+//# sourceMappingURL=driver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../src/lib/driver.ts"],"names":[],"mappings":"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"}