The best way to control Claude Code, Codex and more from any computer or phone
fix(server): keep writes moving while readers pin the WAL (#23496)
Julius Marminge committed
Nov 11, 2026 at 15:42 UTC
a2a3388c5ec82d1f33e5e69ed34303529d882e17
2 files changed
+126
-13
packages/shared/src/nodeSqliteClient.test.ts
+109
@@ -491,3 +491,112 @@ it.effect.each([
491
);
492
}).pipe(Effect.provide(SqliteClient.layer({ filename: ":memory:" }))),
493
);
494
+
495
+const PAYLOAD = new Uint8Array(1024 * 1024).fill(7);
496
+const WAL_SIZE_LIMIT = 32 * 1024 * 1024;
497
+
498
+// Fails instead of hanging when admission holds the write: the worker retries a blocked
499
+// checkpoint on its own, so two blocked reports for one WAL generation mean a held write.
500
+const insertUnlessHeld = Effect.fnUntraced(function* (
501
+ sql: SqlClient.SqlClient,
502
+ worker: NodeWorkerThreads.Worker,
503
+ label: string,
504
+) {
505
+ const stalled = yield* Deferred.make<void>();
506
+ let seen: unknown;
507
+ const onMessage = (message: { type?: unknown; blocked?: unknown; generation?: unknown }) => {
508
+ if (message?.type !== "checkpoint" || message.blocked !== true) return;
509
+ if (message.generation === seen) Deferred.doneUnsafe(stalled, Effect.void);
510
+ seen = message.generation;
511
+ };
512
+ worker.on("message", onMessage);
513
+ const held = yield* Effect.raceFirst(
514
+ sql`INSERT INTO blobs VALUES (${PAYLOAD})`.pipe(Effect.as(false)),
515
+ Deferred.await(stalled).pipe(Effect.as(true)),
516
+ ).pipe(Effect.ensuring(Effect.sync(() => worker.off("message", onMessage))));
517
+ if (held) assert.fail(`${label} is held by admission while an outside reader pins the WAL`);
518
+});
519
+
520
+// `outside` stands in for `sqlite3 statev2.sqlite` or a backup script reading the database.
521
+const withOutsideConnection = <A, E>(
522
+ use: (options: {
523
+ readonly sql: SqlClient.SqlClient;
524
+ readonly worker: NodeWorkerThreads.Worker;
525
+ readonly outside: NodeSqlite.DatabaseSync;
526
+ readonly walSize: Effect.Effect<number>;
527
+ }) => Effect.Effect<A, E, SqlClient.SqlClient>,
528
+) =>
529
+ Effect.gen(function* () {
530
+ const fs = yield* FileSystem.FileSystem;
531
+ const path = yield* Path.Path;
532
+ const directory = yield* fs.makeTempDirectoryScoped({ prefix: "t3-sqlite-pinned-wal-" });
533
+ const filename = path.join(directory, "state.sqlite");
534
+ const outside = yield* Effect.acquireRelease(
535
+ Effect.sync(() => new NodeSqlite.DatabaseSync(filename)),
536
+ (db) =>
537
+ Effect.sync(() => {
538
+ if (db.isTransaction) db.exec("COMMIT");
539
+ db.close();
540
+ }),
541
+ );
542
+ outside.exec(`
543
+ PRAGMA journal_mode = WAL;
544
+ PRAGMA wal_autocheckpoint = 0;
545
+ CREATE TABLE blobs(data BLOB NOT NULL);
546
+ `);
547
+ const walSize = fs.stat(`${filename}-wal`).pipe(
548
+ Effect.map((info) => Number(info.size)),
549
+ Effect.orDie,
550
+ );
551
+ yield* Effect.gen(function* () {
552
+ const sql = yield* SqlClient.SqlClient;
553
+ yield* sql.unsafe(`PRAGMA journal_size_limit = ${WAL_SIZE_LIMIT}`);
554
+ return yield* use({ sql, worker: startedWorkers.at(-1)!, outside, walSize });
555
+ }).pipe(Effect.provide(SqliteClient.layer({ filename, checkpointWorker: true })));
556
+ }).pipe(Effect.scoped, Effect.provide(NodeServices.layer));
557
+
558
+const openReadTransaction = (db: NodeSqlite.DatabaseSync) => {
559
+ db.exec("BEGIN");
560
+ db.prepare("SELECT COUNT(*) FROM blobs").get();
561
+};
562
+
563
+it.effect("keeps admitting writes while an outside read transaction pins the WAL", () =>
564
+ withOutsideConnection(({ sql, worker, outside }) =>
565
+ Effect.gen(function* () {
566
+ yield* sql`INSERT INTO blobs VALUES (${PAYLOAD})`;
567
+ openReadTransaction(outside);
568
+ // 140 MiB passes both the 32 MiB size limit and the 32,768-frame ceiling.
569
+ for (let write = 1; write <= 140; write++) {
570
+ yield* insertUnlessHeld(sql, worker, `write ${write}`);
571
+ }
572
+ const rows = yield* sql<{ count: number }>`SELECT COUNT(*) AS count FROM blobs`;
573
+ assert.equal(rows[0]?.count, 141);
574
+ }),
575
+ ),
576
+);
577
+
578
+it.effect("keeps admitting writes while a reader stops TRUNCATE, then resets the WAL", () =>
579
+ withOutsideConnection(({ sql, worker, outside, walSize }) =>
580
+ Effect.gen(function* () {
581
+ const insert = outside.prepare("INSERT INTO blobs VALUES (?)");
582
+ for (let write = 1; write <= 40; write++) insert.run(PAYLOAD);
583
+ // A snapshot of an unbackfilled WAL lets PASSIVE finish but stops TRUNCATE.
584
+ openReadTransaction(outside);
585
+ const stopped = yield* Deferred.make<void>();
586
+ const reset = yield* Deferred.make<void>();
587
+ worker.on("message", (message: { type?: unknown; truncateId?: unknown; log?: unknown }) => {
588
+ if (message?.type !== "checkpoint" || message.truncateId === undefined) return;
589
+ Deferred.doneUnsafe(message.log === 0 ? reset : stopped, Effect.void);
590
+ });
591
+ // Starts a checkpoint without appending a frame past the reader's snapshot.
592
+ yield* sql`DELETE FROM blobs WHERE 0`;
593
+ yield* Deferred.await(stopped);
594
+ yield* insertUnlessHeld(sql, worker, "a write after the failed TRUNCATE");
595
+ assert.isAbove(yield* walSize, WAL_SIZE_LIMIT);
596
+ outside.exec("COMMIT");
597
+ // No further write arrives; the worker has to retry on its own.
598
+ yield* Deferred.await(reset);
599
+ assert.equal(yield* walSize, 0);
600
+ }),
601
+ ),
602
+);
packages/shared/src/nodeSqliteClient.ts
+17
-13
@@ -524,8 +524,9 @@ const initialize = () => {
524
const atCeiling = (state) => state.log >= workerData.backpressureFrames;
525
const exceedsSizeLimit = () =>
526
journalSizeLimit >= 0 && statSync(workerData.filename + "-wal").size > journalSizeLimit;
527
-const schedule = (state, blocked) => {
528
- if (blocked || state.log - state.checkpointed >= workerData.frames) {
527
+// Retry a WAL past its limits even with admission open, so it resets once a pinning reader closes.
528
+const schedule = (state, retry) => {
529
+ if (retry || state.log - state.checkpointed >= workerData.frames) {
530
idle = setTimeout(() => check(undefined, undefined, true), workerData.idleMs);
531
}
532
};
@@ -535,8 +536,11 @@ const check = (id, nextJournalSizeLimit, force, nextGeneration = generation) =>
536
if (Number.isSafeInteger(nextJournalSizeLimit)) journalSizeLimit = nextJournalSizeLimit;
537
let state = frames.get();
538
const oversized = exceedsSizeLimit();
539
+ let pinned = false;
540
if (force || state.log - state.checkpointed >= workerData.frames || oversized) {
539
- checkpoint.get();
541
+ const result = checkpoint.get();
542
+ // A reader's snapshot stopped the backfill; holding writes cannot let it catch up.
543
+ pinned = result.checkpointed < result.log;
544
state = frames.get();
545
}
546
if (state.checkpointed === state.log && (atCeiling(state) || oversized)) {
@@ -550,24 +554,22 @@ const check = (id, nextJournalSizeLimit, force, nextGeneration = generation) =>
554
});
555
return;
556
}
553
- const blocked = (atCeiling(state) || oversized) && state.checkpointed < state.log;
557
+ const blocked = !pinned && (atCeiling(state) || oversized) && state.checkpointed < state.log;
558
parentPort.postMessage({ type: "checkpoint", id, generation, ...state, blocked });
555
- schedule(state, blocked);
559
+ schedule(state, atCeiling(state) || oversized);
560
};
561
const finishTruncate = (truncateId) => {
562
if (pendingTruncate === undefined || pendingTruncate.truncateId !== truncateId) return;
563
const pending = pendingTruncate;
564
parentPort.postMessage({ type: "truncate-start", truncateId });
561
- let busy;
565
// Admission is paused here; a pinned reader must not make truncation wait.
566
db.exec("PRAGMA busy_timeout = 0;");
567
try {
565
- busy = truncate.get().busy !== 0;
568
+ truncate.get();
569
} finally {
570
db.exec("PRAGMA busy_timeout = 5000;");
571
}
572
const state = frames.get();
570
- const blocked = (atCeiling(state) && (busy || state.checkpointed < state.log)) || exceedsSizeLimit();
573
pendingTruncate = undefined;
574
parentPort.postMessage({
575
type: "checkpoint",
@@ -575,13 +577,15 @@ const finishTruncate = (truncateId) => {
577
generation: pending.generation,
578
truncateId,
579
...state,
578
- blocked,
580
+ // With writes held, only a reader can stop the reset, and holding them longer would not
581
+ // release it.
582
+ blocked: false,
583
});
584
while (pendingBarriers > 0) {
585
pendingBarriers--;
586
parentPort.postMessage("barrier");
587
}
584
- schedule(state, blocked);
588
+ schedule(state, atCeiling(state) || exceedsSizeLimit());
589
};
590
parentPort.on("message", (request) => {
591
clearTimeout(idle);
@@ -669,9 +673,7 @@ const startCheckpointWorker = Effect.fnUntraced(function* (
673
const waiters: Array<Waiter> = [];
674
let elected: Waiter | undefined;
675
const gated = () =>
672
- !stopped &&
673
- !writer.isTransaction &&
674
- (unknown || blocked || truncate !== undefined || log >= CHECKPOINT_BACKPRESSURE_FRAMES);
676
+ !stopped && !writer.isTransaction && (unknown || blocked || truncate !== undefined);
677
const wake = () => {
678
if (!gated() && elected === undefined) {
679
elected = waiters.shift();
@@ -719,6 +721,8 @@ const startCheckpointWorker = Effect.fnUntraced(function* (
721
log = nextLog;
722
checkpointed = nextCheckpointed;
723
unknown = false;
724
+ // Past the ceiling, hold writes until the worker judges this WAL; a reader can pin it there.
725
+ if (log >= CHECKPOINT_BACKPRESSURE_FRAMES) blocked = true;
726
} catch {
727
unknown = true;
728
}