fix(query-builder): honor configured SQLite pragmas

Author: chrisbbreuer

docs/packages/query-builder.md

@@ -47,3 +47,21 @@ const count = await db.selectFrom('users').count()
 ```
 
 Configure dialects, timestamps, pagination, relation limits, transaction retries, SQL features, and soft deletes in `config/query-builder.ts`. SQLite is the default dialect. The database proxy initializes the query builder lazily on first use.
+
+## SQLite write throughput
+
+Stacks defaults to a WAL checkpoint threshold of one page. Applications with frequent writes can choose a larger threshold through `sqlite.pragmas` in `config/query-builder.ts`:
+
+```ts
+// Add this block to the existing query-builder configuration.
+sqlite: {
+  pragmas: [
+    'PRAGMA wal_autocheckpoint = 1000',
+    'PRAGMA synchronous = FULL',
+  ],
+},
+```
+
+Application pragmas run after the framework defaults on both the query-builder connection and the model writer. This example keeps foreign-key enforcement and the busy timeout, reduces checkpoint frequency, and requests full commit synchronization. The one-page default remains in effect when no checkpoint override is configured. See SQLite's [checkpoint threshold](https://www.sqlite.org/pragma.html#pragma_wal_autocheckpoint) and [synchronization modes](https://www.sqlite.org/pragma.html#pragma_synchronous) for the performance and durability tradeoffs.
+
+Committed rows may remain in the WAL sidecar longer with a larger threshold. Use `buddy db:backup`, which creates a consistent SQLite snapshot, instead of copying only the main database file. Measure the chosen settings on the deployment's storage, and label tuned benchmark results separately from stock defaults.

storage/framework/core/query-builder/src/index.ts

@@ -122,10 +122,16 @@ export const SQLITE_BOOTSTRAP_PRAGMAS = [
   // sidecar indefinitely — invisible to anything that reads only the main
   // file: remote SQLite browsing (e.g. TablePlus over SSH downloads just the
   // db file), file-level backups, and snapshot scripts. Low-write apps pay
-  // effectively nothing; a high-write deployment can raise this back up.
+  // effectively nothing; a high-write deployment can raise this through
+  // `sqlite.pragmas` in its query-builder configuration.
   'PRAGMA wal_autocheckpoint = 1',
 ] as const
 
+/** Application pragmas override the framework defaults in declaration order. */
+function sqliteBootstrapPragmas(): readonly string[] {
+  return [...SQLITE_BOOTSTRAP_PRAGMAS, ...(bunQbConfig.sqlite?.pragmas ?? [])]
+}
+
 type UnsafeReturn<TResult = unknown> = Promise<TResult> & { execute: () => Promise<TResult> }
 type SqlitePragmaExecutor = {
   unsafe: (query: string, params?: readonly unknown[]) => UnsafeReturn
@@ -142,7 +148,7 @@ type SqlitePragmaExecutor = {
  * preserve it themselves.
  */
 export function applySqlitePragmas(instance: SqlitePragmaExecutor): void {
-  for (const pragma of SQLITE_BOOTSTRAP_PRAGMAS) {
+  for (const pragma of sqliteBootstrapPragmas()) {
     try {
       // bun:sqlite executes synchronously inside `.execute()` (the returned
       // promise is created already settled), so every pragma is in effect
@@ -159,11 +165,11 @@ export function applySqlitePragmas(instance: SqlitePragmaExecutor): void {
 
 /**
  * Raw `bun:sqlite` `Database` handles that have already been bootstrapped.
- * The model executor caches its Database per configure/config-signature, so
- * a WeakSet keeps re-assertion calls (every wrapped `createQueryBuilder`)
- * from re-running the pragmas on an already-bootstrapped connection.
+ * The model executor can keep its Database when only pragmas change. Remember
+ * the applied list so repeated bootstrap calls stay cheap, while a changed
+ * configuration is applied to the existing connection too.
  */
-const bootstrappedRawDbs = new WeakSet<object>()
+const bootstrappedRawDbs = new WeakMap<object, string>()
 
 /**
  * Bootstrap the MODEL-EXECUTOR connection — the raw `bun:sqlite` `Database`
@@ -176,24 +182,28 @@ const bootstrappedRawDbs = new WeakSet<object>()
  * `getDatabase()` returns the executor's live handle for the sqlite dialect
  * (creating the executor if needed) and throws for mysql/postgres — where
  * there is nothing to bootstrap, hence the silent catch. Safe to call
- * repeatedly: the WeakSet makes it a no-op after the first hit per
- * connection, and a config change that swaps the executor's Database
- * produces a fresh (unseen) handle that gets bootstrapped on the next call.
+ * repeatedly: the WeakMap makes it a no-op while the connection and pragma
+ * list remain unchanged. A new handle or changed list is bootstrapped on
+ * the next call.
  */
 export function bootstrapModelExecutorPragmas(): void {
   try {
     const raw = (bunQueryBuilder as { getDatabase?: () => { run: (sql: string) => unknown } }).getDatabase?.()
-    if (!raw || typeof raw.run !== 'function' || bootstrappedRawDbs.has(raw))
+    if (!raw || typeof raw.run !== 'function')
+      return
+    const pragmas = sqliteBootstrapPragmas()
+    const signature = JSON.stringify(pragmas)
+    if (bootstrappedRawDbs.get(raw) === signature)
       return
-    for (const pragma of SQLITE_BOOTSTRAP_PRAGMAS) {
+    for (const pragma of pragmas) {
       try {
         raw.run(pragma)
       }
       catch {
         // Fail open per-pragma — same rationale as `applySqlitePragmas`.
       }
     }
-    bootstrappedRawDbs.add(raw)
+    bootstrappedRawDbs.set(raw, signature)
   }
   catch {
     // Non-sqlite dialect (`getDatabase()` throws) — nothing to bootstrap.

storage/framework/core/query-builder/tests/fixtures/sqlite-pragma-overrides.ts

@@ -0,0 +1,32 @@
+import { configureOrm, createQueryBuilder, getDatabase, releaseOrm, resetConnection, setConfig } from '../../src'
+
+setConfig({ dialect: 'sqlite', database: { database: ':memory:' } })
+
+async function observe() {
+  const builder = createQueryBuilder()
+  const raw = getDatabase()
+  return {
+    builder: await builder.unsafe('PRAGMA wal_autocheckpoint').execute(),
+    model: raw.query('PRAGMA wal_autocheckpoint').get(),
+    builderForeignKeys: await builder.unsafe('PRAGMA foreign_keys').execute(),
+    modelForeignKeys: raw.query('PRAGMA foreign_keys').get(),
+  }
+}
+
+try {
+  configureOrm({ database: ':memory:' })
+  const defaults = await observe()
+  setConfig({ sqlite: { pragmas: ['PRAGMA wal_autocheckpoint = 1000'] } })
+  const configured = await observe()
+  configureOrm({ database: ':memory:' })
+  const reconnected = await observe()
+  setConfig({ sqlite: { pragmas: ['PRAGMA wal_autocheckpoint = 2000'] } })
+  const changed = await observe()
+  setConfig({ sqlite: { pragmas: [] } })
+  const restored = await observe()
+  console.log(JSON.stringify({ defaults, configured, reconnected, changed, restored }))
+}
+finally {
+  releaseOrm()
+  resetConnection()
+}

storage/framework/core/query-builder/tests/sqlite-pragma-overrides.test.ts

@@ -0,0 +1,26 @@
+import { expect, test } from 'bun:test'
+import { join } from 'node:path'
+
+test('configured SQLite checkpoint thresholds reach both writers and survive reconnects', async () => {
+  const child = Bun.spawn([process.execPath, join(import.meta.dir, 'fixtures/sqlite-pragma-overrides.ts')], {
+    cwd: join(import.meta.dir, '..'),
+    env: { ...process.env, APP_ENV: 'test', DB_CONNECTION: 'sqlite', DB_DATABASE_PATH: ':memory:' },
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  const [code, stdout, stderr] = await Promise.all([
+    child.exited,
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+  ])
+  expect(code, stderr).toBe(0)
+  const observations = JSON.parse(stdout.trim().split('\n').at(-1)!)
+  for (const [name, threshold] of Object.entries({ defaults: 1, configured: 1000, reconnected: 1000, changed: 2000, restored: 1 })) {
+    expect(observations[name], name).toEqual({
+      builder: [{ wal_autocheckpoint: threshold }],
+      model: { wal_autocheckpoint: threshold },
+      builderForeignKeys: [{ foreign_keys: 1 }],
+      modelForeignKeys: { foreign_keys: 1 },
+    })
+  }
+})