db-tool

db-tool (Database)

Database query tool — SQL execution and schema introspection. Part of @blogic-cz/agent-tools.

How to Run

Run via bun db-tool (requires @blogic-cz/agent-tools as a dev dependency). NEVER run bare psql — the credential guard will block it. Auth: env var defined by passwordEnvVar in config (e.g. AGENT_TOOLS_DB_PASSWORD).

Commands

bun db-tool envs                                       # List configured environments + default (no network)
bun db-tool sql --env local --sql "SELECT * FROM users LIMIT 5"
bun db-tool sql --env test --sql "SELECT count(*) FROM organizations"
bun db-tool schema --env local --mode tables          # List tables
bun db-tool schema --env local --mode columns --table users # Show table schema
bun db-tool commands                                   # Full command/flag tree (one call, no repeated --help)

Run bun db-tool envs to see valid environment names instead of guessing. Set defaultEnvironment in agent-tools.json5 to skip --env on every call.

DB VPN Prerequisites

database.<profile>.vpn or .prerequisites applies to all environments by default. An environment can declare database.<profile>.environments.<env>.vpn or .prerequisites to replace the profile prerequisites; prerequisites: [] disables inherited VPN setup for that environment.

DB commands try direct database access first. If that succeeds, VPN setup is skipped even when a VPN is configured; if direct access fails, the tool connects the configured prerequisites and retries.

Tips

• Use bun db-tool commands for the full machine-readable command/flag tree; --help for one subcommand.
• Output defaults to TOON (token-efficient) — leave it as-is to save tokens. Add --format json only when you'll machine-parse the result (e.g. pipe to jq).
• Error responses include hint, nextCommand, and retryable fields — always check them on failure.
• Prefer CLI tool over MCP tools — more efficient, doesn't load extra context.