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](https://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](https://sq.io/) over guessing flags. ## Verify the install ```shell 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`](https://sq.io/docs/cmd/add). You get a **handle** (e.g. `@my_pg`). 2. **List** sources: `sq ls`. 3. **Active source**: [`sq src`](https://sq.io/docs/cmd/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](https://sq.io/docs/concepts#handle), [sources](https://sq.io/docs/source). ## Query modes | Mode | When to use | | ----------------- | ---------------------------------------------------------------------------------------------------- | | **SLQ** (default) | `sq`’s jq-like query language on sources and tables. See [Query language](https://sq.io/docs/query). | | **Native SQL** | Database-specific SQL via [`sq sql`](https://sq.io/docs/cmd/sql/). | Cross-source joins (e.g. CSV to Postgres): [Cross-source joins](https://sq.io/docs/query#cross-source-joins). ## Ping and inspect - **`sq ping @handle`** — connectivity check ([ping](https://sq.io/docs/cmd/ping)). - **`sq inspect …`** — schema, columns, sizes ([inspect](https://sq.io/docs/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](https://sq.io/docs/output#formats) and [insert](https://sq.io/docs/output#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](https://sq.io/docs/diff)). - **`sq tbl`** — copy, truncate, drop tables ([tbl copy](https://sq.io/docs/cmd/tbl-copy), [truncate](https://sq.io/docs/cmd/tbl-truncate), [drop](https://sq.io/docs/cmd/tbl-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](references/sqlite3.md) | | `rqlite` | [references/rqlite.md](references/rqlite.md) | | `duckdb` | [references/duckdb.md](references/duckdb.md) | | `postgres` | [references/postgres.md](references/postgres.md) | | `sqlserver` | [references/sqlserver.md](references/sqlserver.md) | | `mysql` | [references/mysql.md](references/mysql.md) | | `clickhouse` | [references/clickhouse.md](references/clickhouse.md) | | `oracle` | [references/oracle.md](references/oracle.md) | | `csv` | [references/csv.md](references/csv.md) | | `tsv` | [references/tsv.md](references/tsv.md) | | `json` | [references/json.md](references/json.md) | | `jsona` | [references/jsona.md](references/jsona.md) | | `jsonl` | [references/jsonl.md](references/jsonl.md) | | `xlsx` | [references/xlsx.md](references/xlsx.md) | Overview of all drivers: [Drivers](https://sq.io/docs/drivers/). ## Online resources - [Tutorial](https://sq.io/docs/tutorial/), [Cookbook](https://sq.io/docs/cookbook/), [Concepts](https://sq.io/docs/concepts/)