sqrail

Start here 3-minute guide

Bind. Check.
Run.

sqrail gives coding agents one predictable path from SQL and local files to machine-readable output.

01 / Install

One executable.

brew install yhay81/tap/sqrail
sqrail --version
sqrail --agent-help

Prebuilt archives for Linux, macOS, and Windows are available on GitHub Releases

02 / First query

SQL already is the interface.

Bind each input to an explicit table name with -t. Send SQL on stdin when it is long enough to make shell quoting awkward. 

sqrail run \
  -t sales=sales.csv \
  -t drugs=drugs.parquet \
  -o result.parquet \
  - <<'SQL'
SELECT d.name, sum(s.amount) AS total
FROM sales AS s
JOIN drugs AS d USING (drug_id)
GROUP BY d.name
ORDER BY total DESC
SQL
Without -o, rows stream as JSONL to stdout. With -o, the file extension selects CSV, TSV, JSON, JSONL, NDJSON, or Parquet.

03 / Three verbs

Inspect only when needed.

schema — discover names and types

sqrail schema trials.parquet

check — validate without executing

sqrail check -t trials=trials.parquet - < query.sql

run — execute once

sqrail run -t trials=trials.parquet - < query.sql

If names and types are already stated, skip discovery. Run once and stop after success. This explicit decision rule is part of --agent-help.

04 / Boundaries

Make resource use explicit.

sqrail run \
  -t events=events.parquet \
  --memory 512MB \
  --threads 2 \
  --timeout 30s \
  --max-rows 100000 \
  --max-output-bytes 64MB \
  --max-input-files 32 \
  --stats \
  - < query.sql

Limits fail closed. Successful rows stay on stdout; versioned success statistics and single-object JSON errors stay on stderr. Existing outputs are never overwritten, and failed queries leave no partial destination.

05 / File formats

Local files, named precisely.

Format Read Write
CSV / TSV Files, globs, .gz, .zst Files, .gz, .zst
JSON / JSONL / NDJSON Files, globs, .gz, .zst Files, .gz, .zst
Parquet File, glob, partitioned directory File

Multi-file inputs union evolving columns by name. --strict-schema instead requires identical names, order, and types.

06 / Reference

Follow the contract.
Audit the evidence.

CLI contract → Normative behavior, JSON schemas, and exit codes Agent integration → Context, invocation, and stop-condition guidance Benchmark policy → Reproducible performance claims and harnesses Platform support → Release targets and tested support tiers Security boundary → Threat model, guarantees, and non-goals Contributing → How to propose a focused, verifiable change