sqrail Agent-safe SQL on files
GitHub 1 Install

v0.3.4 Agent-native data CLI

sqrail

SQL in. Files out.

Bounded SQL over local CSV, TSV, JSON, and Parquet—for agents that already write the query.

$ brew install yhay81/tap/sqrail

Get started Agent setup CLI reference

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}
strict JSON output bounded · exit 0

One executable. No daemon. No prompt layer.

Three verbs

Three commands. One path.

  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

Why sqrail

DuckDB computes.
sqrail defines the boundary.

Use DuckDB directly for interactive analytics and its complete SQL surface. Use sqrail when an automated caller needs one predictable, inspectable operation over explicitly named files.

Tool fit comparison
Need DuckDB CLI sqrail
Working mode Interactive and general purpose One bounded operation
Inputs SQL can address configured sources Only explicit bindings are allowlisted
Failure contract Human-oriented CLI behavior One strict JSON diagnostic
Output commit Flexible export paths Atomic and never overwrites
01

Agent analysis

Let the model write SQL while the process enforces the limits.

02

Local data handoff

Turn large extracts into a bounded, machine-readable result.

03

Pipeline guardrail

Validate, execute, and commit one file transformation safely.

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 --help

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

-t binds a file, Parquet 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

Choose the next step

Start quickly.
Go deeper when needed.

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