Investigate drizzle-orm/bun-sql

[evantahler]

drizzle from drizzle-orm/node-postgres instead of drizzle-orm/bun-sql

What are the pros/cons?

[evantahler]

Research: drizzle-orm/bun-sql vs drizzle-orm/node-postgres

Current Setup

Keryx uses drizzle-orm/node-postgres with a pg Pool (packages/keryx/initializers/db.ts). The pg and @types/pg packages are direct dependencies. We expose api.db.pool (the raw pg.Pool) and api.db.db (the drizzle instance) on the API singleton. Pool config (max, min, idle timeout, connect timeout, allowExitOnIdle) is managed through config/database.ts with env var overrides.

---

Pros of switching to drizzle-orm/bun-sql

• Performance: Bun.sql uses native C/Zig bindings with the PostgreSQL binary wire protocol. Should be meaningfully faster than node-postgres (which is pure JS and uses the text protocol by default). Bun's blog claims significant throughput improvements.
• Zero extra dependencies: Bun.sql is built into the Bun runtime — switching would let us drop pg and @types/pg from package.json. Fewer deps = smaller install, fewer supply chain concerns, fewer version conflicts for users.
• Leaner on Bun identity: Keryx is a Bun-first framework. Using Bun's native SQL client reinforces that positioning and reduces the Node.js compatibility surface we depend on.
• Built-in features: Connection pooling, transactions, prepared statements, TLS, BigInt support, and SASL auth are all built in — no need for separate pool configuration libraries.
• Connection string compatible: Bun.sql reads DATABASE_URL env vars and accepts postgres:// connection strings, so the config surface stays the same for users.

Cons / Risks of switching

• Adapter maturity: The drizzle-orm/bun-sql adapter is relatively new (4 files: driver, index, migrator, session). There are open bugs on the drizzle-orm tracker:
  • Timestamp precision: Millisecond truncation (#5062) and timezone handling issues (#5090)
  • JSONB handling: Fields returned as strings instead of parsed JSON (#5287, fix in PR #5364)
  • Silent exits: Standalone scripts exit with code 0 instead of completing (#5451)
  • Promise chain bugs: Unawaited promises in queryWithCache (#5465)
• Breaking change to api.db.pool: We currently expose a pg.Pool instance. Bun.sql returns a SQL instance with a different API. Users who access api.db.pool directly (e.g., for raw queries, health checks, or custom pool management) would break. This is a public API change.
• Pool config differences: pg.Pool has fine-grained options (min, max, idleTimeoutMillis, connectionTimeoutMillis, allowExitOnIdle). Bun.sql has pooling built in but the configuration surface is different — we'd need to audit which knobs are still available and update config/database.ts.
• Bun version floor: Bun.sql was introduced in Bun 1.2 (Jan 2025). This would set a minimum Bun version requirement for Keryx. Current Bun is 1.3.10, so this is likely fine in practice, but worth documenting.
• drizzle-kit compatibility: Migration generation uses drizzle-kit which currently works with the node-postgres dialect. Need to verify the bun-sql adapter works with the same dialect: "postgresql" config for drizzle-kit generate.
• Ecosystem maturity: node-postgres has been battle-tested for 10+ years with extensive community support, edge-case handling, and documentation. Bun.sql is ~14 months old.

Recommendation

The switch aligns well with Keryx's Bun-first identity and would reduce dependencies. However, the open bugs around timestamps, JSONB, and promise handling are concerning for a framework that needs to be reliable for its users.

Suggested approach: Wait for the timestamp and JSONB fixes to land in a stable drizzle-orm release, then make the switch. When we do:

1. Replace pg.Pool with Bun.sql connection in db.ts
2. Update api.db.pool → api.db.client (or similar) with the new type
3. Audit pool config options and update config/database.ts
4. Run the full test suite to catch any behavioral differences
5. Bump minor version (breaking change to api.db public API)

[evantahler]

Update: Issue status check (2026-03-17)

Verified all referenced drizzle-orm/bun-sql issues — all 5 are still open as of today:

Issue	Status	Description
#5062	🟡 Open	Timestamp millisecond truncation with Bun driver
#5090	🟡 Open	withTimeZone: true returns incorrect date string
#5287	🟡 Open	JSONB fields inserted/updated as strings
#5451	🟡 Open	bun-sql adapter silently exits with code 0 in standalone scripts
#5465	🟡 Open	Unawaited promise chains in queryWithCache and bun-sql execute

Fix PRs #5364 (JSONB) and #5465 (promises) are also still open/unmerged.

Recommendation stands: wait for at least the timestamp (#5062/#5090) and JSONB (#5287) fixes to land before switching.