| name | sq |
| description | Guides use of the sq CLI to query SQL databases and tabular files with SLQ (sq's jq-like query language) or native SQL, manage sources, choose output formats, and run inspect, diff, and table commands. Use when the user mentions sq, SLQ, wrangling CSV/Excel/JSON/DB data, cross-source joins, or command-line data pipelines after installing sq from https://sq.io. |
| license | MIT |
| compatibility | Requires the sq CLI on PATH; install from https://sq.io/docs/install/ |
| metadata | {"author":"Todd Papaioannou","homepage":"https://sq.io"} |
sq (CLI)
sq is a command-line tool for structured data: SQL databases and formats like CSV, TSV, JSON, and Excel. It combines SQL- and jq-style querying. Official documentation lives at sq.io.
This skill targets use of an already-installed sq binary rather than guidance on building from source. Prefer sq help, sq <command> --help, and sq.io over guessing flags.
Verify the install
sq --version
sq help
sq driver ls
sq driver ls lists drivers available in this build (e.g. postgres, duckdb,
oracle, sqlite3, csv).
Sources and handles
- Add a data source with
sq add. You get a handle (e.g. @my_pg).
- List sources:
sq ls.
- Active source:
sq src shows or sets which source SLQ queries use when you omit an explicit handle.
Use @handle to target a source in queries (e.g. @my_pg.actor). Concepts: handle, sources.
Query modes
| Mode | When to use |
|---|
| SLQ (default) | sq’s jq-like query language on sources and tables. See Query language. |
| Native SQL | Database-specific SQL via sq sql. |
Cross-source joins (e.g. CSV to Postgres): Cross-source joins.
Ping and inspect
sq ping @handle — connectivity check (ping).sq inspect … — schema, columns, sizes (inspect). Can emit a schema entity-relationship diagram as Markdown/HTML (--markdown/--html), Mermaid source (-f mermaid-erd), or an image file (-f svg-erd/-f png-erd).
Output formats
Results can be printed as text, JSON, CSV, HTML, Markdown, XML, XLSX, etc. See Output formats and insert for writing query results into a database.
Common flags: -j/--json, -t/--text, -o FILE; details in sq --help and the docs above.
Diff and table operations
sq diff — compare metadata or row data between sources or tables (diff).sq tbl — copy, truncate, drop tables (tbl copy, truncate, drop).
Driver-specific help (load on demand)
When the task involves a specific driver (connection strings, options, caveats), open the matching file under references/:
Overview of all drivers: Drivers.
Online resources
