Squix Skill for AI Coding Agents

What is Squix

Squix is a CLI tool for managing and executing SQL queries across multiple databases (PostgreSQL, MySQL, SQLite, Oracle, SQL Server, ClickHouse, Firebird). It stores named queries in ~/.config/squix/config.yaml.

Critical Rules

1. Always use -f with squix run for SELECT queries — without it, SELECT results open an interactive TUI; non-SELECT queries print a status message either way
2. No inline connection flag — must squix switch <name> before queries
3. Check connection first — run squix status to verify reachability

Non-Interactive Output

squix run <query> -f json        # JSON array of objects
squix run <query> -f csv         # CSV with header row
squix run <query> -f tsv         # Tab-separated values
squix run <query> -f markdown    # Markdown table
squix run <query> -f html        # HTML table with styling
squix run <query> -f sql         # INSERT statements
squix run "SELECT 1" -f json     # Inline SQL works too
squix run --last -f csv          # Re-run last query

Output goes to stdout, errors to stderr. Exit code 1 on failure. Pipe cleanly: squix run list_users -f json > users.json

Empty results: "No results found" on stderr, nothing on stdout.

Setup Workflow

squix init mydb "postgresql://user:pass@localhost:5432/mydb"  # auto-infers DB type
squix switch mydb                                              # or: squix use mydb
squix add list_users "SELECT * FROM users"                     # SQL must be inline
squix run list_users -f json                                   # always use -f

Explore Schema

squix explore              # List all tables (non-interactive, prints to stdout)
squix explain orders -d 2  # Show FK relationships as ASCII tree

List Queries

squix list queries            # Format: ◆ <id>/<name> (<table>)
squix list queries --oneline  # Compact: <id> <name> <table>
squix list connections        # List all configured connections

Parameterized Queries

Named params use :name syntax. Optional defaults with :name|default:

squix add user_by_id "SELECT * FROM users WHERE id = :user_id"
squix run user_by_id --user_id 42 -f csv    # named
squix run user_by_id 42 -f csv              # positional

Status & Cleanup

squix status                 # Shows: ● postgres/mydb (schema: public) — reachable
squix remove list_users      # Delete query (no confirmation needed)
echo y | squix remove -c mydb  # Delete connection (needs confirmation)

Commands to Avoid (Interactive)

• squix run <query> without -f on a SELECT — opens TUI
• squix shell — interactive REPL
• squix edit — opens $EDITOR
• squix explore <table> — opens TUI
• squix info — opens TUI
• squix add <name> without SQL — opens $EDITOR
• squix run with no args — opens $EDITOR