Skip to content
Back to search

sqrail

SkillWorks with Claude CodeGitHub

Bounded SQL over local CSV, TSV, JSON, and Parquet for coding agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/yhay81--sqrail/badge.svg)](/listings/yhay81--sqrail)

HTML

<a href="/listings/yhay81--sqrail"><img src="/api/listings/yhay81--sqrail/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

On macOS or Linux with Homebrew:

brew install yhay81/tap/sqrail

Or download a prebuilt archive for Linux, macOS, or Windows on x86-64 or Arm64 from [Releases](https://github.com/yhay81/sqrail/releases/latest), extract it, and put `bin/sqrail` on `PATH`. It is one executable: no language runtime, package manager, daemon, or database server is required.

- Linux archives need glibc 2.35 or newer and statically include the C++ runtime. - Windows archives statically include the MSVC runtime and need a UTF-8-capable Windows 10/11 or Windows Server release. - Each release publishes `SHA256SUMS`, an SPDX SBOM, and GitHub build-provenance and SBOM attestations. [Verify a release archive](docs/PLATFORMS.md#verify-a-release-archive) gives the commands for macOS, Linux, and PowerShell.

Then confirm it runs:

sqrail --version
sqrail --help

On macOS and Linux, `man sqrail` shows the same reference. [Platform support](docs/PLATFORMS.md) lists the tested platform tiers.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

plugin.json · Manifest · 11 lines
  1. {
  2. "name": "sqrail",
  3. "version": "0.4.3",
  4. "description": "Bounded SQL over local CSV, TSV, JSON, and Parquet for coding agents.",
  5. "author": {
  6. "name": "yhay81"
  7. },
  8. "repository": "https://github.com/yhay81/sqrail",
  9. "license": "MIT",
  10. "keywords": ["sql", "csv", "tsv", "json", "parquet", "agent-skills"]
  11. }
README.md · README · 426 lines
  1. <div align="center">
  2. <a href="https://sqrail.yhay81.com">
  3. <img
  4. src="site/social-card.svg"
  5. width="720"
  6. alt="sqrail — SQL in. Files out."
  7. >
  8. </a>
  9. <p>
  10. <strong>Run one read-only SQL query over local CSV, TSV, JSON, and Parquet files.</strong><br>
  11. A small, predictable CLI for coding agents that already write SQL.
  12. </p>
  13. <p>
  14. <a href="https://github.com/yhay81/sqrail/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/yhay81/sqrail/actions/workflows/ci.yml/badge.svg"></a>
  15. <a href="https://github.com/yhay81/sqrail/releases/latest"><img alt="Release" src="https://img.shields.io/github/v/release/yhay81/sqrail?display_name=tag&sort=semver"></a>
  16. <a href="https://github.com/yhay81/sqrail/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-caff3d?labelColor=111311"></a>
  17. <a href="https://github.com/yhay81/sqrail"><img alt="C++20" src="https://img.shields.io/badge/C%2B%2B-20-caff3d?labelColor=111311"></a>
  18. </p>
  19. <p>
  20. <a href="https://sqrail.yhay81.com">Website</a>
  21. ·
  22. <a href="https://sqrail.yhay81.com/docs/">3-minute guide</a>
  23. ·
  24. <a href="docs/CONTRACT.md">Contract</a>
  25. ·
  26. <a href="docs/RECIPES.md">Recipes</a>
  27. ·
  28. <a href="docs/BENCHMARKS.md">Benchmarks</a>
  29. ·
  30. <a href="SECURITY.md">Security</a>
  31. </p>
  32. </div>
  33. ---
  34. ## What is sqrail?
  35. sqrail is a single command that treats local data files as SQL tables. You give
  36. each file a table name, write one ordinary SQL query, and get the result back as
  37. JSON Lines on stdout or as a new CSV, TSV, JSON, or Parquet file.
  38. It is built for coding agents. Models already write good SQL, so sqrail does not
  39. translate natural language or add a query language of its own. Instead it gives
  40. that SQL a narrow, predictable place to run:
  41. - **Only the files you name can be read.** Nothing else on disk is reachable.
  42. - **Nothing can be changed.** One `SELECT`, `VALUES`, or `WITH` query is
  43. accepted, inputs are never modified, and existing files are never
  44. overwritten.
  45. - **Every run stays within the limits you set** for memory, threads, time,
  46. rows, bytes, files, and SQL size.
  47. - **Every result is machine-readable.** Rows go to stdout; a failure is one
  48. JSON object on stderr with a stable exit code.
  49. The query engine is [DuckDB](https://duckdb.org), embedded in the binary. sqrail
  50. is the boundary around it, and the whole interface fits in a
  51. [195-word `--help`](https://sqrail.yhay81.com/help.txt).
  52. ## Quick look
  53. Bind each file to a table name with `-t NAME=PATH`, then pass the SQL. Here `-`
  54. reads it from stdin so it needs no shell quoting:
  55. ```sh
  56. sqrail run -t sales=sales.csv -t drugs=drugs.parquet - <<'SQL'
  57. SELECT d.name, sum(s.amount) AS total
  58. FROM sales AS s
  59. JOIN drugs AS d USING (drug_id)
  60. GROUP BY d.name
  61. ORDER BY total DESC
  62. SQL
  63. ```
  64. Each result row is one JSON object on stdout:
  65. ```text
  66. {"name":"Alphazol","total":25}
  67. {"name":"Betamab","total":20}
  68. ```
  69. Add `-o` to write a file instead. The extension selects the format, and the file
  70. appears only after the query succeeds:
  71. ```sh
  72. sqrail run -t sales=sales.csv -o totals.parquet \
  73. 'SELECT drug_id, sum(amount) AS total FROM sales GROUP BY drug_id'
  74. ```
  75. When a query is refused or fails, stdout stays clean, stderr carries exactly one
  76. JSON object, and the exit code says which stage failed:
  77. ```console
  78. $ sqrail run -t sales=sales.csv 'DELETE FROM sales'; echo "exit $?"
  79. {"schema_version":1,"sqrail_version":"0.4.3","ok":false,"code":"READ_ONLY_QUERY","message":"only a SELECT, VALUES, or WITH query is allowed"}
  80. exit 4
  81. ```
  82. The [recipes](docs/RECIPES.md) cover conversion, joins, partitioned Parquet, and
  83. JSONL validation with commands you can paste into an empty directory.
  84. ## How it works
  85. ```text
  86. -t sales=sales.csv --+
  87. -t drugs=drugs.parquet --+--> one read-only SQL query --> rows as JSONL on stdout
  88. -t events=events/ --+ run by DuckDB within or one file with -o
  89. your limits
  90. |
  91. +--> on failure: one JSON object on stderr
  92. and a stable exit code
  93. ```
  94. Three commands cover the whole workflow:
  95. | Command | Use it to | Prints |
  96. | --------------------------- | ----------------------------------- | ------------------------------------------------------ |
  97. | `sqrail schema FILE...` | learn column names and types | one JSON object per path with its files and columns |
  98. | `sqrail check [-t ...] SQL` | validate a query without running it | result columns, bound inputs, and the physical plan |
  99. | `sqrail run [-t ...] SQL` | execute the query once | JSONL rows, or nothing when `-o` writes a file instead |
  100. A typical agent turn is short: run `schema` once if the names and types are
  101. unknown, otherwise trust them; `run` once; stop when the exit code is `0`.
  102. ## Why not call DuckDB directly?
  103. You can. sqrail runs the same engine and does not claim to be faster than it.
  104. The difference is what one invocation is allowed to do. Even with read-only
  105. flags or agent-oriented CLI output modes, a general database shell still
  106. exposes arbitrary path reads, session commands, and ambient environment
  107. heuristics unless the caller wraps and locks every invocation. sqrail is
  108. designed so that a command can do only one bounded thing, which is what you
  109. want when a model chooses the SQL and a program reads the result.
  110. | Question | sqrail's answer |
  111. | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
  112. | What can the query read? | Only paths bound with `-t`. DuckDB external access and extension loading are disabled, and the configuration is locked. |
  113. | What can it change? | Nothing. Inputs are exposed as read-only views; writes, `COPY`, `ATTACH`, `INSTALL`, `LOAD`, `PRAGMA`, and multiple statements are rejected. |
  114. | How much can it use? | Only what you allow with the [resource limits](#resource-limits). Going over a limit is an error, never a silently truncated result. |
  115. | What if it fails halfway? | With `-o`, output is written privately and committed atomically. A failed run leaves no file, and an existing file is never replaced. |
  116. | What does the caller parse? | stdout carries only rows. Each failure is one versioned JSON object on stderr with a [documented exit code](#errors-and-exit-codes). |
  117. | Is there any hidden state? | No configuration file, network service, embedded model, daemon, or telemetry. The same command behaves the same way every time. |
  118. | How does an agent learn it? | From `sqrail --help`, which is complete in 195 words, instead of a long tool manual in every prompt. |
  119. sqrail is **not** a natural-language-to-SQL tool, an interactive shell, a
  120. persistent database, or an operating-system sandbox. The
  121. [concept](docs/CONCEPT.md) ([日本語](docs/CONCEPT.ja.md)) explains the design
  122. constraints and non-goals.
  123. ## Install
  124. On macOS or Linux with Homebrew:
  125. ```sh
  126. brew install yhay81/tap/sqrail
  127. ```
  128. Or download a prebuilt archive for Linux, macOS, or Windows on x86-64 or Arm64
  129. from [Releases](https://github.com/yhay81/sqrail/releases/latest), extract it,
  130. and put `bin/sqrail` on `PATH`. It is one executable: no language runtime,
  131. package manager, daemon, or database server is required.
  132. - Linux archives need glibc 2.35 or newer and statically include the C++
  133. runtime.
  134. - Windows archives statically include the MSVC runtime and need a
  135. UTF-8-capable Windows 10/11 or Windows Server release.
  136. - Each release publishes `SHA256SUMS`, an SPDX SBOM, and GitHub build-provenance
  137. and SBOM attestations.
  138. [Verify a release archive](docs/PLATFORMS.md#verify-a-release-archive) gives
  139. the commands for macOS, Linux, and PowerShell.
  140. Then confirm it runs:
  141. ```sh
  142. sqrail --version
  143. sqrail --help
  144. ```
  145. On macOS and Linux, `man sqrail` shows the same reference.
  146. [Platform support](docs/PLATFORMS.md) lists the tested platform tiers.
  147. ## Use it from a coding agent
  148. sqrail needs no SDK: an agent calls it like any other shell command. The
  149. smallest useful instruction is:
  150. ```text
  151. Run `sqrail --help`.
  152. If names and types are unknown, use `sqrail schema` once.
  153. Otherwise trust the stated schema, run once, and stop after success.
  154. ```
  155. The same decision rule and stop condition are built into `--help`. The
  156. low-cost-model experiments behind them are in the
  157. [agent experiment log](benchmarks/agent-eval/EXPERIMENTS.md).
  158. The optional [Agent Skill](skills/sqrail/SKILL.md) tells compatible agents when
  159. to reach for sqrail without adding the manual to every prompt. With GitHub CLI
  160. 2.90 or newer:
  161. ```sh
  162. gh skill preview yhay81/sqrail sqrail
  163. gh skill install yhay81/sqrail sqrail --agent codex --scope user
  164. ```
  165. Replace `codex` with your host, such as `claude-code`, `cursor`,
  166. `github-copilot`, `opencode`, `cline`, `kiro-cli`, or `windsurf`. Google's
  167. AGY/Antigravity CLI uses the repository's native plugin instead:
  168. ```sh
  169. agy plugin install https://github.com/yhay81/sqrail
  170. ```
  171. To have an agent install both the executable and the Skill, give it the
  172. review-first [AI installer](https://sqrail.yhay81.com/install-agent.md). It falls
  173. back to `npx skills` when GitHub CLI is unavailable.
  174. [Agent integration](docs/AGENT_INTEGRATION.md) collects further patterns.
  175. ## Reference
  176. `sqrail --help` is the complete short interface. The
  177. [CLI contract](docs/CONTRACT.md) is normative for every detail, including the
  178. JSON schemas and failure semantics.
  179. ```text
  180. sqrail schema [--memory SIZE] [--threads N] [--timeout DURATION]
  181. [--max-input-files N] [--strict-schema] [--all-varchar] FILE...
  182. sqrail check [-t NAME=PATH]... [--memory SIZE] [--threads N]
  183. [--timeout DURATION] [--max-rows N] [--max-input-files N]
  184. [--max-sql-bytes SIZE] [--strict-schema] [--all-varchar] [SQL|-]
  185. sqrail run [-t NAME=PATH]... [-o FILE] [--memory SIZE] [--threads N]
  186. [--spill DIR [--max-spill SIZE]] [--timeout DURATION]
  187. [--max-rows N] [--max-output-bytes SIZE] [--max-input-files N]
  188. [--max-sql-bytes SIZE] [--stats] [--strict-schema]
  189. [--all-varchar] [SQL|-]
  190. ```
  191. ### Inputs and queries
  192. - `-t NAME=PATH` binds a table name to one file, a glob, or a partitioned
  193. Parquet directory, whose `key=value` directory names such as `year=2026`
  194. become columns. Repeat it for each table.
  195. - The files in one binding are combined by column name, and a column missing
  196. from some files is `null`. `--strict-schema` instead requires identical
  197. names, order, and types across files.
  198. - `--all-varchar` keeps CSV and TSV columns as `VARCHAR` so leading-zero codes
  199. and mid-file type shifts are preserved without altering Parquet or JSON types.
  200. - The SQL is one `SELECT`, `VALUES`, or `WITH` query in the DuckDB dialect that
  201. `sqrail --version` reports. Pass it as an argument, or as `-` to read it from
  202. stdin.
  203. - Row order is undefined unless the query contains `ORDER BY`.
  204. Every format can be read and written:
  205. | Format | Extensions | Notes |
  206. | ---------- | ------------------- | ------------------------------------------------ |
  207. | CSV | `.csv` | |
  208. | TSV | `.tsv`, `.tab` | |
  209. | JSON | `.json` | written as one JSON array |
  210. | JSON Lines | `.jsonl`, `.ndjson` | written as one object per line |
  211. | Parquet | `.parquet` | also read from a glob or a partitioned directory |
  212. Text formats may also end in `.gz` or `.zst`. Externally compressed Parquet and
  213. bzip2/xz streams are deliberately rejected.
  214. ### Outputs
  215. - **Without `-o`**, each row is one JSON object on stdout and nothing else is
  216. written there. Rows stream as they are produced, so a query that fails midway
  217. may already have printed a valid prefix. Use `-o` when the consumer needs
  218. all-or-nothing output.
  219. - **With `-o FILE`**, the extension selects the format and a successful run is
  220. silent. The file is written under a private temporary name with owner-only
  221. permissions and committed atomically after success. An existing file is
  222. never replaced; the run fails with `OUTPUT_EXISTS` instead.
  223. - **`--stats`** makes a successful `run` add one JSON object on stderr:
  224. ```json
  225. {
  226. "schema_version": 1,
  227. "sqrail_version": "0.4.3",
  228. "ok": true,
  229. "command": "run",
  230. "rows": 2,
  231. "bytes": 342,
  232. "elapsed_ms": 127,
  233. "input_files": 1,
  234. "destination": "file"
  235. }
  236. ```
  237. ### Resource limits
  238. Every limit is stated on the command line, and exceeding one fails with a
  239. structured diagnostic instead of degrading silently:
  240. ```sh
  241. sqrail run \
  242. --memory 1GB \
  243. --threads 2 \
  244. --spill /fast-nvme/sqrail-spill \
  245. --max-spill 100GB \
  246. --timeout 10m \
  247. --max-rows 1000000 \
  248. --max-output-bytes 4GiB \
  249. --max-input-files 10000 \
  250. --max-sql-bytes 1MiB \
  251. --stats \
  252. -t data='warehouse/**/*.parquet' \
  253. -o result.parquet \
  254. - < query.sql
  255. ```
  256. | Option | What it bounds |
  257. | --------------------------------- | ---------------------------------------------------------------------------------------- |
  258. | `--memory SIZE` | DuckDB's memory limit. It is not a hard operating-system RSS limit. |
  259. | `--threads N` | Worker threads. |
  260. | `--timeout DURATION` | The whole command, from input discovery and schema inference to output commit. |
  261. | `--spill DIR`, `--max-spill SIZE` | Temporary disk. Without `--spill`, nothing spills to disk. |
  262. | `--max-rows N` | Rows in the final result. A larger result fails with `RESULT_LIMIT` and commits no file. |
  263. | `--max-output-bytes SIZE` | Bytes written to stdout or the output file. |
  264. | `--max-input-files N` | Files matched across every glob and directory, checked before they are read. |
  265. | `--max-sql-bytes SIZE` | Size of the SQL text, checked before parsing. |
  266. `--spill` creates a unique, owner-only workspace beneath `DIR` for each process
  267. and removes it afterwards; other files under `DIR` are never visible to SQL.
  268. sqrail also disables insertion-order preservation so that unordered file
  269. transformations can use less memory.
  270. ### Errors and exit codes
  271. Every handled failure writes exactly one JSON object with `schema_version`,
  272. `sqrail_version`, `ok: false`, a stable `code`, and a human-readable `message`.
  273. The exit code identifies the failing stage:
  274. | Exit | Stage | Example codes |
  275. | ---: | ----------------------------- | ------------------------------------------------------------------ |
  276. | 0 | success | |
  277. | 2 | command usage | `UNKNOWN_OPTION`, `MISSING_VALUE`, `SQL_LIMIT` |
  278. | 3 | input file or format | `INPUT_NOT_FOUND`, `INPUT_LIMIT`, `SCHEMA_MISMATCH` |
  279. | 4 | SQL parse, bind, or execution | `READ_ONLY_QUERY`, `QUERY_FAILED`, `QUERY_TIMEOUT`, `RESULT_LIMIT` |
  280. | 5 | output path or commit | `OUTPUT_EXISTS`, `OUTPUT_LIMIT`, `STDOUT_WRITE` |
  281. | 70 | unexpected internal failure | `INTERNAL` |
  282. ## Safety boundary
  283. The restrictions above are enforced inside the process. sqrail rejects write
  284. statements, disables DuckDB external access and extension loading, locks the
  285. configuration, and allowlists only the bound inputs, the private output
  286. temporary path, and the private spill workspace. SQL therefore cannot read
  287. arbitrary local paths, including other files under the spill root.
  288. This is defense in depth, not an operating-system sandbox. Run hostile SQL or
  289. malformed data inside an OS sandbox as well, and report suspected
  290. vulnerabilities through the [security policy](SECURITY.md).
  291. ## Performance
  292. The goal is DuckDB-class execution behind a smaller, deterministic interface,
  293. not to outrun the engine sqrail embeds. The committed harness builds sqrail and
  294. the DuckDB CLI from the same source revision, checks that their outputs match,
  295. and records time and peak RSS. See the [benchmark policy](docs/BENCHMARKS.md),
  296. the [harness](benchmarks/README.md), and the
  297. [measured baseline](docs/BASELINE.md). Treat the numbers as observations on
  298. specific hardware unless the harness supports a broader claim.
  299. ## Build from source
  300. You need CMake 3.25+, Ninja, and a C++20 compiler. The first configure also
  301. needs Git and network access to fetch DuckDB v2.0.0 and Catch2 v3.16.1 at
  302. pinned commits; Catch2 is used only by tests and never linked into sqrail.
  303. ```sh
  304. cmake --workflow --preset core
  305. cmake --workflow --preset dev
  306. cmake --workflow --preset release
  307. ./out/build/release/sqrail run 'SELECT 42 AS answer'
  308. ```
  309. - `core` runs the native C++ unit suite and does not need Python.
  310. - `dev` and `release` add the Python integration, agent-evaluation, and
  311. release-tool suites, so they need Python 3. A production-only build with
  312. `-DSQRAIL_BUILD_TESTS=OFF` does not.
  313. - `release` is the optimized configuration used for official binaries. It uses
  314. the default `BUNDLED` provider, which statically links DuckDB.
  315. Distribution packages can build from the release source archive against an
  316. installed DuckDB instead. The package must export DuckDB's CMake configuration
  317. with the `core_functions`, `parquet`, and `json` extensions:
  318. ```sh
  319. CMAKE_PREFIX_PATH=/path/to/duckdb cmake --workflow --preset system
  320. cmake --install out/build/system --prefix out/install/system --component sqrail
  321. ```
  322. The `system` provider links DuckDB's shared library, reports its actual runtime
  323. version, and does not install a second copy of DuckDB's licences.
  324. The `strict`, `sanitize`, `thread`, `fuzz`, `native`, `pgo-generate`, and
  325. `pgo-use` presets cover static analysis, sanitizers, fuzzing, and profile-guided
  326. builds. A pinned Ubuntu 24.04/LLVM 18 development container runs the developer
  327. workflow on creation. See the [testing architecture](docs/TESTING.md) and the
  328. [contribution guide](CONTRIBUTING.md).
  329. ## Documentation and community
  330. The [documentation index](docs/README.md) maps each question to the document
  331. that answers it, from the contract and platform support to the release gate.
  332. Questions, careful bug reports, reproducible performance evidence,
  333. documentation improvements, and focused patches are welcome. Ask in
  334. [Discussions](https://github.com/yhay81/sqrail/discussions), pick up a
  335. [`good first issue`](https://github.com/yhay81/sqrail/labels/good%20first%20issue),
  336. or start with the [support guide](SUPPORT.md) and
  337. [contribution guide](CONTRIBUTING.md). Everyone taking part must follow the
  338. [Code of Conduct](CODE_OF_CONDUCT.md). The
  339. [community growth plan](docs/COMMUNITY_GROWTH.md) records who sqrail is for and
  340. how the project measures progress.
  341. ## License
  342. MIT. Official release binaries statically link DuckDB; distribution packages
  343. may link a packaged DuckDB shared library. See
  344. [Third-party notices](THIRD_PARTY_NOTICES.md).

Version history

  • v0.4.311/17/2026

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.