Metadata-Version: 2.4
Name: sql-harness
Version: 0.1.0
Summary: Single-process SQL + SSH CLI for LLM agents. PostgreSQL/MySQL/SSH via SQLAlchemy + paramiko. Plaintext credentials in one TOML file. Helpers auto-injected into the heredoc namespace.
Project-URL: Source, https://github.com/zhaoliuxue/much_bigpy/tree/master/lab/sql_harness
Project-URL: Issues, https://github.com/zhaoliuxue/much_bigpy/issues
Author: much-bigpy
License: MIT
Keywords: agent,cli,database,heredoc,mysql,postgres,sql,ssh
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: System :: Shells
Requires-Python: >=3.12
Requires-Dist: paramiko<4,>=3.4
Requires-Dist: psycopg[binary]<4,>=3.2
Requires-Dist: pymysql<2,>=1.1
Requires-Dist: sqlalchemy<3,>=2.0
Description-Content-Type: text/markdown

# sql-harness

A thin, single-process SQL CLI for LLM agents. Mirrors [browser-harness](https://github.com/browser-use/browser-harness)'s structure but targets relational databases (Postgres, MySQL, Redis-soon).

## Quickstart

```bash
# 1. Install deps (one-time)
uv sync

# 2. Scaffold a starter connections.toml
uv run sql-harness init

# 3. Add a connection
uv run sql-harness add local_pg --driver postgres --url 'postgresql://postgres:postgres@localhost:5432/postgres'

# 4. Test it
uv run sql-harness test local_pg

# 5. Use it
uv run sql-harness <<'PY'
use_workspace("local_pg")
print(query("SELECT version()"))
print(list_tables())
print(describe("pg_class"))
PY
```

## Architecture (~1k lines across 8 core files)

- `install.md` — first-time install + first connection
- `SKILL.md` — day-to-day usage
- `lab/sql_harness/src/sql_harness/` — protected core package (src-layout, mirrors browser-harness)
- `${XDG_CONFIG_HOME:-~/.config}/sql-harness/connections.toml` — plaintext credentials in ONE place
- `${XDG_CONFIG_HOME:-~/.config}/sql-harness/agent-workspace/agent_helpers.py` — task-specific helpers
- `${XDG_CONFIG_HOME:-~/.config}/sql-harness/agent-workspace/skills/` — per-task/per-table skills

## Why mirror browser-harness?

- Same operational ergonomics for agents: heredoc CLI with auto-imported helpers.
- Same agent-workspace pattern (helpers + skills stay editable per-project).
- Same path/state layout (XDG-style state directory).
- Same doc layering: `SKILL.md` body + `interaction-skills/*.md` for stuck points.

## What this is NOT

- Not a database migration framework.
- Not an ORM.
- Not a connection-string parser (`pgcli`/`mycli` already exist for interactive REPL use; this is for *agents*).
- Not a long-running daemon. SQL connections don't need one.

## Connection file format

Default: `${XDG_CONFIG_HOME:-~/.config}/sql-harness/connections.toml`.

```toml
default_workspace = "local_pg"

[pool_defaults]
size = 5
recycle = 3600
pre_ping = true
echo = false

[[connections]]
name = "local_pg"
driver = "postgres"
url = "postgresql+psycopg://postgres:postgres@localhost:5432/postgres"
description = "Local PostgreSQL for dev"

[[connections]]
name = "prod_pg"
driver = "postgres"
url = "${env:PROD_PG_URL}"            # env-var indirection
pool_size = 10
```

Use `${env:VAR}` placeholders inside `url` for prod secrets — they're expanded at load time from the process environment.

## Configuration env vars

| Var | Purpose |
|---|---|
| `BH_SQL_HOME` | Override state root (`~/.config/sql-harness` by default) |
| `BH_SQL_CONFIG_FILE` | Override connections.toml path |
| `BH_SQL_AGENT_WORKSPACE` | Override agent-workspace directory |
| `BH_SQL_RUNTIME_DIR` | Override runtime state dir |
| `BH_SQL_TMP_DIR` | Override temp dir |
| `BH_PG_URL` | Used by integration tests (skipped if unset) |
| `BH_MYSQL_URL` | Used by integration tests (skipped if unset) |

## Drivers

| Driver | Backend | Package | Status |
|---|---|---|---|
| `postgres` | PostgreSQL | `psycopg[binary]>=3.2` | ✅ |
| `mysql` | MySQL | `pymysql>=1.1` | ✅ |
| `redis` | Redis | `redis>=5.0` (not yet added) | 🚧 stub |
| `sqlite` | SQLite | stdlib (`sqlite3`) | ✅ (test-only) |
| `ssh` / `ssh+password` / `ssh+key` | remote shell + SFTP (paramiko) | `paramiko>=3.4` | ✅ |

To enable Redis: `uv add "redis>=5.0,<6"` then implement `drivers/redis.py`.
To add another SSH host: append a `[[connections]]` block with `driver = "ssh"` and an `ssh://...` URL.

## Contributing

PRs and improvements welcome. See `AGENTS.md` for code priorities.

- **Skills are written by the harness, not by you.** When you figure out a non-obvious SQL flow (a weird schema, a slow query, a JSON column trick), file a skill in `agent-workspace/skills/<name>.md`. Future sessions will read it before re-discovering it.
- Bug fixes, new drivers, helper additions all welcome.

## License

MIT.