sql-agent-cli: A Read-Only SQL Command-Line Tool Designed for AI Agent Workflows

sql-agent-cli is a read-only SQL command-line tool designed specifically for AI agent workflows. It supports mainstream databases like MySQL, PostgreSQL, SQLite, and MariaDB. Its core goal is to provide a secure query interface for AI assistants to access database information reliably, addressing the safety risks of AI interacting with databases. Key features include strict read-only restrictions, multiple output formats (JSON, Markdown, etc.), native credential management, and SSL encryption.

As AI agents are widely used in business scenarios, enabling AI to access databases safely and reliably has become critical. Traditional database clients lack AI-specific security constraints—granting AI full write access risks accidental data modification or security breaches, especially when using AI coding assistants like Claude Code or Codex CLI. sql-agent-cli was created to solve this problem by prioritizing security through read-only limits and fine-grained access control.

The core design philosophy of sql-agent-cli is "Safety First, Simplicity Above All". It uses a read-only design to eliminate data modification risks. It supports multiple databases (MySQL, MariaDB, PostgreSQL, SQLite) and offers standardized output formats (JSON default, Markdown, table, CSV). Basic usage examples:

• Direct query: sql-agent-cli \\"SELECT id, name FROM users LIMIT 10\\"
• Named target: sql-agent-cli --target reporting \\"SELECT COUNT(*) AS total FROM users\\" It also supports input from SQL files or stdin.

Read-only protection: It intercepts data-modifying statements (INSERT, UPDATE, DELETE, CREATE, DROP, ALTER) via SQL parsing, allowing only SELECT, WITH...SELECT, SHOW, DESCRIBE, EXPLAIN. Credential management: Uses native client mechanisms (e.g., .pgpass for PostgreSQL, ~/.my.cnf for MySQL) to avoid password exposure. Supports --password-stdin or --prompt-password for safe password input. SSL connection: Defaults to SSL encryption, with modes like required/preferred/disabled (production recommends required).

AI integration: JSON output (default) is ideal for AI agents to parse and process. Markdown/table formats suit human reading or reports. Use cases:

1. AI-assisted development: Let Claude Code query DB structure for accurate code without modification risks.
2. Data exploration: Analysts safely explore data distribution.
3. Automated reporting: Generate DB status reports via scheduled tasks.
4. CI/CD integration: Verify DB migration consistency or test data readiness.

Config file uses TOML format (~/.sql-agent-cli/config.toml) for default targets, output formats, and DB connections. Key commands:

• config show: Display current config (no sensitive info).
• config set-default-target: Set default DB target.
• config add-target/remove-target: Manage DB targets.
• config init-native-auth: Generate native auth config templates.
• targets: List all configured targets.

sql-agent-cli uses Python database drivers: PyMySQL (MySQL/MariaDB), psycopg (PostgreSQL), sqlite3 (SQLite). SQL parsing relies on sqlglot library to enforce read-only rules. It uses uv as the Python package manager, supporting direct execution via uvx without manual dependency installation.

sql-agent-cli addresses AI agent DB access safety concerns through multiple security layers (read-only, native credentials, SSL). It enables developers to let AI explore data without worrying about accidental modifications. It is a valuable tool for any scenario integrating DB queries into AI workflows, such as AI-assisted development, data analysis, and automation.