agent-sql

Eight drivers, one interface — PostgreSQL, CockroachDB, MySQL, MariaDB, SQLite, DuckDB, Snowflake and MSSQL

Two gates before any write — the credential must carry writePermission and the query must pass --write, so allowed credentials still cannot write by accident

Enforcement per engine, not per convention — libpg-query validates PostgreSQL statements, MySQL runs each query in START TRANSACTION READ ONLY, SQLite opens SQLITE_OPEN_READONLY, DuckDB runs -readonly

Fails closed on syntax it cannot parse — the CockroachDB guard refuses CRDB-specific syntax rather than waving it through

LLM-safe credential entry — credential add --form opens a native OS dialog (osascript, zenity/kdialog, Win32) so the secret never touches argv or the model's context; the agent sees a redacted receipt

Config files never hold secrets — connection add rejects URLs with embedded credentials and demands a keychain-backed --credential instead

Schema exploration — tables, describe, indexes, constraints, pattern search and a whole-schema dump

Query surface — run, sample, count with --where, and explain with optional --analyze

Parquet through DuckDB — query files directly with duckdb:// and a glob, no import step

Result caps and timeouts by default — 10,000 rows and 30s, both configurable and overridable per command

Token-aware output — --compact emits typed NDJSON with column names once and rows as arrays; long strings truncate with @truncated metadata recording original lengths

Honest pagination — a trailing @pagination line says whether more rows exist rather than silently cutting off

Structured errors and advisories — errors as JSON on stderr with fixable_by and hint; non-error notices as their own structured lines, so stdout stays clean NDJSON

Single compiled Go binary — no runtime dependencies, except the duckdb CLI for DuckDB connections