Sq

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

1. Add a data source with sq add. You get a handle (e.g. @my_pg).
2. List sources: sq ls.
3. 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

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

• Tutorial, Cookbook, Concepts