# aiQueryLab

AI-collaborative DB IDE for VSCode. Execute queries from `.sql` files, view results as tables or charts, and let an AI (via MCP) drive the same panel — read queries, edit queries, run queries, push results back.

## Status

Scaffold. MySQL + ClickHouse adapters wired. MCP server (HTTP + bearer) exposes `list_connections`, `execute_query`, `get_result`, `inject_result`, `pin_result`, `list_results`. Svelte webview with table + ECharts chart host. Chart config = plain JS file next to the `.sql` (`queries/foo.sql` → `queries/foo.chart.js`).

## Roadmap

- v0: MySQL + ClickHouse, execute-under-cursor, results panel, MCP wiring
- v1: connection editor UI, richer chart presets
- v2: Redis, Iceberg, Elasticsearch adapters
- v3: multi-tab result slots, streaming large results

## Install

One-liner (installs into detected editor CLI: code / cursor / code-insiders / codium):

```bash
curl -sSL https://raw.githubusercontent.com/gr4c2-2000/aiQueryLab/main/install.sh | bash
```

Or from a local clone:

```bash
git clone https://github.com/gr4c2-2000/aiQueryLab.git
cd aiQueryLab
AIQL_LOCAL=1 ./install.sh
```

## Install (dev)

```bash
npm install
cd webview && npm install && cd ..
npm run build
```

Then open the folder in VSCode and press `F5` to launch the Extension Development Host.

## Configuration

- `.aiql/connections.json` — connection specs (checked into repo, no passwords)
- Passwords — stored in VSCode `SecretStorage` per connection
- `.aiql/config.example.json` — full config schema (also exposed via VSCode settings under `aiql.*`)

## MCP

After activation, run **aiQueryLab: Copy MCP Config** to get a snippet like:

```json
{
  "mcpServers": {
    "aiquerylab": {
      "url": "http://127.0.0.1:53827/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}
```

Paste into your MCP client (Claude Code, etc). Available tools:

| Tool              | Purpose                                                           |
|-------------------|-------------------------------------------------------------------|
| `list_connections`| enumerate configured connections                                  |
| `execute_query`   | run a single statement, get `resultId` + preview                  |
| `get_result`      | paginated read of stored result rows                              |
| `inject_result`   | push a stored result to the open results panel (optional `slot`)  |
| `pin_result`      | mark result immune to eviction                                    |
| `list_results`    | enumerate stored results (metadata)                               |

## Charts

Convention: `queries/foo.sql` → optional `queries/foo.chart.js`.

```js
// queries/foo.chart.js
function render(data, ctx) {
  const { records } = data;
  ctx.setOption({
    tooltip: { trigger: 'axis' },
    xAxis: { type: 'category', data: records.map(r => r.day) },
    yAxis: { type: 'value' },
    series: [{ type: 'bar', data: records.map(r => r.count) }],
  });
}
```

`data` = `{ columns: string[], rows: unknown[][], records: Record<string, unknown>[] }`.
`ctx` = `{ echarts, container, setOption }`.

## Storage

Results persist to `.aiql/cache/results/<resultId>/{data.ndjson,meta.json}`. Sliding-window LRU keeps total under `storage.results.maxSizeMb` (default 500). Set `storage.results.mode = "unlimited"` to disable eviction. `pin_result` protects specific results.

Logs write to `.aiql/logs/aiql-YYYY-MM-DD.log`, JSON-lines, capped by `retentionDays` and `maxSizeMb`.

## License

Apache 2.0. See [LICENSE](LICENSE).