ReviewOS

stacks/bun-query-builder

perf: add a narrow SQL runtime entry

#1164
Closed chris opened this 8 days ago ·
8 days ago

Problem

The package root is the only server SQL entry, so applications that need createQueryBuilder, configuration, and connection lifecycle also evaluate migrations, generators, seeders, DynamoDB tooling, browser models, factories, and CLI actions.

On exact main commit 7cdd77f8faa83b8ce5908f43fb824efd6307918d with stable Bun 1.4.2, 30 alternating fresh-process measurements report:

  • root import median: 15.711 ms
  • settled root RSS median: 30,081,024 bytes
  • empty harness median: 0.002 ms and 12,500,992 bytes
  • built root graph: 688,614 bytes across seven generated JavaScript files

This cost is inherited by @stacksjs/database/runtime. In Stacks, the query-builder import accounts for roughly 15.74 ms of the database runtime entry's 20.20 ms median.

Proposed change

Add a supported bun-query-builder/runtime entry containing the SQL request-time surface: query construction, configuration, connection lifecycle, and SQLite bootstrap support. Keep migrations, schema tooling, seeders, DynamoDB, browser-only code, factories, and CLI actions on the package root or their existing dedicated entries.

The root entry remains API compatible. Consumers can opt into the runtime entry without importing generated chunk filenames or private paths.

Acceptance criteria

  • Export the SQL request-time API needed by framework database packages through bun-query-builder/runtime.
  • Preserve the root, browser, DynamoDB, and CLI entry behavior.
  • Add package export metadata and generated declarations for the runtime entry.
  • Add a fresh-process root/runtime benchmark with retained raw samples and exact source/runtime provenance.
  • Verify root/runtime SQL behavior parity against SQLite.
  • Measure import time, settled RSS, and reachable built graph on stable Bun 1.4.2.
  • Run the full test suite, lint, typecheck, build, CLI compile, and a fresh packed-consumer import check.

Baseline artifact

/Users/chris/.cache/codex-bench/stacks/database-runtime/bqb-main-root-30.json

8 days ago

Implemented and pushed to main in small commits:

  • Runtime entry and parity coverage: 4a7c5a3
  • Reproducible fresh-process diagnostic: 14e3599
  • Dialect-independent CI follow-up: b6df9d9, tracked in #1165

Result

Clean revision 14e35990d48f6bfbf5722c708220a1123ed2f8c2, Bun 1.4.2, macOS arm64, 30 alternating fresh-process pairs:

  • Import median: 15.7006 ms root to 11.5775 ms runtime, -26.26%
  • Paired import median: -4.0626 ms, runtime won 30/30
  • Settled RSS median: 34,603,008 bytes root to 32,120,832 bytes runtime, -7.17%
  • Paired RSS median: -2,564,096 bytes, runtime won 30/30
  • Reachable built graph: 7 files / 519,113 bytes root to 3 files / 268,514 bytes runtime, -48.27%
  • Source and built graph fingerprints were unchanged throughout the run.

Benchmark artifact SHA-256: ca3a35d47e4154c958e9c84104ef45c3e34a24a7fb5b3b63aa1cf4e7fc571e65.

Validation

  • Runtime exports, declarations, and both root/runtime compile probes pass.
  • SQLite root/runtime read-write parity, runtime-first shared state, cross-entry configuration, and connection reset coverage pass.
  • Exact Bun 1.4.2 local suite: 2,297 pass, 19 skip, 0 fail.
  • Type checking and changed-file pickier lint pass. Full lint has no errors.
  • Two independent package archives are byte-identical: 305,472 bytes, SHA-256 080b83fe844719ede95a2b6b0d4a7466d9ed6fec14d8af0b8b72d9161af71a2b.
  • A fresh packed consumer passes runtime-first SQL, root/runtime shared-state behavior, root/browser/dynamodb imports, declaration compilation, and the packaged CLI.
  • Independent standards and spec reviews report no findings.
  • CI on the final exact head is green, including live database tests and commit publication.

This adds the supported bun-query-builder/runtime surface without changing the existing root, browser, DynamoDB, or CLI entries. A stable npm release was not triggered.

Sign in to comment on this issue.