All plugins

sql-dryrun

Shows how many rows a DELETE/UPDATE/DROP/TRUNCATE will touch before it runs, and sends it to Hermes' approval prompt when it is too many. Built-in approval matches command shape only, so UPDATE with no WHERE, DELETE ... WHERE 1=1, a WHERE that matches every row, and DELETE FROM t; SELECT ... WHERE ... all run unprompted; sql-dryrun flags them with the real count ("228,789 of 250,000 rows"). Covers sqlite3, psql and mysql/mariadb (inline -c/-e, heredoc, piped), execute_code, and tools passing SQL in a sql/query/statement argument. Settings: row_threshold (default 100), mode approve|block, count timeout. Adds a sql_impact tool for dry-running a statement and a /sql-dryrun command. Tested on SQLite, Postgres and MariaDB. MIT licensed. Disclosure — reads the arguments of terminal, execute_code and tools with a sql/query/statement argument. For a destructive statement whose database it can reach, it runs read-only SELECT COUNT(*) queries: SQLite in-process (mode=ro, trusted_schema=OFF); Postgres/MySQL only via a bare psql/mysql/mariadb resolved with shutil.which() and never from inside the working tree, with a minimal env (PATH/HOME/LANG/LC_*/TZ plus PG* except PGOPTIONS, or MYSQL_PWD/HOST/TCP_PORT/UNIX_PORT) and allowlisted connection flags only (options= in a conninfo/URI, any other flag including --defaults-file, or a password prompt skips the count; mysql always runs with --no-defaults). A statement containing ';' or a backslash is never sent to a database and goes to approval uncounted. Because the WHERE runs before approval, it is only counted when it is a plain predicate (comparisons, AND/OR, IN/EXISTS subqueries, an allowlist of pure built-in functions); any other function call, INTO, FOR UPDATE, '$' or a comment marker skips the count. Postgres runs BEGIN READ ONLY and verifies SHOW transaction_read_only before counting; MySQL runs inside START TRANSACTION READ ONLY ... ROLLBACK; both with a timeout and no password prompt. Counts only run when terminal.backend is local; on docker/ssh/modal/daytona statements are flagged by shape only. No network calls of its own, no files written, no data changed, no credentials stored; the flagged SQL appears in the approval message.

AoyamaToolsv0.1.3Updated 7 days ago

About

Shows how many rows a DELETE/UPDATE/DROP/TRUNCATE will touch before it runs, and sends it to Hermes' approval prompt when it is too many. Built-in approval matches command shape only, so UPDATE with no WHERE, DELETE ... WHERE 1=1, a WHERE that matches every row, and DELETE FROM t; SELECT ... WHERE ... all run unprompted; sql-dryrun flags them with the real count ("228,789 of 250,000 rows"). Covers sqlite3, psql and mysql/mariadb (inline -c/-e, heredoc, piped), execute_code, and tools passing SQL in a sql/query/statement argument. Settings: row_threshold (default 100), mode approve|block, count timeout. Adds a sql_impact tool for dry-running a statement and a /sql-dryrun command. Tested on SQLite, Postgres and MariaDB. MIT licensed. Disclosure — reads the arguments of terminal, execute_code and tools with a sql/query/statement argument. For a destructive statement whose database it can reach, it runs read-only SELECT COUNT() queries: SQLite in-process (mode=ro, trusted_schema=OFF); Postgres/MySQL only via a bare psql/mysql/mariadb resolved with shutil.which() and never from inside the working tree, with a minimal env (PATH/HOME/LANG/LC_*/TZ plus PG except PGOPTIONS, or MYSQL_PWD/HOST/TCP_PORT/UNIX_PORT) and allowlisted connection flags only (options= in a conninfo/URI, any other flag including --defaults-file, or a password prompt skips the count; mysql always runs with --no-defaults). A statement containing ';' or a backslash is never sent to a database and goes to approval uncounted. Because the WHERE runs before approval, it is only counted when it is a plain predicate (comparisons, AND/OR, IN/EXISTS subqueries, an allowlist of pure built-in functions); any other function call, INTO, FOR UPDATE, '$' or a comment marker skips the count. Postgres runs BEGIN READ ONLY and verifies SHOW transaction_read_only before counting; MySQL runs inside START TRANSACTION READ ONLY ... ROLLBACK; both with a timeout and no password prompt. Counts only run when terminal.backend is local; on docker/ssh/modal/daytona statements are flagged by shape only. No network calls of its own, no files written, no data changed, no credentials stored; the flagged SQL appears in the approval message.

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 runsBuilt-insql-dryrun
DELETE FROM orders WHERE id = 7runsruns (1 row)
DELETE FROM users WHERE 1=1runsapproval: WHERE is always true — every row in users (500)
UPDATE users SET active=0runsapproval: UPDATE with no WHERE — every row in users (500)
DELETE FROM orders WHERE created_at < '2030-01-01'runsapproval: WHERE matches ALL 12,850 rows in orders
DELETE FROM users; SELECT * FROM orders WHERE id=1runsapproval: 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

  1. A pre_tool_call hook looks at terminal and execute_code calls, plus any tool that passes SQL in a sql / query / statement argument (MCP database servers).
  2. It finds SQL fed to sqlite3, psql, mysql or mariadb — inline (-c, -e, positional), heredoc (<<SQL) or piped (echo "…" | sqlite3 db).
  3. Each DELETE / UPDATE / DROP TABLE / TRUNCATE / ALTER TABLE … DROP COLUMN is split out (quotes, comments and ; handled), and its WHERE is re-used in a SELECT COUNT(*):
    • SQLite — opened with mode=ro, in-process.
    • Postgres — psql with default_transaction_read_only=on and a statement timeout.
    • MySQL / MariaDB — inside START TRANSACTION READ ONLY … ROLLBACK.
  4. 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:

KeyDefaultMeaning
row_threshold100A WHERE-qualified DELETE/UPDATE touching more rows than this needs approval
modeapproveapprove = Hermes approval prompt, block = refuse and tell the agent why
count_timeout_seconds5Max time for the count query (0.5–20)
flag_uncountedfalseAlso 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 / mariadb token, resolved with shutil.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 libpq PG* variables (never PGOPTIONS) or MYSQL_PWD / MYSQL_HOST / MYSQL_TCP_PORT / MYSQL_UNIX_PORT. No provider API keys or anything else. $DATABASE_URL is 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 with options= (percent-encoded too), or a password prompt → no count. MySQL always runs with --no-defaults, so no option file can add an init-command.
    • Read-only, checked: Postgres runs BEGIN TRANSACTION READ ONLY, then SHOW transaction_read_only must return on before any count is trusted; PGOPTIONS is set by the plugin, not inherited. MySQL runs inside START TRANSACTION READ ONLY … ROLLBACK. Both with a timeout and no password prompt.
  • 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() or SELECT … INTO OUTFILE. So a WHERE is only counted when it is comparisons, AND/OR, IN/EXISTS subqueries 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 through hermes_cli.config) is local. 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.

More by Aoyama

2 plugins by Aoyama in the catalog.

Developer Mode

Explore built-in Hermes toolsets and actions.

HermesAgent

Developer?

Create a Hermes extension for Desktop or agent workflows.

Developer Section