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/readsagent-workspace/zones/meta/skills/— cross-DSN strategy skills (apply_skill()fallback)
Drivers
| Driver | Backend | Package | Status |
|---|---|---|---|
postgres |
PostgreSQL | psycopg[binary]>=3.2 |
✅ |
mysql |
MySQL | pymysql>=1.1 |
✅ |
redis |
Redis | redis>=5.0 |
✅ |
sqlite |
SQLite | stdlib (sqlite3) |
✅ (test-only) |
ssh / ssh+password / ssh+key |
remote shell + SFTP | paramiko>=3.4 |
✅ |
Key env vars
| Var | Purpose |
|---|---|
BH_SQL_HOME |
Override state root (default ~/.config/sql-harness) |
BH_SQL_CONFIG_FILE |
Override connections.toml path |
BH_SQL_AGENT_WORKSPACE |
Override agent-workspace dir |
BH_SQL_ZONE_SKILLS=1 |
use_workspace() auto-surfaces the zone's skills/scripts |
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.
Metadata
Release files for sql-harness 0.3.10
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sql_harness-0.3.10.tar.gz | 618.4 kB | Without provenance | Details for sql_harness-0.3.10.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sql_harness-0.3.10-py3-none-any.whl | Python 3 | none | any | Details for sql_harness-0.3.10-py3-none-any.whl |
Total release size: 1.1 MB
Release files / sql_harness-0.3.10.tar.gz
| Download URL | sql_harness-0.3.10.tar.gz |
|---|---|
| Size | 618.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
33394b1849e7e54b7740d36d44c0c5ff2ce8a158c0f35a239628c0a616c4f06d
|
|
BLAKE2b-256 checksum How to use checksums |
332ccf155b5b3633b619cbc1b3da83b0fe3f8e5fde8741b63f591aa4d4074518
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / sql_harness-0.3.10-py3-none-any.whl
| Download URL | sql_harness-0.3.10-py3-none-any.whl |
|---|---|
| Size | 506.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
244485a1ac169721a70d30acd03611b14895c7ccc9ff0bb99e66b7f52a3c50cf
|
|
BLAKE2b-256 checksum How to use checksums |
1981fb6f3dc99f842ff19b6d2be9b9337b349a160e460d56e7598bed03f89569
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for sql-harness 0.3.10
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.