perf(database): make production query history opt-in

Author: chrisbbreuer

bench/routing/README.md

@@ -90,29 +90,34 @@ papered over. `post-validate` has the same shape: Elysia uses its `t` schema,
 Hono a hand-written check behind its own `validator()` seam, and both are
 cheaper than a compiled rule set.
 
-The fixture includes `query_logs` and its indexes, so stock Stacks query logging
-performs successful writes. Those writes are part of the database workload;
-the bare SQLite targets do not provide query logging. Accumulated logs are
-cleared before each repetition, outside warm-up and measurement, while the
-seeded read data stays unchanged. Results from the earlier fixture without
-`query_logs` measured failed logging writes and are not comparable.
+The fixture includes `query_logs` and its indexes, but persistent query history
+is disabled by default in production. This keeps the stock database scenario
+focused on the request and read path shared by every target. Request-scoped
+query tracking remains active for Stacks error diagnostics.
+
+Set `DB_QUERY_LOGGING_ENABLED=true` to include durable query history in the
+workload. The bare SQLite targets do not provide an equivalent logger, so treat
+that run as an observability-cost profile rather than a like-for-like database
+comparison. Accumulated logs are cleared before each repetition, outside
+warm-up and measurement, while the seeded read data stays unchanged.
 
 A former process-wide recursion guard could also skip legitimate queries while a
 log write was pending. Logging now suppresses only queries descended from its
 own write, with warm sequential and concurrent persistence checks. Database
 results from before that correction should be rerun because they may include
 less logging work.
 
-Before measuring a Stacks database scenario, the parity probe clears old logs
-and waits for a successful log of its benchmark SELECT. Disabled or failing
-query logging aborts the run instead of producing a faster, incomplete workload.
-This check runs outside warm-up and measurement.
+When persistent logging is explicitly enabled, the parity probe clears old logs
+and waits for a successful log of its benchmark SELECT. Failing query logging
+then aborts the run instead of producing a faster, incomplete workload. This
+check runs outside warm-up and measurement.
 
-With `oha` or `builtin`, each Stacks database load run also verifies that the successful
-persisted SELECT count matches the total warmup and measured request count. A
-count mismatch, request errors, or an empty measured load aborts the run. Counting
-happens after CPU sampling, outside the timed window. Raw warmup output and a
-`--persistence.json` sidecar record the request counts used by this check.
+With `oha` or `builtin` and persistent logging enabled, each Stacks database
+load run also verifies that the successful persisted SELECT count matches the
+total warmup and measured request count. A count mismatch, request errors, or
+an empty measured load aborts the run. Counting happens after CPU sampling,
+outside the timed window. Raw warmup output and a `--persistence.json` sidecar
+record the request counts used by this check.
 
 Other drivers do not guarantee that their response counts include every in-flight
 request at the deadline. Their sidecars explicitly mark aggregate persistence
@@ -139,7 +144,7 @@ equivalent guarantees or it says plainly which profile produced the number.
 
 The opt-in `stacks-wal-full` target measures a configured SQLite deployment:
 1000-page WAL checkpoints and `synchronous=FULL`, with the same security,
-validation, query logging, and cookie behavior as `stacks-warm`. It verifies
+validation, query-tracking, and cookie behavior as `stacks-warm`. It verifies
 both SQLite settings before listening. Run it explicitly:
 
 ```bash

bench/routing/report.ts

@@ -37,6 +37,7 @@ export interface RunMeta {
   warmupSeconds: number
   durationSeconds: number
   runs: number
+  persistentQueryLogging: boolean
   machine: {
     platform: string
     release: string
@@ -81,6 +82,7 @@ export function renderReport(input: ReportInput): string {
   lines.push(`| Load generator | \`${meta.driver}\`${meta.publishable ? '' : ' (direction-only)'} |`)
   lines.push(`| Connections | ${meta.connections} |`)
   lines.push(`| Window | ${meta.warmupSeconds}s warm-up discarded, ${meta.durationSeconds}s measured, ${meta.runs} run(s), median reported |`)
+  lines.push(`| Persistent query history | ${meta.persistentQueryLogging ? 'enabled (opt-in)' : 'disabled (production default)'} |`)
   lines.push(`| CPU | ${meta.machine.cpu} (${meta.machine.cores} cores) |`)
   lines.push(`| OS | ${meta.machine.platform} ${meta.machine.release} |`)
   lines.push(`| Bun | ${meta.machine.bun} |`)

bench/routing/run.ts

@@ -25,7 +25,7 @@ import { createFixture, resetFixtureLogs } from './fixture'
 import { measureLoad } from './measurement'
 import { verifyLoadPersistence } from './persistence'
 import { renderReport } from './report'
-import { assertParity, boot, FIXTURE, headersFor, PORT, REPO_ROOT, stop } from './runtime'
+import { assertParity, benchmarkQueryLoggingEnabled, boot, FIXTURE, headersFor, PORT, REPO_ROOT, stop } from './runtime'
 import { SCENARIOS } from './scenarios'
 import { readSourceState } from './source'
 import { DEFAULT_TARGETS, TARGETS } from './targets'
@@ -149,6 +149,7 @@ async function main(): Promise<void> {
     warmupSeconds: opts.warmupSeconds,
     durationSeconds: opts.durationSeconds,
     runs: opts.runs,
+    persistentQueryLogging: benchmarkQueryLoggingEnabled(),
     machine: {
       platform: platform(),
       release: release(),
@@ -199,7 +200,7 @@ async function main(): Promise<void> {
           writeFileSync(join(rawDir, `${target.id}--${scenario.id}--run${run}.txt`), result.raw)
           if (warmupResult)
             writeFileSync(join(rawDir, `${target.id}--${scenario.id}--run${run}--warmup.txt`), warmupResult.raw)
-          if (scenario.requiresDb && target.server === 'stacks.ts') {
+          if (benchmarkQueryLoggingEnabled() && scenario.requiresDb && target.server === 'stacks.ts') {
             // The fixture was cleared before warmup. Count both load windows,
             // after CPU sampling, so verification cannot inflate measured cost.
             const persistence = await verifyLoadPersistence(FIXTURE, driver, result, warmupResult)

bench/routing/runtime-version.test.ts

@@ -36,13 +36,15 @@ describe('benchmark runtime requirements', () => {
       meta: {
         startedAt: '2026-09-05T00:00:00Z', driver: 'oha', publishable: true,
         connections: 50, warmupSeconds: 1, durationSeconds: 3, runs: 1,
+        persistentQueryLogging: false,
         machine: { platform: 'darwin', release: 'test', cpu: 'test', cores: 1, bun: '1.3.14' },
         runtimeRequirement: { range: '1.4.1', matches: false },
       },
       scenarios: [], targets: [], measurements: [],
     })
     expect(report).toContain('| Bun | 1.3.14 |')
     expect(report).toContain('| Project Bun requirement | 1.4.1 (runtime mismatch) |')
+    expect(report).toContain('| Persistent query history | disabled (production default) |')
     expect(report).toContain('Runtime mismatch: Bun 1.3.14 does not satisfy package.json engines.bun (1.4.1).')
   })
 })

bench/routing/runtime.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'bun:test'
 import { join } from 'node:path'
-import { BENCH_ROOT, serverCommand, serverEnvironment } from './runtime'
+import { BENCH_ROOT, benchmarkQueryLoggingEnabled, serverCommand, serverEnvironment } from './runtime'
 import { DEFAULT_TARGETS, targetById } from './targets'
 
 describe('benchmark server isolation', () => {
@@ -26,6 +26,24 @@ describe('benchmark server isolation', () => {
     expect(env.BENCH_SCENARIO).toBe('static-json')
   })
 
+  it('treats persistent query logging as an explicit benchmark profile', () => {
+    const previous = process.env.DB_QUERY_LOGGING_ENABLED
+    try {
+      delete process.env.DB_QUERY_LOGGING_ENABLED
+      expect(benchmarkQueryLoggingEnabled()).toBe(false)
+      process.env.DB_QUERY_LOGGING_ENABLED = 'true'
+      expect(benchmarkQueryLoggingEnabled()).toBe(true)
+      process.env.DB_QUERY_LOGGING_ENABLED = '1'
+      expect(benchmarkQueryLoggingEnabled()).toBe(true)
+      process.env.DB_QUERY_LOGGING_ENABLED = 'false'
+      expect(benchmarkQueryLoggingEnabled()).toBe(false)
+    }
+    finally {
+      if (previous === undefined) delete process.env.DB_QUERY_LOGGING_ENABLED
+      else process.env.DB_QUERY_LOGGING_ENABLED = previous
+    }
+  })
+
   it('keeps tuned settings opt-in and prevents shell settings from changing stock profiles', () => {
     const keys = ['BENCH_MODE', 'BENCH_SQLITE_PROFILE', 'STACKS_SECURITY_HEADERS_DISABLE', 'BENCH_SCENARIO', 'DB_CONNECTION'] as const
     const previous = keys.map(key => process.env[key])

bench/routing/runtime.ts

@@ -14,6 +14,12 @@ export const TMP = join(BENCH_ROOT, '.tmp')
 export const FIXTURE = join(TMP, 'bench.sqlite')
 export const PORT = Number(process.env.BENCH_PORT ?? 39400)
 
+/** Persistent query history is opt-in for the production benchmark. */
+export function benchmarkQueryLoggingEnabled(): boolean {
+  const value = process.env.DB_QUERY_LOGGING_ENABLED?.toLowerCase()
+  return value === 'true' || value === '1'
+}
+
 export interface BootedServer {
   proc: ReturnType<typeof Bun.spawn>
   pid: number
@@ -129,7 +135,7 @@ export function headersFor(target: Target, scenario: Scenario): Record<string, s
 
 /** Require byte-identical successful responses before measuring a target. */
 export async function assertParity(target: Target, scenario: Scenario): Promise<void> {
-  const requiresQueryLog = target.server === 'stacks.ts' && scenario.requiresDb
+  const requiresQueryLog = benchmarkQueryLoggingEnabled() && target.server === 'stacks.ts' && scenario.requiresDb
   if (requiresQueryLog)
     resetFixtureLogs(FIXTURE)
 

config/database.ts

@@ -184,9 +184,12 @@ export default {
    */
   queryLogging: {
     /**
-     * Enable query logging to database
+     * Persist query diagnostics to the database. Development keeps the
+     * dashboard useful out of the box; production makes the write-heavy
+     * history an explicit opt-in. Request-scoped error diagnostics remain
+     * available in either mode.
      */
-    enabled: env.DB_QUERY_LOGGING_ENABLED ?? true,
+    enabled: env.DB_QUERY_LOGGING_ENABLED ?? !['production', 'prod'].includes(env.APP_ENV || ''),
 
     /**
      * Capture caller stacks for successful fast queries too. Slow and failed

docs/guide/query-monitoring.md

@@ -24,8 +24,8 @@ export default {
   // ... other database configs
 
   queryLogging: {
-    // Enable or disable query logging
-    enabled: true,
+    // Persistent history defaults on outside production and off in production
+    enabled: process.env.DB_QUERY_LOGGING_ENABLED === 'true',
 
     // Also capture caller stacks for successful fast queries
     captureAllTraces: false,
@@ -69,6 +69,12 @@ DB_QUERY_LOGGING_EXPLAIN_PLAN=true
 DB_QUERY_LOGGING_SUGGESTIONS=true
 ```
 
+Persistent query history is disabled by default in production because every
+application query otherwise creates an additional database write. Set
+`DB_QUERY_LOGGING_ENABLED=true` when durable history is worth that cost.
+Request-scoped query tracking for error diagnostics remains available when
+persistence is disabled.
+
 ## Dashboard Interface
 
 The query monitoring dashboard provides several views:

storage/framework/defaults/ai/skills/stacks-database/SKILL.md

@@ -258,7 +258,8 @@ Entity-centric API for single-table design:
   migrations: 'migrations',
   migrationLocks: 'migration_locks',
   queryLogging: {
-    enabled: true,
+    // Defaults on outside production and off in production.
+    enabled: env.DB_QUERY_LOGGING_ENABLED ?? !['production', 'prod'].includes(env.APP_ENV || ''),
     captureAllTraces: false, // slow and failed queries always keep traces
     slowThreshold: 100,  // ms
     retention: 7,        // days