@mastra/mysql 0.0.0 → 0.1.0-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# @mastra/mysql
+
+## 0.1.0-alpha.0
+
+### Minor Changes
+
+- Added the MySQL storage adapter for Mastra. Use it as a storage backend with the same domain coverage as the other first-party adapters (memory, threads, workflows, observability, agents, and more). ([#17446](https://github.com/mastra-ai/mastra/pull/17446))
+
+  ```ts
+  import { MySQLStore } from '@mastra/mysql';
+
+  const store = new MySQLStore({
+    connectionString: 'mysql://user:password@localhost:3306/mastra',
+  });
+  ```
+
+  This release also makes table and index setup reliable on a brand-new database:
+  - Fixed store initialization failing on a fresh database. Idempotency for favorites is now enforced by the table's primary key instead of a separate index that MySQL rejected, which previously aborted setup and left the connection pool unusable.
+  - Fixed default performance indexes silently failing to be created. Indexes on text columns now include a key-length prefix so they are created instead of skipped.
+
+### Patch Changes
+
+- Updated dependencies [[`19a8658`](https://github.com/mastra-ai/mastra/commit/19a86589c788ef48bb6c1b0612cc82a201857379), [`a659a77`](https://github.com/mastra-ai/mastra/commit/a659a779bdebe3a52a518c56d2260592d0240fe0), [`3332be9`](https://github.com/mastra-ai/mastra/commit/3332be9701ecd77aba840959d9a1d1ce7aef02d3)]:
+  - @mastra/core@1.38.0-alpha.6

package/LICENSE.md

@@ -0,0 +1,30 @@
+Portions of this software are licensed as follows:
+
+- All content that resides under any directory named "ee/" within this
+  repository, including but not limited to:
+  - `packages/core/src/auth/ee/`
+  - `packages/server/src/server/auth/ee/`
+    is licensed under the license defined in `ee/LICENSE`.
+
+- All third-party components incorporated into the Mastra Software are
+  licensed under the original license provided by the owner of the
+  applicable component.
+
+- Content outside of the above-mentioned directories or restrictions is
+  available under the "Apache License 2.0" as defined below.
+
+# Apache License 2.0
+
+Copyright (c) 2025 Kepler Software, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -1,81 +1,152 @@
 # @mastra/mysql
 
-MySQL storage provider for Mastra.
+MySQL storage implementation for Mastra, providing persistent storage for threads, messages, workflows, traces, and more with connection pooling and transaction support.
 
-## Stable v1.5 Compatibility
+## Installation
 
-This version has been adapted to meet the stable v1.5 contract for Mastra storage adapters. It supports:
+```bash
+npm install @mastra/mysql
+```
+
+## Prerequisites
+
+- MySQL 8.0 or higher
+
+## Usage
+
+```typescript
+import { MySQLStore } from '@mastra/mysql';
+
+const store = new MySQLStore({
+  connectionString: 'mysql://user:password@localhost:3306/mastra',
+});
+
+// Create a thread
+await store.saveThread({
+  thread: {
+    id: 'thread-123',
+    resourceId: 'resource-456',
+    title: 'My Thread',
+    metadata: { key: 'value' },
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  },
+});
+
+// Add messages to thread
+await store.saveMessages({
+  messages: [
+    {
+      id: 'msg-789',
+      threadId: 'thread-123',
+      role: 'user',
+      content: { content: 'Hello' },
+      resourceId: 'resource-456',
+      createdAt: new Date(),
+    },
+  ],
+});
+
+// Query threads and messages
+const savedThread = await store.getThreadById({ threadId: 'thread-123' });
+const messages = await store.listMessages({ threadId: 'thread-123' });
+```
 
-- Full observability/tracing (spans, traces)
-- Workflow run management
-- Thread and message persistence
-- Scoring and evaluation storage
+### With Mastra
 
-To verify compatibility:
+```typescript
+import { Mastra } from '@mastra/core';
+import { MySQLStore } from '@mastra/mysql';
 
-```bash
-pnpm exec tsc --noEmit
-pnpm test src/storage/index.unit.test.ts
+export const mastra = new Mastra({
+  storage: new MySQLStore({
+    connectionString: 'mysql://user:password@localhost:3306/mastra',
+  }),
+});
 ```
 
-## Running the test suite
+## Configuration
 
-### Unit tests (no database required)
+`MySQLStore` supports two connection methods:
 
-Run unit tests that don't require a database connection:
+**1. Connection String**
 
-```bash
-# Run all unit tests
-pnpm test src/storage/domains/utils.test.ts src/storage/index.unit.test.ts
+```typescript
+const store = new MySQLStore({
+  connectionString: 'mysql://user:password@localhost:3306/mastra',
+});
+```
 
-# Or run just the unit test file
-pnpm test src/storage/index.unit.test.ts
+**2. Host/Port/Database**
+
+```typescript
+const store = new MySQLStore({
+  host: 'localhost',
+  port: 3306,
+  user: 'mastra',
+  password: 'mastra',
+  database: 'mastra',
+});
 ```
 
-### Integration tests (requires Docker)
+### Optional Configuration
 
-The integration test suite uses Docker to run a MySQL instance:
+- `ssl`: Enable SSL or provide custom SSL options (`true` | `false` | object)
+- `max`: Maximum pool connections (default: `10`)
+- `database`: Override the database name parsed from the connection string
+- `waitForConnections`: Queue requests when the pool is full (default: `true`, host config only)
+- `queueLimit`: Maximum queued connection requests, `0` for unlimited (default: `0`, host config only)
+- `skipDefaultIndexes`: Skip creating the built-in performance indexes during setup (default: `false`)
+- `indexes`: Additional custom indexes to create during setup
 
-```bash
-# Ensure Docker is running, then run all tests including integration tests
-pnpm test
-```
+## Features
+
+- Persistent storage for threads, messages, workflows, scores, datasets, and experiments
+- Full observability/tracing storage (spans and traces)
+- Atomic transactions for data consistency
+- Efficient batch operations
+- Connection pooling via `mysql2`
+- Automatic table and index setup on first use
+- Rich metadata support with JSON columns
+- Timestamp tracking and cascading deletes
+
+## Storage Methods
+
+- `saveThread({ thread })`: Create or update a thread
+- `getThreadById({ threadId })`: Get a thread by ID
+- `deleteThread({ threadId })`: Delete a thread and its messages
+- `saveMessages({ messages })`: Save multiple messages in a transaction
+- `listMessages({ threadId, perPage?, page? })`: Get messages for a thread with pagination
+- `deleteMessages(messageIds)`: Delete specific messages
+
+## Development
+
+### Environment Variables
 
-This will automatically start a MySQL container, run the tests, and clean up afterward.
+The test suite reads the following variables to connect to MySQL, falling back to the defaults shown:
 
-## Environment Variables
+- `MYSQL_HOST` (default: `localhost`)
+- `MYSQL_PORT` (default: `3306`)
+- `MYSQL_USER` (default: `mastra`)
+- `MYSQL_PASSWORD` (default: `mastra`)
+- `MYSQL_DB` (default: `mastra`)
 
-You can override the default database connection settings:
+### Running Tests
 
-- `MYSQL_HOST` (default: localhost)
-- `MYSQL_PORT` (default: 3306)
-- `MYSQL_USER` (default: mastra)
-- `MYSQL_PASSWORD` (default: mastra)
-- `MYSQL_DB` (default: mastra)
+Unit tests run without a database:
 
-## Rollback Procedure
+```bash
+pnpm test src/storage/index.unit.test.ts
+```
 
-If issues arise with this version, follow these steps to rollback:
+Integration tests use Docker to start a MySQL instance, run the suite, and clean up afterward:
 
-1. Checkout the last known good commit:
-   ```bash
-   git checkout <last-known-good-commit>
-   ```
-2. Reinstall dependencies:
-   ```bash
-   pnpm install
-   ```
-3. Verify the previous state:
-   ```bash
-   pnpm exec tsc --noEmit
-   pnpm test src/storage/index.unit.test.ts
-   ```
+```bash
+# Ensure Docker is running
+pnpm test
+```
 
-## Notes
+## Related Links
 
-- Integration tests require Docker to be running
-- The test suite includes both unit tests and integration tests
-- Unit tests use mocked MySQL connections and run quickly without external dependencies
-- Integration tests verify real database interactions and require a running MySQL instance
-- AI tracing features (span creation, updates, pagination, and batch operations) are supported by the MySQL observability domain.
-- Observability tables are initialized during store setup.
+- [Mastra Storage Documentation](https://mastra.ai/docs)
+- [MySQL Documentation](https://dev.mysql.com/doc/)

package/dist/index.cjs

@@ -406,12 +406,35 @@ var StoreOperationsMySQL = class extends storage.StoreOperations {
       if (existing.length > 0) {
         return;
       }
+      const [columnMeta] = await this.pool.execute(
+        `SELECT COLUMN_NAME, DATA_TYPE FROM information_schema.COLUMNS
+         WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ?`,
+        [db, table]
+      );
+      const dataTypeByColumn = new Map(
+        columnMeta.map((row) => [String(row.COLUMN_NAME).toLowerCase(), String(row.DATA_TYPE).toLowerCase()])
+      );
+      const PREFIX_TYPES = /* @__PURE__ */ new Set([
+        "tinytext",
+        "text",
+        "mediumtext",
+        "longtext",
+        "blob",
+        "tinyblob",
+        "mediumblob",
+        "longblob"
+      ]);
+      const indexColumn = (colName) => {
+        const quoted = quoteIdentifier(colName, "column name");
+        const dataType = dataTypeByColumn.get(colName.toLowerCase());
+        return dataType && PREFIX_TYPES.has(dataType) ? `${quoted}(191)` : quoted;
+      };
       const columnsStr = columns.map((col) => {
         if (col.includes(" DESC") || col.includes(" ASC")) {
           const [colName, ...modifiers] = col.split(" ");
-          return `${quoteIdentifier(colName, "column name")} ${modifiers.join(" ")}`;
+          return `${indexColumn(colName)} ${modifiers.join(" ")}`;
         }
-        return quoteIdentifier(col, "column name");
+        return indexColumn(col);
       }).join(", ");
       const uniqueStr = unique ? "UNIQUE " : "";
       const sql = `CREATE ${uniqueStr}INDEX ${indexName} ON ${tableName} (${columnsStr})`;
@@ -3490,19 +3513,6 @@ var FavoritesMySQL = class _FavoritesMySQL extends storage.FavoritesStorage {
       tableName: storage.TABLE_FAVORITES,
       schema: storage.FAVORITES_SCHEMA
     });
-    const tableName = formatTableName(storage.TABLE_FAVORITES);
-    const [idxCheck] = await this.pool.execute(
-      `SELECT INDEX_NAME FROM information_schema.STATISTICS 
-       WHERE TABLE_SCHEMA = DATABASE() 
-         AND TABLE_NAME = ? 
-         AND INDEX_NAME = 'unique_favorite'`,
-      [storage.TABLE_FAVORITES]
-    );
-    if (idxCheck.length === 0) {
-      await this.pool.execute(
-        `CREATE UNIQUE INDEX unique_favorite ON ${tableName} (${quoteIdentifier("userId", "index column")}(255), ${quoteIdentifier("entityType", "index column")}(255), ${quoteIdentifier("entityId", "index column")}(255))`
-      );
-    }
     await this.createDefaultIndexes();
     await this.createCustomIndexes();
   }
@@ -3889,7 +3899,15 @@ var MCPClientsMySQL = class _MCPClientsMySQL extends storage.MCPClientsStorage {
     const { id, ...updates } = input;
     try {
       const existing = await this.getById(id);
-      if (!existing) throw new Error(`MCP client with id ${id} not found`);
+      if (!existing) {
+        throw new error.MastraError({
+          id: storage.createStorageErrorId("MYSQL", "UPDATE_MCP_CLIENT", "NOT_FOUND"),
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.USER,
+          text: `MCP client with id ${id} not found`,
+          details: { id }
+        });
+      }
       const { authorId, activeVersionId, metadata, status } = updates;
       const updateData = { updatedAt: /* @__PURE__ */ new Date() };
       if (authorId !== void 0) updateData.authorId = authorId;