sql-harness

A thin, single-process SQL CLI for LLM agents. Mirrors browser-harness's structure but targets relational databases (Postgres, MySQL, Redis-soon).

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

Quickstart

# 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/zones/<conn>/skills/ — per-DSN skills (one zone per connection)
• ${XDG_CONFIG_HOME:-~/.config}/sql-harness/agent-workspace/zones/meta/skills/ — cross-DSN strategy skills (passive fallback for apply_skill)

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/zones/<conn>/skills/<name>.md for that DSN, or agent-workspace/zones/meta/skills/<name>.md if it generalizes. Future sessions will read it before re-discovering it.
• Bug fixes, new drivers, helper additions all welcome.

License

MIT.