@remix-run/data-table-mysql 0.0.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shopify Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,97 @@
-# Placeholder package
+# data-table-mysql
 
-This package is intentionally empty and published only as a temporary placeholder.
+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`.
+
+## Features
+
+- **Native `mysql2` Integration**: Works with `mysql2/promise` `Pool` and `PoolConnection` instances
+- **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`
+- **Migration DDL Support**: Compiles and executes `DataMigrationOperation` operations for `remix/data-table/migrations`
+- **MySQL Capabilities Enabled By Default**:
+  - `returning: false`
+  - `savepoints: true`
+  - `upsert: true`
+  - `transactionalDdl: false`
+  - `migrationLock: true`
+
+## Installation
+
+```sh
+npm i remix mysql2
+```
+
+## Usage
+
+```ts
+import { createPool } from 'mysql2/promise'
+import { createDatabase } from 'remix/data-table'
+import { createMysqlDatabaseAdapter } from 'remix/data-table-mysql'
+
+let pool = createPool(process.env.DATABASE_URL as string)
+let db = createDatabase(createMysqlDatabaseAdapter(pool))
+```
+
+Use `db.query(...)`, relation loading, and transactions from `remix/data-table`.
+Import any driver-specific types you need directly from `mysql2/promise`.
+
+## Adapter Capabilities
+
+`data-table-mysql` reports this capability set by default:
+
+- `returning: false`
+- `savepoints: true`
+- `upsert: true`
+- `transactionalDdl: false`
+- `migrationLock: true`
+
+## Advanced Usage
+
+### Capability Overrides For Testing
+
+Capability overrides are mainly for tests where you want to force or disable specific behavior
+checks. In production, keep defaults so adapter behavior matches MySQL behavior.
+
+```ts
+import { createMysqlDatabaseAdapter } from 'remix/data-table-mysql'
+
+let adapter = createMysqlDatabaseAdapter(pool, {
+  capabilities: {
+    upsert: false,
+  },
+})
+```
+
+### `returning` On MySQL
+
+MySQL does not natively support SQL `RETURNING`. In this adapter, using `returning` on write
+operations throws `DataTableQueryError`.
+
+Use write metadata (`affectedRows`, `insertId`) on MySQL, or switch adapters when returned rows
+are required.
+
+```ts
+import { DataTableQueryError } from 'remix/data-table'
+
+try {
+  await db
+    .query(Accounts)
+    .insert({ email: 'a@example.com', status: 'active' }, { returning: ['id'] })
+} catch (error) {
+  if (error instanceof DataTableQueryError) {
+    // insert() returning is not supported by this adapter
+  }
+}
+```
+
+## 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
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { MysqlDatabaseAdapterOptions } from './lib/adapter.ts';
+export { createMysqlDatabaseAdapter, MysqlDatabaseAdapter } from './lib/adapter.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1 @@
+export { createMysqlDatabaseAdapter, MysqlDatabaseAdapter } from "./lib/adapter.js";

package/dist/lib/adapter.d.ts

@@ -0,0 +1,132 @@
+import type { AdapterCapabilityOverrides, DataManipulationRequest, DataMigrationRequest, DataMigrationResult, DataMigrationOperation, 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';
+/**
+ * Mysql adapter configuration.
+ */
+export type MysqlDatabaseAdapterOptions = {
+    capabilities?: AdapterCapabilityOverrides;
+};
+type MysqlTransactionConnection = MysqlConnection | MysqlPoolConnection;
+type MysqlQueryable = MysqlPool | MysqlTransactionConnection;
+/**
+ * `DatabaseAdapter` implementation for mysql-compatible clients.
+ */
+export declare class MysqlDatabaseAdapter implements DatabaseAdapter {
+    #private;
+    /**
+     * The SQL dialect identifier reported by this adapter.
+     */
+    dialect: string;
+    /**
+     * Feature flags describing the mysql behaviors supported by this adapter.
+     */
+    capabilities: {
+        returning: boolean;
+        savepoints: boolean;
+        upsert: boolean;
+        transactionalDdl: boolean;
+        migrationLock: boolean;
+    };
+    constructor(client: MysqlQueryable, options?: MysqlDatabaseAdapterOptions);
+    /**
+     * Compiles a data or migration operation to mysql SQL statements.
+     * @param operation Operation to compile.
+     * @returns Compiled SQL statements.
+     */
+    compileSql(operation: DataManipulationOperation | DataMigrationOperation): SqlStatement[];
+    /**
+     * Executes a mysql data-manipulation request.
+     * @param request Request to execute.
+     * @returns Execution result.
+     */
+    execute(request: DataManipulationRequest): Promise<DataManipulationResult>;
+    /**
+     * Executes mysql migration operations.
+     * @param request Migration request to execute.
+     * @returns Migration result.
+     */
+    migrate(request: DataMigrationRequest): Promise<DataMigrationResult>;
+    /**
+     * Checks whether a table exists in mysql.
+     * @param table Table reference to inspect.
+     * @param transaction Optional transaction token.
+     * @returns `true` when the table exists.
+     */
+    hasTable(table: TableRef, transaction?: TransactionToken): Promise<boolean>;
+    /**
+     * Checks whether a column exists in mysql.
+     * @param table Table reference to inspect.
+     * @param column Column name to look up.
+     * @param transaction Optional transaction token.
+     * @returns `true` when the column exists.
+     */
+    hasColumn(table: TableRef, column: string, transaction?: TransactionToken): Promise<boolean>;
+    /**
+     * Starts a mysql transaction.
+     * @param options Transaction options.
+     * @returns Transaction token.
+     */
+    beginTransaction(options?: TransactionOptions): Promise<TransactionToken>;
+    /**
+     * Commits an open mysql transaction.
+     * @param token Transaction token to commit.
+     * @returns A promise that resolves when the transaction is committed.
+     */
+    commitTransaction(token: TransactionToken): Promise<void>;
+    /**
+     * Rolls back an open mysql transaction.
+     * @param token Transaction token to roll back.
+     * @returns A promise that resolves when the transaction is rolled back.
+     */
+    rollbackTransaction(token: TransactionToken): Promise<void>;
+    /**
+     * Creates a savepoint in an open mysql transaction.
+     * @param token Transaction token to use.
+     * @param name Savepoint name.
+     * @returns A promise that resolves when the savepoint is created.
+     */
+    createSavepoint(token: TransactionToken, name: string): Promise<void>;
+    /**
+     * Rolls back to a savepoint in an open mysql transaction.
+     * @param token Transaction token to use.
+     * @param name Savepoint name.
+     * @returns A promise that resolves when the rollback completes.
+     */
+    rollbackToSavepoint(token: TransactionToken, name: string): Promise<void>;
+    /**
+     * Releases a savepoint in an open mysql transaction.
+     * @param token Transaction token to use.
+     * @param name Savepoint name.
+     * @returns A promise that resolves when the savepoint is released.
+     */
+    releaseSavepoint(token: TransactionToken, name: string): Promise<void>;
+    /**
+     * Acquires the mysql migration lock.
+     * @returns A promise that resolves when the lock is acquired.
+     */
+    acquireMigrationLock(): Promise<void>;
+    /**
+     * Releases the mysql migration lock.
+     * @returns A promise that resolves when the lock is released.
+     */
+    releaseMigrationLock(): Promise<void>;
+}
+/**
+ * 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, options?: MysqlDatabaseAdapterOptions): MysqlDatabaseAdapter;
+export {};
+//# sourceMappingURL=adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/lib/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,0BAA0B,EAC1B,uBAAuB,EACvB,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,EACtB,sBAAsB,EACtB,yBAAyB,EACzB,eAAe,EAEf,YAAY,EACZ,QAAQ,EACR,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,uBAAuB,CAAA;AAO9B,OAAO,KAAK,EACV,UAAU,IAAI,eAAe,EAC7B,IAAI,IAAI,SAAS,EACjB,cAAc,IAAI,mBAAmB,EAGtC,MAAM,gBAAgB,CAAA;AAIvB;;GAEG;AACH,MAAM,MAAM,2BAA2B,GAAG;IACxC,YAAY,CAAC,EAAE,0BAA0B,CAAA;CAC1C,CAAA;AAYD,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,EAAE,OAAO,CAAC,EAAE,2BAA2B,EASxE;IAED;;;;OAIG;IACH,UAAU,CAAC,SAAS,EAAE,yBAAyB,GAAG,sBAAsB,GAAG,YAAY,EAAE,CAOxF;IAED;;;;OAIG;IACG,OAAO,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CA8B/E;IAED;;;;OAIG;IACG,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAWzE;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,CACxC,MAAM,EAAE,cAAc,EACtB,OAAO,CAAC,EAAE,2BAA2B,GACpC,oBAAoB,CAEtB"}