Skip to content

feat(sqlite): db.pragma() named read/write and stmt.iterate() generator - #50

Merged
espetro merged 4 commits into
mainfrom
feat/sqlite-pragma-iterate
Nov 10, 2026
Merged

espetro merged 4 commits into
mainfrom
feat/sqlite-pragma-iterate

Conversation

@espetro

@espetro espetro commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Summary

better-sqlite3 DX parity for @cutils/sqlite:

  • pragmaNamed(name) — read form runs PRAGMA "name" and returns row objects (e.g. db.pragmaNamed("user_version")[0].user_version). Write form takes a number/boolean/string value and returns a RunResult. The name sits in identifier position where binding is impossible, so it is validated against a strict identifier charset first and double-quoted on use: anything else (quotes, semicolons, whitespace) throws SQLITE_MISUSE before reaching prepare. Values cannot be parameterized (the pragma parser takes a literal only — PRAGMA x = ? is a syntax error), so they are emitted as literals: numbers verbatim, booleans as 0/1, strings single-quoted with internal quotes doubled.
  • stmt.iterate(params) — generator yielding one validated row per step, lazily, mirroring better-sqlite3's iterate(). Binds first (schema-validated; empty/omitted args keep current bindings like all()/get()), throws MISUSE eagerly on a finalized statement. Probe-verified that function* class methods lower under both the shipped scriptc 0.4.7 and 0.4.10, so no callback fallback was needed. Implementation note: the statement is deliberately NOT reset between rows — reset rewinds, which replayed the query forever until fixed.
  • pragma(sql) (raw string, returns { rows }) is unchanged for compatibility.

Tests

  • node suite (koffi): read/write pragmaNamed incl. journal_mode string form, injection-name rejection, iterate for...of + manual next() exhaustion + named binds + finalized-statement throw — 12/12 pass
  • gate.ts extended for both; scriptc coverage still 100%
  • test/elf.test.sh + test/consumer-elf.test.sh green; shim.test.c green
  • oxlint/oxfmt clean

Also commented on #33 (shim ABI verified at scriptc 0.4.10, no relink needed) and #34 (Symbol.dispose shipped on Database/StmtCore/Transaction) for closure by the maintainer.

…) generator

pragmaNamed(name) reads PRAGMA "name", pragmaNamed(name, value) writes a
literal value (number/boolean/string with doubled-quote escaping; the pragma
parser takes no bound parameters, so values cannot be parameterized). The
name is validated against a strict identifier charset before double-quoting,
so an injection attempt is SQLITE_MISUSE, never interpolated.

iterate(params) binds (schema-validated, same empty-args-keep-bindings rule
as all()/get()) and returns a generator yielding one validated row per step.
The statement is not reset between rows (reset rewinds), and a finalized
statement throws SQLITE_MISUSE eagerly at the iterate() call.
Cover the better-sqlite3 DX surface through koffi: pragmaNamed read rows,
numeric/string/boolean writes, injection-name rejection, iterate via
for...of, manual next() exhaustion, named-parameter binds, and the eager
MISUSE throw on a finalized statement.
…and iterate

Same fixtures through scriptc coverage (still 100 percent) and the ELF build:
read/write pragmaNamed including quote-in-name rejection, and iterate row
streaming with manual next() exhaustion.
@cloudflare-workers-and-pages

Copy link
Copy Markdown

Deploying cutilsjs with  Cloudflare Pages  Cloudflare Pages

Latest commit: c9b6bc9
Status: ✅  Deploy successful!
Preview URL: https://6d9741e4.cutilsjs.pages.dev
Branch Preview URL: https://feat-sqlite-pragma-iterate.cutilsjs.pages.dev

View logs

@espetro
espetro merged commit 362ba05 into main Nov 10, 2026
3 checks passed
@espetro
espetro deleted the feat/sqlite-pragma-iterate branch November 10, 2026 01:28
@espetro espetro mentioned this pull request Nov 10, 2026
3 tasks done
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