puddle
Runs a real SQL engine in the browser, with no server, verifiable in the network tab.
A SQL notebook that runs entirely in a browser tab.
puddle-neon.vercel.app
Drop in a CSV and write SQL against it. DuckDB is compiled to WebAssembly and runs in the
page, so the file is read off your disk by the tab you are looking at. There is no
backend, no account, and no API key: open the page on a plane and it still works.
The privacy claim is checkable rather than promised: open the network panel and watch a
query run without a request.
Try it
Open puddle-neon.vercel.app and press Try the demo.
It loads a bundled 2,000-row dataset, runs a query against it, and draws the result. No
file of your own, no sign-up.
Or run it locally:
npm install
npm run dev
The first screen is a specimen sheet of the demo data (four weekly revenue traces drawn
from the bundled CSV. Clicking a reading hands you the SQL behind that week rather than
just a picture of it.
What it does
One file per session. CSV, TSV, or Parquet, by drag-drop or file picker. The File
object is handed to DuckDB, which reads the bytes it needs when it needs them; a 200MB
CSV is never pulled through FileReader into a JS string. Every dataset is exposed as a
view called data, whatever the file is called, so a query written against one file is
portable to another.
A schema panel listing every column with the type DuckDB inferred for it: VARCHAR,
BIGINT, DATE. Click a column to insert its name at the cursor; Enter and Space do the
same from the keyboard.
A SQL editor on CodeMirror, with a DuckDB dialect written for it rather than borrowed
from Postgres: QUALIFY, PIVOT, EXCLUDE and USING SAMPLE highlight, # is not a
comment, and :: is a cast. Columns that exist in the loaded file are marked as you type,
so a misspelled name is visible before you run it. Run with the button or Cmd/Ctrl+Enter.
A results grid, virtualized on both axes, with a sticky header, a row count, and the
query's execution time. Formatting is type-aware and nothing is rounded: numbers keep
every digit DuckDB gave them, grouped for reading. NULL renders as a token, never as an
empty cell. An absent value and an empty string are different answers.
A chart below the grid. It picks an x and a y from the result's column types and lets
you override either; bar and line. A bar starts at zero and a line does not, because a bar
encodes value as length and a baseline anywhere else overstates every difference. Ticks
are round numbers (200, 400, 600) instead of the exact data extent cut into fifths.
NULL stays a hole in the line rather than a segment drawn across it.
A share link carrying the query, the column names it was written against, and the
file name, compressed with lz-string into the URL hash, which browsers never send to a
server. It never carries a row. Open one without a file and you get the query read-only
beside the columns it expects; drop a matching file and it runs itself. Drop one that is
missing columns and Puddle names them rather than refusing, because the person holding the
link is the one who knows whether their export is the same data under different headings.
The states in between
Most of the work is in the parts that are not the happy path, and they are designed rather
than defaulted:
- Booting. DuckDB is several megabytes and does not load with the landing page. It
starts on the first real intent (the demo button or a dropped file) behind a
determinate progress bar reading actual bytes.
- Refusing. A
.docx is turned away by extension before the engine downloads, so a
wrong file never costs a stranger the WASM bundle. A drop carrying three files says so
instead of silently taking the first.
- Failing to load. DuckDB's CSV sniffer answers a bad file with twenty lines about
candidate delimiters and a caret pointing at SQL you never wrote. Puddle writes a
sentence for what happened and a sentence for what to try, and keeps DuckDB's own text
beside them in a disclosure.
- Failing to run. The opposite call: you wrote this SQL, and
Referenced column "amont" not found in FROM clause! Candidate bindings: "amount" is the most useful
sentence on the screen. It is shown verbatim, with a headline that only says which kind
of wrong it is.
- Loading strangely. A file whose separator was guessed wrong raises nothing; it just
comes back looking odd. When DuckDB numbers the columns
column0, column1, Puddle says
the first line was read as data and leaves the judgement to you.
- Empty. A query that succeeded and matched no rows reads as a success, not as a blank
area that looks the same as a failure.
How it works
File ──registerFileHandle──▶ DuckDB-WASM (worker)
│
src/duckdb/client.ts ← the only module that imports the bindings
│
┌──────────────────┼──────────────────┐
dataset query results / chart
(ingest, schema) (editor, run) (grid, series, axes)
│
share ← query + schema → URL hash, never rows
Six decisions shape the codebase. Most are recorded in CLAUDE.md as locked, which means
an implementation that finds one inconvenient has to change the decision there rather than
route around it in code.
DuckDB loads lazily. A landing page that hangs for five seconds before it can show
anything reads as broken, so nothing fetches the engine until someone asks for it.
The non-cross-origin-isolated bundle. DuckDB's coi build needs COOP/COEP response
headers, which break third-party embeds and tax portability. Puddle uses mvp/eh, which
run without SharedArrayBuffer. Slower on huge files; irrelevant at this scale.
The WASM ships from our own origin. DuckDB's published recipe pulls its bundle from
jsDelivr, which would make every first query depend on a CDN being reachable. Vite
fingerprints and serves the assets instead. The same rule rules out webfonts from a CDN: a
font fetched to render "nothing leaves the tab" would contradict that sentence in the
network panel.
One module owns the engine. src/duckdb/client.ts holds the worker, the connection
lifecycle, and the query API. Nothing above it imports @duckdb/duckdb-wasm. That is the
seam every test mocks and the reason the engine is swappable.
Data is parsed at the boundary, then trusted. Arrow hands back live objects that are
valid only while their table is. src/duckdb/result.ts narrows them into plain values, so
a result can outlive the table it came from and no component ever holds an Arrow type.
Past that boundary, types are trusted because they were earned.
Decisions live in pure modules. Each feature folder keeps its judgement in files with
no React in them: chart-axes.ts picks the axes, cell-format.ts rules that NULL is
never blank, run-state.ts answers whether Run may fire and why not, and one impure
module that talks to the engine. It is what makes 316 tests possible without a DOM.
Layout
src/
duckdb/ client.ts, bundles.ts, result.ts, use-duckdb.ts
dataset/ ingest, the schema panel, the drop surface
query/ the CodeMirror editor, the DuckDB dialect, the run
results/ the virtualized grid, cell formatting, column widths
chart/ axis inference, series, scales, the Recharts render
share/ the payload, the lz-string codec, schema matching
landing/ the specimen sheet and its precomputed series
docs/
adr/ decision records
design/ the token plan every component composes from
agents/ issue tracker and triage conventions
Tests sit beside the code they cover as *.test.ts. CLAUDE.md is the scope table and
the locked decisions; PRODUCT.md is who it is for; DESIGN.md is the shipped design
system.
Development
npm run dev # Vite dev server
npm test # Vitest: 316 tests across 31 files
npm run typecheck # tsc -b
npm run build # tsc -b && vite build
TypeScript runs strict plus noUncheckedIndexedAccess, exactOptionalPropertyTypes and
noImplicitOverride. any does not ship. as is treated as a claim you cannot back;
tests use @total-typescript/shoehorn for partial fixtures instead.
It deploys as a static build: vercel.json rewrites every path to index.html. There is
no server behind it, because there is no server.
Design
The interface is built from hairline rules and monospace rather than cards and shadows,
because a result set has no cards in it: structure comes from the same device the data
already uses. docs/design/tokens.md is the token plan, written before the first
component; src/index.css implements it. Text contrast meets WCAG AA, every interactive
element keeps a visible focus ring, the keyboard path works without a pointer, and motion
collapses under prefers-reduced-motion.
Desktop is the case Puddle is designed against: a SQL notebook is a keyboard-and-pointer
tool with width to spend. Phones stay usable: the same path works, nothing overflows,
controls take a thumb.
Known limits
Parquet does not read yet. .parquet is accepted and routed to read_parquet, but
the DuckDB-WASM bundles keep the Parquet reader in a separate extension this build does
not carry, so it fails, with a message naming the missing reader rather than blaming your
file. CSV and TSV work. The options and their costs are written up in
docs/adr/0001-parquet-needs-an-extension-we-do-not-ship.md; the decision is still open.
The demo dataset is synthetic. It is not a real business's numbers.
Planned
Each of these is a decision to ship the smaller thing first, not an oversight:
- Multiple cells: v1 is one editor, not a cell sequence.
- Joins across files: v1 loads one file per session.
- Saved workspaces or history: share links carry a query; nothing persists.
- SQL autocomplete: the schema panel inserts column names in the meantime.
- Nested schema browser: v1 shows a flat column list.
- Export to CSV: results are read-only for now.
- Dark mode toggle: v1 ships one theme.
- Auth: there is no server to authenticate against.
