@neverinfamous/mysql-mcp 2.3.0 → 3.0.0

package/CODE_MODE.md

@@ -1,245 +0,0 @@
-# Code Mode
-
-**Execute multi-step MySQL workflows in a single tool call.**
-
-Code Mode (`mysql_execute_code`) runs JavaScript/TypeScript code in a sandboxed VM with full access to all 192 MySQL tools via the `mysql.*` API namespace. Instead of chaining dozens of sequential tool calls, write a single script that queries, transforms, and acts on your data.
-
----
-
-## When to Use Code Mode
-
-| Scenario                     | Without Code Mode                          | With Code Mode                         |
-| ---------------------------- | ------------------------------------------ | -------------------------------------- |
-| Multi-step data pipeline     | 5-10 sequential tool calls                 | 1 `mysql_execute_code` call            |
-| Conditional branching        | Agent decides after each tool result       | `if/else` logic in one script          |
-| Cross-table aggregation      | Multiple reads + manual aggregation        | Loop and aggregate in JS               |
-| Schema migration with checks | Describe → check → alter → verify sequence | Single script with error handling      |
-| Batch operations             | Repeated tool calls per item               | `for` loop over items in one execution |
-
-**Rule of thumb**: If a task requires **3+ sequential tool calls** or **conditional logic based on query results**, use Code Mode.
-
----
-
-## Tool Reference
-
-### `mysql_execute_code`
-
-| Parameter | Type   | Required | Description                              |
-| --------- | ------ | -------- | ---------------------------------------- |
-| `code`    | string | ✅       | JavaScript/TypeScript code to execute    |
-| `timeout` | number | ❌       | Execution timeout in ms (default: 30000) |
-
-**Scope**: Requires `admin` scope.
-
-**Returns**: The value of the last expression in the code block, wrapped in an execution result with timing and memory metrics.
-
----
-
-## API Namespace
-
-The `mysql` global object exposes **24 tool groups** as sub-objects:
-
-| Group                | Tools | Description                              |
-| -------------------- | ----- | ---------------------------------------- |
-| `mysql.core`         | 8     | Read/write queries, tables, indexes      |
-| `mysql.transactions` | 7     | BEGIN, COMMIT, ROLLBACK, savepoints      |
-| `mysql.json`         | 17    | JSON functions, merge, diff, stats       |
-| `mysql.text`         | 6     | REGEXP, LIKE, SOUNDEX                    |
-| `mysql.fulltext`     | 5     | Natural language & boolean search        |
-| `mysql.performance`  | 8     | EXPLAIN, query analysis, slow queries    |
-| `mysql.optimization` | 4     | Index hints, recommendations             |
-| `mysql.admin`        | 6     | OPTIMIZE, ANALYZE, CHECK                 |
-| `mysql.monitoring`   | 7     | PROCESSLIST, status variables            |
-| `mysql.backup`       | 4     | Export, import, mysqldump                |
-| `mysql.replication`  | 5     | Master/slave, binlog                     |
-| `mysql.partitioning` | 4     | Partition management                     |
-| `mysql.schema`       | 10    | Views, procedures, triggers, constraints |
-| `mysql.shell`        | 10    | MySQL Shell utilities                    |
-| `mysql.events`       | 6     | Event Scheduler management               |
-| `mysql.sysschema`    | 8     | sys schema diagnostics                   |
-| `mysql.stats`        | 8     | Statistical analysis tools               |
-| `mysql.spatial`      | 12    | Spatial/GIS operations                   |
-| `mysql.security`     | 9     | Audit, SSL, encryption, masking          |
-| `mysql.roles`        | 8     | MySQL 8.0 role management                |
-| `mysql.docstore`     | 9     | Document Store collections               |
-| `mysql.cluster`      | 10    | Group Replication, InnoDB Cluster        |
-| `mysql.proxysql`     | 12    | ProxySQL management                      |
-| `mysql.router`       | 9     | MySQL Router REST API                    |
-
-### Method Naming Convention
-
-Tool names map to methods by stripping the group prefix and converting to camelCase:
-
-```
-mysql_read_query      → mysql.core.readQuery()
-mysql_json_extract    → mysql.json.extract()
-mysql_describe_table  → mysql.core.describeTable()
-mysql_spatial_point   → mysql.spatial.point()
-mysql_show_processlist → mysql.monitoring.showProcesslist()
-```
-
-### Positional Shorthand
-
-Common tools accept positional arguments for convenience:
-
-```javascript
-// Object form
-mysql.core.readQuery({
-  query: "SELECT * FROM users WHERE id = ?",
-  params: [1],
-});
-
-// Positional shorthand
-mysql.core.readQuery("SELECT * FROM users WHERE id = ?", [1]);
-```
-
-### Discovery
-
-```javascript
-// List all groups and their methods
-mysql.help();
-
-// Group-specific help with examples
-mysql.core.help();
-mysql.json.help();
-mysql.transactions.help();
-```
-
----
-
-## Usage Examples
-
-### Basic: Multi-Step Data Pipeline
-
-```javascript
-// Get table stats, identify large tables, and analyze their indexes
-const tables = await mysql.core.readQuery(
-  "SELECT table_name, table_rows FROM information_schema.tables WHERE table_schema = DATABASE() ORDER BY table_rows DESC LIMIT 5",
-);
-
-const results = [];
-for (const table of tables.rows) {
-  const indexes = await mysql.core.getIndexes({ table: table.table_name });
-  const stats = await mysql.performance.tableStats({ table: table.table_name });
-  results.push({
-    table: table.table_name,
-    rows: table.table_rows,
-    indexCount: indexes.indexes?.length || 0,
-    stats,
-  });
-}
-results;
-```
-
-### Conditional Logic
-
-```javascript
-// Check if a column exists before adding it
-const desc = await mysql.core.describeTable({ table: "users" });
-const hasEmail = desc.columns.some((c) => c.Field === "email_verified");
-
-if (!hasEmail) {
-  await mysql.core.writeQuery({
-    query: "ALTER TABLE users ADD COLUMN email_verified TINYINT(1) DEFAULT 0",
-  });
-  ("Column added");
-} else {
-  ("Column already exists");
-}
-```
-
-### Transactions with Error Handling
-
-```javascript
-// Atomic transfer between accounts
-const tx = await mysql.transactions.begin();
-try {
-  await mysql.core.writeQuery({
-    query: "UPDATE accounts SET balance = balance - ? WHERE id = ?",
-    params: [100, 1],
-    transactionId: tx.transactionId,
-  });
-  await mysql.core.writeQuery({
-    query: "UPDATE accounts SET balance = balance + ? WHERE id = ?",
-    params: [100, 2],
-    transactionId: tx.transactionId,
-  });
-  await mysql.transactions.commit({ transactionId: tx.transactionId });
-  ("Transfer complete");
-} catch (e) {
-  await mysql.transactions.rollback({ transactionId: tx.transactionId });
-  `Transfer failed: ${e.message}`;
-}
-```
-
-### Cross-Group Aggregation
-
-```javascript
-// Comprehensive database health check
-const [health, pool, processlist, variables] = await Promise.all([
-  mysql.monitoring.serverHealth(),
-  mysql.monitoring.poolStats(),
-  mysql.monitoring.showProcesslist({ full: false }),
-  mysql.monitoring.showStatus({ like: "%Threads%" }),
-]);
-
-({
-  serverVersion: health.version,
-  uptime: health.uptime,
-  activeConnections: pool.active,
-  idleConnections: pool.idle,
-  runningQueries:
-    processlist.processes?.filter((p) => p.Command === "Query").length || 0,
-  threadMetrics: variables.variables,
-});
-```
-
----
-
-## Security & Sandbox
-
-### Isolation
-
-Code runs in an **isolated VM sandbox** (Node.js `vm` module) with no access to:
-
-- File system (`fs`, `path`, `os`)
-- Network (`http`, `https`, `net`, `fetch`)
-- Process control (`process`, `child_process`)
-- Module system (`require`, `import`)
-
-### Blocked Patterns
-
-The following patterns are detected and rejected **before execution**:
-
-| Pattern             | Reason                    |
-| ------------------- | ------------------------- |
-| `require(...)`      | Module loading            |
-| `import ...`        | ES module imports         |
-| `process.`          | Process access            |
-| `eval(...)`         | Dynamic code execution    |
-| `new Function(...)` | Dynamic function creation |
-| `__dirname`         | File system path access   |
-| `__filename`        | File system path access   |
-
-### Rate Limiting
-
-Code Mode is rate-limited to prevent abuse. Excessive calls within a short window will return an error with a retry-after suggestion.
-
-### Transaction Cleanup
-
-Any transactions opened during code execution but **not explicitly committed** are automatically rolled back when execution completes. This prevents orphaned locks.
-
-### Timeout
-
-Default execution timeout is **30 seconds**. Use the `timeout` parameter to adjust for long-running operations.
-
----
-
-## Tips
-
-1. **Use `await`** — All `mysql.*` methods return Promises.
-2. **Return values** — The last expression in your code is returned as the result.
-3. **Error handling** — Wrap operations in `try/catch` for graceful error handling.
-4. **Parallel queries** — Use `Promise.all()` for independent queries to reduce execution time.
-5. **Transaction safety** — Always use `try/catch/finally` with transactions to ensure cleanup.
-6. **Help system** — Call `mysql.help()` or `mysql.<group>.help()` to discover available methods.