Bun SQL
PostgreSQL driver using Bun's built-in SQL client
Requirements
- Bun runtime
Configuration
import { createClient } from "viborm/bun-sql";
const client = createClient({
databaseUrl: process.env.DATABASE_URL,
schema,
});
Options
| Option | Type | Description |
|---|---|---|
client |
SQL |
Existing Bun SQL client |
databaseUrl |
string |
PostgreSQL connection URL |
namespace |
string |
PostgreSQL schema for VibORM-owned objects (default public) |
options |
object |
Connection options |
pgvector |
boolean |
Enable pgvector support |
postgis |
boolean |
Enable PostGIS support |
sharedRelationBodies |
boolean |
State each relation-filter body a statement repeats once, in a WITH (default true; false keeps the bodies inline) |
relationsPerStatement |
number |
The most relations (FROM items) one statement may reference (PlanetScale Neki: 256); a statement over it is rewritten to fit. See Neki |
createClient refuses any other key with a ClientInitializationError that
names it.
Options Object
| Option | Type | Description |
|---|---|---|
hostname |
string |
Database host |
port |
number |
Database port |
username |
string |
Database user |
password |
string |
Database password |
database |
string |
Database name |
tls |
boolean | object |
TLS configuration |
max |
number |
Maximum connections |
idleTimeout |
number |
Idle connection timeout |
maxLifetime |
number |
Maximum connection lifetime |
Using Options
import { createClient } from "viborm/bun-sql";
const client = createClient({
options: {
hostname: "localhost",
port: 5432,
username: "postgres",
password: "password",
database: "mydb",
},
schema,
});
With pgvector
import { createClient } from "viborm/bun-sql";
const client = createClient({
databaseUrl: process.env.DATABASE_URL,
pgvector: true,
schema,
});
Namespace
namespace selects the PostgreSQL schema holding this driver’s tables,
junctions, indexes, ORM-managed enums, and migration tracking table. Omitted, it
is public.
import { createClient } from "viborm/bun-sql";
const db = createClient({
databaseUrl: process.env.DATABASE_URL,
namespace: "billing",
schema,
});
Generated SQL is always qualified, so routing never depends on search_path,
and the database connection option keeps its ordinary meaning — it selects the
PostgreSQL database, while namespace selects the schema inside it:
SELECT "user"."id" FROM "billing"."user" AS "user"
Bun SQL can reserve a session, so it supports the full migration verb set
against the selected schema. Raw SQL is never rewritten and keeps ordinary
search_path semantics — see Namespaces.
GeoPoint
Bun SQL exposes the PostgreSQL GeoPoint vocabulary with postgis: true, but it
enters the full tier only after a real Bun/PostGIS provider contract proves the
functions, rows, and migrations. The Node test estate cannot qualify Bun’s
runtime. See GeoPoint provider tiers.
Prepared statements
Bun SQL prepares every statement that has values by default (its own prepare
option, true unless you set it), the ones VibORM writes included: each
connection parses a statement once and keeps it while it lives, with no bound
on how many. Verified with Bun 1.4.4. VibORM’s namedStatements option does not
apply here; Bun decides. A call’s named option is accepted and does nothing:
Bun’s unsafe() takes no per-statement prepare, so even named: false is
prepared when the client prepares. Behind PgBouncer in transaction mode, set
PgBouncer’s max_prepared_statements, or pass options: { prepare: false } to
send every statement unprepared.
Transactions
Bun SQL supports full transactions with savepoints for nested transactions — see Transactions.
Limitations
- Only available in Bun runtime
- API similar to postgres.js