---
title: Bun SQL
description: PostgreSQL driver using Bun's built-in SQL client
---

## Requirements

- Bun runtime

## Configuration

```typescript
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](/docs/extensions/permissions#providers) |

`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

```typescript
import { createClient } from "viborm/bun-sql";

const client = createClient({
  options: {
    hostname: "localhost",
    port: 5432,
    username: "postgres",
    password: "password",
    database: "mydb",
  },
  schema,
});
```

### With pgvector

```typescript
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`.

```typescript
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:

```sql
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](/docs/drivers/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](/docs/schema/scalars/point#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](/docs/client/transactions).

## Limitations

- Only available in Bun runtime
- API similar to postgres.js
