Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/weak-cherries-invite.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@cutils/sqlite": minor
---

add db.pragma() and stmt.iterate()/each for better-sqlite3 DX parity
93 changes: 93 additions & 0 deletions packages/sqlite/gate.ts
Original file line number Diff line number Diff line change
Expand Up @@ -140,6 +140,99 @@ function main(): void {
const pv = db.pragma("user_version");
check(pv.rows.length === 1, "pragma() rows");

// pragmaNamed read form: row objects keyed by pragma name.
const pn = db.pragmaNamed("user_version");
check(pn.length === 1, "pragmaNamed() read");
check(pn[0].user_version === 0, "pragmaNamed() user_version default");

// pragmaNamed write form: numeric, string, boolean values.
db.pragmaNamed("user_version", 42);
check(db.pragmaNamed("user_version")[0].user_version === 42, "pragmaNamed() numeric write");
db.pragmaNamed("journal_mode", "MEMORY");
check(
String(db.pragmaNamed("journal_mode")[0].journal_mode).toUpperCase() === "MEMORY",
"pragmaNamed() string write",
);
db.pragmaNamed("user_version", true);
check(db.pragmaNamed("user_version")[0].user_version === 1, "pragmaNamed() boolean write");
db.pragmaNamed("user_version", 0);
check(db.pragmaNamed("user_version")[0].user_version === 0, "pragmaNamed() reset write");
check(db.pragmaNamed("user_version", 7).changes >= 0, "pragmaNamed() write returns RunResult");

// Injection rejection: identifier position is validated, never interpolated.
let pcode = "";
try {
db.pragmaNamed("user_version; DROP TABLE todos");
} catch (e) {
if (e instanceof SqliteError) {
pcode = e.code;
}
}
check(pcode === "SQLITE_MISUSE", "pragmaNamed() rejects injection name");
let pcode2 = "";
try {
db.pragmaNamed("");
} catch (e) {
if (e instanceof SqliteError) {
pcode2 = e.code;
}
}
check(pcode2 === "SQLITE_MISUSE", "pragmaNamed() rejects empty name");
// A pragma name with a quote must be rejected, not double-quoted through.
let pcode3 = "";
try {
db.pragmaNamed('us"er_version');
} catch (e) {
if (e instanceof SqliteError) {
pcode3 = e.code;
}
}
check(pcode3 === "SQLITE_MISUSE", "pragmaNamed() rejects quote in name");

// iterate: one row per step through a generator, plus manual next().
const itSel = db.prepareRaw("SELECT title FROM todos WHERE done = 0 ORDER BY id");
let itCount = 0;
let firstTitle = "";
for (const row of itSel.iterate([])) {
itCount += 1;
if (itCount === 1) {
firstTitle = String((row as Row).title);
}
}
check(itCount === 1, "iterate() row count");
check(firstTitle === "write docs", "iterate() first row");

const manual = itSel.iterate([]);
const m1 = manual.next();
check(m1.done === false, "iterate() not done on first");
check((m1.value as Row).title === "write docs", "iterate() manual first");
check(manual.next().done === true, "iterate() done at exhaustion");

// Named-parameter bind form.
const named = db.prepareRaw("SELECT title FROM todos WHERE done = :d ORDER BY id");
let done1 = 0;
for (const row of named.iterate({ d: 1 })) {
if ((row as Row).title === "raw insert") {
done1 += 1;
}
}
check(done1 === 1, "iterate() named params");
named.finalize();
itSel.finalize();

// iterate on a finalized statement throws eagerly (MISUSE), not lazily.
const dead = db.prepareRaw("SELECT 1 AS one");
dead.finalize();
let icode = "";
try {
dead.iterate([]);
} catch (e) {
if (e instanceof SqliteError) {
icode = e.code;
}
}
check(icode === "SQLITE_MISUSE", "iterate() on finalized stmt");

// Transactions: commit, auto-savepoint on nesting, explicit savepoint,
// rollback, and error-driven rollback via dispose.
{
Expand Down
87 changes: 87 additions & 0 deletions packages/sqlite/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -481,6 +481,43 @@ class StmtCore implements Disposable {
}
}

iterate<TRow>(params: BindValue[]): Generator<TRow>;
iterate<TRow>(params: BindRecord): Generator<TRow>;
iterate(params: unknown): Generator<unknown> {
// Bind eagerly (a finalized statement throws here, not on first next()),
// then hand out the lazy row-at-a-time generator over the current
// bindings. An omitted or EMPTY params arg keeps the existing bindings,
// mirroring all()/get() semantics.
this._checkLive();
let bound = params;
if (this._schema !== null && typeof params !== "undefined") {
bound = validateRow(this._schema, params);
}
this._bindParams(bound);
return this._iterateBound();
}

*_iterateBound(): Generator<unknown> {
// No per-row reset: sqlite3_reset rewinds the statement, so resetting
// between rows would replay the query forever. The statement is left
// at the last row until DONE (or the consumer re-binds, which resets
// via _bindParams).
for (;;) {
const rc = ffiStep(this._stmt);
if (rc === STEP_ROW) {
yield this._validateOut(this._readRow());
continue;
}
if (rc === STEP_DONE) {
ffiReset(this._stmt);
return;
}
ffiReset(this._stmt);
this._db._throwDb(rc, "step failed");
return;
}
}

bind(params: BindValue[]): StmtCore;
bind(params: BindRecord): StmtCore;
bind(params: unknown): StmtCore {
Expand Down Expand Up @@ -588,6 +625,8 @@ export interface Stmt<TRow = unknown> extends StmtCore {
allRaw(params: BindRecord): unknown[];
bind(params: BindValue[]): this;
bind(params: BindRecord): this;
iterate(params: BindValue[]): Generator<TRow>;
iterate(params: BindRecord): Generator<TRow>;
}

export const Stmt = StmtCore;
Expand Down Expand Up @@ -782,6 +821,54 @@ export class Database implements Disposable {
return { rows: out };
}

pragmaNamed(name: string): Row[];
pragmaNamed(name: string, value: number): RunResult;
pragmaNamed(name: string, value: string): RunResult;
pragmaNamed(name: string, value: boolean): RunResult;
pragmaNamed(name: string, value?: number | string | boolean): Row[] | RunResult {
// better-sqlite3 DX: `pragma(name)` reads, `pragma(name, value)` writes.
// The name is an identifier position — no binding exists there — so it
// is validated (no injection surface) and double-quoted instead of
// interpolated raw. The value IS parameterized (`PRAGMA x = ?`).
if (name.length === 0 || !/^[A-Za-z0-9_$]+$/.test(name)) {
throw new SqliteError("SQLITE_MISUSE", "invalid pragma name: " + name);
}
this._checkOpen();
if (typeof value === "undefined") {
const stmt = this._prepareCore('PRAGMA "' + name + '"', null);
const rows = stmt.allRaw([]);
stmt.finalize();
const out: Row[] = [];
for (let i = 0; i < rows.length; i++) {
out.push(rows[i] as Row);
}
return out;
}
// The value slot in `PRAGMA x = ?` does not accept bound parameters
// (the pragma parser takes a literal), so the value goes into the SQL
// as a literal: numbers directly, strings single-quoted with ''-escaped
// quotes, booleans as 0/1, null as NULL — better-sqlite3's convention.
let lit: string;
if (typeof value === "number") {
if (!Number.isFinite(value)) {
throw new SqliteError("SQLITE_MISUSE", "pragma value must be finite");
}
lit = String(value);
} else if (typeof value === "boolean") {
lit = value ? "1" : "0";
} else {
lit = "'" + value.replace(/'/g, "''") + "'";
}
const stmt = this._prepareCore('PRAGMA "' + name + '" = ' + lit, null);
stmt._drain();
const result: RunResult = {
changes: stmt.database.changes(),
lastInsertRowid: stmt.database.lastInsertRowid(),
};
stmt.finalize();
return result;
}

transaction(): Transaction {
this._checkOpen();
if (this.inTransaction) {
Expand Down
71 changes: 71 additions & 0 deletions packages/sqlite/test/wrapper.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -205,6 +205,77 @@ test("pragma, columns, expanded sql, bind", () => {
db.close();
});

test("pragmaNamed: read and write forms", () => {
const db = fresh();
const before = db.pragmaNamed("user_version");
assert.equal(before.length, 1);
assert.equal(before[0].user_version, 0);

const wr = db.pragmaNamed("user_version", 42);
assert.equal(wr.changes, 0);
const after = db.pragmaNamed("user_version");
assert.equal(after[0].user_version, 42);

db.pragmaNamed("journal_mode", "MEMORY");
const jm = db.pragmaNamed("journal_mode");
assert.equal(String(jm[0].journal_mode).toUpperCase(), "MEMORY");

// double-quoted identifier: mixed case + digits + underscore survive
db.exec("CREATE TABLE t2 (a)");
db.pragmaNamed("temp_store", 1);
assert.equal(db.pragmaNamed("temp_store")[0].temp_store, 1);

// injection attempt must be rejected, not interpolated
assert.throws(
() => db.pragmaNamed("user_version; DROP TABLE todos"),
(e) => e.code === "SQLITE_MISUSE",
);
assert.throws(
() => db.pragmaNamed(""),
(e) => e.code === "SQLITE_MISUSE",
);
db.close();
});

test("iterate: rows one at a time, lazily", () => {
const db = fresh();
const ins = db.prepareRaw("INSERT INTO todos (title, done) VALUES (?, ?)");
ins.run(["i1", 0]);
ins.run(["i2", 1]);
ins.run(["i3", 0]);
ins.finalize();

const sel = db.prepareRaw("SELECT title FROM todos WHERE done = 0 ORDER BY id");
const it = sel.iterate([]);
const seen = [];
for (const row of it) {
seen.push(row.title);
}
assert.deepEqual(seen, ["i1", "i3"]);

// manual next() driving + done detection
const it2 = sel.iterate([]);
assert.deepEqual(it2.next().value, { title: "i1" });
assert.equal(it2.next().done, false);
assert.equal(it2.next().done, true);
sel.finalize();

// named-parameter bind form + empty reuse
const sel2 = db.prepareRaw("SELECT title FROM todos WHERE done = :d ORDER BY id");
const one = Array.from(sel2.iterate({ d: 1 })).map((r) => r.title);
assert.deepEqual(one, ["i2"]);
sel2.finalize();

// iterate on a finalized statement throws eagerly at the call
const dead = db.prepareRaw("SELECT 1");
dead.finalize();
assert.throws(
() => dead.iterate([]),
(e) => e.code === "SQLITE_MISUSE",
);
db.close();
});

test("errors: SqliteError codes propagate", () => {
const db = fresh();
assert.throws(
Expand Down
Loading