@vibeorm/adapter-bun 1.1.4 → 1.1.5

package/README.md

@@ -35,14 +35,44 @@ const db = VibeClient({
 
 ```ts
 type BunAdapterOptions = {
-  url?: string;               // Connection string (defaults to DATABASE_URL env)
-  max?: number;               // Pool size (default: 20)
+  url?: string;                // Connection string (defaults to DATABASE_URL env)
+  max?: number;                // Pool size (default: 10)
+  statementTimeout?: number;   // Default query timeout in ms (default: none)
+  connectionTimeout?: number;  // Max time to establish a connection in ms (default: none)
   preparedStatements?: boolean; // Enable prepared statement caching (default: false)
-  stmtCacheMax?: number;      // Max cached prepared statements (default: 1000)
-  planCacheMode?: string;     // PostgreSQL plan_cache_mode (default: "force_custom_plan")
+  stmtCacheMax?: number;       // Max cached prepared statements (default: 1000)
+  planCacheMode?: string;      // PostgreSQL plan_cache_mode (default: "force_custom_plan")
 };
 ```
 
+### Statement timeout
+
+Set a default timeout for all queries. Any query exceeding this duration is cancelled by PostgreSQL (SQLSTATE `57014`), surfaced as a `VibeTransientError` with code `STATEMENT_TIMEOUT`.
+
+```ts
+const adapter = bunAdapter({
+  url: "postgres://...",
+  statementTimeout: 30000, // 30 seconds
+});
+```
+
+Injected as a PostgreSQL connection-level startup parameter (`-c statement_timeout=N`), so every query on every pooled connection inherits it automatically with zero per-query overhead.
+
+Transaction-level `timeout` (via `db.$transaction(fn, { timeout })`) overrides this default for that transaction using `SET LOCAL statement_timeout`.
+
+### Connection timeout
+
+Limit how long initial TCP connection establishment can take:
+
+```ts
+const adapter = bunAdapter({
+  url: "postgres://...",
+  connectionTimeout: 5000, // 5 seconds
+});
+```
+
+Injected as `connect_timeout` in the PostgreSQL connection URL (converted to seconds).
+
 ## License
 
 [MIT](../../LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibeorm/adapter-bun",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "description": "Bun-native database adapter for VibeORM using bun:sql",
   "license": "MIT",
   "keywords": [
@@ -33,7 +33,7 @@
     "bun": ">=1.1.0"
   },
   "dependencies": {
-    "@vibeorm/runtime": "1.1.4"
+    "@vibeorm/runtime": "1.1.5"
   },
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -13,6 +13,32 @@ export type BunAdapterOptions = {
   url?: string;
   /** Maximum number of connections in the pool (default: 10). */
   max?: number;
+  /**
+   * Default statement timeout in milliseconds for all queries (default: none).
+   *
+   * Sets PostgreSQL's `statement_timeout` as a connection-level startup parameter,
+   * so every query on every connection inherits it automatically with zero per-query
+   * overhead. Queries exceeding this duration are cancelled by PostgreSQL with
+   * SQLSTATE 57014, which VibeORM surfaces as a `VibeTransientError` with code
+   * `STATEMENT_TIMEOUT`.
+   *
+   * Transaction-level `timeout` (via `$transaction` options) overrides this default
+   * for the duration of that transaction using `SET LOCAL statement_timeout`.
+   *
+   * Recommended: Set to a value appropriate for your workload (e.g. 30000 for
+   * general use, 250–1000 for latency-sensitive OLTP services).
+   */
+  statementTimeout?: number;
+  /**
+   * Maximum time in milliseconds to wait for a connection from the pool (default: none).
+   *
+   * When set, connection acquisition that exceeds this duration will throw.
+   * Prevents indefinite blocking when the pool is exhausted under load.
+   *
+   * Injected as `connect_timeout` in the PostgreSQL connection URL. Note that
+   * bun:sql uses this for initial TCP connection establishment, not pool checkout.
+   */
+  connectionTimeout?: number;
   /**
    * Whether to use named prepared statements for read queries (default: false).
    *
@@ -123,19 +149,52 @@ export function bunAdapter(options?: BunAdapterOptions): DatabaseAdapter {
   }
 
   /**
-   * Resolve the connection URL, injecting plan_cache_mode if needed.
+   * Resolve the connection URL, injecting startup parameters as needed.
    * Falls back to DATABASE_URL env var when no explicit URL is provided.
+   *
+   * Injects via the PostgreSQL `options` startup parameter:
+   * - plan_cache_mode (unless "auto")
+   * - statement_timeout (if configured)
+   *
+   * Injects as a URL parameter:
+   * - connect_timeout (if configured, converted to seconds for PG)
    */
   function resolveConnectionUrl(): string | undefined {
-    if (PLAN_CACHE_MODE === "auto") return options?.url;
+    const STATEMENT_TIMEOUT = options?.statementTimeout;
+    const CONNECTION_TIMEOUT = options?.connectionTimeout;
+
+    // Build startup options string (for -c parameters)
+    const startupParts: string[] = [];
+    if (PLAN_CACHE_MODE !== "auto") {
+      startupParts.push(`-c plan_cache_mode=${PLAN_CACHE_MODE}`);
+    }
+    if (STATEMENT_TIMEOUT !== undefined) {
+      startupParts.push(`-c statement_timeout=${Number(STATEMENT_TIMEOUT)}`);
+    }
+
+    const needsUrlMutation = startupParts.length > 0 || CONNECTION_TIMEOUT !== undefined;
+    if (!needsUrlMutation) return options?.url;
 
     const baseUrl = options?.url ?? process.env.DATABASE_URL;
     if (!baseUrl) return undefined;
 
-    return appendStartupOption({
-      url: baseUrl,
-      option: `-c plan_cache_mode=${PLAN_CACHE_MODE}`,
-    });
+    let url = baseUrl;
+
+    // Inject startup options (-c params)
+    if (startupParts.length > 0) {
+      url = appendStartupOption({
+        url,
+        option: startupParts.join(" "),
+      });
+    }
+
+    // Inject connect_timeout as a URL parameter (PG uses seconds)
+    if (CONNECTION_TIMEOUT !== undefined) {
+      const separator = url.includes("?") ? "&" : "?";
+      url = `${url}${separator}connect_timeout=${Math.ceil(CONNECTION_TIMEOUT / 1000)}`;
+    }
+
+    return url;
   }
 
   function getSql(): SqlInstance {
@@ -159,12 +218,10 @@ export function bunAdapter(options?: BunAdapterOptions): DatabaseAdapter {
     const connectionUrl = resolveConnectionUrl();
     if (connectionUrl) {
       sqlInstance = new SQL(connectionUrl, sqlOptions) as unknown as SqlInstance;
-    } else if (options?.url) {
-      // URL provided but planCacheMode is "auto" — use URL as-is
-      sqlInstance = new SQL(options.url, sqlOptions) as unknown as SqlInstance;
     } else {
-      // No URL — bun:sql will use PG* env vars. plan_cache_mode cannot be
-      // injected via startup options in this case (would need SET on connect).
+      // No URL resolved — bun:sql will use PG* env vars.
+      // Startup parameters (plan_cache_mode, statement_timeout) cannot be
+      // injected via URL options in this case (would need SET on connect).
       sqlInstance = new SQL(sqlOptions) as unknown as SqlInstance;
     }