@vibeorm/adapter-bun 2.4.1 → 4.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VibeORM contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -16,8 +16,10 @@ bun add @vibeorm/adapter-bun
 import { VibeClient } from "./generated/vibeorm/index.js";
 import { bunAdapter } from "@vibeorm/adapter-bun";
 
-// url defaults to process.env.DATABASE_URL, then bun's PG* env vars
-const db = VibeClient({ adapter: bunAdapter({ url: process.env.DATABASE_URL, max: 10 }) });
+// The adapter reads no environment variable: pass the address you mean.
+const url = process.env.DATABASE_URL;
+if (!url) throw new Error("DATABASE_URL is not set");
+const db = VibeClient({ adapter: bunAdapter({ url, max: 10 }) });
 
 const users = await db.user.findMany({ where: { email: { contains: "@example.com" } }, take: 10 });
 
@@ -26,54 +28,70 @@ await db.$disconnect();
 
 ## Options
 
-`bunAdapter(options?: BunAdapterOptions)`:
+`bunAdapter(options: BunAdapterOptions)` — `url` is required. Without it, the factory throws `VIBE_CONFIG` (`meta.reason: "missing-address"`) before any driver instance or connection exists. The adapter never reads `DATABASE_URL` and always hands bun:sql this URL, so bun:sql's own `POSTGRES_URL` / `DATABASE_URL` / `PG*` lookup never chooses the server. A database named in the URL path is pinned explicitly, because bun:sql would otherwise let `PGDATABASE` replace it. Give a complete URL: bun:sql fills parts a URL leaves out (user, database, …) from the `PG*` variables.
 
 | Option | Type | Default | Meaning |
 |---|---|---|---|
-| `url` | `string` | `process.env.DATABASE_URL`, then bun's `PG*` env vars | PostgreSQL connection URL |
+| `url` | `string` | — (required) | PostgreSQL connection URL |
 | `max` | `number` | `10` | Maximum pooled connections |
 | `statementTimeout` | `number` (ms) | — | Pool-wide `statement_timeout`, sent as a startup parameter so every connection inherits it; a per-transaction `timeout` overrides it |
-| `connectionTimeout` | `number` (ms) | — | Wait for a connection to be established. bun:sql expects seconds; the adapter converts |
-| `preparedStatements` | `boolean` | `false` | Run ORM-path queries as tagged templates, creating named prepared statements. On node-postgres the same switch measured −17…−25 % on reads (`@vibeorm/adapter-pg` README, "Prepared statements: the measured trade"); off by default because named statements break behind transaction-mode poolers without prepared-statement support |
-| `stmtCacheMax` | `number` | `1000` | Maximum entries in the synthetic template cache (LRU) |
+| `connectionTimeout` | `number` (ms) | URL `connect_timeout`, else none | Wait for a connection to be established. bun:sql expects seconds; the adapter converts |
+| `preparedStatements` | `boolean` | `false` | Use bun:sql's **named** prepared statements and run ORM-path queries as tagged templates. Off, every statement is an unnamed statement with text results — the node-postgres model. Read "Statements and values" before you turn it on |
+| `stmtCacheMax` | `number` | `1000` | Maximum entries in the synthetic template cache (LRU); used only with `preparedStatements: true` |
 | `planCacheMode` | `"auto" \| "force_custom_plan" \| "force_generic_plan"` | `"force_custom_plan"` | PostgreSQL `plan_cache_mode` for every connection |
 
-`planCacheMode` and `statementTimeout` merge into one `options` startup parameter, with adapter settings taking precedence over matching URL settings. Other URL settings are preserved. With PG* environment variables and no URL, the adapter sends the same startup options through Bun's `connection` constructor option. Client-side libpq options such as `connect_timeout` must never go in the URL — bun:sql forwards unrecognised URL parameters to the server, which rejects them. (The same forwarding is how a server setting reaches every connection: `?jit=off` on the URL disables JIT compilation for the pool — see `docs/dialect-notes.md` "PostgreSQL JIT and statistics".)
+`planCacheMode` and `statementTimeout` merge into one `options` startup parameter, with adapter settings taking precedence over matching URL settings. Other URL settings are preserved. bun:sql forwards unrecognised URL parameters to the server, which rejects a client-side libpq option. The adapter therefore takes libpq's `connect_timeout` (whole seconds) out of the URL and uses it as `connectionTimeout`, so a URL written for node-postgres or `psql` connects here too; an explicit `connectionTimeout` option wins. Other client-side libpq options must not go in the URL. (The same forwarding is how a server setting reaches every connection: `?jit=off` on the URL disables JIT compilation for the pool — see `docs/dialect-notes.md` "PostgreSQL JIT and statistics".)
 
 `connectionTimeout` does **not** bound waiting for a busy pool connection. The adapter therefore declares `budgets.acquireTimeout: false`. Newer Bun versions support cancellable explicit reservations, but implicit query and transaction checkout does not expose the same guarantee across supported versions. There is no timer race that leaves an abandoned checkout running.
 
 `Date` parameters are spelled as UTC ISO text on both paths: bun:sql's own serializer for a `date`-typed parameter is `Date#toString()`, which the server rejects in every host time zone. Zone-less columns (`@db.Timestamp(n)`, `@db.Date`) therefore hold the UTC wall-clock on write — the contract shared with node-postgres, PGlite and Prisma. On read, bun:sql is UTC from **Bun 1.4.1**; earlier Bun versions parse zone-less timestamp text as host-local time (1.3.x: scalars on parameterless statements and every array element; 1.4.0: array elements), and bun:sql has no per-query parser hook the adapter could use to correct it. On Bun < 1.4.1 keep the process on `TZ=UTC` when the schema has zone-less columns, or upgrade (`docs/dialect-notes.md` "DateTime without time zone on postgres").
 
+## Statements and values
+
+By default the adapter runs bun:sql with `prepare: false`: every statement is an **unnamed** prepared statement, the server plans it from scratch, and results come back in PostgreSQL's text format. That is how node-postgres works, and it is what keeps the two postgres adapters interchangeable. Parameters are spelled the way node-postgres spells them: numbers, bigints and booleans as text, `Date` as UTC ISO text, plain objects as `JSON.stringify` text. bun:sql would otherwise bind a JS number as `int4` or `float8` and let the server cast from that type — `0.1` into an `int4` slot was stored as `0`, `0.30000000000000004` into `numeric` became `0.3`, and `WHERE "real_column" = 0.1` matched nothing. With text the server reads the literal as the slot's own type, exactly or with SQLSTATE `22P02`. `tests/node-postgres-parity.live.test.ts` pins each of these against a live server.
+
+`preparedStatements: true` switches bun:sql to **named** statements: one per SQL text per connection, pipelined, with results in the binary format for some types. On the repository benchmark (Bun 1.4.3, PostgreSQL 18, small scale, 27 scenarios, three interleaved rounds) the default mode, named mode and adapter-pg were within 3 % of each other (geometric mean of the median p50s); single rounds varied by up to 10 %, so there is no measured speed reason to turn named statements on where the database is local. Across a network, named mode saves round trips because Bun pipelines only named statements: transaction control (`BEGIN`, `SAVEPOINT`, a deadline bound) rides with the next read, and concurrent statements inside one transaction share a round trip (a one-read `$transaction` costs 2 round trips instead of 3; `tests/round-trip-wire.live.test.ts` pins both modes). Named mode also changes behaviour:
+
+- After DDL that changes a statement's result columns (`ALTER COLUMN … TYPE`, or `ADD COLUMN` under `SELECT *`), that statement fails with SQLSTATE `0A000` ("cached plan must not change result type") on every connection that prepared it, until the pool is replaced. Run migrations with the application stopped, or restart it after. node-postgres named statements behave the same way.
+- `int4[]` and `float4[]` values with a NULL element or more than one dimension are refused by bun:sql (`ERR_POSTGRES_NULLS_IN_ARRAY_NOT_SUPPORTED_YET`, `ERR_POSTGRES_MULTIDIMENSIONAL_ARRAY_NOT_SUPPORTED_YET`).
+- A string bound to a raw `::jsonb` slot is JSON-encoded again (see "Raw parameters").
+- A plain object bound to a raw slot that is not `json`/`jsonb` (for example `$1::text`) arrives as `[object Object]`; the default mode and node-postgres send its `JSON.stringify` text.
+
 ## Raw parameters
 
-Trusted parameterless SQL scripts remain supported. The raw result contains the final command's rows and affected-row count; preceding commands still execute once. Empty final DDL results remain empty. The first ORM query observes Bun's JSON wire format. A failed or unrecognized observation rejects that operation before its user statement is sent; a later call can probe again on a healthy connection.
+Trusted parameterless SQL scripts remain supported. The raw result contains the final command's rows and affected-row count; preceding commands still execute once. Empty final DDL results remain empty. The first ORM query observes Bun's JSON wire format, on the connection it already holds. A failed or unrecognized observation rejects that operation before its user statement is sent; a later call can probe again on a healthy connection.
+
+Raw parameters follow node-postgres: a JS **array** becomes a PostgreSQL array literal (for `= ANY($1)`), any other plain object is sent as `JSON.stringify` text, and a string is sent as text, so the server parses JSON text bound to a `::jsonb` slot. With `preparedStatements: true`, bun:sql types each parameter by the OID the server infers for its slot and JSON-encodes **whatever JavaScript value** is bound to a `json`/`jsonb` slot, so pre-encoded text becomes a JSON *string*. Measured on Bun 1.4.3 / PostgreSQL 18 (`tests/raw-jsonb.live.test.ts` here and in `@vibeorm/adapter-pg`):
 
-bun:sql types every parameter by the OID the server infers for its slot, and for a `json`/`jsonb` slot it JSON-encodes **whatever JavaScript value is bound** — an object becomes the document, and a string that already holds JSON text becomes a JSON *string* (double-encoded). node-postgres sends a string as text regardless of the slot, so the same raw statement stores the document there. Measured on Bun 1.4.3 / PostgreSQL 18 (`tests/raw-jsonb.live.test.ts` here and in `@vibeorm/adapter-pg`):
+| `$executeRaw` … `VALUES (${value}::jsonb)` | adapter-bun (default) | adapter-bun, `preparedStatements: true` | adapter-pg |
+|---|---|---|---|
+| `{ a: 1 }` (JS object) | `object` | `object` | `object` |
+| `'{"a":1}'` (pre-encoded text) | `object` | **`string`** | `object` |
+| `'{"a":1}'` through `${value}::text::jsonb` | `object` | `object` | `object` |
 
-| `$executeRaw` … `VALUES (${value}::jsonb)` | adapter-bun stores | adapter-pg stores |
-|---|---|---|
-| `{ a: 1 }` (JS object) | `object` | `object` |
-| `'{"a":1}'` (pre-encoded text) | **`string`** | `object` |
-| `'{"a":1}'` through `${value}::text::jsonb` | `object` | `object` |
+`::text::jsonb` is the spelling that is correct in every mode, and it is what the ORM path renders for every `Json` field (`jsonParamCast` in the postgres dialect). A JSON array bound into a json column from raw SQL needs `JSON.stringify` plus the `::text::jsonb` spelling, because a raw JS array is an array literal.
 
-Bind the object itself, or spell the slot `::text::jsonb` when you bind pre-encoded text — that is the portable form, and it is what the ORM path renders for every `Json` field (`jsonParamCast` in the postgres dialect), which is why `Json` columns behave identically on both adapters. A JS **array** on the raw path is rendered as a PostgreSQL array literal (for `= ANY($1)`), so a JSON array bound into a json column from raw SQL needs `JSON.stringify` plus the `::text::jsonb` spelling.
+Raw results are the driver's own values. bun:sql returns some types differently from node-postgres in raw queries: `uuid[]` and `citext[]` as the array-literal string (`"{…}"`), `interval`, `point` and `circle` as PostgreSQL's text (`"1 day 02:00:00"`, `"(1,2)"`; node-postgres returns objects), and `xid` as a number. The ORM path decodes list fields the same way on both adapters. One difference reaches the ORM path too: bun:sql reads a date or timestamp before year 1 (`BC`) as `Invalid Date`, where node-postgres returns the date.
 
 ## Session lifetime on `$disconnect()`
 
-`disconnect()` rolls back an open raw transaction, releases its reserved connection and closes the pool with bun:sql's `close()`, which waits for in-flight statements to finish. The promise resolves once the client sockets are shut; PostgreSQL removes the sessions from `pg_stat_activity` a few milliseconds later (0–5 ms measured on Bun 1.4.3, the same window node-postgres' `pool.end()` has). `tests/session-lifetime.live.test.ts` pins that every session the adapter can hold — pool, options-transaction connection, raw-transaction session — is gone after `disconnect()`, with a bounded poll.
+`disconnect()` ends the adapter for good: every later call refuses with `VIBE_ADAPTER_CLOSED`, and only a new adapter connects again. It first waits for admitted work (statements, whole transaction and `withSession` callbacks, whose private session pools close on their own), then rolls back an open raw transaction, releases its reserved connection and closes the pool with bun:sql's `close()`. The promise resolves once the client sockets are shut; PostgreSQL removes the sessions from `pg_stat_activity` a few milliseconds later (0–5 ms measured on Bun 1.4.3, the same window node-postgres' `pool.end()` has). `tests/session-lifetime.live.test.ts` pins that every session the adapter can hold — pool, options-transaction connection, raw-transaction session — is gone after `disconnect()`, with a bounded poll.
 
 Two things that are NOT the adapter's doing but look like a leak:
 
 - A `DROP DATABASE` issued from another connection in the same millisecond can still see a closing session and refuse with SQLSTATE 55006. Poll `pg_stat_activity` for your `application_name` first, or use `DROP DATABASE … WITH (FORCE)` (PostgreSQL 13+).
-- bun:sql never closes idle connections by default (`idleTimeout: 0`), whereas node-postgres reaps an idle client after 10 s. An adapter you never `disconnect()` therefore holds its sessions for the life of the process on bun:sql, where node-postgres would have quietly dropped them.
+- bun:sql never closes idle connections by default (`idleTimeout: 0`), whereas node-postgres reaps an idle client after 10 s. An adapter you never `disconnect()` therefore holds its sessions for the life of the process on bun:sql, where node-postgres would have quietly dropped them. The adapter does not offer bun:sql's `idleTimeout`: measured on Bun 1.4.1 and 1.4.3, it also closes a reserved connection and a connection inside a transaction that waits between two statements ("Idle timeout reached"), which node-postgres never does.
 
 ## Runtime support
 
 | Runtime | Supported |
 |---|---|
-| Bun ≥ 1.2 | yes |
+| Bun ≥ 1.4.1 | yes |
+| Bun < 1.4.1 | no — `bunAdapter()` throws `VIBE_CONFIG` |
 | Node | no — `bun:sql` is a Bun built-in |
 
+Older bun:sql releases have data bugs the adapter cannot work around: on 1.3.14 a `COPY … TO STDOUT` hangs the connection, timestamps without a time zone are read in host-local time, `±infinity` dates become `Invalid Date`, and named statements could deliver one query's rows to another (fixed in Bun 1.4). 1.4.1, 1.4.2 and 1.4.3 pass the same probes. The repository's CI runs on the minimum version.
+
 On Node, use [`@vibeorm/adapter-pg`](https://github.com/vibeorm/vibeorm/tree/master/packages/adapter-pg) instead; it speaks the same postgres dialect with the same semantics.
 
 ## Capabilities
@@ -82,16 +100,17 @@ This is a postgres-dialect adapter, so the full capability set is available: `RE
 
 ## Transactions
 
-A top-level `transaction()` without options uses `sql.begin()` and lets bun:sql drive `BEGIN`/`COMMIT`. With `isolationLevel`, `timeout` or `deadline` the adapter reserves one connection and issues the statements itself, because `begin()` takes no such options.
-
-Nested transactions become savepoints, chosen by probing the handle:
+Every top-level `transaction()`, with or without options, runs on a reserved connection (`sql.reserve()`). The adapter sends its control (`BEGIN`, `COMMIT`, `SAVEPOINT`, `RELEASE`, the deadline bound) itself, as extended-protocol statements.
 
-- Modern bun:sql exposes `savepoint(fn)` on the in-transaction handle, and the adapter uses it. `begin()` is never called inside a transaction — it throws there ("use savepoint() instead").
-- Reserved connections (and older bun:sql builds) expose no `savepoint` helper, so the adapter issues `SAVEPOINT` / `RELEASE SAVEPOINT` / `ROLLBACK TO SAVEPOINT` SQL by hand, with a name counter shared across the whole top-level transaction.
+Nested transactions become savepoints: the adapter issues `SAVEPOINT` / `RELEASE SAVEPOINT` / `ROLLBACK TO SAVEPOINT` SQL by hand on the reserved connection, with a name counter shared across the whole top-level transaction.
 
 Nested handles share the root budget and expire when their own callback finishes. Deadline-bearing statements are serialized on the connection, so each checks the remaining time after earlier work completes. Server-cancellation mode installs a fresh `statement_timeout` before each adapter statement and before COMMIT. This does not cancel JavaScript callbacks, network waits or pool acquisition. Trusted raw SQL can change server settings, and a multi-command script applies PostgreSQL's timeout separately to its commands; it is not a hard wall-clock limit for the whole script. Use individual adapter calls when the total deadline must be checked between commands.
 
-If native savepoint recovery cannot be confirmed, the whole transaction is poisoned. Catching that error cannot permit further statements or a successful root commit. A lost COMMIT reply or failed rollback reports `meta.outcome: "unknown"`; no query or transaction callback is replayed. A reserved connection whose root rollback fails is closed rather than returned to the pool.
+If native savepoint recovery cannot be confirmed, the whole transaction is poisoned. Catching that error cannot permit further statements or a successful root commit. A lost COMMIT reply throws `VIBE_TRANSACTION` with `meta.outcome: "unknown"`. So does a COMMIT on a connection that was already dead before it (for example a backend terminated while the callback was still running): bun:sql gives no signal that tells "refused before sending" from "lost in flight", so this adapter cannot report that case as not committed, where adapter-pg can. When the callback fails and the cleanup ROLLBACK fails too (for example the backend was terminated), COMMIT was never sent: the callback's own error is thrown, like node-postgres, the transaction is not committed, and `transactionOutcomeOf({ error })` from `@vibeorm/runtime` reports `{ commit: "not-committed", commitSent: false, rollback: "failed", connection: "discarded" }`; a later use of the handle reports `meta.outcome: "not-committed"`. A deadline that refuses COMMIT stays the deadline error in that case too. No query or transaction callback is replayed. A reserved connection whose root rollback fails is closed rather than returned to the pool. A COMMIT the server answers with an error (a deferred unique or foreign-key constraint, a serialization failure) is a definite rollback and throws that error's own code, for example `VIBE_UNIQUE_VIOLATION`, exactly like node-postgres.
+
+A statement with more than 65,535 parameters is refused by bun:sql before it reaches the server; node-postgres sends it and the server aborts the transaction. Inside a transaction the adapter treats that refusal as an abort too, so a callback that catches it cannot commit the transaction's other writes.
+
+Two transaction differences from adapter-pg remain by design: a nested-transaction handle used after its own callback has returned is refused here (`VIBE_TRANSACTION`, `reason: "expired"`), and `withSession` runs on a private one-connection pool, so session settings it changes never reach the shared pool.
 
 Raw transaction control (`BEGIN` / `COMMIT` / `ROLLBACK` through the raw path, as `@vibeorm/migrate` does) reserves one connection for the duration: bun:sql refuses transaction control through `sql.unsafe()` on a pooled instance (`ERR_POSTGRES_UNSAFE_TRANSACTION`). Concurrent raw transactions on a single adapter are unsupported.
 

package/dist/bun-version.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Refuse a Bun whose bun:sql the adapter does not support (see
+ * {@link MINIMUM_BUN_VERSION}), at construction — before any statement can
+ * meet one of that driver's known data bugs.
+ *
+ * @throws VibeError `VIBE_CONFIG`.
+ */
+export declare function refuseUnsupportedBun(params: {
+    version: string;
+}): void;
+//# sourceMappingURL=bun-version.d.ts.map

package/dist/config.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Oldest Bun whose bun:sql the adapter accepts. Older releases — measured on
+ * 1.3.14 with every adapter fix in place — hang after `COPY … TO STDOUT`,
+ * read zone-less timestamps as host-local time and turn ±infinity dates into
+ * `Invalid Date`; 1.4.1, 1.4.2 and 1.4.3 pass the same probes.
+ */
+export declare const MINIMUM_BUN_VERSION: string;
+/**
+ * PostgreSQL's limit on bound parameters in one statement (the Bind message
+ * carries a 16-bit count).
+ */
+export declare const MAX_BIND_PARAMETERS: number;
 /** Migration-only driver instance; never force-close the application's pool. */
 export declare const SESSION_CONNECTION: Readonly<{
     max: number;

package/dist/connection-url.d.ts

@@ -8,9 +8,10 @@
  *
  * v1 lesson (LEARNINGS.md): bun:sql forwards *unrecognised* URL parameters to
  * the server as runtime configuration, so a libpq client-side option such as
- * `connect_timeout` must never be put in the URL (PostgreSQL rejects it as an
- * unrecognised configuration parameter). Connection timeouts use bun:sql's
- * `connectionTimeout` constructor option instead.
+ * `connect_timeout` reaches PostgreSQL, which rejects it as an unrecognised
+ * configuration parameter (42704). A URL written for libpq or node-postgres
+ * still works here: {@link takeConnectTimeout} removes `connect_timeout` and
+ * hands its seconds to bun:sql's `connectionTimeout` constructor option.
  */
 /**
  * PostgreSQL plan-cache behaviour for the implicit prepared statements bun:sql
@@ -29,6 +30,20 @@ export declare function buildStartupOptions(params: {
     planCacheMode: PlanCacheMode;
     statementTimeout?: number;
 }): string | undefined;
+/**
+ * Remove libpq's client-side `connect_timeout` (whole seconds) from a URL and
+ * return its value, so the URL bun:sql forwards to the server no longer carries
+ * it. `0` or a negative value means "no limit" in libpq and yields
+ * `undefined`. A URL bun cannot parse is returned unchanged.
+ *
+ * @throws VibeError `VIBE_VALIDATION` when the value is not an integer.
+ */
+export declare function takeConnectTimeout(params: {
+    url: string;
+}): {
+    url: string;
+    seconds?: number;
+};
 /** Merge startup settings into one `options` key; adapter settings take precedence. */
 export declare function applyStartupOptions(params: {
     url: string;

package/dist/driver.d.ts

@@ -1,7 +1,11 @@
 import { SQL } from "bun";
-/** Internal constructor boundary; keeps the driver double out of the public adapter API. */
+/**
+ * Internal constructor boundary; keeps the driver double out of the public
+ * adapter API. Always the URL form: bun:sql's options-only form fills the
+ * whole connection from the environment.
+ */
 export declare function createBunSql(params: {
-    url?: string;
+    url: string;
     options: Record<string, unknown>;
 }): SQL;
 //# sourceMappingURL=driver.d.ts.map

package/dist/index.d.ts

@@ -10,8 +10,16 @@ import type { DatabaseAdapter } from "@vibeorm/runtime";
 import { type PlanCacheMode } from "./connection-url.ts";
 /** Options for {@link bunAdapter}. */
 export type BunAdapterOptions = {
-    /** PostgreSQL connection URL. Defaults to `process.env.DATABASE_URL`, then bun's `PG*` env vars. */
-    readonly url?: string;
+    /**
+     * PostgreSQL connection URL — required. The adapter never reads
+     * `DATABASE_URL` (or any other environment variable) itself, and always
+     * hands bun:sql this URL, so bun's own environment lookup (`POSTGRES_URL`,
+     * `DATABASE_URL`, `PGHOST`, …) never chooses the server. A database named in
+     * the URL path is pinned explicitly, because bun:sql would otherwise let
+     * `PGDATABASE` replace it. Give a complete URL: bun:sql fills parts the URL
+     * omits (user, database, …) from the `PG*` variables.
+     */
+    readonly url: string;
     /** Maximum pooled connections (default 10). */
     readonly max?: number;
     /**
@@ -22,15 +30,26 @@ export type BunAdapterOptions = {
     readonly statementTimeout?: number;
     /**
      * Milliseconds to wait for a connection to be established. Passed to bun:sql
-     * as `connectionTimeout` (which expects **seconds**; converted here).
+     * as `connectionTimeout` (which expects **seconds**; converted here). Wins
+     * over a libpq `connect_timeout` in the URL, which is otherwise honoured.
      */
     readonly connectionTimeout?: number;
     /**
-     * Execute ORM-path queries as tagged templates, creating named prepared
-     * statements (default false). Saves planning time but lets PostgreSQL fall
-     * back to a generic plan after ~5 executions — leave off unless profiling
-     * says otherwise. bun:sql's `prepare: false` constructor option is never set
-     * (it triggers a known bun:sql performance regression).
+     * Use bun:sql's NAMED prepared statements (default false).
+     *
+     * Off (the default) runs every statement as an unnamed statement with text
+     * results — bun:sql's `prepare: false`, the node-postgres model: values,
+     * parameter typing and DDL behaviour match `@vibeorm/adapter-pg`.
+     *
+     * On, bun:sql keeps one named statement per SQL text per connection,
+     * pipelines, and reads results in its binary format, with these driver
+     * consequences (README "Statements and values"): a statement whose result
+     * type a later DDL change alters fails with SQLSTATE 0A000 on that
+     * connection until the pool is replaced (node-postgres named statements
+     * behave the same); `int4[]`/`float4[]` values with NULL elements or more
+     * than one dimension are refused; a JSON text bound into a raw `::jsonb`
+     * slot is stored as a JSON string. ORM-path queries also run as tagged
+     * templates.
      */
     readonly preparedStatements?: boolean;
     /** Maximum entries in the synthetic template cache (default 1000, LRU). */
@@ -41,14 +60,17 @@ export type BunAdapterOptions = {
 /**
  * Create a VibeORM adapter backed by bun:sql.
  *
+ * Requires an explicit `url`; without one the factory throws `VIBE_CONFIG`
+ * before any driver instance or connection exists.
+ *
  * @example
  * ```ts
- * const adapter = bunAdapter({ url: process.env.DATABASE_URL, max: 10 });
+ * const adapter = bunAdapter({ url: "postgresql://app:secret@db.internal:5432/app", max: 10 });
  * await adapter.connect();
  * const rows = await adapter.execute({ text: 'SELECT * FROM "User" WHERE "id" = $1', values: [1] });
  * ```
  */
-export declare function bunAdapter(options?: BunAdapterOptions): DatabaseAdapter;
+export declare function bunAdapter(options: BunAdapterOptions): DatabaseAdapter;
 export { BUN_SQLSTATE_ERROR_CODES, BUN_SQLSTATE_REASONS, bunErrorSqlstate, mapBunDriverError, } from "./errors.ts";
 export { serializeParams, serializeParamsRaw, toPgArrayLiteral } from "./params.ts";
 export { applyStartupOptions, buildStartupOptions } from "./connection-url.ts";