Metadata-Version: 2.4
Name: sql-harness
Version: 0.2.2
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).

Connection file format, env vars, and driver list: see `install.md`.

## 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
- `${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.

## 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.
