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

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/:

Driver (as in sq driver ls)	Reference
sqlite3	references/sqlite3.md
rqlite	references/rqlite.md
duckdb	references/duckdb.md
postgres	references/postgres.md
sqlserver	references/sqlserver.md
mysql	references/mysql.md
clickhouse	references/clickhouse.md
oracle	references/oracle.md
csv	references/csv.md
tsv	references/tsv.md
json	references/json.md
jsona	references/jsona.md
jsonl	references/jsonl.md
xlsx	references/xlsx.md

Overview of all drivers: Drivers.

Online resources

• Tutorial, Cookbook, Concepts