sql-harness 0.3.3__tar.gz → 0.3.4__tar.gz

{sql_harness-0.3.3 → sql_harness-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sql-harness
-Version: 0.3.3
+Version: 0.3.4
 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
@@ -37,7 +37,7 @@ uv sync
 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'
+uv run sql-harness add --name local_pg --driver postgres --url 'postgresql://postgres:postgres@localhost:5432/postgres'
 
 # 4. Test it
 uv run sql-harness test local_pg

{sql_harness-0.3.3 → sql_harness-0.3.4}/SKILL.md

@@ -7,7 +7,7 @@ description: "Always use sql-harness for SQL, SSH, and database operations — q
 
 A single-process SQL + SSH CLI for agents. 5 drivers (`postgres`, `mysql`, `sqlite`, `redis`, `ssh`) share one heredoc namespace. Connections live in plaintext in one TOML file.
 
-For setup, read `install.md`. For stuck-point mechanics, see `interaction-skills/` (cross-DB) and `interaction-skills/postgres/` (PG depth).
+For setup, read `install.md` (shipped next to this file; in a source checkout it's `docs/install.md`). For stuck-point mechanics, see `interaction-skills/` (cross-DB) and `interaction-skills/postgres/` (PG depth).
 
 ## Reach for sql-harness when...
 
@@ -26,9 +26,9 @@ For setup, read `install.md`. For stuck-point mechanics, see `interaction-skills
 ```bash
 sql-harness --help
 sql-harness list
-sql-harness add <name> --driver postgres --url 'postgresql://user:pw@host/db'
-sql-harness add <name> --driver mysql   --url 'mysql+pymysql://user:pw@host/db'
-sql-harness add <name> --driver ssh     --url 'ssh://user@host:22?key=/path/id_ed25519'
+sql-harness add --name <name> --driver postgres --url 'postgresql://user:pw@host/db'
+sql-harness add --name <name> --driver mysql    --url 'mysql+pymysql://user:pw@host/db'
+sql-harness add --name <name> --driver ssh      --url 'ssh://user@host:22?key=/path/id_ed25519'
 sql-harness test <name>
 
 sql-harness <<'PY'
@@ -71,7 +71,7 @@ Standard SQLAlchemy + PyMySQL. JSON syntax differs from PG — see `interaction-
 
 ### SQLite (`sqlite:///path.db`)
 
-Local dev / tests. All standard helpers work. Use `sql-harness add --driver sqlite --url 'sqlite:///<absolute-path>'` (SQLite needs absolute path).
+Local dev / tests. All standard helpers work. Use `sql-harness add --name <name> --driver sqlite --url 'sqlite:///<absolute-path>'` (SQLite needs absolute path).
 
 ### Redis (`redis://host:port`)
 
@@ -103,7 +103,7 @@ See `interaction-skills/ssh/` for: `ssh.md` (helpers + CLI + gotchas), `docker-v
 | `list_tables(schema=None)` | `list[str]` | Schema recon — always start here |
 | `describe(table, schema=None)` | `list[dict]` | Columns + types — before writing SQL |
 | `table(name, schema=None, limit=None)` | `list[dict]` | Quick peek: `SELECT * FROM x LIMIT n` |
-| `with_transaction()` | context manager yielding `Connection` | ≥ 2 statements / DDL / atomicity |
+| `with_transaction()` | context manager yielding `Connection` | ≥ 2 DML statements / atomicity (DDL: PG+SQLite only) |
 | `run_sql_file(path)` | `list[dict]` | Multi-statement `.sql`, one transaction |
 | `server_version()` | `str` | Round-trip liveness check |
 | `connection_info()` | `dict` | Current workspace metadata |
@@ -159,7 +159,8 @@ Reached via `apply_skill("pool")` etc. from any active zone — `zones/meta/skil
 
 - **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.
 - **Set `BH_SQL_ZONE_SKILLS=1` once** so every `use_workspace()` surfaces that zone's per-DSN skill docs as a hint list (10 filenames max). Then `apply_skill(name)` reads the body when relevant.
-- **Default to `with_transaction()`** for any write with ≥ 2 statements (insert + update, drop + create, …). Atomic + automatic rollback on exception.
+- **Default to `with_transaction()`** for any write with ≥ 2 statements (insert + update, update + delete, …). Automatic rollback on exception — **for DML**. DDL is a different story: PostgreSQL and SQLite roll back `CREATE`/`DROP`/`ALTER` inside a transaction, **MySQL does not** (it implicitly commits), so a `drop + create` migration that fails halfway leaves you with neither table. Run DDL migrations with a backup or a reversible plan, not on the strength of the transaction. See `interaction-skills/migrations.md`.
+- **Transactions are only real on a transactional engine.** A MySQL table created on a server whose `@@default_storage_engine` is not InnoDB (e.g. MyISAM) ignores `ROLLBACK` *silently* — the write sticks and nothing warns you. Check with `SELECT @@default_storage_engine`, and write `ENGINE=InnoDB` explicitly if you need rollback.
 - **For PG performance tasks, reach for the 8 PG-only helpers first** (`explain_analyze`, `slow_queries`, `unused_indexes`, `seq_scan_heavy`, `table_stats`, `index_usage_stats`, `missing_indexes_hint`). Don't hand-parse `pg_stat_*` SQL.
 - **For remote tasks, reach for SSH workspace first.** Don't reach for raw `subprocess` + ssh-key files in agent code — `ssh_exec("systemctl restart myapp")` is one line.
 - **For "insert returning the new id"**: psycopg supports `INSERT … RETURNING id`; MySQL has no `RETURNING` — use `execute(...)` and read `result.lastrowid`.
@@ -189,6 +190,29 @@ Reached via `apply_skill("pool")` etc. from any active zone — `zones/meta/skil
 - For tables > 10k rows, use `engine.connect().execution_options(stream_results=True)` and iterate manually — `query()` loads everything into memory.
 - SSH SFTP subsystem may be disabled on the remote host. `ssh_upload/ssh_download` raise `RuntimeError("SFTP subsystem not available")`; fall back to `tar -czf - | ssh host tar -xzf -` via `ssh_exec`.
 - Default `ssh_exec` timeout is 30 s. Long-running commands (e.g. `pg_dump`, `tar czf`) need explicit `timeout=`.
+- **Long output is spilled to a file, not printed.** A failed run whose traceback is long, and any `ssh exec` / `ssh run-script` output past a few KB, are written to `$BH_SQL_HOME/tmp/output/` and replaced by a pointer line naming the path, line count and size. That is deliberate — read the file when you actually need it. `BH_SQL_TRACEBACK=1` forces the raw traceback to stderr instead. The full traceback always also lands in `$BH_SQL_HOME/sql-harness.log` (NDJSON), whatever the terminal shows.
+
+## Read-only connections (`read_only = true`)
+
+For a sensitive database, mark the connection read-only. Two rails are installed at the driver layer, both attached to the **engine** rather than to `query()`/`execute()` — so `conn.execute()`, `run_sql_file()` and any path that skips the helpers are covered too.
+
+```toml
+[[connections]]
+name = "prod_ro"
+driver = "mysql"
+url = "mysql+pymysql://ro_user@host:3306/proddb"
+read_only = true
+```
+
+```bash
+sql-harness add --name prod_ro --driver mysql --url '...' --read-only
+```
+
+What it refuses: anything whose verb is not `SELECT`/`SHOW`/`DESCRIBE`/`EXPLAIN`/`TABLE`/`VALUES`/`PRAGMA`, plus transaction control. **Unrecognised statements are refused, not permitted** — that is why it is an allow-list: a deny-list misses `CALL`, `DO`, `LOAD DATA`, `HANDLER` and every future statement type. It also handles the dodges a naive keyword match falls for: `/*!50000 DROP */` (MySQL executes those), `SELECT 1; DROP TABLE t`, `WITH x AS (...) DELETE`, `EXPLAIN ANALYZE DELETE` (PostgreSQL executes it), and `#` — which is a comment in MySQL but the XOR operator in PostgreSQL, so treating it as a comment there would hide a write. On MySQL it additionally refuses `INTO OUTFILE`/`INTO DUMPFILE`/`FOR UPDATE`/`LOCK IN SHARE MODE`; on PostgreSQL, `SELECT ... INTO` (creates a table) and the `FOR ...` lock variants.
+
+Where the backend has a session setting, it is applied on **every new pooled connection**: `SET SESSION TRANSACTION READ ONLY` (MySQL) / `SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY` (PostgreSQL). That rail is enforced by the server, so it catches anything that slips past the statement guard (e.g. a stored procedure).
+
+**This is a guard rail, not a security boundary.** Both rails are escapable from the same session — a caller can run `SET SESSION TRANSACTION READ WRITE` and carry on, and any client-side check is pattern matching rather than a parser. The only hard boundary is the database account: use `GRANT SELECT ON db.* TO ...` for a database you genuinely must not write to, and treat everything above as defence in depth on top of it. SQLite has no session rail at all; for a file database the real boundary is the URL (`sqlite:///file:path?mode=ro&uri=true`). SSH workspaces ignore the flag — a remote shell is not a statement stream.
 
 ## Domain / table skills
 

{sql_harness-0.3.3 → sql_harness-0.3.4}/docs/AGENTS.md

@@ -12,10 +12,12 @@ Core code lives in `lab/sql_harness/src/sql_harness/`:
 - `config.py` — TOML schema + ConnectionConfig / ConnectionsConfig dataclasses
 - `paths.py` — XDG-style state directory resolution
 - `drivers/` — backend abstractions (postgres, mysql, redis stub, sqlite for tests)
+- `drivers/readonly.py` — read-only statement guard shared by the SQL drivers: comment/literal-stripping, allow-list verb check, and `install_guard()` which attaches both rails to an engine. Read its module docstring before relying on it — it is a guard rail, not a security boundary
 - `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`
 - `analytics.py` — event bus (observer) + JSON stats + NDJSON execution log: CLI call counts, doc-read tracking, command/error history; `BH_SQL_ANALYTICS` (default ON), view with `sql-harness stats`
+- `output.py` — terminal output policy: UTF-8 stream setup, long-output spill to `$BH_SQL_HOME/tmp/output/`, concise error rendering; `BH_SQL_TRACEBACK=1` forces raw tracebacks
 - `run.py` — heredoc entry; delegates to CLI otherwise
 - `cli.py` — argparse subparser CLI (18 subcommands)
 

{sql_harness-0.3.3 → sql_harness-0.3.4}/docs/README.md

@@ -14,7 +14,7 @@ uv sync
 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'
+uv run sql-harness add --name local_pg --driver postgres --url 'postgresql://postgres:postgres@localhost:5432/postgres'
 
 # 4. Test it
 uv run sql-harness test local_pg

{sql_harness-0.3.3/skills/sql-harness/references → sql_harness-0.3.4/docs}/install.md

@@ -27,7 +27,8 @@ Writes `~/.config/sql-harness/connections.toml` (or `$BH_SQL_HOME/connections.to
 ## 3. Add your first connection
 
 ```bash
-uv run sql-harness add my_pg \
+uv run sql-harness add \
+    --name my_pg \
     --driver postgres \
     --url 'postgresql://user:pw@localhost:5432/db' \
     --description "My dev DB"
@@ -89,7 +90,9 @@ password = "${env:IOT_SSH_PASSWORD}"  # standalone secret — keeps the URL clea
 
 `${env:VAR}` placeholders inside `url` and `password` are expanded at load time from the process environment — keep prod secrets out of the file.
 
-Optional per-connection keys: `description`, `password`, `pool_size`, `pool_recycle`, `pre_ping`, `echo`, `application_name`.
+Optional per-connection keys: `description`, `password`, `read_only`, `pool_size`, `pool_recycle`, `pre_ping`, `echo`, `application_name`.
+
+`read_only = true` refuses writes on that connection — a statement allow-list on every statement the engine sends, plus the server-side session read-only setting where the backend has one. Use it for sensitive databases, but note it is a **guard rail, not a security boundary**: the session setting is escapable from the same session, and any client-side check is pattern matching. Pair it with a `SELECT`-only database account, which is the actual boundary. See `SKILL.md` → "Read-only connections".
 
 SSH password precedence (highest first): password embedded in `url` > the `password` key > `$BH_SSH_PASSWORD`. A connection that sets a password uses password auth exclusively — local `~/.ssh` keys are not consulted (see `interaction-skills/ssh/auth-and-tunnels.md`).
 

{sql_harness-0.3.3 → sql_harness-0.3.4}/docs/maintainer.md

@@ -17,14 +17,26 @@ hand-synced copies. `pyproject.toml` `[tool.hatch.build.targets.wheel.force-incl
 maps the repo docs into the wheel:
 
 - `SKILL.md` → `sql_harness/_skills/SKILL.md`
+- `docs/install.md` → `sql_harness/_skills/install.md`
 - `interaction-skills` → `sql_harness/_skills/interaction-skills`
 - `agent-workspace/zones/meta/skills` → `sql_harness/_skills/zones-meta-skills`
 
 The root `SKILL.md` is the **single source of truth** (v0.3.0 consolidation —
 the old `skills/sql-harness/SKILL.md` and `src/sql_harness/SKILL.md` copies
-were removed). After editing it, just `uv build` again. `sql-harness skill`
-reads `sql_harness/_skills/SKILL.md` from the installed package and falls
-back to the repo-root `SKILL.md` in a source checkout.
+were removed; v0.3.4 removed the last hand-synced copy,
+`skills/sql-harness/references/install.md`). After editing it, just
+`uv build` again. `sql-harness skill` reads `sql_harness/_skills/SKILL.md`
+from the installed package and falls back to the repo-root `SKILL.md` in a
+source checkout.
+
+`SKILL.md` references `install.md` as a sibling file — that only resolves
+because `docs/install.md` is force-included into the bundle as
+`_skills/install.md`. Dropping it from the force-include list breaks the
+reference for every `skill install` user.
+
+`skill install` needs a real (non-editable) wheel install to work: it reads
+`sql_harness/_skills/`, which only exists after `uv build`. In a bare source
+checkout `_bundled_skills_root()` returns `None` and the command exits 2.
 
 ## Build outputs
 
@@ -44,7 +56,7 @@ The wheel contains the package modules + the `_skills/` doc bundle
 ```bash
 # standalone venv
 uv sync
-uv run pytest tests/unit -q    # 80 tests must pass
+uv run pytest tests/unit -q    # 133 tests must pass
 uv run sql-harness --help      # CLI works
 uv run sql-harness skill       # SKILL.md emit works
 ```

{sql_harness-0.3.3 → sql_harness-0.3.4}/interaction-skills/transactions.md

@@ -55,3 +55,4 @@ for attempt in range(3):
 - `text("SELECT ...").execution_options(...)` is per-statement; transaction-level options belong on the `SET` line.
 - Nested `with_transaction()` will create a SAVEPOINT (PostgreSQL) or fail (MySQL). Don't nest.
 - A failed statement inside a transaction does NOT auto-rollback the whole transaction in some dialects — call `conn.rollback()` explicitly if you've swallowed the exception.
+- **A non-transactional table ignores `ROLLBACK` silently.** On MySQL, check `SELECT @@default_storage_engine` before trusting a rollback: if it is not InnoDB, any table created without an explicit `ENGINE=InnoDB` accepts `BEGIN`/`ROLLBACK` and discards them — the row is still there afterwards and nothing errors. Reach for `with_transaction()` on such tables and you get the *appearance* of atomicity with none of the substance.

{sql_harness-0.3.3 → sql_harness-0.3.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sql-harness"
-version = "0.3.3"
+version = "0.3.4"
 description = "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."
 readme = "docs/README.md"
 license = { text = "MIT" }
@@ -50,6 +50,7 @@ packages = ["src/sql_harness"]
 # shipping its SKILL.md in the wheel, but extended to the whole doc bundle.
 # Paths are relative to this pyproject.toml (lab/sql_harness/).
 "SKILL.md" = "sql_harness/_skills/SKILL.md"
+"docs/install.md" = "sql_harness/_skills/install.md"
 "interaction-skills" = "sql_harness/_skills/interaction-skills"
 "agent-workspace/zones/meta/skills" = "sql_harness/_skills/zones-meta-skills"
 

{sql_harness-0.3.3 → sql_harness-0.3.4}/src/sql_harness/analytics.py

@@ -48,8 +48,12 @@ CLI_INVOKED = "cli.invoked"  # payload: {"subcommand": str}
 DOC_READ = "doc.read"        # payload: {"doc": str, "via": str}
 COMMAND_EXECUTED = "command.executed"
 # payload: {"argv": list[str], "code": str|None, "ok": bool,
-#           "exit_code": int, "error": str|None}   (argv = CLI args incl. subcommand;
-#           code = heredoc body when run via stdin; error = message/traceback)
+#           "exit_code": int, "error": str|None}
+#   argv  = CLI args including the subcommand; [] in heredoc mode
+#   code  = the heredoc body; None in CLI mode
+#   error = the FULL traceback when the run died on an uncaught exception,
+#           else None. stderr shows a compressed form (see output.py), so this
+#           log is the only complete channel — it keeps everything.
 
 _OFF_VALUES = {"0", "off", "false", "no"}
 DOC_READS_CAP = 500

{sql_harness-0.3.3 → sql_harness-0.3.4}/src/sql_harness/cli.py

@@ -32,6 +32,7 @@ import shutil
 import subprocess
 import sys
 import time
+import traceback
 from importlib import resources as importlib_resources
 from pathlib import Path
 from typing import Callable
@@ -47,6 +48,7 @@ from .config import (
     save as save_config,
 )
 from .manager import SqlHarness
+from .output import render_exception, set_utf8_streams, spill
 from .paths import (
     config_file,
     ensure_private_dir,
@@ -84,6 +86,7 @@ def cmd_list(_args, harness: SqlHarness) -> int:
             "url": c.masked_url(),
             "description": c.description,
             "password_set": bool(c.password),
+            "read_only": c.read_only,
             "pool_size": c.pool.size,
         })
     _emit({"default_workspace": cfg.default_workspace, "connections": rows})
@@ -113,6 +116,7 @@ def cmd_add(args, harness: SqlHarness) -> int:
 
     description = args.description or ""
     password = getattr(args, "password", None) or ""
+    read_only = bool(getattr(args, "read_only", False))
     pool = PoolConfig(size=args.pool_size or cfg.pool_defaults.size)
 
     cfg.connections.append(
@@ -122,11 +126,18 @@ def cmd_add(args, harness: SqlHarness) -> int:
             url=url,
             description=description,
             password=password,
+            read_only=read_only,
             pool=pool,
         )
     )
     save_config(cfg, config_file())
-    _emit({"added": name, "driver": driver, "url": _mask(url), "password_set": bool(password)})
+    _emit({
+        "added": name,
+        "driver": driver,
+        "url": _mask(url),
+        "password_set": bool(password),
+        "read_only": read_only,
+    })
     return 0
 
 
@@ -176,6 +187,7 @@ def cmd_show(args, harness: SqlHarness) -> int:
         "description": c.description,
         "password_set": bool(c.password),
         "password": c.masked_password(),
+        "read_only": c.read_only,
         "pool": {
             "size": c.pool.size,
             "recycle": c.pool.recycle,
@@ -296,17 +308,15 @@ def cmd_skill(args, _harness: SqlHarness) -> int:
         if body is None:
             print(
                 "error: packaged SKILL.md not found (expected at "
-                "skills/sql-harness/SKILL.md relative to the package)",
+                "sql_harness/_skills/SKILL.md, or the repo-root SKILL.md "
+                "in a source checkout)",
                 file=sys.stderr,
             )
             return 2
-        # Force UTF-8 on stdout so non-ASCII skill bodies emit cleanly on Windows
-        # (default GBK/CP936 codepage can't encode symbols like ⇄).
+        # stdout is already UTF-8 (set_utf8_streams() runs at the top of main()),
+        # which is what lets non-ASCII skill bodies emit cleanly on Windows —
+        # the default GBK/CP936 codepage can't encode symbols like ⇄.
         out = sys.stdout
-        try:
-            out.reconfigure(encoding="utf-8", errors="replace")
-        except (AttributeError, OSError):
-            pass
         out.write(body)
         if not body.endswith("\n"):
             out.write("\n")
@@ -594,13 +604,9 @@ def cmd_save(args, _harness: SqlHarness) -> int:
     conn, code = _require_connection_or_fail(args)
     if code:
         return code
-    # Read stdin as UTF-8 on Windows (default locale is GBK/CP936, which
-    # mangles non-ASCII bytes into surrogates that write_text rejects).
-    # Mirrors run.py's heredoc-mode stdin handling.
-    try:
-        sys.stdin.reconfigure(encoding="utf-8", errors="replace")
-    except (AttributeError, OSError):
-        pass
+    # stdin is already UTF-8 (set_utf8_streams() runs at the top of main()):
+    # on Windows the default GBK/CP936 locale mangles non-ASCII bytes into
+    # surrogates that write_text rejects. Mirrors run.py's heredoc mode.
     body = sys.stdin.read()
     if not body.strip():
         print("error: stdin is empty; nothing to save", file=sys.stderr)
@@ -668,11 +674,11 @@ def cmd_run(args, harness: SqlHarness) -> int:
         return 0
     except SystemExit as e:
         return int(e.code) if e.code is not None else 0
-    except Exception:
-        import traceback
+    # Real failures propagate to main(), which stores the full traceback in the
+    # analytics log and renders the short form to stderr. Catching here would
+    # mean a saved-script crash left no traceback anywhere — the frames already
+    # carry the script's real path, so the report names the failing line.
 
-        traceback.print_exc()
-        return 1
 
 
 def cmd_scripts(args, _harness: SqlHarness) -> int:
@@ -853,9 +859,11 @@ def cmd_ssh(args, harness: SqlHarness) -> int:
 
     if sub == "exec":
         result = _h.ssh_exec(args.command, timeout=args.timeout)
-        sys.stdout.write(result["stdout"])
+        # Remote output length is unbounded (cat of a big file, a chatty log);
+        # spill it so a long command doesn't flood the caller's context.
+        sys.stdout.write(spill(result["stdout"], "ssh-stdout"))
         if result["stderr"]:
-            sys.stderr.write(result["stderr"])
+            sys.stderr.write(spill(result["stderr"], "ssh-stderr"))
         return 0 if result["ok"] else result["exit_code"]
 
     if sub == "upload":
@@ -870,9 +878,9 @@ def cmd_ssh(args, harness: SqlHarness) -> int:
 
     if sub == "run-script":
         result = _h.ssh_run_script(args.local, args.remote_dir, args.interpreter)
-        sys.stdout.write(result["stdout"])
+        sys.stdout.write(spill(result["stdout"], "ssh-stdout"))
         if result["stderr"]:
-            sys.stderr.write(result["stderr"])
+            sys.stderr.write(spill(result["stderr"], "ssh-stderr"))
         return 0 if result["ok"] else result["exit_code"]
 
     if sub == "info":
@@ -906,6 +914,11 @@ def _build_parser() -> argparse.ArgumentParser:
         "--password",
         help="standalone secret (SSH password); keeps the URL credential-free",
     )
+    p_add.add_argument(
+        "--read-only",
+        action="store_true",
+        help="refuse writes on this connection (statement guard + session read-only)",
+    )
     p_add.add_argument("--pool-size", type=int)
 
     p_edit = sub.add_parser("edit", help="edit connections.toml in $EDITOR")
@@ -1006,6 +1019,12 @@ def _build_parser() -> argparse.ArgumentParser:
 
 
 def main(argv: list[str]) -> int:
+    # Before anything can print: force UTF-8 on the standard streams so data
+    # that legitimately contains non-GBK characters (Chinese descriptions in
+    # connections.toml, CJK paths, remote host output) reports instead of
+    # crashing the process that was trying to report it.
+    set_utf8_streams()
+
     parser = _build_parser()
     args = parser.parse_args(argv)
     if not args.cmd:
@@ -1044,12 +1063,15 @@ def main(argv: list[str]) -> int:
             {"argv": argv, "code": None, "ok": rc == 0, "exit_code": rc, "error": None},
         )
         return rc
-    except Exception as e:
+    except Exception as exc:
+        # The analytics log keeps the full traceback (machine-readable record);
+        # the terminal gets the short form. Same split as heredoc mode.
         emit(
             COMMAND_EXECUTED,
             {"argv": argv, "code": None, "ok": False, "exit_code": 1,
-             "error": f"{type(e).__name__}: {e}"},
+             "error": "".join(traceback.format_exception(exc))},
         )
-        raise
+        sys.stderr.write(render_exception(exc, label=f"cli-{args.cmd}"))
+        return 1
     finally:
         harness.close_all()

{sql_harness-0.3.3 → sql_harness-0.3.4}/src/sql_harness/config.py

@@ -69,6 +69,7 @@ class ConnectionConfig:
     url: str
     description: str = ""
     password: str = ""                         # standalone secret (SSH password)
+    read_only: bool = False                    # refuse writes: see drivers/readonly.py
     pool: PoolConfig = field(default_factory=PoolConfig)
     application_name: str = "sql-harness"
 
@@ -161,6 +162,8 @@ def save(cfg: ConnectionsConfig, path: Path) -> None:
             lines.append(f'description = "{_toml_str(c.description)}"')
         if c.password:
             lines.append(f'password = "{_toml_str(c.password)}"')
+        if c.read_only:
+            lines.append("read_only = true")
         if c.pool.size != cfg.pool_defaults.size:
             lines.append(f"pool_size = {c.pool.size}")
         if c.pool.recycle != cfg.pool_defaults.recycle:
@@ -218,6 +221,7 @@ def _from_dict(raw: dict[str, Any]) -> ConnectionsConfig:
                 url=_expand_env(str(entry["url"])),
                 description=str(entry.get("description", "")),
                 password=_expand_env(str(entry.get("password", ""))),
+                read_only=bool(entry.get("read_only", False)),
                 pool=pool,
                 application_name=str(entry.get("application_name", "sql-harness")),
             )

{sql_harness-0.3.3 → sql_harness-0.3.4}/src/sql_harness/drivers/__init__.py

@@ -17,12 +17,24 @@ class Driver(Protocol):
 
     name: str
 
-    def make_engine(self, url: str, pool: "PoolConfig", password: str | None = None) -> Engine:
+    def make_engine(
+        self,
+        url: str,
+        pool: "PoolConfig",
+        password: str | None = None,
+        read_only: bool = False,
+    ) -> Engine:
         """Create a SQLAlchemy Engine with the given pool config.
 
         `password` is the connection's standalone secret (ConnectionConfig.password).
         Drivers whose URL already carries credentials (SQL backends) ignore it;
         SSH uses it when no password is embedded in the URL.
+
+        `read_only` installs that dialect's read-only rails (see
+        `drivers/readonly.py`): a statement allow-list on every
+        `before_cursor_execute`, plus the server-side session setting where the
+        backend has one. Drivers with no notion of statements (SSH, Redis)
+        accept it for API parity.
         """
 
     def list_tables(self, engine: Engine, schema: str | None) -> list[str]:

{sql_harness-0.3.3 → sql_harness-0.3.4}/src/sql_harness/drivers/mysql.py

@@ -4,17 +4,44 @@ from __future__ import annotations
 
 from sqlalchemy import Engine, create_engine, inspect, text
 
+from .readonly import install_guard
+
+# Dangerous even inside an otherwise read-only statement: file writes and row
+# locks. MySQL's `#` is a comment and `\'` escapes inside strings.
+_MYSQL_FORBIDDEN = frozenset(
+    {
+        "INTO OUTFILE",
+        "INTO DUMPFILE",
+        "FOR UPDATE",
+        "FOR SHARE",
+        "LOCK IN SHARE MODE",
+    }
+)
+
 
 class MysqlDriver:
     name = "mysql"
 
-    def make_engine(self, url: str, pool, password: str | None = None) -> Engine:
+    def make_engine(
+        self, url: str, pool, password: str | None = None, read_only: bool = False
+    ) -> Engine:
         # `password` is ignored: credentials live in the URL for SQL backends.
         if not url.startswith("mysql+pymysql://"):
             raise ValueError(
                 f"MySQL URL must start with mysql+pymysql:// (got {url[:30]!r})"
             )
-        return create_engine(url, **pool.sqlalchemy_kwargs())
+        engine = create_engine(url, **pool.sqlalchemy_kwargs())
+        if read_only:
+            install_guard(
+                engine,
+                hash_comments=True,
+                backslash_escapes=True,
+                extra_forbidden=_MYSQL_FORBIDDEN,
+                # Server-enforced rail: MySQL then rejects DML *and* DDL with
+                # 1792 "Cannot execute statement in a READ ONLY transaction".
+                session_sql="SET SESSION TRANSACTION READ ONLY",
+            )
+        return engine
 
     def list_tables(self, engine: Engine, schema: str | None) -> list[str]:
         insp = inspect(engine)

{sql_harness-0.3.3 → sql_harness-0.3.4}/src/sql_harness/drivers/postgres.py

@@ -4,11 +4,28 @@ from __future__ import annotations
 
 from sqlalchemy import Engine, create_engine, inspect, text
 
+from .readonly import install_guard
+
+# `SELECT ... INTO t` creates a table in PostgreSQL (unlike MySQL, where INTO
+# means OUTFILE). Spaced so `FROM into_log` is not a false positive. The FOR
+# variants take row locks.
+_PG_FORBIDDEN = frozenset(
+    {
+        " INTO ",
+        "FOR UPDATE",
+        "FOR NO KEY UPDATE",
+        "FOR SHARE",
+        "FOR KEY SHARE",
+    }
+)
+
 
 class PostgresDriver:
     name = "postgres"
 
-    def make_engine(self, url: str, pool, password: str | None = None) -> Engine:
+    def make_engine(
+        self, url: str, pool, password: str | None = None, read_only: bool = False
+    ) -> Engine:
         # `password` is ignored: credentials live in the URL for SQL backends.
         # Accept all three SQLAlchemy-recognized PostgreSQL URL prefixes:
         #   postgresql+psycopg://  (explicit dialect — preferred)
@@ -26,7 +43,20 @@ class PostgresDriver:
                 f"PostgreSQL URL must start with postgres:// or postgresql:// "
                 f"(got {url[:30]!r})"
             )
-        return create_engine(url, **pool.sqlalchemy_kwargs())
+        engine = create_engine(url, **pool.sqlalchemy_kwargs())
+        if read_only:
+            install_guard(
+                engine,
+                # `#` is the bitwise-XOR operator in PostgreSQL, not a comment —
+                # treating it as one would swallow real code and hide a write.
+                hash_comments=False,
+                backslash_escapes=False,
+                extra_forbidden=_PG_FORBIDDEN,
+                # Server-enforced rail: writes then fail with
+                # "cannot execute ... in a read-only transaction".
+                session_sql="SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY",
+            )
+        return engine
 
     def list_tables(self, engine: Engine, schema: str | None) -> list[str]:
         insp = inspect(engine)