/squix

name: squix
description: Run SQL queries across databases (Postgres, MySQL, SQLite, etc.) via the squix CLI. Use for running named queries, exploring schema, or parameterized queries. Always use -f for non-interactive output.

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`