Skip to content

docs: README around exact types, loud failures and bounded memory, with a re-recorded demo - #336

Merged
kvlonge merged 5 commits into
mainfrom
docs-readme-trust
Nov 18, 2026
Merged

kvlonge merged 5 commits into
mainfrom
docs-readme-trust

Conversation

@kvlonge

@kvlonge kvlonge commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

The README's top says "Exact types. Loud failures. Bounded memory.", but the page below it was still about routing and speed. This restructures it to back up those three claims, in the home page's order, and re-records the demo GIF on the current release.

README (and the PyPI README, which is now an exact copy)

  • Intro: what SQLLoad loads, what sqlload plan shows (and that plan -v adds column types and the memory budget, as it has since plan got shorter), and one sentence per claim: decimals keep their precision, a value a column can't hold exactly fails its table, naming the column and the value, each run has one memory budget, and tables with a cursor column carry on from the warehouse's own maximum.

  • GIF: re-recorded (see below). Its caption and alt text describe what it now shows.

  • Why SQLLoad: four bullets with one concrete example each, and a docs link:

    • Exact types: decimal(12,2) loads as DECIMAL(12,2), and a pinned type narrower than the live column fails plan.
    • Loud failures: plan names each problem it can find and its fix, a commit whose checks fail publishes none of its rows, commits land whole, and in a warehouse (except a ClickHouse Ordinary database) a full refresh swaps in at once.
    • Bounded memory: one budget per run, refused up front when it's too small for a table, and near the limit a table or the run stops and rolls back rather than waiting for the operating system to kill it.
    • No hidden state: tables with a cursor_column continue from the warehouse's own maximum.

    The Postgres CDC bullet is gone; CDC is in the "What it loads" table.

  • Speed and memory: the existing table and caption, moved below "Why SQLLoad".

  • What it loads: DuckDB and MotherDuck are now ticked as sources, since 0.72.0.

Each claim was checked against the docs and a live run on the current release.

Demo recording

.github/demos/plan-load.gif was from before load stopped printing the whole plan tree. The new one is made by scripts under website/recordings/, laid out like SQLBuild's:

  • prepare.sh <demo> builds a clean project under scratch/ (here, sqlload playground shop, plus a copy of its settings with cursor_column misspelled).
  • record.sh <demo> renders tapes/<demo>.tape with VHS into an uncommitted out/. tapes/common.tape holds the shared settings and a theme matching the website's terminal blocks.
  • The file the README uses is copied to .github/demos/.

The demo runs sqlload plan, then sqlload load, then one load with cursor_column = "updated", which stops with "did you mean updated_at?". It runs about 15 s, and every frame was checked.

Docs

The load page said plain plan shows the memory budget line; it shows it only when it asks something (no budget, the budget off, or concurrency lowered), and plan -v always does. The page and its example now say so.

Verification

  • README.md and packages/sqlload/README.md are identical (diff is empty).
  • The Website workflow builds and checks the site; no code changes.
  • website/recordings/prepare.sh fails loudly if the playground's settings change so the misspelling can't be added.

@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Deploying sqlload with  Cloudflare Pages  Cloudflare Pages

Latest commit: f993768
Status: ✅  Deploy successful!
Preview URL: https://c3b46367.sqlload.pages.dev
Branch Preview URL: https://docs-readme-trust.sqlload.pages.dev

View logs

@kvlonge
kvlonge merged commit 5661a2f into main Nov 18, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant