sql-harness 0.1.0

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.

sql-harness

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

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

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.