sql-dryrun
Know how many rows a query will hit before your agent runs it.
Hermes asks for approval on DROP TABLE, TRUNCATE and DELETE FROM with no WHERE — it matches the shape of the command. sql-dryrun checks the impact: it asks the database (read-only) how many rows a DELETE/UPDATE would actually touch, and puts that number in front of you before anything changes.
What it catches that shape-matching misses
Same SQLite file, 500 users, 12,850 orders. Left: Hermes' built-in detector. Right: sql-dryrun.
| Command the agent runs | Built-in | sql-dryrun |
|---|---|---|
DELETE FROM orders WHERE id = 7 | runs | runs (1 row) |
DELETE FROM users WHERE 1=1 | runs | approval: WHERE is always true — every row in users (500) |
UPDATE users SET active=0 | runs | approval: UPDATE with no WHERE — every row in users (500) |
DELETE FROM orders WHERE created_at < '2030-01-01' | runs | approval: WHERE matches ALL 12,850 rows in orders |
DELETE FROM users; SELECT * FROM orders WHERE id=1 | runs | approval: DELETE with no WHERE — every row in users (500) |
On Postgres (250,000 orders):
sql-dryrun checked this SQL before it runs:
• DELETE FROM orders WHERE created_at < '2025-12-01'
where: psql
⚠ 228,789 rows would change in orders (91.5% of the table), over the 100-row limit
impact: 228,789 of 250,000 rows
How it works
- A
pre_tool_callhook looks atterminalandexecute_codecalls, plus any tool that passes SQL in asql/query/statementargument (MCP database servers). - It finds SQL fed to
sqlite3,psql,mysqlormariadb— inline (-c,-e, positional), heredoc (<<SQL) or piped (echo "…" | sqlite3 db). - Each
DELETE/UPDATE/DROP TABLE/TRUNCATE/ALTER TABLE … DROP COLUMNis split out (quotes, comments and;handled), and itsWHEREis re-used in aSELECT COUNT(*):- SQLite — opened with
mode=ro, in-process. - Postgres —
psqlwithdefault_transaction_read_only=onand a statement timeout. - MySQL / MariaDB — inside
START TRANSACTION READ ONLY … ROLLBACK.
- SQLite — opened with
- Flagged statements go to Hermes' normal approval prompt (or are blocked, if you choose). Safe ones run with no prompt at all.
A statement is flagged when it has no WHERE, a WHERE that is always true (1=1, true, id=id, … OR 1=1), a WHERE that matches every row, or touches more rows than row_threshold. DROP / TRUNCATE / DROP COLUMN are always flagged, with the row count of what's lost.
When there's no database to count in (SQL inside Python code, a remote MCP tool), it still flags by shape — including the UPDATE-without-WHERE and 1=1 cases Hermes lets through.
Agent tool and command
sql_impact— the agent can dry-run a statement before writing it:{"sql": "UPDATE users SET active=0 WHERE id <= 40", "sqlite_db": "shop.db"}→rows_affected: 40, rows_in_table: 500./sql-dryrun— current settings and the last checks this session.
Install
hermes plugins install aoyamari/hermes-sql-dryrun
hermes plugins enable sql-dryrun
Settings
plugins.entries.sql-dryrun.settings in config.yaml:
| Key | Default | Meaning |
|---|---|---|
row_threshold | 100 | A WHERE-qualified DELETE/UPDATE touching more rows than this needs approval |
mode | approve | approve = Hermes approval prompt, block = refuse and tell the agent why |
count_timeout_seconds | 5 | Max time for the count query (0.5–20) |
flag_uncounted | false | Also ask approval when a WHERE-qualified statement couldn't be counted |
Disclosure
Reads the tool arguments of terminal, execute_code and tools with a sql/query/statement argument. When a destructive statement targets a database it can reach, it runs read-only SELECT COUNT(*) queries against it:
- SQLite — in-process,
mode=ro,trusted_schema=OFF. - Postgres / MySQL / MariaDB — the system client, under strict rules:
- Which binary: only a bare
psql/mysql/mariadbtoken, resolved withshutil.which(). A path (./psql,/tmp/x/psql) or a PATH hit inside the agent's working tree is never run — the statement is flagged by shape instead. - Which environment:
PATH,HOME,LANG,LC_*,TZ, plus libpqPG*variables (neverPGOPTIONS) orMYSQL_PWD/MYSQL_HOST/MYSQL_TCP_PORT/MYSQL_UNIX_PORT. No provider API keys or anything else.$DATABASE_URLis expanded only when it is the whole argument. - Which flags: connection flags only (
psql -h -p -U -d, a dbname/URI;mysql -h -P -u -D -S -pVALUE, a database). Any other flag (including--defaults-file), a conninfo/URI withoptions=(percent-encoded too), or a password prompt → no count. MySQL always runs with--no-defaults, so no option file can add aninit-command. - Read-only, checked: Postgres runs
BEGIN TRANSACTION READ ONLY, thenSHOW transaction_read_onlymust returnonbefore any count is trusted;PGOPTIONSis set by the plugin, not inherited. MySQL runs insideSTART TRANSACTION READ ONLY … ROLLBACK. Both with a timeout and no password prompt.
- Which binary: only a bare
- One statement only: if the statement contains a
;or a backslash anywhere, it is never sent to a database — it goes to the approval prompt uncounted. Servers disagree on what\'means, so the text can't be trusted to stay one statement. - Plain predicates only: the WHERE is executed before you approve anything, and a read-only transaction doesn't stop
pg_reload_conf(),dblink_exec()orSELECT … INTO OUTFILE. So a WHERE is only counted when it is comparisons,AND/OR,IN/EXISTSsubqueries and a short list of pure built-ins (lower,coalesce,now,date, …). Any other function call, a schema-qualified or quoted function name,INTO,FOR UPDATE,$, or a comment marker → no count. - Where: counts only run when
terminal.backend(read throughhermes_cli.config) islocal. On docker / ssh / modal / daytona the host's database isn't the sandbox's, so statements are flagged by shape only.
No network calls of its own, no files written, no data changed, nothing stored; the flagged SQL appears in the approval message. Not counted: statements with CTEs or joins (USING, UPDATE … FROM, multi-table) — those are still flagged by shape.
Tests
python -m pytest tests
MIT © Aoyama
README from the reviewed commit 666d11f; it updates when the author re-pins.

Aoyama