feat(wren): extend standalone CLI with MySQL support and auto-discovery

.claude/skills/README.md

@@ -0,0 +1,21 @@
+# Wren Engine Skills
+
+Claude Code skills for the Wren Engine CLI.
+
+## Available skills
+
+| Skill | Trigger | Description |
+|-------|---------|-------------|
+| [`wren-query`](wren-query/SKILL.md) | `/wren-query [sql]` | Run, dry-run, or validate a SQL query through the Wren semantic CLI |
+
+## Usage
+
+Skills are invoked via slash commands in Claude Code:
+
+```
+/wren-query SELECT order_id FROM "orders" LIMIT 5
+/wren-query --dry-plan SELECT * FROM "orders"
+/wren-query --validate SELECT * FROM "NonExistent"
+```
+
+See each skill's `SKILL.md` for full details.

.claude/skills/wren-query/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: wren-query
+description: >
+  Run, dry-plan, or validate a SQL query through the Wren semantic CLI.
+  Use when the user asks to query a data source using wren, run wren --sql,
+  dry-plan SQL through MDL, or test a wren query against MySQL/Postgres/etc.
+argument-hint: "[sql query]"
+allowed-tools: Read, Bash(uv run wren *), Bash(wren *)
+---
+
+The user wants to run a Wren CLI command. $ARGUMENTS is the SQL query or instruction.
+
+## What to do
+
+1. **Check for `~/.wren/mdl.json` and `~/.wren/connection_info.json`** using Read or Glob.
+   - If either is missing, tell the user what's needed and show the format below.
+   - If both exist, proceed directly.
+
+2. **Run the appropriate command** based on what the user asked:
+
+| Intent | Command |
+|--------|---------|
+| Execute and return results | `uv run wren --sql '...'` |
+| Translate to native SQL (no DB) | `uv run wren dry-plan --sql '...'` |
+| Validate without fetching rows | `uv run wren dry-run --sql '...'` |
+| Check SQL is valid | `uv run wren validate --sql '...'` |
+
+If `wren` is installed globally (not via uv), use `wren` directly instead of `uv run wren`.
+
+3. **Show the result** and explain what happened.
+
+---
+
+## Required files
+
+Both files are auto-discovered from `~/.wren/`.
+
+### mdl.json — semantic model
+```json
+{
+  "catalog": "wren",
+  "schema": "public",
+  "models": [
+    {
+      "name": "orders",
+      "tableReference": { "schema": "mydb", "table": "orders" },
+      "columns": [
+        { "name": "order_id",  "type": "integer" },
+        { "name": "total",     "type": "double" },
+        { "name": "status",    "type": "varchar" }
+      ],
+      "primaryKey": "order_id"
+    }
+  ]
+}
+```
+
+### connection_info.json — connection info (include `datasource` field)
+```json
+{
+  "datasource": "mysql",
+  "host": "localhost",
+  "port": 3306,
+  "database": "mydb",
+  "user": "root",
+  "password": "secret"
+}
+```
+
+Supported datasource values: `mysql`, `postgres`, `bigquery`, `snowflake`,
+`clickhouse`, `trino`, `mssql`, `databricks`, `redshift`, `oracle`, `duckdb`.
+
+---
+
+## Override flags
+
+When needed, flags can override the defaults:
+
+```bash
+wren --sql '...' --mdl other-mdl.json --connection-file prod-connection_info.json
+wren --sql '...' --output csv          # table (default) | csv | json
+wren --sql '...' --limit 100
+```
+
+---
+
+## Common errors
+
+| Error | Fix |
+|-------|-----|
+| `mdl.json not found` | Create `~/.wren/mdl.json` |
+| `connection_info.json not found` | Create `~/.wren/connection_info.json` with a `datasource` field |
+| `datasource key not found` | Add `"datasource": "mysql"` to connection_info.json |
+| `unknown datasource 'X'` | Check spelling; see supported values above |
+| Connection refused | Confirm the DB is running and host/port are correct |

.github/workflows/wren-ci.yml

@@ -69,9 +69,20 @@ jobs:
       - name: Run unit tests
         run: uv run pytest tests/unit/ -v -m unit
 
-  test-postgres:
-    name: postgres tests
+  test-connector:
+    name: ${{ matrix.datasource }} tests
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - datasource: postgres
+            extra: postgres
+            test_file: tests/connectors/test_postgres.py
+            marker: postgres
+          - datasource: mysql
+            extra: mysql
+            test_file: tests/connectors/test_mysql.py
+            marker: mysql
     defaults:
       run:
         working-directory: wren
@@ -82,6 +93,11 @@ jobs:
           python-version: "3.11"
       - name: Install uv
         uses: astral-sh/setup-uv@v4
+      - name: Install system dependencies for mysqlclient
+        if: matrix.datasource == 'mysql'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y default-libmysqlclient-dev pkg-config
       - name: Cache Cargo
         uses: actions/cache@v4
         with:
@@ -103,6 +119,6 @@ jobs:
       - name: Install dependencies
         run: |
           uv lock --find-links ../wren-core-py/target/wheels/ --upgrade-package wren-core-py
-          uv sync --extra postgres --extra dev --find-links ../wren-core-py/target/wheels/
-      - name: Run postgres tests
-        run: uv run pytest tests/connectors/test_postgres.py -v -m postgres
+          uv sync --extra ${{ matrix.extra }} --extra dev --find-links ../wren-core-py/target/wheels/
+      - name: Run ${{ matrix.datasource }} tests
+        run: uv run pytest ${{ matrix.test_file }} -v -m ${{ matrix.marker }}

wren/README.md

@@ -1,42 +1,91 @@
-# wren
+# wren-engine
 
 Wren Engine CLI and Python SDK — semantic SQL layer for 20+ data sources.
 
+Translate natural SQL queries through an MDL (Modeling Definition Language) semantic layer and execute them against your database.
+
 ## Installation
 
 ```bash
-pip install wren-engine
+pip install wren-engine[mysql]      # MySQL
+pip install wren-engine[postgres]   # PostgreSQL
+pip install wren-engine[duckdb]     # DuckDB (local files)
+pip install wren-engine[all]        # All connectors
+```
+
+## Quick start
+
+**1. Create `~/.wren/mdl.json`** — your semantic model:
+
+```json
+{
+  "catalog": "wren",
+  "schema": "public",
+  "models": [
+    {
+      "name": "orders",
+      "tableReference": { "schema": "mydb", "table": "orders" },
+      "columns": [
+        { "name": "order_id",    "type": "integer" },
+        { "name": "customer_id", "type": "integer" },
+        { "name": "total",       "type": "double" },
+        { "name": "status",      "type": "varchar" }
+      ],
+      "primaryKey": "order_id"
+    }
+  ]
+}
+```
+
+**2. Create `~/.wren/connection_info.json`** — your connection:
+
+```json
+{
+  "datasource": "mysql",
+  "host": "localhost",
+  "port": 3306,
+  "database": "mydb",
+  "user": "root",
+  "password": "secret"
+}
+```
+
+**3. Run queries** — `wren` auto-discovers both files from `~/.wren`:
+
+```bash
+wren --sql 'SELECT order_id FROM "orders" LIMIT 10'
 ```
 
-## Usage
+For the full CLI reference and per-datasource `connection_info.json` formats, see [`docs/cli.md`](docs/cli.md) and [`docs/connections.md`](docs/connections.md).
+
+---
+
+## Python SDK
 
 ```python
+import base64, orjson
 from wren import WrenEngine, DataSource
+
+manifest = { ... }  # your MDL dict
+manifest_str = base64.b64encode(orjson.dumps(manifest)).decode()
+
+with WrenEngine(manifest_str, DataSource.mysql, {"host": "...", ...}) as engine:
+    result = engine.query('SELECT * FROM "orders" LIMIT 10')
+    print(result.to_pandas())
 ```
 
-See the [Wren Engine documentation](https://getwren.ai) for details.
+---
 
 ## Running tests
 
-Install dev dependencies first:
-
 ```bash
 just install-dev
 ```
 
 | Command | What it runs | Docker needed |
 |---------|-------------|---------------|
-| `just test-unit` | Unit tests (transpile, dry-plan, context manager) | No |
-| `just test-duckdb` | DuckDB connector tests — generates TPCH data via `dbgen` | No |
-| `just test-postgres` | PostgreSQL connector tests — spins up a container | Yes |
+| `just test-unit` | Unit tests | No |
+| `just test-duckdb` | DuckDB connector tests | No |
+| `just test-postgres` | PostgreSQL connector tests | Yes |
+| `just test-mysql` | MySQL connector tests | Yes |
 | `just test` | All tests | Yes |
-
-Run a specific connector via marker:
-
-```bash
-just test-connector postgres
-```
-
-To add tests for a new connector, subclass `WrenQueryTestSuite` in
-`tests/connectors/test_<name>.py` and provide a class-scoped `engine` fixture.
-All base tests are inherited automatically.

wren/docs/cli.md

@@ -0,0 +1,64 @@
+# CLI reference
+
+## Default command — query
+
+Running `wren --sql '...'` executes a query and prints the result. This is the same as `wren query --sql '...'`.
+
+```bash
+wren --sql 'SELECT COUNT(*) FROM "orders"'
+wren --sql 'SELECT * FROM "orders" LIMIT 5' --output csv
+wren --sql 'SELECT * FROM "orders"' --limit 100 --output json
+```
+
+Output formats: `table` (default), `csv`, `json`.
+
+## `wren query`
+
+Execute SQL and return results.
+
+```bash
+wren query --sql 'SELECT order_id, total FROM "orders" ORDER BY total DESC LIMIT 5'
+```
+
+## `wren dry-plan`
+
+Translate MDL SQL to the native dialect SQL for your data source. No database connection required.
+
+```bash
+wren dry-plan --sql 'SELECT order_id FROM "orders"'
+```
+
+## `wren dry-run`
+
+Validate SQL against the live database without returning rows. Prints `OK` on success.
+
+```bash
+wren dry-run --sql 'SELECT * FROM "orders" LIMIT 1'
+```
+
+## `wren validate`
+
+Same as `dry-run` but prints `Valid` / `Invalid: <reason>`.
+
+```bash
+wren validate --sql 'SELECT * FROM "NonExistent"'
+# Invalid: table not found ...
+```
+
+## Overriding defaults
+
+All flags are optional when `~/.wren/mdl.json` and `~/.wren/connection_info.json` exist:
+
+```bash
+wren --sql '...' \
+  --mdl /path/to/other-mdl.json \
+  --connection-file /path/to/prod-connection_info.json \
+  --datasource postgres
+```
+
+Or pass connection info inline:
+
+```bash
+wren --sql 'SELECT COUNT(*) FROM "orders"' \
+  --connection-info '{"datasource":"mysql","host":"localhost","port":3306,"database":"mydb","user":"root","password":"secret"}'
+```