The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 22, 12:00 UTC
perf(shared): SQLite reads stop queueing behind each other, up to 5x faster under load (#27097)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Julius Marminge committed
Oct 29, 2026 at 13:38 UTC
facaa08b36c5511108752aa08d48182c37412ce4
2 files changed
+183
-89
packages/shared/src/nodeSqliteClient.test.ts
+40
@@ -238,6 +238,27 @@ it.effect("lets the writer commit while a read-only transaction is open", () =>
238
),
239
);
240
241
+it.effect("serves another read while a read-only transaction is open", () =>
242
+ withReaderClient((sql) =>
243
+ Effect.gen(function* () {
244
+ const opened = yield* Deferred.make<void>();
245
+ const other = yield* Effect.forkChild(
246
+ Deferred.await(opened).pipe(Effect.andThen(countEntries(sql).pipe(SqliteClient.readOnly))),
247
+ );
248
+ yield* sql
249
+ .withTransaction(
250
+ Effect.gen(function* () {
251
+ yield* countEntries(sql);
252
+ yield* Deferred.succeed(opened, undefined);
253
+ // One shared reader would make this join wait on the transaction forever.
254
+ assert.equal(yield* Fiber.join(other), 1);
255
+ }),
256
+ )
257
+ .pipe(SqliteClient.readOnly);
258
+ }),
259
+ ),
260
+);
261
+
262
// regression: #19226 read-only transactions run on the separate reader connection
263
it.effect("rejects a write in a read-only transaction", () =>
264
withReaderClient((sql) =>
@@ -333,6 +354,25 @@ it.effect("uses the writer when the reader cannot open the database", () =>
354
355
assert.equal(yield* sql.withTransaction(countEntries(sql)).pipe(SqliteClient.readOnly), 1);
356
assert.equal(yield* sql.withTransaction(countEntries(sql)).pipe(SqliteClient.readOnly), 1);
357
+
358
+ // A read beside an open read transaction must not start a worker on the next slot.
359
+ const held = yield* Deferred.make<void>();
360
+ const release = yield* Deferred.make<void>();
361
+ const holder = yield* sql
362
+ .withTransaction(
363
+ countEntries(sql).pipe(
364
+ Effect.andThen(Deferred.succeed(held, undefined)),
365
+ Effect.andThen(Deferred.await(release)),
366
+ ),
367
+ )
368
+ .pipe(SqliteClient.readOnly, Effect.forkChild);
369
+ yield* Deferred.await(held);
370
+ const other = yield* countEntries(sql).pipe(SqliteClient.readOnly, (effect) =>
371
+ Effect.forkChild(effect, { startImmediately: true }),
372
+ );
373
+ yield* Deferred.succeed(release, undefined);
374
+ yield* Fiber.join(holder);
375
+ assert.equal(yield* Fiber.join(other), 1);
376
assert.equal(startedWorkers.length, startedBefore + 1);
377
}),
378
),
packages/shared/src/nodeSqliteClient.ts
+143
-89
@@ -293,8 +293,14 @@ const failed = (cause: unknown, message: string, operation: string) =>
293
// Read-transaction cleanup succeeds after worker exit because it can no longer change anything.
294
const endsReadTransaction = (sql: string) => /^\s*ROLLBACK\b|^\s*COMMIT\b/i.test(sql);
295
296
+// WAL readers run concurrently; one worker serialized every read behind the slowest transaction.
297
+const READER_POOL_SIZE = 4;
298
+
299
// Bind transactions to one worker; fail after its exit instead of resuming outside the transaction on a replacement.
297
-const makeReader = Effect.fnUntraced(function* (options: SqliteClientConfig) {
300
+const makeReader = Effect.fnUntraced(function* (
301
+ options: SqliteClientConfig,
302
+ pool: { unavailable: boolean },
303
+) {
304
let current:
305
| {
306
readonly worker: NodeWorkerThreads.Worker;
@@ -302,7 +308,6 @@ const makeReader = Effect.fnUntraced(function* (options: SqliteClientConfig) {
308
readonly started: Promise<ReaderStartup>;
309
}
310
| undefined;
305
- let unavailable = false;
311
let nextRequestId = 0;
312
313
const start = () => {
@@ -439,8 +444,8 @@ const makeReader = Effect.fnUntraced(function* (options: SqliteClientConfig) {
444
void reader.worker.terminate();
445
}
446
// @effect-diagnostics-next-line effectSucceedWithVoid:off - The connection result distinguishes undefined from void.
442
- if (unavailable) return Effect.succeed(undefined);
443
- unavailable = true;
447
+ if (pool.unavailable) return Effect.succeed(undefined);
448
+ pool.unavailable = true;
449
return Effect.logWarning("SQLite reader worker unavailable; reads use the main connection", {
450
reason,
451
}).pipe(Effect.as(undefined));
@@ -448,7 +453,7 @@ const makeReader = Effect.fnUntraced(function* (options: SqliteClientConfig) {
453
454
return Effect.suspend((): Effect.Effect<Connection | undefined> => {
455
// @effect-diagnostics-next-line effectSucceedWithVoid:off - The connection result distinguishes undefined from void.
451
- if (unavailable) return Effect.succeed(undefined);
456
+ if (pool.unavailable) return Effect.succeed(undefined);
457
let reader: NonNullable<typeof current>;
458
try {
459
reader = current ?? start();
@@ -467,7 +472,7 @@ const makeReader = Effect.fnUntraced(function* (options: SqliteClientConfig) {
472
}),
473
(startup): Effect.Effect<Connection | undefined> =>
474
// A late ready event must not hand out a worker retired by another acquire timeout.
470
- unavailable || current !== reader
475
+ pool.unavailable || current !== reader
476
? // @effect-diagnostics-next-line effectSucceedWithVoid:off - The connection result distinguishes undefined from void.
477
Effect.succeed(undefined)
478
: Option.isSome(startup) && startup.value.type === "ready"
@@ -1073,21 +1078,48 @@ const make = Effect.fn("makeWithDatabase")(function* (
1078
1079
const semaphore = yield* Semaphore.make(1);
1080
const connection = yield* makeConnection;
1076
- const acquireReader =
1077
- options.readerWorker && isFileDatabase ? yield* makeReader(options) : undefined;
1078
- const readerSemaphore = yield* Semaphore.make(1);
1081
+ // A reader that cannot start turns off the whole pool, so routing never picks a dead slot.
1082
+ const readerPool = { unavailable: false };
1083
+ const readers =
1084
+ options.readerWorker && isFileDatabase
1085
+ ? yield* Effect.forEach(Array.from({ length: READER_POOL_SIZE }), () =>
1086
+ Effect.map(
1087
+ Effect.all([makeReader(options, readerPool), Semaphore.make(1)]),
1088
+ ([acquire, lock]) => ({
1089
+ acquire,
1090
+ lock,
1091
+ claims: 0,
1092
+ }),
1093
+ ),
1094
+ )
1095
+ : [];
1096
1097
const writer = { name: "writer" as const, lock: semaphore, connection };
1098
let activeWriter: ConnectionOwner | undefined;
1082
- const route = Effect.withFiber((fiber) =>
1083
- acquireReader !== undefined && Context.get(fiber.context, ReadOnly)
1084
- ? Effect.map(acquireReader, (readerConnection) =>
1099
+ // Callers must run route uninterruptibly and pass `claimed` a finalizer that runs `release` once.
1100
+ const route = (claimed: (release: Effect.Effect<void>) => Effect.Effect<void>) =>
1101
+ Effect.withFiber((fiber) => {
1102
+ if (readers.length === 0 || readerPool.unavailable || !Context.get(fiber.context, ReadOnly)) {
1103
+ return Effect.succeed(writer);
1104
+ }
1105
+ // Least claimed wins and ties go to the lowest slot, so idle slots never start a worker.
1106
+ let slot = readers[0]!;
1107
+ for (const candidate of readers) if (candidate.claims < slot.claims) slot = candidate;
1108
+ slot.claims++;
1109
+ const reader = slot;
1110
+ return Effect.andThen(
1111
+ claimed(
1112
+ Effect.sync(() => {
1113
+ reader.claims--;
1114
+ }),
1115
+ ),
1116
+ Effect.map(reader.acquire, (readerConnection) =>
1117
readerConnection === undefined
1118
? writer
1087
- : { name: "reader" as const, lock: readerSemaphore, connection: readerConnection },
1088
- )
1089
- : Effect.succeed(writer),
1090
- );
1119
+ : { name: "reader" as const, lock: reader.lock, connection: readerConnection },
1120
+ ),
1121
+ );
1122
+ });
1123
1124
const acquired = (
1125
target: { readonly name: Acquired["connection"] },
@@ -1101,88 +1133,110 @@ const make = Effect.fn("makeWithDatabase")(function* (
1133
const writerBorrowBatchSize = 16;
1134
let writerBorrowsSinceYield = 0;
1135
const borrower: Borrower = (use) =>
1104
- Effect.flatMap(route, (target) =>
1105
- Effect.withFiber((fiber) => {
1106
- const clock = fiber.getRef(Clock.Clock);
1107
- const start = clock.monotonicTimeNanosUnsafe();
1108
- const ownerAtWaitStart = target.name === "writer" ? activeWriter : undefined;
1109
- const owner = target.name === "writer" ? connectionOwner(fiber) : undefined;
1110
- const useConnection = Effect.suspend(() => {
1111
- if (target.name === "writer") activeWriter = owner;
1112
- if (
1113
- fiber.getRef(References.TracerEnabled) &&
1114
- fiber.getRef(Statement.SpanPropagationEnabled)
1115
- ) {
1116
- annotateAcquired(fiber, acquired(target, clock, start), ownerAtWaitStart);
1117
- }
1118
- return use(target.connection);
1119
- });
1120
- const useOwnedConnection =
1121
- target.name === "writer"
1122
- ? Effect.onExit(useConnection, () =>
1123
- Effect.sync(() => {
1124
- if (activeWriter === owner) activeWriter = undefined;
1125
- }),
1126
- )
1127
- : useConnection;
1128
- if (!options.checkpointWorker || target.name !== "writer") {
1129
- return target.lock.withPermits(1)(useOwnedConnection);
1130
- }
1131
- const writerUse = Effect.onExit(useOwnedConnection, (exit) =>
1132
- Effect.sync(() => {
1133
- writerBorrowsSinceYield = Exit.hasInterrupts(exit)
1134
- ? 0
1135
- : Math.min(writerBorrowsSinceYield + 1, writerBorrowBatchSize);
1136
- }),
1137
- );
1138
- return Effect.flatMap(target.lock.withPermitsIfAvailable(1)(writerUse), (result) =>
1139
- Option.isSome(result)
1140
- ? Effect.succeed(result.value)
1141
- : target.lock.withPermits(1)(
1142
- Effect.andThen(
1143
- // Failed SQL also consumes the batch; cancellation hands off immediately.
1144
- Effect.suspend(() => {
1145
- if (writerBorrowsSinceYield < writerBorrowBatchSize) return Effect.void;
1146
- writerBorrowsSinceYield = 0;
1147
- return Effect.callback<void>((resume) => {
1148
- const immediate = setImmediate(() => resume(Effect.void));
1149
- return Effect.sync(() => clearImmediate(immediate));
1150
- });
1151
- }),
1152
- writerUse,
1153
- ),
1154
- ),
1155
- );
1156
- }),
1157
- );
1158
- const transactionAcquirer = Effect.flatMap(route, (target) =>
1136
Effect.uninterruptibleMask((restore) => {
1160
- const fiber = Fiber.getCurrent()!;
1161
- const scope = Context.getUnsafe(fiber.context, Scope.Scope);
1137
+ let release: Effect.Effect<void> = Effect.void;
1138
+ const claimed = (next: Effect.Effect<void>) =>
1139
+ Effect.sync(() => {
1140
+ release = next;
1141
+ });
1142
+ return Effect.flatMap(route(claimed), (target) => restore(borrowTarget(target, use))).pipe(
1143
+ Effect.ensuring(Effect.suspend(() => release)),
1144
+ );
1145
+ });
1146
+ const borrowTarget = <A, E, R>(
1147
+ target: {
1148
+ readonly name: Acquired["connection"];
1149
+ readonly lock: Semaphore.Semaphore;
1150
+ readonly connection: Connection;
1151
+ },
1152
+ use: (connection: Connection) => Effect.Effect<A, E, R>,
1153
+ ): Effect.Effect<A, E, R> =>
1154
+ Effect.withFiber((fiber) => {
1155
const clock = fiber.getRef(Clock.Clock);
1156
const start = clock.monotonicTimeNanosUnsafe();
1164
- const pending = fiber.getRef(TransactionAcquire);
1157
const ownerAtWaitStart = target.name === "writer" ? activeWriter : undefined;
1158
const owner = target.name === "writer" ? connectionOwner(fiber) : undefined;
1167
- const acquire = Effect.tap((pending?.restore ?? restore)(target.lock.take(1)), () => {
1159
+ const useConnection = Effect.suspend(() => {
1160
if (target.name === "writer") activeWriter = owner;
1169
- if (pending !== undefined) {
1170
- pending.acquired = acquired(target, clock, start);
1171
- pending.ownerAtWaitStart = ownerAtWaitStart;
1161
+ if (
1162
+ fiber.getRef(References.TracerEnabled) &&
1163
+ fiber.getRef(Statement.SpanPropagationEnabled)
1164
+ ) {
1165
+ annotateAcquired(fiber, acquired(target, clock, start), ownerAtWaitStart);
1166
}
1173
- return Scope.addFinalizer(
1174
- scope,
1175
- Effect.sync(() => {
1176
- if (target.name === "writer" && activeWriter === owner) activeWriter = undefined;
1177
- }).pipe(Effect.andThen(target.lock.release(1))),
1178
- );
1167
+ return use(target.connection);
1168
});
1180
- return Effect.as(
1181
- // A scheduler yield after taking the permit must not precede its release finalizer.
1182
- Effect.provideService(acquire, Scheduler.PreventSchedulerYield, true),
1183
- target.connection,
1169
+ const useOwnedConnection =
1170
+ target.name === "writer"
1171
+ ? Effect.onExit(useConnection, () =>
1172
+ Effect.sync(() => {
1173
+ if (activeWriter === owner) activeWriter = undefined;
1174
+ }),
1175
+ )
1176
+ : useConnection;
1177
+ if (!options.checkpointWorker || target.name !== "writer") {
1178
+ return target.lock.withPermits(1)(useOwnedConnection);
1179
+ }
1180
+ const writerUse = Effect.onExit(useOwnedConnection, (exit) =>
1181
+ Effect.sync(() => {
1182
+ writerBorrowsSinceYield = Exit.hasInterrupts(exit)
1183
+ ? 0
1184
+ : Math.min(writerBorrowsSinceYield + 1, writerBorrowBatchSize);
1185
+ }),
1186
);
1185
- }),
1187
+ return Effect.flatMap(target.lock.withPermitsIfAvailable(1)(writerUse), (result) =>
1188
+ Option.isSome(result)
1189
+ ? Effect.succeed(result.value)
1190
+ : target.lock.withPermits(1)(
1191
+ Effect.andThen(
1192
+ // Failed SQL also consumes the batch; cancellation hands off immediately.
1193
+ Effect.suspend(() => {
1194
+ if (writerBorrowsSinceYield < writerBorrowBatchSize) return Effect.void;
1195
+ writerBorrowsSinceYield = 0;
1196
+ return Effect.callback<void>((resume) => {
1197
+ const immediate = setImmediate(() => resume(Effect.void));
1198
+ return Effect.sync(() => clearImmediate(immediate));
1199
+ });
1200
+ }),
1201
+ writerUse,
1202
+ ),
1203
+ ),
1204
+ );
1205
+ });
1206
+ const claimedUntilScopeCloses = (release: Effect.Effect<void>) =>
1207
+ Effect.withFiber((fiber) =>
1208
+ Scope.addFinalizer(Context.getUnsafe(fiber.context, Scope.Scope), release),
1209
+ );
1210
+ const transactionAcquirer = Effect.uninterruptible(route(claimedUntilScopeCloses)).pipe(
1211
+ Effect.flatMap((target) =>
1212
+ Effect.uninterruptibleMask((restore) => {
1213
+ const fiber = Fiber.getCurrent()!;
1214
+ const scope = Context.getUnsafe(fiber.context, Scope.Scope);
1215
+ const clock = fiber.getRef(Clock.Clock);
1216
+ const start = clock.monotonicTimeNanosUnsafe();
1217
+ const pending = fiber.getRef(TransactionAcquire);
1218
+ const ownerAtWaitStart = target.name === "writer" ? activeWriter : undefined;
1219
+ const owner = target.name === "writer" ? connectionOwner(fiber) : undefined;
1220
+ const acquire = Effect.tap((pending?.restore ?? restore)(target.lock.take(1)), () => {
1221
+ if (target.name === "writer") activeWriter = owner;
1222
+ if (pending !== undefined) {
1223
+ pending.acquired = acquired(target, clock, start);
1224
+ pending.ownerAtWaitStart = ownerAtWaitStart;
1225
+ }
1226
+ return Scope.addFinalizer(
1227
+ scope,
1228
+ Effect.sync(() => {
1229
+ if (target.name === "writer" && activeWriter === owner) activeWriter = undefined;
1230
+ }).pipe(Effect.andThen(target.lock.release(1))),
1231
+ );
1232
+ });
1233
+ return Effect.as(
1234
+ // A scheduler yield after taking the permit must not precede its release finalizer.
1235
+ Effect.provideService(acquire, Scheduler.PreventSchedulerYield, true),
1236
+ target.connection,
1237
+ );
1238
+ }),
1239
+ ),
1240
);
1241
1242
const client = yield* Client.make({