sql-harness 0.1.0__tar.gz → 0.2.2__tar.gz

{sql_harness-0.1.0 → sql_harness-0.2.2}/AGENTS.md

@@ -8,13 +8,13 @@ sql-harness is the same idea for SQL — connects agents to relational databases
 - Versatility
 
 # Overview
-Core code lives in `lab/sql_harness/src/sql_harness/` (src-layout, mirrors browser-harness's `src/browser_harness/`):
+Core code lives in `lab/sql_harness/src/sql_harness/`:
 - `config.py` — TOML schema + ConnectionConfig / ConnectionsConfig dataclasses
-- `paths.py` — XDG-style state directory resolution (mirrors browser-harness paths.py)
+- `paths.py` — XDG-style state directory resolution
 - `drivers/` — backend abstractions (postgres, mysql, redis stub, sqlite for tests)
 - `manager.py` — SqlHarness class: holds engines, workspaces, skills registry
 - `helpers.py` — heredoc helpers (auto-imported)
-- `agent_loader.py` — loads `$BH_SQL_AGENT_WORKSPACE/agent_helpers.py` (mirrors browser-harness helpers.py:493-508)
+- `agent_loader.py` — loads `$BH_SQL_AGENT_WORKSPACE/agent_helpers.py`
 - `run.py` — heredoc entry; delegates to CLI otherwise
 - `cli.py` — argparse subparser CLI (~10 subcommands)
 
@@ -28,10 +28,4 @@ An agent operating the harness only edits inside `agent-workspace/`:
 # Contributing
 Consider what is really needed. Prefer the smallest diff that fixes the bug.
 
-# Driver extension
-To add a new backend (Redis is the obvious next target):
-1. Add the package to `pyproject.toml` via `uv add <pkg>`.
-2. Create `drivers/<name>.py` implementing the `Driver` protocol (see `drivers/__init__.py`).
-3. Register it in `drivers/__init__.py:get_driver()`.
-4. Add a unit test in `tests/unit/test_<name>.py`.
-5. Optionally add an integration test in `tests/integration/test_<name>.py` gated on `BH_<NAME>_URL`.
+To add a backend: implement `drivers/<name>.py` against the Driver protocol, register in `drivers/__init__.py:get_driver()`, add `tests/unit/test_<name>.py` (see install.md §Drivers).

{sql_harness-0.1.0 → sql_harness-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql-harness
-Version: 0.1.0
+Version: 0.2.2
 Summary: 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.
 Project-URL: Source, https://github.com/zhaoliuxue/much_bigpy/tree/master/lab/sql_harness
 Project-URL: Issues, https://github.com/zhaoliuxue/much_bigpy/issues
@@ -25,6 +25,8 @@ Description-Content-Type: text/markdown
 
 A thin, single-process SQL CLI for LLM agents. Mirrors [browser-harness](https://github.com/browser-use/browser-harness)'s structure but targets relational databases (Postgres, MySQL, Redis-soon).
 
+Connection file format, env vars, and driver list: see `install.md`.
+
 ## Quickstart
 
 ```bash
@@ -53,7 +55,7 @@ PY
 
 - `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)
+- `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/skills/` — per-task/per-table skills
@@ -72,59 +74,6 @@ PY
 - 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`.
-
-```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.
@@ -134,4 +83,4 @@ PRs and improvements welcome. See `AGENTS.md` for code priorities.
 
 ## License
 
-MIT.
+MIT.

{sql_harness-0.1.0 → sql_harness-0.2.2}/README.md

@@ -2,6 +2,8 @@
 
 A thin, single-process SQL CLI for LLM agents. Mirrors [browser-harness](https://github.com/browser-use/browser-harness)'s structure but targets relational databases (Postgres, MySQL, Redis-soon).
 
+Connection file format, env vars, and driver list: see `install.md`.
+
 ## Quickstart
 
 ```bash
@@ -30,7 +32,7 @@ PY
 
 - `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)
+- `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/skills/` — per-task/per-table skills
@@ -49,59 +51,6 @@ PY
 - 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`.
-
-```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.
@@ -111,4 +60,4 @@ PRs and improvements welcome. See `AGENTS.md` for code priorities.
 
 ## License
 
-MIT.
+MIT.

sql_harness-0.2.2/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: sql-harness
+description: "Always use sql-harness for any 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.
+
+## 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.
+
+## Interaction Skills
+
+Stuck-point mechanics — one file per topic, bare filenames only:
+
+- `interaction-skills/aggregations.md`
+- `interaction-skills/docker-via-ssh.md`
+- `interaction-skills/encoding-and-charset.md`
+- `interaction-skills/indexes-and-explain.md`
+- `interaction-skills/joins.md`
+- `interaction-skills/json-columns.md`
+- `interaction-skills/large-result-sets.md`
+- `interaction-skills/migrations.md`
+- `interaction-skills/pooling.md`
+- `interaction-skills/recursive-ctes.md`
+- `interaction-skills/save-run-cycle.md`
+- `interaction-skills/schema-introspection.md`
+- `interaction-skills/ssh.md`
+- `interaction-skills/timeouts-and-cancellation.md`
+- `interaction-skills/transactions.md`
+- `interaction-skills/window-functions.md`
+- `interaction-skills/zone-skill-auto-surface.md`
+
+PG optimization depth — `interaction-skills/postgres/`:
+
+- `interaction-skills/postgres/btree-indexes.md`
+- `interaction-skills/postgres/plan-reading.md`
+- `interaction-skills/postgres/slow-queries-joins.md`
+- `interaction-skills/postgres/specialized-indexes.md`
+- `interaction-skills/postgres/table-optimization.md`
+
+## Workspace / strategy skills
+
+Read these when working across multiple connections, tuning pool behavior, or operating remote hosts:
+
+- `agent-workspace/skills/pool.md` — pool sizing, `pre_ping`, idle reuse.
+- `agent-workspace/skills/workspace.md` — workspace isolation, multi-DB workflows.
+- `agent-workspace/skills/ssh.md` — strategy for hitting remote DB hosts over SSH.
+- `agent-workspace/skills/docker-deploy.md` — strategy: when to use docker-via-ssh, the `~/sql-harness/<svc>/` cohesion convention, service catalog (coturn/mysql/redis/...).
+
+## What actually works (field-tested)
+
+- **Start with `list_tables` + `describe`, not `query`.** Before writing SQL on an unknown DB, run `list_tables(schema=None)` then `describe("table", schema=None)` to learn the columns. Skips the trial-and-error SELECT cycle.
+- **Default to `with_transaction()` for any write with ≥ 2 statements** (insert + update, drop + create, …). Atomic + automatic rollback on exception.
+- **For `insert` returning the new id**: psycopg supports `INSERT … RETURNING id`; MySQL has no `RETURNING` — use `execute(...)` and read `result.lastrowid`.
+- **Streaming large result sets**: `query()` loads every row into memory. For >10k rows, use `ws.engine.connect().execution_options(stream_results=True)` and iterate manually.
+- **Read-only "is this alive?" check**: `print(server_version())` — single round-trip, works on every DSN, no per-driver fudging.
+- **Auth wall**: redirected to login → stop and ask the user. Don't type credentials from `page_info`/`describe`.
+- **Credentials in TOML**: use `${env:VAR}` indirection for prod secrets. The connections.toml loader expands these at load time.
+- **Cross-DB SQL**: prefer ANSI syntax (`'string'`, `LIMIT n OFFSET m`, `COALESCE`, `CURRENT_TIMESTAMP`). PG-specific: `::TYPE`, `JSONB`, `RETURNING`. MySQL-specific: `AUTO_INCREMENT`, backticks, `?` placeholders (sqlalchemy normalizes to `:name`).
+- **Save the workflow**: every working block → `sql-harness save <name> -c <conn>`. Tomorrow's session re-runs with one command. See `interaction-skills/save-run-cycle.md`.
+- **Zone skills surface automatically**: set `BH_SQL_ZONE_SKILLS=1` once; every `use_workspace(name)` then tells you what zone skills exist (see `interaction-skills/zone-skill-auto-surface.md`).
+
+## 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.
+- There is no Chrome and no remote "cloud" backend. SQL is single-process. All engines live in `SqlHarness`'s in-memory registry.
+
+## 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: `practice/pgexercises/` (71 pgexercises problems, see its README). Per-table or per-schema skills: drop a markdown file into `agent-workspace/skills/<name>.md`, read with `apply_skill(name)`.

{sql_harness-0.1.0 → sql_harness-0.2.2}/agent-workspace/README.md

@@ -11,7 +11,7 @@ sessions. The live runtime copies live in `$BH_SQL_AGENT_WORKSPACE` (default
 - `scripts/sh_demo_crud.py` — full e-commerce CRUD walkthrough against a live
   PostgreSQL. Generated via `sql-harness save sh_demo_crud`. Idempotent (drops
   + recreates the `sh_demo` schema each run). Re-run with
-  `sql-harness run sh_demo_crud`.
+    `sql-harness run sh_demo_crud`.
 - `agent_helpers.py` — reusable helpers (`seed_users`, `place_order`,
   `ship_pending_orders`, `list_orders`, `user_by_email`, `product_by_sku`)
   auto-imported into the heredoc/run namespace.
@@ -39,4 +39,4 @@ sql-harness run sh_demo_crud
 ```
 
 That last step — **executed code is saved and re-runnable** — is the essence
-this harness inherits from browser-harness.
+this harness inherits from browser-harness.

sql_harness-0.2.2/agent-workspace/skills/README.md

@@ -0,0 +1,26 @@
+# agent-workspace/skills — strategy layer
+
+Strategy-altitude notes for sql-harness: **when** and **why** to reach for a
+pattern. The **how** (helpers, commands, gotchas) lives one level down in
+`interaction-skills/` — these docs point there, they don't duplicate it.
+
+## Files in this folder
+
+- `pool.md` — ships the `[pool_defaults]` block + recycle-timing rule; points at the pooling mechanic for sizing
+- `workspace.md` — one connection = one workspace; isolation, lifecycle, multi-DB, cross-workspace-transaction warning
+- `ssh.md` — when to reach for `driver = "ssh"` vs a DB workspace; auth reference; host-key-trust decision
+- `docker-deploy.md` — when to deploy docker-compose over SSH; service catalog; `~/sql-harness/<svc>/` convention; lifecycle decisions
+
+## When to read which
+
+- Queries stall / connections go stale → `pool.md` (then the pooling mechanic)
+- Juggling >1 database, or "can I share a connection?" → `workspace.md`
+- Need to run shell / move files on a remote box → `ssh.md`
+- Standing up mysql / redis / coturn / nginx on a remote host → `docker-deploy.md`
+
+## When to skip
+
+Most pool / workspace / ssh / docker tuning is **mechanic work** — read
+`interaction-skills/` first (`pooling.md`, `ssh.md`, `docker-via-ssh.md`,
+`transactions.md`). Come here only when a mechanic doc points at strategy, or
+when you're deciding *whether* to use a pattern rather than *how* to run it.

sql_harness-0.2.2/agent-workspace/skills/docker-deploy.md

@@ -0,0 +1,85 @@
+# Docker-via-SSH deployment — strategy
+
+> **Strategy layer** for deploying docker-compose services to remote hosts via
+> sql-harness SSH. For the **mechanic** (upload + `docker compose up` + verify),
+> see `interaction-skills/docker-via-ssh.md`. This doc is about **when**, **why**,
+> and **which service** — the convention, the catalog, the lifecycle decisions.
+
+## When to use this pattern
+
+Use `docker-via-ssh` when:
+
+- You have **1–N remote hosts** (Aliyun ECS, a VPS, a home lab box) reachable by SSH
+- You want **standard services** (mysql / postgres / redis / coturn / nginx / grafana) running, self-contained
+- You want **re-deployable / scriptable** deploys (not manual `docker run` you'll forget)
+- You **don't** need k8s-scale orchestration (no auto-scaling, no multi-node clustering)
+
+Don't use it when:
+
+- You need **multi-node clustering** (Hadoop / HBase across N hosts) → k8s / Nomad
+- The service needs **bare-metal perf** (GPU passthrough, hugepages) → systemd unit
+- You're on a **managed platform** (Aliyun RDS, Redis Cloud) → use the managed one
+
+## The convention: `~/sql-harness/<service>/` on the remote
+
+Every deployed service lives in its own dir under `~/sql-harness/<service>/` **on
+the remote host** — compose + config + data + logs, all with relative mounts
+(`./data`, not absolute paths). The mechanic doc shows the layout tree and the
+relative-mount rationale in full; the strategy payoff is:
+
+| Property | How the convention delivers it |
+|---|---|
+| **Cohesion** | A service's compose + config + data + logs are all in one dir |
+| **Backup** | `tar czf coturn.tgz ~/sql-harness/coturn/` — one command, complete |
+| **Teardown** | `docker compose down && rm -rf ~/sql-harness/<svc>` — clean |
+| **Upgrade** | re-upload compose → `docker compose up -d` (rolling, keeps data) |
+| **Discovery** | `ls ~/sql-harness/` shows what's deployed |
+| **Isolation** | services don't share mounts/networks unless explicitly composed together |
+| **Portability** | relative mounts follow the dir — move or migrate hosts without editing paths |
+
+## Service catalog (shipped templates in `docker-services/`)
+
+| Service | Image | Ports | Use case |
+|---|---|---|---|
+| `coturn` | `coturn/coturn` | 3478, 5349, 49152-65535/udp | WebRTC TURN/STUN (P2P hole-punching) |
+| `mysql` | `mysql:8.0` | 3306 | Relational DB (sql-harness `mysql` driver connects here) |
+| `postgresql` | `postgres:16` | 5432 | Relational DB (sql-harness `postgres` driver connects here) |
+| `redis` | `redis:7-alpine` | 6379 | Cache / KV (sql-harness `redis` driver — when implemented) |
+| `nginx` | `nginx:alpine` | 80, 443 | Reverse proxy / static hosting |
+| `rabbitmq` | `rabbitmq:3-management` | 5672, 15672 | Message queue |
+| `cloud-grafana` | `grafana/grafana` + `prom/prometheus` | 3000, 9090 | Monitoring stack |
+
+Each template in `docker-services/<svc>/` ships a `docker-compose.yml` + config
+files, all with relative mounts. Pick one → the mechanic's 4-step loop uploads
+and starts it. Pair a deployed DB service with a matching **DB workspace**
+(`driver = "mysql"`/`postgres`) to run SQL against it — SSH-level container
+management + DB-level queries on the same host is the typical diagnostic loop.
+
+## Lifecycle decisions
+
+| Question | Answer |
+|---|---|
+| New service? | pick template → upload → `up -d` (4-step loop in mechanic doc) |
+| Image update? | edit compose tag → re-upload → `up -d` (keeps data) |
+| Config change? | edit conf → re-upload → `restart` (or `up -d` if compose changed) |
+| Host migration? | `tar` the service dir → scp to new host → `up -d` |
+| Out of disk? | `docker system prune -af` (careful) + check service `data/` growth |
+| Service flapping? | `docker logs -f` → `docker compose ps` → healthcheck output |
+| Stop paying for it? | `down -v` + `rm -rf ~/sql-harness/<svc>` + snapshot data first |
+
+## Gotchas (strategy-level)
+
+- **One host = one `~/sql-harness/` root**. Multi-host deploys loop the deploy per
+  host — one sql-harness SSH workspace per host.
+- **Don't mount the SAME host port from two services** — mysql + postgres coexist
+  fine on their defaults, but two mysql instances need port remapping.
+- **Healthy ≠ reachable by the DB workspace**: if a container isn't healthy,
+  `sql-harness test <db-workspace>` fails confusingly — check `docker compose ps`
+  before assuming a sql-harness bug. (Per-service startup gotchas live with the
+  mechanic and `docker-services/<svc>/README.md`.)
+
+## See also
+
+- `interaction-skills/docker-via-ssh.md` — the mechanic (layout tree, relative-mount
+  rationale, 4-step deploy loop, per-op lifecycle commands, deploy gotchas)
+- `docker-services/<svc>/` — shipped templates (and `<svc>/README.md` service gotchas)

sql_harness-0.2.2/agent-workspace/skills/pool.md

@@ -0,0 +1,30 @@
+# Connection pooling — strategy
+
+> **Strategy stub.** Sizing rules, `pre_ping`, `pool_recycle`, `NullPool` and pool
+> gotchas all live in the mechanic: `interaction-skills/pooling.md`. Read that
+> first. This file owns only the shipped default block below.
+
+## `[pool_defaults]`
+
+Every workspace pool starts from these conservative defaults (`pool_size=5` means
+5 connections to *that* database, per workspace — not 5 total). Tune per workload
+using the mechanic's sizing rules.
+
+```toml
+[pool_defaults]
+size = 5
+recycle = 3600
+pre_ping = true
+echo = false
+```
+
+**Recycle-timing rule:** when a load balancer / proxy kills idle connections
+(AWS RDS Proxy = 1800s; PostgreSQL `idle_in_transaction_session_timeout`), set
+`recycle` to (their timeout) × 0.8 so connections recycle *before* being killed
+externally.
+
+## Read full guide
+
+`interaction-skills/pooling.md` — when to tune `pool_size` (1 / 2-5 / 10+), when
+`pre_ping` and `pool_recycle` matter, `NullPool` vs `QueuePool`, and pool-stat
+gotchas.

sql_harness-0.2.2/agent-workspace/skills/ssh.md

@@ -0,0 +1,70 @@
+# SSH workspaces — when to use the SSH driver
+
+> **Strategy guide.** For the mechanics (helper calls, CLI subcommands, SFTP /
+> timeout / quoting gotchas), see `interaction-skills/ssh.md`.
+
+## When to reach for `driver = "ssh"`
+
+Use an SSH workspace to **operate on a remote host** (not a database). It reuses
+the same `use_workspace("name")` abstraction as DB workspaces, but opens a
+paramiko `SSHClient` + SFTP instead of a SQLAlchemy engine — so you get shell +
+file ops with the same ergonomics.
+
+Reach for it to: run ad-hoc shell commands (`ps`, `systemctl`, `cat /var/log/...`);
+do a one-shot deploy / restart / log inspection without a full Ansible playbook;
+upload-then-run a script (`ssh_run_script`); pull a log/artifact down for analysis;
+or pair with a DB workspace (shell check, then `query(...)`).
+
+Don't use it for: heavy interactive shells (no TUI/scrollback/resize — use
+`term-cli` from `lab.subprocess`); long-running daemons (the channel is
+short-lived — use systemd / supervisord); or anything that must survive the
+sql-harness process exit (the connection closes on exit).
+
+## Auth reference
+
+Configure in `connections.toml` (`driver = "ssh"`, `url = "ssh://user@host:port"`).
+Pick an auth strategy:
+
+| Strategy | When | Example URL |
+|---|---|---|
+| SSH key (preferred) | CI / dev boxes with `~/.ssh/id_*` | `ssh://user@host` (auto-resolves key) |
+| Explicit key path | Specific key per connection | `ssh://user@host?key=/opt/keys/prod.pem` |
+| Password | Quick lab use; NOT for prod | `ssh://user:pw@host` (works but key is better) |
+| `ssh+password://` | Force password (no key lookup) | `ssh+password://user:pw@host` |
+| `ssh+key://` | Force key-only auth (no password fallback) | `ssh+key://user@host?key=/path` |
+
+Key resolution order (first hit wins): (1) `?key=...` in the URL, (2) `$BH_SSH_KEY`
+env var, (3) `~/.ssh/id_ed25519` → `id_rsa` → `id_ecdsa`, (4) password from URL or
+`$BH_SSH_PASSWORD`.
+
+## Workspace lifecycle parity
+
+SSH workspaces follow the **same** lazy-open / cached / dispose pattern as DB
+workspaces: `use_workspace("prod-app")` opens TCP+SSH+shell+SFTP and caches it;
+re-opening returns the cached handle for free; process exit / `dispose()` /
+`close_workspace(name)` tears it down.
+
+## Combining with DB workspaces
+
+SSH and DB workspaces are independent — keep one of each open at once. The typical
+diagnostic flow: shell-level process check, then in-process DB check.
+
+```python
+ssh_use_workspace("prod-app")
+print(ssh_exec("ps aux | grep postgres | head -3")["stdout"])
+
+use_workspace("prod_pg")
+print(query("SELECT count(*) FROM pg_stat_activity")["count"])
+```
+
+## Safety — the host-key-trust decision
+
+The driver trusts host keys on first connect (`AutoAddPolicy()`, like
+`StrictHostKeyChecking=accept-new`). Fine for trusted networks; for hostile ones,
+harden this in a subclass. Also prefer a non-root user, and set an explicit
+`timeout=` for long commands. (Connection pooling, shell-vs-exec, path handling,
+non-ASCII decoding and other operational gotchas live in the mechanic doc.)
+
+## See also
+
+- `interaction-skills/ssh.md` — the mechanic (helpers, CLI, SFTP/timeout/quoting gotchas)

{sql_harness-0.1.0 → sql_harness-0.2.2}/agent-workspace/skills/workspace.md

@@ -37,19 +37,10 @@ Each `query()` call grabs its workspace's connection and returns it to the pool
 
 ## Transactions across workspaces
 
-Don't. A single transaction is bound to one connection. To move data between workspaces:
-
-```python
-use_workspace("prod_pg")
-rows = query("SELECT * FROM users WHERE created_at > :t", {"t": "2024-01-01"})
-
-use_workspace("staging_pg")
-for row in rows:
-    execute("INSERT INTO users (id, name, created_at) VALUES (:i, :n, :c)",
-            {"i": row["id"], "n": row["name"], "c": row["created_at"]})
-```
-
-This is two separate transactions — one per workspace — and is NOT atomic. If you need atomicity, you need a single DB.
+Don't. A single transaction is bound to one connection, so moving data between
+workspaces is two separate transactions (`query` from A → `execute` into B) — one
+per workspace, and NOT atomic. If you need atomicity, you need a single DB. See
+`interaction-skills/transactions.md` for the transaction mechanics.
 
 ## Gotchas
 

sql_harness-0.2.2/docker-services/coturn/README.md

@@ -0,0 +1,69 @@
+# coturn (TURN/STUN server) — docker-services template
+
+Self-contained TURN/STUN relay for WebRTC clients. Deploy via
+`../../interaction-skills/docker-via-ssh.md`. Service dir on the remote:
+`~/sql-harness/coturn/`.
+
+## Key config knobs (`turnserver.conf`)
+
+- `realm` — your domain / public hostname (clients see this in their URL).
+- `external-ip` — the server's PUBLIC ip when behind NAT (Aliyun ECS is).
+  Set as `AUTO` in the shipped template; the deploy script substitutes the
+  real public ip before `up -d`.
+- `listening-ip=0.0.0.0` — bind interface (private is fine; only `external-ip`
+  needs to be public).
+- `listening-port=3478` (TURN/STUN), `tls-listening-port=5349` (TURNS over TLS).
+- `min-port=49152` / `max-port=65535` — relay UDP range. Must match the firewall.
+- `user=<u>:<p>` + `lt-cred-mech` — long-term credential mechanism.
+
+Test creds after deploy:
+```bash
+turnutils_uclient -u webrtc -w webrtc <server-ip> 3478
+```
+
+## Service-specific gotchas (from production)
+
+- **`external-ip` behind NAT**: Aliyun ECS is behind NAT — coturn's
+  `turnserver.conf` `external-ip=` must be the **public** ip, not the private
+  one `listening-ip=0.0.0.0` binds. Templated as `AUTO`; substitute at deploy
+  time (`sed -i "s/external-ip=AUTO/external-ip=$PUBIP/"`).
+
+- **Firewall / security group**: docker-publishes ports on the host, but Aliyun
+  security group + host firewall (ufw/firewalld) must ALSO allow them. The
+  coturn relay UDP range (49152-65535) is the easy one to forget. Open in
+  security group, NOT via docker `ports:`.
+
+- **Don't publish the relay port range via `ports:`** — publishing coturn's
+  relay range `49152-65535` (16k ports) makes Docker create ~16k iptables
+  DNAT rules, which **OOM-kills the container start** (exit 137) on small
+  hosts (Aliyun ECS). Use `network_mode: host` instead — coturn binds the
+  range natively, zero iptables overhead. This is the official
+  coturn/docker recommendation, and the shipped `docker-compose.yml` already
+  does this.
+
+- **`network_mode: host` disables `ports:`** — the container binds host ports
+  directly; don't also list `ports:` (compose rejects the combo). All port
+  management moves to the host firewall + cloud security group.
+
+- **Config-as-dir gotcha**: if `./turnserver.conf` doesn't exist locally when
+  docker tries to mount it, Docker creates a **directory** at that path
+  (not a file) → coturn fails to read config. Always upload the file BEFORE
+  `up -d`, or pre-`touch` it on the remote.
+
+## Why host networking (rationale)
+
+coturn's relay UDP range (49152-65535 = ~16k ports) must NOT be published via
+docker `-p` — Docker would create ~16k iptables DNAT rules, OOM-killing the
+daemon on small hosts (Aliyun ECS etc.). Host networking lets coturn bind
+the range natively, zero iptables overhead. This is the official
+coturn/docker recommendation.
+
+Ports to open in the host firewall / cloud security group:
+- 3478/tcp + 3478/udp   (TURN/STUN)
+- 5349/tcp + 5349/udp   (TURNS over TLS)
+- 49152-65535/udp       (relay range — open in security group, NOT in docker)
+
+## Files in this template
+
+- `docker-compose.yml` — host-networked coturn container.
+- `turnserver.conf` — minimal config; edit `realm`/`external-ip`/`user` before deploy.

sql_harness-0.2.2/docker-services/coturn/docker-compose.yml

@@ -0,0 +1,29 @@
+# coturn via docker-compose — HOST NETWORKING (production-correct)
+#
+# Why host networking: coturn's relay UDP range (49152-65535 = ~16k ports)
+# must NOT be published via docker `-p` — Docker would create ~16k iptables
+# DNAT rules, OOM-killing the daemon on small hosts (Aliyun ECS etc.).
+# Host networking lets coturn bind the range natively, zero iptables overhead.
+# This is the official coturn/docker recommendation.
+#
+# Ports to open in the host firewall / cloud security group:
+#   3478/tcp + 3478/udp   (TURN/STUN)
+#   5349/tcp + 5349/udp   (TURNS over TLS)
+#   49152-65535/udp       (relay range — open in security group, NOT in docker)
+
+services:
+  coturn:
+    image: coturn/coturn:latest
+    container_name: coturn
+    restart: unless-stopped
+    network_mode: host           # ← binds directly to host ports; no `ports:`
+    volumes:
+      # Relative to THIS dir (~/sql-harness/coturn/) — data + config cohesive.
+      - ./turnserver.conf:/etc/turnserver.conf:ro
+      - ./data:/var/lib/coturn
+    command: ["-c", "/etc/turnserver.conf"]
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"