agent-sql

Read-only-by-default SQL CLI for AI agents

Language: Go
Version: 1.3.0
License: MIT
Category: CLI Tool

A SQL CLI designed for AI agents that need safe database exploration across eight engines. It provides schema inspection, flexible querying, and configurable output formats — with defense-in-depth safety rails that require explicit opt-in for any write operations.

Features

Structured JSONL output — all output to stdout, errors to stderr as JSON

LLM-optimized docs via agent-sql usage for agent consumption

Read-only by default — write access requires explicit opt-in per credential and per query

Defense in depth — driver-level, parser-level, and credential-level enforcement layers

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

Schema exploration — tables, describe, indexes, constraints, search

Configurable output formats — JSONL, JSON, YAML, CSV

Compact mode for reduced token count in agent workflows

Single compiled Go binary — no runtime dependencies

Install

Homebrew

$ brew install shhac/tap/agent-sql

AI Agent Skill

$ npx skills add shhac/agent-sql

GitHub Release (macOS)

$ curl -L https://github.com/shhac/agent-sql/releases/latest/download/agent-sql-darwin-arm64.tar.gz | tar xz

Go Install

$ go install github.com/shhac/agent-sql/cmd/agent-sql@latest

Build from Source

$ git clone https://github.com/shhac/agent-sql.git && cd agent-sql && make build

Getting Started

agent-sql accepts inline connection strings, file paths, or saved aliases. For databases you use repeatedly, store credentials and connections for easy reuse.

01 · Quick ad-hoc query

$ agent-sql run -c ./data.db 'SELECT * FROM users'

SQLite and DuckDB files work directly with -c. PostgreSQL, MySQL, MariaDB, CockroachDB, Snowflake, and MSSQL accept connection URLs.

02 · Store credentials for repeated use

$ agent-sql credential add pg-cred --username app --password secret

Passwords are stored in macOS Keychain when available. Credentials are always redacted in list output.

03 · Add a named connection

$ agent-sql connection add mydb postgres://localhost:5432/myapp --credential pg-cred

The credential is injected at connect time, keeping passwords out of connection strings and invisible to LLMs.

04 · Test the connection

$ agent-sql connection test

Usage

>_ List tables

$ agent-sql schema tables

>_ Describe a table

$ agent-sql schema describe users

>_ Query with inline connection

$ agent-sql run -c postgres://user:pass@localhost/myapp 'SELECT * FROM users LIMIT 10'

>_ Sample rows

$ agent-sql query sample users --limit 5

>_ Explain a query plan

$ agent-sql query explain "SELECT * FROM orders JOIN users ON orders.user_id = users.id"

>_ Search schema for a column

$ agent-sql schema search email