sqrail

v0.3.0 Agent-native data CLI

sqrail

SQL in. Files out.

One read-only DuckDB query over local CSV, JSON, and Parquet. Built for agents that already know the SQL.

Install sqrail Read the 3-minute guide
sqrail / run 01 read only 
$ sqrail run \
  -t trials=trials.parquet \
  --memory 512MB --threads 2 \
  --stats \
  'SELECT phase, count(*) AS n
   FROM trials
   GROUP BY phase
   ORDER BY phase'

{"phase":1,"n":8231}
{"phase":2,"n":4817}
{"phase":3,"n":1092}
JSONL stdout exit 0

One executable. No daemon. No prompt layer.

01
read-only query
04
input formats
170
words of agent help
00
configuration files read

The operating model

The model writes SQL.
sqrail holds the boundary.

Canonical file binding, streamed execution, atomic output, explicit resource limits, and strict JSON diagnostics—without teaching an agent another query language.

Three verbs

A decision rail, not a toolbox.

  1. 01

    schema

    Inspect names and types once when the input is unknown.

    sqrail schema data.parquet
  2. 02

    check

    Validate bindings and inspect the plan without execution.

    sqrail check -t d=data.csv - < query.sql
  3. 03

    run

    Execute once, consume the result, and stop after success.

    sqrail run -t d=data.csv - < query.sql

Complete agent context

Learn it in one call.

The stable help is deliberately short enough to place in an agent context without a separate tool manual.

Open as plain text 
sqrail --agent-help

Names/types result: schema once.
Otherwise trust stated names/types,
run once, and stop after success.

-t binds a file, directory, or glob.
- reads SQL from stdin.
No -o streams JSONL.
-o selects format by extension.
Limits fail closed.
Errors are one stderr JSON.

Measured, not imagined

DuckDB-class execution.
A tighter surface.

sqrail embeds DuckDB v1.5.5. It does not claim a faster engine; it removes layers around one carefully constrained local query.

10M
Parquet rows fully sorted out of core
128 MiB
DuckDB memory limit in the committed harness
2.123 s
Observed harness time on Apple M2 Pro

Hardware-specific observation, not a universal claim. Dataset generator, raw timing, peak RSS, row counts, and logical checksums are committed for reproduction.

Audit the baseline

Constrained by default

Give SQL only the files it needs.

Exact inputs are allowlisted. Extension loading and arbitrary external access are disabled. Output stays private until an atomic, no-overwrite commit succeeds.

  • One read-only SELECT, VALUES, or WITH query
  • Strict JSONL rows and JSON diagnostics
  • Memory, thread, deadline, spill, row, byte, file, and SQL caps
  • Schema evolution by name, with opt-in strict validation
Read the safety boundary

Documentation

Follow the contract.
Verify the evidence.

Ready for the next command

Put sqrail on the path.

$ brew install yhay81/tap/sqrail

Linux, macOS, and Windows · Arm64 and x86-64 · MIT licensed