Skip to content

Commit 39f8d40

Browse files
fix(shared): writer-worker WAL admission waits are cancellable and cover mutating pragmas
A write held for WAL admission now waits on a timer in the worker instead of blocking it, so the caller's interrupt cancels it before it runs; a statement already running still finishes before the interrupt completes. Closing the writer ends the wait. The worker classifies mutating pragmas such as incremental_vacuum and user_version as writes, like the main-thread writer. AI-assisted; verified with the tests and tools listed above. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 71c8f69 commit 39f8d40

2 files changed

Lines changed: 123 additions & 64 deletions

File tree

‎packages/shared/src/nodeSqliteClient.test.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -279,11 +279,17 @@ it.effect("holds writer-worker writes past the WAL size limit until a pinned rea
279279
});
280280
yield* sql.withTransaction(blob);
281281
yield* sql.withTransaction(blob);
282+
// Held writes, mutating pragmas included, can be cancelled before they run.
283+
for (const cancelled of [blob, sql`PRAGMA user_version = 7`]) {
284+
yield* Fiber.interrupt(yield* Effect.forkChild(cancelled, { startImmediately: true }));
285+
}
282286
const held = yield* Effect.forkChild(sql.withTransaction(blob), { startImmediately: true });
283287
yield* Effect.sync(() => other.exec("COMMIT"));
284288
yield* Fiber.join(held);
285289
// Without admission the third write appends to a WAL the pinned reader kept from resetting.
286290
assert.isBelow(Number((yield* fs.stat(`${filename}-wal`)).size), limit);
291+
assert.deepEqual(yield* sql`SELECT COUNT(*) FROM blobs`.values, [[3]]);
292+
assert.deepEqual(yield* sql`PRAGMA user_version`.values, [[0]]);
287293
}).pipe(
288294
Effect.provide(SqliteClient.layer({ filename, writerWorker: true, checkpointWorker: true })),
289295
);

‎packages/shared/src/nodeSqliteClient.ts‎

Lines changed: 117 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -217,7 +217,6 @@ try {
217217
db = next;
218218
if (workerData.admission !== undefined && typeof db.setAuthorizer === "function") {
219219
admission = {
220-
control: new Int32Array(workerData.admission.control),
221220
writes: new WeakMap(),
222221
preparing: undefined,
223222
sizeLimit: db.prepare("PRAGMA journal_size_limit"),
@@ -226,15 +225,25 @@ try {
226225
checkpoint: db.prepare("PRAGMA wal_checkpoint(PASSIVE)"),
227226
truncate: db.prepare("PRAGMA wal_checkpoint(TRUNCATE)"),
228227
};
229-
db.setAuthorizer((code, action) => {
228+
// Same classification as the main-thread writer's checkpoint admission.
229+
const valuePragmas = new Set(["application_id", "auto_vacuum", "journal_mode", "schema_version", "user_version"]);
230+
const mutatesPragma = (name, value) => {
231+
const pragma = name === null ? undefined : name.toLowerCase();
232+
if (pragma === undefined) return false;
233+
if (pragma === "incremental_vacuum" || pragma === "optimize") return true;
234+
if (pragma === "wal_checkpoint") return value === null || value.toLowerCase() !== "noop";
235+
return value !== null && valuePragmas.has(pragma);
236+
};
237+
db.setAuthorizer((code, action, argument) => {
230238
const writes =
231239
code === constants.SQLITE_TRANSACTION || code === constants.SQLITE_SAVEPOINT
232240
? action === "BEGIN"
233-
: code !== constants.SQLITE_READ &&
234-
code !== constants.SQLITE_SELECT &&
235-
code !== constants.SQLITE_FUNCTION &&
236-
code !== constants.SQLITE_RECURSIVE &&
237-
code !== constants.SQLITE_PRAGMA;
241+
: code === constants.SQLITE_PRAGMA
242+
? mutatesPragma(action, argument)
243+
: code !== constants.SQLITE_READ &&
244+
code !== constants.SQLITE_SELECT &&
245+
code !== constants.SQLITE_FUNCTION &&
246+
code !== constants.SQLITE_RECURSIVE;
238247
if (writes && admission.preparing !== undefined) admission.preparing.writes = true;
239248
return constants.SQLITE_OK;
240249
});
@@ -264,32 +273,28 @@ const walBytes = () => {
264273
}
265274
};
266275
// Mirrors the checkpoint worker's admission: a write waits while the WAL is over its bound and
267-
// a pinned reader keeps checkpoints from shrinking it. Blocking here leaves the event loop free.
268-
const admit = () => {
269-
const { control } = admission;
270-
const { backpressureFrames, idleMs } = workerData.admission;
271-
while (Atomics.load(control, 0) === 0) {
276+
// a pinned reader keeps checkpoints from shrinking it. The wait polls, so it can be cancelled.
277+
const admitted = () => {
278+
const { backpressureFrames } = workerData.admission;
279+
for (let attempt = 0; attempt < 2; attempt++) {
272280
const limit = Number(admission.sizeLimit.get().journal_size_limit);
273281
const frameBytes = Number(admission.pageSize.get().page_size) + 24;
274282
const size = walBytes();
275283
const oversized = limit >= 0 && size > limit;
276-
if (!oversized && size < backpressureFrames * frameBytes) return;
284+
if (!oversized && size < backpressureFrames * frameBytes) return true;
277285
const state = admission.checkpoint.get();
278-
if (!oversized && state.log < backpressureFrames) return;
279-
if (state.checkpointed === state.log) {
280-
const timeout = Number(admission.busyTimeout.get().timeout);
281-
// A pinned reader must not make truncation wait; retry after the idle delay instead.
282-
db.exec("PRAGMA busy_timeout = 0;");
283-
let busy;
284-
try {
285-
busy = admission.truncate.get().busy !== 0;
286-
} finally {
287-
db.exec("PRAGMA busy_timeout = " + timeout + ";");
288-
}
289-
if (!busy) continue;
286+
if (!oversized && state.log < backpressureFrames) return true;
287+
if (state.checkpointed !== state.log) return false;
288+
const timeout = Number(admission.busyTimeout.get().timeout);
289+
// A pinned reader must not make truncation wait; retry after the idle delay instead.
290+
db.exec("PRAGMA busy_timeout = 0;");
291+
try {
292+
if (admission.truncate.get().busy !== 0) return false;
293+
} finally {
294+
db.exec("PRAGMA busy_timeout = " + timeout + ";");
290295
}
291-
Atomics.wait(control, 0, 0, idleMs);
292296
}
297+
return false;
293298
};
294299
const prepare = (sql, cached) => {
295300
if (!cached) return prepareClassified(sql);
@@ -303,19 +308,38 @@ const prepare = (sql, cached) => {
303308
statements.set(sql, statement);
304309
return statement;
305310
};
306-
parentPort.on("message", ({ type, id, sql, params, cached, values, raw, safeIntegers }) => {
307-
if (type === "close") {
308-
if (db !== undefined) db.close();
309-
parentPort.close();
310-
return;
311-
}
311+
const reply = (id, operation, error) =>
312+
parentPort.postMessage({
313+
id,
314+
error: {
315+
operation,
316+
message: String(error && error.message ? error.message : error),
317+
code: error && error.code,
318+
errcode: error && error.errcode,
319+
errstr: error && error.errstr,
320+
},
321+
});
322+
let waiting;
323+
const backlog = [];
324+
const run = (request) => {
325+
const { id, sql, params, cached, values, raw, safeIntegers } = request;
312326
let operation = "open";
313327
try {
314328
if (db === undefined) throw new Error("database reader is unavailable");
315329
operation = "prepare";
316330
const statement = prepare(sql, cached);
317331
operation = "execute";
318-
if (admission !== undefined && admission.writes.get(statement) && !db.isTransaction) admit();
332+
if (admission !== undefined && admission.writes.get(statement) && !db.isTransaction && !admitted()) {
333+
waiting = {
334+
id,
335+
timer: setTimeout(() => {
336+
waiting = undefined;
337+
run(request);
338+
while (waiting === undefined && backlog.length > 0) run(backlog.shift());
339+
}, workerData.admission.idleMs),
340+
};
341+
return;
342+
}
319343
statement.setReadBigInts(safeIntegers);
320344
if (statement.columns().length > 0) {
321345
statement.setReturnArrays(values);
@@ -325,17 +349,38 @@ parentPort.on("message", ({ type, id, sql, params, cached, values, raw, safeInte
325349
parentPort.postMessage({ id, rows: raw ? result : [] });
326350
}
327351
} catch (error) {
328-
parentPort.postMessage({
329-
id,
330-
error: {
331-
operation,
332-
message: String(error && error.message ? error.message : error),
333-
code: error && error.code,
334-
errcode: error && error.errcode,
335-
errstr: error && error.errstr,
336-
},
337-
});
352+
reply(id, operation, error);
353+
}
354+
};
355+
const stopWaiting = (message) => {
356+
if (waiting === undefined) return false;
357+
clearTimeout(waiting.timer);
358+
reply(waiting.id, "execute", message);
359+
waiting = undefined;
360+
return true;
361+
};
362+
parentPort.on("message", (request) => {
363+
if (request.type === "close") {
364+
stopWaiting("Database writer closed");
365+
for (const queued of backlog) reply(queued.id, "execute", "Database writer closed");
366+
if (db !== undefined) db.close();
367+
parentPort.close();
368+
return;
369+
}
370+
if (request.type === "cancel") {
371+
// A request that is not waiting has already run; its reply is on the way.
372+
const queued = backlog.findIndex((entry) => entry.id === request.id);
373+
if (queued !== -1) {
374+
reply(request.id, "execute", "Statement cancelled before it ran");
375+
backlog.splice(queued, 1);
376+
} else if (waiting !== undefined && waiting.id === request.id) {
377+
stopWaiting("Statement cancelled before it ran");
378+
while (waiting === undefined && backlog.length > 0) run(backlog.shift());
379+
}
380+
return;
338381
}
382+
if (waiting !== undefined) backlog.push(request);
383+
else run(request);
339384
});
340385
`;
341386

@@ -568,8 +613,6 @@ const makeReader = Effect.fnUntraced(function* (
568613

569614
// The writer cannot be replaced after an exit: a new connection would lack setup PRAGMAs and any open transaction.
570615
const startWriterWorker = Effect.fnUntraced(function* (options: SqliteClientConfig) {
571-
// Set when the writer closes so a write held for WAL admission stops waiting.
572-
const closing = new Int32Array(new SharedArrayBuffer(4));
573616
const warn = (reason: string) =>
574617
Effect.logWarning("SQLite writer worker unavailable; writes run on the main thread", {
575618
reason,
@@ -586,7 +629,6 @@ const startWriterWorker = Effect.fnUntraced(function* (options: SqliteClientConf
586629
prepareCacheSize: 200,
587630
admission: options.checkpointWorker
588631
? {
589-
control: closing.buffer,
590632
backpressureFrames: CHECKPOINT_BACKPRESSURE_FRAMES,
591633
idleMs: CHECKPOINT_IDLE_MS,
592634
}
@@ -653,8 +695,6 @@ const startWriterWorker = Effect.fnUntraced(function* (options: SqliteClientConf
653695
Effect.promise(() => {
654696
if (stoppedMessage !== undefined) return exited;
655697
stoppedMessage = "Database writer closed";
656-
Atomics.store(closing, 0, 1);
657-
Atomics.notify(closing, 0);
658698
// Queued after in-flight statements; the ref keeps the process alive until the database closes.
659699
worker.ref();
660700
// oxlint-disable-next-line unicorn/require-post-message-target-origin -- Node workers do not accept a target origin.
@@ -674,24 +714,37 @@ const startWriterWorker = Effect.fnUntraced(function* (options: SqliteClientConf
674714
);
675715
}
676716
const safeIntegers = Boolean(Context.get(fiber.context, Client.SafeIntegers));
677-
// Like a statement on the main thread, a sent statement finishes before its caller sees an interrupt.
678-
return Effect.uninterruptible(
679-
Effect.callback<ReadonlyArray<any>, SqlError>((resume) => {
680-
const id = nextRequestId++;
681-
pending.set(id, (reply) => resume(replyToExit(reply)));
682-
if (pending.size === 1) worker.ref();
683-
const cached = input.cached && !hasLargeBinding(input.params);
717+
return Effect.callback<ReadonlyArray<any>, SqlError>((resume) => {
718+
const id = nextRequestId++;
719+
let replied: () => void = () => {};
720+
const settled = new Promise<void>((resolve) => {
721+
replied = resolve;
722+
});
723+
pending.set(id, (reply) => {
724+
replied();
725+
resume(replyToExit(reply));
726+
});
727+
if (pending.size === 1) worker.ref();
728+
const cached = input.cached && !hasLargeBinding(input.params);
729+
try {
730+
// oxlint-disable-next-line unicorn/require-post-message-target-origin -- Node workers do not accept a target origin.
731+
worker.postMessage({ id, safeIntegers, ...input, cached });
732+
} catch (cause) {
733+
settle(id, {
734+
id,
735+
error: { operation: "execute", message: String(cause) },
736+
});
737+
}
738+
// Only a write still waiting for WAL admission is cancelled; a running statement finishes first.
739+
return Effect.promise(() => {
740+
if (!pending.has(id)) return settled;
684741
try {
685742
// oxlint-disable-next-line unicorn/require-post-message-target-origin -- Node workers do not accept a target origin.
686-
worker.postMessage({ id, safeIntegers, ...input, cached });
687-
} catch (cause) {
688-
settle(id, {
689-
id,
690-
error: { operation: "execute", message: String(cause) },
691-
});
692-
}
693-
}),
694-
);
743+
worker.postMessage({ type: "cancel", id });
744+
} catch {}
745+
return settled;
746+
});
747+
});
695748
});
696749
return workerConnection(request);
697750
});

0 commit comments

Comments
 (0)