gcq: Command-Line SQL Query Tool Documentation

Get gcq

A single binary for Linux, macOS and Windows, from the gcq product page.

Basic usage

Run a query:

./gcq --db postgres --dsn 'postgres://user:pass@localhost:5432/db?sslmode=disable' --query 'select 1 as n' --out json

Read query from stdin:

echo 'select 1 as n' | ./gcq --db sqlite3 --dsn ./db.sqlite --out table

Read query from file:

./gcq --db sqlite3 --dsn ./db.sqlite --file ./query.sql --out csv --output ./out.csv

Output formats

Supported --out values:

table (default), text, ansi, md, rtf
json (--json-mode objects|arrays)
csv, tsv
yaml, xml
html, pdf

Templates (GCQ tag mode)

Enable with --template PATH --template-mode.

Template tags:

{{row}}...{{/row}} repeats per row
{{col1}} / {{col2}} etc
{{col_Name}} uses a named column
Formatting: {{col_Price,r10,2}}
Aggregates: {{sum(col_Price,2)}}, {{avg(col2)}}, {{min(col1)}}, {{max(col1)}}
Conditionals:
- {{if col1 > 100 && col2 < 200}}...{{else}}...{{/if}}

Config file

Default path: ~/.config/gcq/config.yaml.

Example:

defaults:
  out: table
  table_style: unicode
  border: true
  null: ""
  max_col_width: 80

profiles:
  default:
    db: postgres
    dsn: postgres://USER:PASSWORD@localhost:5432/dbname?sslmode=disable
    connect_timeout: 10s
    query_timeout: 0s

Environment variables

Environment variables override config (but are overridden by CLI flags):

GCQ_DB, GCQ_DSN, GCQ_OUT, GCQ_TEMPLATE, GCQ_TEMPLATE_MODE
GCQ_EMAIL_TO, GCQ_EMAIL_FROM, GCQ_EMAIL_SUBJECT
GCQ_SMTP_HOST, GCQ_SMTP_USERNAME, GCQ_SMTP_PASSWORD

Email

Send output via SMTP:

./gcq --db postgres --dsn '...' --query 'select 1' --out html \
  --email-to ops@example.com --email-from report-bot@example.com --email-subject 'Report' \
  --smtp-host smtp.example.com --smtp-port 587 --smtp-username report-bot --smtp-password "$GCQ_SMTP_PASSWORD"

Attachments:

./gcq ... --out table --email-attach csv --email-attach json

CLI options (detailed)

Every option in the current version.

General

-h, --help: Print help (includes license link).
-v, --version: Print sign-on/version/copyright.

Configuration

--config PATH (default: ~/.config/gcq/config.yaml): YAML config file (missing file is OK).
--profile NAME (default: default): Profile name inside the config file.

Database selection / connection

--db {postgres|mysql|mariadb|sqlite3} (required unless config/env provides it)
--dsn DSN (required unless config/env provides it)
- Postgres example: postgres://user:pass@host:5432/dbname?sslmode=disable
- MySQL/MariaDB example: user:pass@tcp(host:3306)/dbname
- SQLite example: /path/to/file.sqlite
--connect-timeout DURATION (default: 10s): Timeout used for initial connection/ping.
--query-timeout DURATION (default: 0 / disabled): Per-statement timeout; 0 disables.

Convenience DSN overrides:

--sslmode MODE: If provided and your Postgres DSN does not already contain sslmode=..., it is appended.
--tls MODE: If provided and your MySQL/MariaDB DSN does not already contain tls=..., it is appended.

Query input

Exactly one query source is required unless stdin fallback applies.

--query SQL: SQL text to run.
--file PATH: Load SQL text from a file.
stdin fallback: If neither --query nor --file is supplied and stdin is not a TTY, gcq reads SQL from stdin.

Multiple statements:

--all-results: If your SQL contains multiple ;-separated statements, output all result sets (otherwise only the last result set is kept).

Result output

--out FORMAT (default: table): Supported: table, text, ansi, md, rtf, json, csv, tsv, yaml, xml, html, pdf.
--output PATH: Write output to a file.
--no-headers: Suppress the column header row (applies to table/text/md/rtf/csv/tsv/html/pdf).
--null STRING: String used when rendering NULLs for text-ish formats.
--encoding NAME (default: utf-8): Only utf-8 is supported in v1.
--eol {lf|crlf|cr} (default: lf): End-of-line normalization for line-oriented outputs.

JSON:

--json-mode {objects|arrays} (default: objects)

CSV/TSV:

--csv-delim CHAR (default: ,)
--tsv-delim CHAR (default: \t)

Text/table rendering:

--table-style STYLE (default: unicode): Supported: unicode, ascii, markdown, pipes, dokuwiki, none.
--border / --border=false (default: true): Toggle table border drawing.
--header TEXT (repeatable): Adds header lines above the table output.
--footer TEXT (repeatable): Adds footer lines after the table output.
--max-col-width N (default: 0 / disabled): Best-effort max width for unicode/ascii table output.
--wrap (default: false): Reserved for future (currently truncation/wrapping behavior is library-dependent).

Templates

--template PATH
--template-mode: Required when using --template. Supported for: text, ansi, md, html.

Logging / redaction

--redact-dsn / --redact-dsn=false (default: true): Redacts DSN passwords in logs (best-effort).
--log-level {debug|info|warn|error} (default: info)
--log-file PATH (default: stderr)

Email / SMTP

Recipients / headers:

--email-to ADDR (repeatable)
--email-from ADDR
--email-subject TEXT

Body:

--email-body TEXT
--email-body-html: Treat --email-body as HTML.
--email-body-template PATH: Loads the email body from a file (treated as HTML).