FileSQL

FileSQL runs DuckDB SQL on CSV, JSON, JSONL, Parquet, Arrow, and SQLite files with a browser-first flow and transparent worker fallback for larger jobs. Drop a file on the homepage, run read-only SQL with Monaco autocomplete, inspect EXPLAIN plans, and export results — all without setting up a database.

Live demo: https://chayprabs.github.io/duckdb-file-sql/

Features

• Browser-first DuckDB-WASM execution for files up to 1 GB.
• Transparent worker fallback for oversized files and remote URLs.
• Monaco SQL editor with schema-aware completion and Cmd/Ctrl + Enter.
• Schema panel with sample values, rename, and drop actions.
• Result tabs for results, plans, and logs.
• Read-only SQL enforcement in browser and worker modes.
• Result export as CSV, JSON, Parquet, and Arrow.
• Share links that round-trip SQL through the URL.
• Built-in sample pack for CSV, TSV, JSON, JSONL, Parquet, Arrow, and SQLite.
• Privacy Policy, Terms & Conditions, and License at /privacy/, /terms/, and /license/.

Workspace

• packages/core: shared engine contracts and browser/worker routing logic.
• packages/web: FileSQL playground UI.
• apps/worker: FastAPI worker with native DuckDB.

Local Run

Web:

pnpm install
pnpm --filter @filesql/web dev -- --host 127.0.0.1 --port 4318

Worker:

cd apps/worker
python -m venv .venv
. .venv/Scripts/activate
pip install -e .[dev]
uvicorn app.main:app --host 127.0.0.1 --port 8000

Docker:

docker compose up --build

Verification

pnpm typecheck
pnpm test
pnpm build
cd apps/worker && python -m pytest

SEO Routes

• /sql-on-csv
• /sql-on-parquet
• /sql-on-jsonl
• /sqlite-online-query
• /duckdb-online
• /.well-known/security.txt

Self-Host

The web app is a static Vite build in packages/web/dist. The worker is a FastAPI service and the repo ships docker-compose.yml for the hybrid local run path.

For a public worker deployment, the repo now includes apps/worker/fly.toml for the PRD-aligned Fly.io target. It publishes the worker on port 8000, uses /health checks, keeps the retention TTL at 10 minutes, enforces HTTPS, and starts from zero machines when idle. The hosted frontend can call that public worker by pasting the worker base URL into the "Remote URL / Worker" panel.

Typical Fly.io flow:

cd apps/worker
fly launch --no-deploy
fly deploy

The repo also keeps a root render.yaml for an alternate Docker-backed worker deployment path.

Typical Render flow:

git add render.yaml apps/worker/fly.toml
git commit -m "Add worker deployment configuration"
git push origin main

Then open the repo in Render Blueprint mode and apply the filesql-worker service definition from render.yaml, or deploy the worker directly from apps/worker/fly.toml with Fly.io.

Legal

• Privacy Policy
• Terms & Conditions
• License & Notices
• DISCLAIMER.md — software and service disclaimer
• THIRD-PARTY-NOTICES.md — dependency licenses

Use of the hosted Service is subject to the Terms and Privacy Policy. Source code is released under MIT (web/core) and AGPL-3.0-or-later (worker). These documents reduce legal risk but do not eliminate it; consult a qualified attorney for advice in your jurisdiction.

License (source code)

• Root repo, packages/core, and packages/web: MIT — Copyright (c) 2026 Chaitanya Prabuddha
• apps/worker: AGPL-3.0-or-later

The hosted web build now publishes /.well-known/security.txt, and the repository includes SECURITY.md, .github/dependabot.yml, and .github/workflows/codeql.yml so vulnerability reporting, dependency updates, and code scanning are all wired into the default branch.

Security