Skip to content
VibORM
Esc
↑↓navigate↵open⌘Jpreview
On this page

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

Was this page helpful?