sql-harness 0.1.0__py3-none-any.whl

sql_harness/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: sql-harness
+description: "Use sql-harness for SQL work — querying, schema inspection, migrations, and cross-database workflows."
+---
+
+# sql-harness
+
+Direct SQL access via a thin Python heredoc CLI. Connections live in plaintext in a single TOML file (default: `~/.config/sql-harness/connections.toml`).
+
+For setup or install problems, read `install.md`. For stuck-point mechanics, see `interaction-skills/` (cross-DB) and `interaction-skills/postgres/` (PG optimization depth: plan reading, B-Tree scans, specialized indexes, table optimization, slow-query detection).
+
+## Usage
+
+```bash
+sql-harness --help
+sql-harness list
+sql-harness add <name> --driver postgres --url 'postgresql://...'
+sql-harness test <name>
+
+sql-harness <<'PY'
+use_workspace("local_pg")
+print(query("SELECT version()"))
+print(list_tables())
+PY
+```
+
+- Helpers are pre-imported; you can call them by name in heredoc mode.
+- **First call requires `use_workspace(name)`** — there is no implicit default.
+- For task-specific helpers, drop them into `$BH_SQL_AGENT_WORKSPACE/agent_helpers.py` and they'll merge into the heredoc namespace.
+
+## Connection-pool skill + workspace skill
+
+Read these when working across multiple connections or tuning pool behavior:
+
+- `agent-workspace/skills/pool.md` — pool sizing, `pre_ping`, idle reuse
+- `agent-workspace/skills/workspace.md` — workspace isolation, multi-DB workflows
+- `interaction-skills/save-run-cycle.md` — the correct workflow: write a block, `save` it, `run` it; repeat. Don't batch-save at the end.
+- `interaction-skills/zone-skill-auto-surface.md` — set `$BH_SQL_ZONE_SKILLS=1` and `use_workspace(name)` returns a dict auto-attaching `zone_skills` + `zone_scripts` (mirrors browser-harness's `BH_DOMAIN_SKILLS=1` + `goto_url` returning domain skills).
+
+## Local Chrome? No, this is SQL.
+
+There is no Chrome and no remote "cloud" backend. SQL is single-process. All engines live in `SqlHarness`'s in-memory registry.
+
+## Design Constraints
+
+- One connection = one workspace; never share engines across workspaces.
+- Connection pool defaults: `size=5, recycle=3600, pre_ping=True` (per-connection overrides win).
+- `with_transaction()` yields a `Connection`; use `conn.execute(text(...))` for raw control.
+- `query()` returns `list[dict]`; use `execute()` for INSERT/UPDATE/DELETE.
+- `list_tables()` and `describe()` are read-only schema introspection helpers.
+
+## Gotchas
+
+- Driver label in TOML must match the URL scheme (`postgres` ⇄ `postgresql://`, `mysql` ⇄ `mysql+pymysql://`).
+- Passwords in TOML are plaintext; use `${env:VAR}` indirection for prod secrets.
+- `query()` is for SELECTs only. For INSERTs, use `execute()`.
+- For tables > 10k rows, use `engine.connect().execution_options(stream_results=True)` and iterate manually — `query()` loads everything into memory.
+
+## Domain / table skills
+
+PG optimization practice: 71 real [pgexercises](https://pgexercises.com/) problems in `practice/pgexercises/` — one `.sql` file per problem (header = question, body = answer). Load schema/seed and replay an answer with `run_sql_file`; tune it with `explain_analyze`. To add a per-table or per-schema skill, drop a markdown file into `agent-workspace/skills/<name>.md`. Read with `apply_skill(name)`.

sql_harness/__init__.py

@@ -0,0 +1,27 @@
+"""sql-harness — single-process SQL CLI for LLM agents.
+
+Mirrors browser-harness's structure: a small protected core plus an
+agent-editable workspace. Connections live in plaintext in one TOML file
+(default: ~/.config/sql-harness/connections.toml).
+"""
+
+from __future__ import annotations
+
+from .config import ConnectionConfig, ConnectionsConfig, PoolConfig, load, save
+from .drivers import Driver, get_driver
+from .manager import SqlHarness, Workspace
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ConnectionConfig",
+    "ConnectionsConfig",
+    "Driver",
+    "PoolConfig",
+    "SqlHarness",
+    "Workspace",
+    "__version__",
+    "get_driver",
+    "load",
+    "save",
+]

sql_harness/agent_loader.py

@@ -0,0 +1,55 @@
+"""Auto-load agent-editable helpers from $BH_SQL_AGENT_WORKSPACE/agent_helpers.py.
+
+Mirrors browser-harness's helpers.py:493-508 pattern. Public attributes
+(no leading underscore) are merged into the supplied globals dict.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+from pathlib import Path
+from types import ModuleType
+
+from .paths import workspace_dir
+
+
+def _resolve_agent_file() -> Path | None:
+    override = os.environ.get("BH_SQL_AGENT_WORKSPACE")
+    if override:
+        return Path(override).expanduser() / "agent_helpers.py"
+    return workspace_dir() / "agent_helpers.py"
+
+
+def load_agent_helpers(target_globals: dict) -> int:
+    """Load agent_helpers.py and merge public names into `target_globals`.
+
+    The agent_helpers.py module is exec'd in a namespace pre-seeded with the
+    core helpers (query, execute, use_workspace, ...) so that functions defined
+    there can call them directly. Returns the number of names merged
+    (0 if no file present).
+    """
+    path = _resolve_agent_file()
+    if path is None or not path.is_file():
+        return 0
+    spec = importlib.util.spec_from_file_location("sql_harness_agent_helpers", path)
+    if spec is None or spec.loader is None:
+        return 0
+    module = importlib.util.module_from_spec(spec)
+
+    # Pre-seed the module namespace with core helpers so that functions
+    # defined in agent_helpers.py can call query()/execute()/etc. by name.
+    from . import helpers as _helpers
+
+    for _n, _v in vars(_helpers).items():
+        if not _n.startswith("_"):
+            setattr(module, _n, _v)
+
+    spec.loader.exec_module(module)
+    merged = 0
+    for name, value in vars(module).items():
+        if name.startswith("_"):
+            continue
+        target_globals[name] = value
+        merged += 1
+    return merged