Bun Native SQL

Overview

UQL supports Bun’s native SQL client (bun:sql) directly, so you can use Bun’s built-in drivers for PostgreSQL, MySQL, MariaDB, and SQLite with UQL’s unified API, without installing external driver packages.

Key Benefits

1. Native speed: Uses Bun’s built-in SQL implementations instead of pure-JS drivers.
2. Zero Dependencies: No need to install pg, mysql2, or better-sqlite3.
3. Unified Connection: Use a single BunSqlQuerierPool for all SQL dialects.
4. Adapter Mapping: UQL automatically configures Bun’s internal drivers to match your specified dialect, preventing silent protocol mismatches.

---

1. Installation

You only need uql-orm. Bun provides the SQL drivers built-in.

bun add uql-orm

---

2. Using Bun SQL

Import from uql-orm/bunSql and pass a Bun SQL.Options object (connection URL, adapter, SQLite filename, etc.). UQL infers the dialect from that shape.

import { BunSqlQuerierPool } from 'uql-orm/bunSql';
import { User } from './entities.js';

// the url may be postgres://, mysql://, sqlite://, or a file path; UQL infers the dialect
const pool = new BunSqlQuerierPool({ url: 'postgres://localhost:5432/app' });

const users = await pool.findMany(User, { $limit: 10 });

---

3. SQLite with Bun

For SQLite, use a sqlite: / file: URL, :memory:, or a filename option, whatever your Bun version accepts in SQL.Options.

const pool = new BunSqlQuerierPool({ url: 'sqlite://:memory:' });
// or: new BunSqlQuerierPool({ filename: ':memory:' })

---

4. Connection & Pooling Behaviors

Bun’s bun:sql treats different databases with distinct connection semantics. UQL’s BunSqlQuerierPool abstracts these details so you don’t have to worry about race conditions or driver-specific errors.

Automatic Reservation (Pooling)

For PostgreSQL and MySQL, Bun exposes a .reserve() method to obtain a dedicated connection from the pool.

• UQL’s Role: UQL identifies these as “Reserved Connections.” It automatically calls .reserve() and ensures .release() is called when the querier is released back to the pool.

Unpooled Persistence (SQLite)

Bun’s native SQLite driver does not support connection reservation and throws if you attempt to call .reserve().

• UQL’s Role: BunSqlQuerierPool identifies the SQLite dialect and transparently returns a singleton handle. It skips the reservation phase, allowing you to use the standard withQuerier or transaction wrappers without modification.

CockroachDB

Bun talks to CockroachDB through its PostgreSQL wire adapter.

• UQL’s Role: Use a Cockroach connection URL (or adapter: 'cockroachdb' in SQL.Options when Bun exposes it). UQL keeps the dialect id as cockroachdb for AST generation while normalizeBunOpts maps Bun’s adapter to postgres under the hood. Since Bun’s sql client treats the connection exactly like Postgres at the wire level, UQL uses BunSqlCockroachDialect, the same Bun-tuned parameter binding as BunSqlPostgresDialect below - without it, $merge/$push on a JSONB column would silently produce the wrong value or throw.

PostgreSQL dialect

For postgres:// / postgresql:// URLs, UQL uses BunSqlPostgresDialect, a Postgres AST tuned for Bun’s parameter binding (not the same as PgDialect for node pg). You do not configure this explicitly; the pool infers it from SQL.Options.

---

5. Why Bun SQL in UQL?

Bun’s sql client has a “silent fallback” where it defaults to PostgreSQL if an adapter isn’t explicitly provided or recognized. BunSqlQuerierPool in UQL eliminates this risk by:

• Enforcing adapter mapping: Normalizing SQL.Options per dialect (e.g. CockroachDB uses Bun’s postgres adapter while UQL still emits Cockroach-specific SQL).
• Dialect Guardrails: Ensuring your UQL code uses the correct SQL AST generator for the target database.
• Unified Result Mapping: Correctly handles Bun’s custom result objects, including affectedRows and lastInsertRowid, mapping them to UQL’s standard QueryUpdateResult.

---

Next Steps

Querying APILearn how to use the unified query API with Bun SQL.

TransactionsManage ACID transactions in Bun SQL.

AI & Vector SearchSet up PGVector and semantic search with Bun.