@vibeorm/adapter-pg 1.1.3 → 1.1.5

package/README.md

@@ -39,11 +39,13 @@ When you pass an existing pool, the adapter will **not** call `pool.end()` on di
 type PgAdapterOptions = {
   connectionString?: 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 acquire a connection in ms (default: none)
   preparedStatements?: boolean;  // Enable prepared statement caching (default: false)
   stmtCacheMax?: number;         // Max cached prepared statements (default: 1000)
 };
 
-// Or use an existing pool
+// Or use an existing pool (BYOP — you manage pool config)
 type PgAdapterOptions = {
   pool: PgPool;                  // Existing pg.Pool instance
   preparedStatements?: boolean;
@@ -51,6 +53,36 @@ type PgAdapterOptions = {
 };
 ```
 
+### 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 = pgAdapter({
+  connectionString: "postgres://...",
+  statementTimeout: 30000, // 30 seconds
+});
+```
+
+Passed as `statement_timeout` in the pg Pool config, so every 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`.
+
+> **Note:** `statementTimeout` and `connectionTimeout` are only available when creating a new pool. When you pass an existing `pool`, you manage these settings yourself via your pool config.
+
+### Connection timeout
+
+Limit how long pool checkout (acquiring a connection) can take:
+
+```ts
+const adapter = pgAdapter({
+  connectionString: "postgres://...",
+  connectionTimeout: 5000, // 5 seconds
+});
+```
+
+Mapped to pg Pool's `connectionTimeoutMillis` option. Throws when the pool is exhausted and no connection becomes available within the limit.
+
 ## License
 
 [MIT](../../LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibeorm/adapter-pg",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "node-postgres adapter for VibeORM — use VibeORM with pg on Bun or Node.js",
   "license": "MIT",
   "keywords": [
@@ -31,7 +31,7 @@
     "url": "https://github.com/vibeorm/vibeorm/issues"
   },
   "dependencies": {
-    "@vibeorm/runtime": "1.1.3"
+    "@vibeorm/runtime": "1.1.5"
   },
   "peerDependencies": {
     "pg": ">=8"

package/src/index.ts

@@ -16,6 +16,31 @@ export type PgAdapterOptions = {
   connectionString?: 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` at the pool level via the pg driver's
+   * `statement_timeout` option, so every query on every connection inherits it
+   * automatically. 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, pool checkout that exceeds this duration throws an error.
+   * Prevents indefinite blocking when the pool is exhausted under load.
+   *
+   * Maps to pg Pool's `connectionTimeoutMillis` option.
+   */
+  connectionTimeout?: number;
   /**
    * Whether to use named prepared statements for read queries (default: false).
    *
@@ -194,11 +219,27 @@ export function pgAdapter(options?: PgAdapterOptions): DatabaseAdapter {
         (options && "connectionString" in options ? options.connectionString : undefined) ??
         process.env.DATABASE_URL;
       const max = (options && "max" in options ? options.max : undefined) ?? 10;
+      const statementTimeout =
+        options && "statementTimeout" in options ? options.statementTimeout : undefined;
+      const connectionTimeout =
+        options && "connectionTimeout" in options ? options.connectionTimeout : undefined;
 
-      pool = new Pool({
+      const poolConfig: Record<string, unknown> = {
         connectionString,
         max,
-      }) as PgPool;
+      };
+
+      // Set statement_timeout at the pool level — every connection inherits it
+      if (statementTimeout !== undefined) {
+        poolConfig.statement_timeout = Number(statementTimeout);
+      }
+
+      // Set connectionTimeoutMillis — pool.connect() throws if exceeded
+      if (connectionTimeout !== undefined) {
+        poolConfig.connectionTimeoutMillis = Number(connectionTimeout);
+      }
+
+      pool = new Pool(poolConfig) as PgPool;
       ownsPool = true;
     }