sql-harness

A thin, single-process SQL + Redis + SSH CLI for LLM agents. Mirrors browser-harness's structure but targets relational databases (Postgres, MySQL, SQLite) plus Redis (keyspace ops + Lua) and SSH (remote shell + SFTP). No daemon, no cloud backend — engines live in one process.

Quickstart

# install (from PyPI)
uv tool install sql-harness        # or: pipx install sql-harness

# or develop locally from a source checkout
uv sync

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

# add a connection (or edit ~/.config/sql-harness/connections.toml directly)
uv run sql-harness add --name local_pg --driver postgres --url 'postgresql://postgres:postgres@localhost:5432/postgres'

# verify
uv run sql-harness test local_pg

# use it — helpers are pre-imported in heredoc mode
uv run sql-harness <<'PY'
use_workspace("local_pg")
print(query("SELECT version()"))
print(list_tables())
PY

# browse + edit the doc library (SKILL.md, interaction-skills/, your zone skills, connections.toml)
uv run sql-harness web

Architecture

• SKILL.md — the agent-facing entry (day-to-day usage; auto-shipped in the wheel)
• src/sql_harness/ — protected core package (~1k lines: drivers, manager, helpers, web UI)
• ${XDG_CONFIG_HOME:-~/.config}/sql-harness/connections.toml — plaintext credentials in ONE file (${env:VAR} indirection for prod secrets)
• agent-workspace/zones/<conn>/skills/ — per-DSN skills the agent writes/reads
• agent-workspace/zones/meta/skills/ — cross-DSN strategy skills (apply_skill() fallback)

Drivers

Key env vars

Full connection-file schema, read-only guard notes, and troubleshooting: read SKILL.md (shipped in the package, or sql-harness skill prints it).

What this is NOT

Not a migration framework, not an ORM, not an interactive REPL (pgcli exists for that) — this is for agents: heredoc scripts with auto-injected helpers, saved per-DSN and re-runnable.

License

MIT.