From 8e5593c64e50a88d102180d76ce3ccc2b33aa9f8 Mon Sep 17 00:00:00 2001
From: Theo Browne <me@t3.gg>
Date: Fri, 25 Sep 2026 14:02:55 -0700
Subject: [PATCH] fix(server): the SQLite WAL file shrinks back after large
 writes

PASSIVE auto-checkpoints copy frames back into the database but never
make the -wal file smaller. The file keeps its largest size until the
last connection closes, so one large write or a long foreign read
snapshot left a multi-GB file on disk.

Set journal_size_limit to 32 MiB in the shared setup. SQLite now cuts the
-wal file back to that size on the first commit after a WAL reset. Normal
use keeps the WAL near 4 MB, so this is a no-op there. No periodic
TRUNCATE checkpoint: on the synchronous connection with a 5 s busy handler
it would stall the event loop while another reader holds a snapshot.

The test writes past the limit through the real layer on a temp file and
checks the -wal size on disk after one more commit.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../src/persistence/Layers/Sqlite.test.ts     | 32 ++++++++++++++++++-
 apps/server/src/persistence/Layers/Sqlite.ts  |  6 ++++
 2 files changed, 37 insertions(+), 1 deletion(-)

diff --git a/apps/server/src/persistence/Layers/Sqlite.test.ts b/apps/server/src/persistence/Layers/Sqlite.test.ts
index 0b64e4f7fdcb..5bcbd35e918c 100644
--- a/apps/server/src/persistence/Layers/Sqlite.test.ts
+++ b/apps/server/src/persistence/Layers/Sqlite.test.ts
@@ -10,7 +10,11 @@ import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 
-import { SqlitePersistenceMemory, makeSqlitePersistenceLive } from "./Sqlite.ts";
+import {
+  SqlitePersistenceMemory,
+  WAL_SIZE_LIMIT_BYTES,
+  makeSqlitePersistenceLive,
+} from "./Sqlite.ts";
 
 const lockHolderSource = `
 const { DatabaseSync } = require("node:sqlite");
@@ -57,6 +61,32 @@ it.effect("waits out a concurrent writer instead of failing with SQLITE_BUSY", (
   );
 });
 
+it.effect("shrinks the WAL file back to the size limit after a large write", () => {
+  const tempDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-sqlite-wal-"));
+  const dbPath = NodePath.join(tempDir, "state.sqlite");
+  const walFileSize = () => NodeFS.statSync(`${dbPath}-wal`).size;
+  // About 25% more 4 KB rows than the limit holds, in one transaction.
+  const rowCount = Math.ceil((WAL_SIZE_LIMIT_BYTES * 1.25) / 4000);
+
+  return Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    yield* sql`CREATE TABLE wal_probe(payload BLOB)`;
+    yield* sql`
+      WITH RECURSIVE n(i) AS (SELECT 1 UNION ALL SELECT i + 1 FROM n WHERE i < ${rowCount})
+      INSERT INTO wal_probe(payload) SELECT randomblob(4000) FROM n
+    `;
+    assert.isAbove(walFileSize(), WAL_SIZE_LIMIT_BYTES);
+
+    // The auto-checkpoint after the large commit copied every frame into the
+    // database, so the next commit restarts the WAL and cuts the file back.
+    yield* sql`INSERT INTO wal_probe(payload) VALUES (x'00')`;
+    assert.isAtMost(walFileSize(), WAL_SIZE_LIMIT_BYTES);
+  }).pipe(
+    Effect.provide(makeSqlitePersistenceLive(dbPath).pipe(Layer.provide(NodeServices.layer))),
+    Effect.ensuring(Effect.sync(() => NodeFS.rmSync(tempDir, { recursive: true, force: true }))),
+  );
+});
+
 it.effect("applies busy_timeout in the shared persistence setup", () =>
   Effect.gen(function* () {
     const sql = yield* SqlClient.SqlClient;
diff --git a/apps/server/src/persistence/Layers/Sqlite.ts b/apps/server/src/persistence/Layers/Sqlite.ts
index 032b44645089..56536087d69c 100644
--- a/apps/server/src/persistence/Layers/Sqlite.ts
+++ b/apps/server/src/persistence/Layers/Sqlite.ts
@@ -8,6 +8,9 @@ import * as NodeSqliteClient from "@t3tools/shared/nodeSqliteClient";
 import { runMigrations } from "../Migrations.ts";
 import { ServerConfig } from "../../config.ts";
 
+// Size the -wal file is cut back to on the first commit after a WAL reset.
+export const WAL_SIZE_LIMIT_BYTES = 32 * 1024 * 1024;
+
 const setup = Layer.effectDiscard(
   Effect.gen(function* () {
     const sql = yield* SqlClient.SqlClient;
@@ -15,6 +18,9 @@ const setup = Layer.effectDiscard(
     yield* sql`PRAGMA busy_timeout = 5000;`;
     yield* sql`PRAGMA foreign_keys = ON;`;
     yield* sql`PRAGMA journal_mode = WAL;`;
+    // PASSIVE checkpoints never shrink the -wal file, so it otherwise keeps its
+    // largest size until the last connection closes.
+    yield* sql.unsafe(`PRAGMA journal_size_limit = ${WAL_SIZE_LIMIT_BYTES};`);
     yield* runMigrations();
   }),
 );