@agentuity/postgres 1.0.15 → 1.0.17

package/src/client.ts

@@ -1,5 +1,11 @@
 import { SQL as BunSQL, type SQLQuery, type SQL } from 'bun';
-import type { PostgresConfig, ConnectionStats, TransactionOptions, ReserveOptions } from './types';
+import type {
+	PostgresConfig,
+	ConnectionStats,
+	TransactionOptions,
+	ReserveOptions,
+	UnsafeQueryResult,
+} from './types';
 import {
 	ConnectionClosedError,
 	PostgresError,
@@ -12,6 +18,73 @@ import { computeBackoff, sleep, mergeReconnectConfig } from './reconnect';
 import { Transaction, ReservedConnection } from './transaction';
 import { registerClient, unregisterClient } from './registry';
 import { injectSslMode } from './tls';
+import { isMutationStatement } from './mutation';
+
+/**
+ * Creates a lazy thenable with format locking for safe query execution.
+ *
+ * The returned object implements the {@link UnsafeQueryResult} interface: it is
+ * thenable (`.then()`, `.catch()`, `.finally()`) and exposes a `.values()`
+ * method for array-format results. Execution is deferred until the first
+ * consumption method is called.
+ *
+ * **Format locking:** The first access (`.then()` or `.values()`) determines
+ * the result format for the lifetime of the thenable. Attempting the other
+ * format afterwards throws an error, preventing accidental duplicate execution.
+ *
+ * @param makeExecutor - Factory that creates the execution promise.
+ *   Called with `true` for array format (`.values()`) or `false` for row-object
+ *   format (`.then()`).
+ * @returns A lazy thenable with `.values()` support
+ *
+ * @internal Exported for use by `@agentuity/drizzle` — not part of the public API.
+ */
+export function createThenable(
+	makeExecutor: (useValues: boolean) => Promise<unknown>
+): UnsafeQueryResult {
+	let started: Promise<unknown> | null = null;
+	let executionMode: boolean | null = null; // tracks useValues for first call
+
+	const startExecution = (useValues: boolean): Promise<unknown> => {
+		if (started) {
+			if (executionMode !== useValues) {
+				throw new Error(
+					`Cannot access .${useValues ? 'values()' : 'then()'} after .${!useValues ? 'values()' : 'then()'} ` +
+						'on the same query result. The result format is locked to the first access mode ' +
+						'to prevent duplicate query execution. Create a new unsafeQuery() call for a different format.'
+				);
+			}
+			return started;
+		}
+		executionMode = useValues;
+		started = makeExecutor(useValues);
+		return started;
+	};
+
+	return new Proxy({} as UnsafeQueryResult, {
+		get(_target, prop) {
+			if (prop === 'then') {
+				return <TResult1 = unknown, TResult2 = never>(
+					onfulfilled?: ((value: unknown) => TResult1 | PromiseLike<TResult1>) | null,
+					onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null
+				): Promise<TResult1 | TResult2> => startExecution(false).then(onfulfilled, onrejected);
+			}
+			if (prop === 'catch') {
+				return <TResult = never>(
+					onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null
+				): Promise<unknown | TResult> => startExecution(false).catch(onrejected);
+			}
+			if (prop === 'finally') {
+				return (onfinally?: (() => void) | null): Promise<unknown> =>
+					startExecution(false).finally(onfinally ?? undefined);
+			}
+			if (prop === 'values') {
+				return () => startExecution(true);
+			}
+			return undefined;
+		},
+	});
+}
 
 /**
  * Bun SQL options for PostgreSQL connections.
@@ -149,8 +222,23 @@ export class PostgresClient {
 	 * ```
 	 */
 	query(strings: TemplateStringsArray, ...values: unknown[]): Promise<unknown[]> {
+		// Reconstruct query shape for mutation detection.
+		// Space as separator is safe — doesn't affect SQL keyword detection.
+		const queryShape = strings.join(' ');
+		const mutation = isMutationStatement(queryShape);
+
 		return this._executeWithRetry(async () => {
 			const sql = await this._ensureConnectedAsync();
+			if (mutation) {
+				// Use sql.begin() callback API for pool-safe transactions.
+				// Bun requires this instead of manual BEGIN/COMMIT when max > 1,
+				// because sql.begin() reserves a specific connection for the
+				// transaction. Manual BEGIN via sql.unsafe('BEGIN') would throw
+				// ERR_POSTGRES_UNSAFE_TRANSACTION on pooled connections.
+				return sql.begin(async (tx) => {
+					return tx(strings, ...values) as unknown as unknown[];
+				});
+			}
 			return sql(strings, ...values);
 		});
 	}
@@ -179,6 +267,13 @@ export class PostgresClient {
 		// This ensures _warmConnection() updates connection stats before we proceed
 		const sql = await this._ensureConnectedAsync();
 
+		// Reserve a dedicated connection from the pool. Bun requires either
+		// sql.begin(callback), sql.reserve(), or max:1 for transactions.
+		// Since this API returns a Transaction object for manual commit/rollback,
+		// we need a reserved connection to guarantee all queries hit the same
+		// connection as the BEGIN.
+		const reserved = await sql.reserve();
+
 		// Build BEGIN statement with options
 		let beginStatement = 'BEGIN';
 
@@ -198,10 +293,15 @@ export class PostgresClient {
 			beginStatement += ' NOT DEFERRABLE';
 		}
 
-		// Execute BEGIN
-		const connection = await sql.unsafe(beginStatement);
-
-		return new Transaction(sql, connection);
+		// Execute BEGIN on the reserved connection
+		try {
+			const connection = await reserved.unsafe(beginStatement);
+			return new Transaction(reserved, connection);
+		} catch (error) {
+			// Release the reserved connection if BEGIN fails
+			reserved.release();
+			throw error;
+		}
 	}
 
 	/**
@@ -278,6 +378,79 @@ export class PostgresClient {
 		return sql.unsafe(query);
 	}
 
+	/**
+	 * Execute a raw SQL query with automatic retry and transaction wrapping for mutations.
+	 *
+	 * Unlike {@link unsafe}, this method:
+	 * - Automatically retries on retryable errors (connection drops, resets)
+	 * - Wraps mutation statements in transactions for safe retry
+	 * - Returns a thenable with `.values()` support matching Bun's SQLQuery interface
+	 *
+	 * Detected mutation types: INSERT, UPDATE, DELETE, COPY, TRUNCATE, MERGE, CALL, DO.
+	 * EXPLAIN queries are never wrapped (read-only analysis).
+	 *
+	 * For SELECT queries, retries without transaction wrapping (idempotent).
+	 * For mutations, wraps in BEGIN/COMMIT so PostgreSQL auto-rolls back
+	 * uncommitted transactions on connection drop, making retry safe.
+	 *
+	 * **⚠️ COMMIT Uncertainty Window:**
+	 * If the connection drops after the server processes COMMIT but before the client
+	 * receives confirmation (~<1ms window), changes ARE committed but the client sees
+	 * a failure. Retry will then duplicate the mutation. This is an inherent limitation
+	 * of retry-based approaches. Use application-level idempotency (e.g., unique
+	 * constraints with ON CONFLICT) for critical operations.
+	 *
+	 * **⚠️ Result Format Locking:**
+	 * Each unsafeQuery() result can only be consumed via ONE access pattern — either
+	 * `await result` (row objects) or `await result.values()` (arrays), not both.
+	 * Attempting the second pattern throws an error to prevent accidental duplicate execution.
+	 *
+	 * @param query - The raw SQL query string
+	 * @param params - Optional query parameters
+	 * @returns A thenable that resolves to rows (objects) or arrays via `.values()`
+	 *
+	 * @see https://github.com/agentuity/sdk/issues/911
+	 *
+	 * @example
+	 * ```typescript
+	 * // INSERT with safe retry
+	 * const rows = await client.unsafeQuery('INSERT INTO items (name) VALUES ($1) RETURNING *', ['test']);
+	 *
+	 * // SELECT with retry (no transaction overhead)
+	 * const items = await client.unsafeQuery('SELECT * FROM items WHERE id = $1', [42]);
+	 *
+	 * // Get raw arrays via .values()
+	 * const arrays = await client.unsafeQuery('SELECT id, name FROM items').values();
+	 * ```
+	 */
+	unsafeQuery(query: string, params?: unknown[]): UnsafeQueryResult {
+		if (isMutationStatement(query)) {
+			// Use sql.begin() callback API for pool-safe transactions.
+			// Bun requires this instead of manual BEGIN/COMMIT when max > 1.
+			// sql.begin() auto-COMMITs on success and auto-ROLLBACKs on error.
+			const makeTransactionalExecutor = (useValues: boolean) =>
+				this._executeWithRetry(async () => {
+					const raw = this._ensureConnected();
+					return raw.begin(async (tx) => {
+						const q = params ? tx.unsafe(query, params) : tx.unsafe(query);
+						return useValues ? await q.values() : await q;
+					});
+				});
+
+			return createThenable(makeTransactionalExecutor);
+		}
+
+		// Non-mutation: plain retry without transaction overhead
+		const makeExecutor = (useValues: boolean) =>
+			this._executeWithRetry(async () => {
+				const raw = this._ensureConnected();
+				const q = params ? raw.unsafe(query, params) : raw.unsafe(query);
+				return useValues ? q.values() : q;
+			});
+
+		return createThenable(makeExecutor);
+	}
+
 	/**
 	 * Registers signal handlers to detect application shutdown.
 	 * When shutdown is detected, reconnection is disabled.
@@ -335,10 +508,12 @@ export class PostgresClient {
 		if (this._config.username) bunOptions.username = this._config.username;
 		if (this._config.password) bunOptions.password = this._config.password;
 		if (this._config.database) bunOptions.database = this._config.database;
+		if (this._config.path) bunOptions.path = this._config.path;
 		if (this._config.max) bunOptions.max = this._config.max;
 		if (this._config.idleTimeout !== undefined) bunOptions.idleTimeout = this._config.idleTimeout;
 		if (this._config.connectionTimeout !== undefined)
 			bunOptions.connectionTimeout = this._config.connectionTimeout;
+		if (this._config.maxLifetime !== undefined) bunOptions.maxLifetime = this._config.maxLifetime;
 
 		// Handle TLS configuration
 		if (this._config.tls !== undefined) {
@@ -349,6 +524,23 @@ export class PostgresClient {
 			}
 		}
 
+		// Postgres client runtime configuration (search_path, statement_timeout, etc.)
+		if (this._config.connection) bunOptions.connection = this._config.connection;
+
+		// Default to unnamed prepared statements (prepare: false) to prevent
+		// "prepared statement did not exist" errors when backend connections
+		// rotate (e.g., connection poolers, hot reloads, server restarts).
+		// See: https://github.com/agentuity/sdk/issues/1005
+		bunOptions.prepare = this._config.prepare ?? false;
+
+		// BigInt handling for integers outside i32 range
+		if (this._config.bigint !== undefined) bunOptions.bigint = this._config.bigint;
+
+		// Set up onconnect handler
+		if (this._config.onconnect) {
+			bunOptions.onconnect = this._config.onconnect;
+		}
+
 		// Set up onclose handler for reconnection
 		bunOptions.onclose = (err: Error | null) => {
 			this._handleClose(err ?? undefined);
@@ -735,6 +927,7 @@ export class PostgresClient {
  */
 export type CallablePostgresClient = PostgresClient & {
 	(strings: TemplateStringsArray, ...values: unknown[]): Promise<unknown[]>;
+	unsafeQuery(query: string, params?: unknown[]): UnsafeQueryResult;
 };
 
 /**
@@ -790,6 +983,7 @@ export function createCallableClient(config?: string | PostgresConfig): Callable
 	callable.close = client.close.bind(client);
 	callable.shutdown = client.shutdown.bind(client);
 	callable.unsafe = client.unsafe.bind(client);
+	callable.unsafeQuery = client.unsafeQuery.bind(client);
 	callable.waitForConnection = client.waitForConnection.bind(client);
 	callable.executeWithRetry = client.executeWithRetry.bind(client);
 

package/src/index.ts

@@ -35,7 +35,12 @@
 export { postgres, default } from './postgres';
 
 // Client class for advanced usage
-export { PostgresClient, createCallableClient, type CallablePostgresClient } from './client';
+export {
+	PostgresClient,
+	createCallableClient,
+	createThenable,
+	type CallablePostgresClient,
+} from './client';
 
 // Pool class for pg.Pool-based connections
 export { PostgresPool, Pool, createPool } from './pool';
@@ -49,6 +54,9 @@ export { patchBunSQL, isPatched, SQL } from './patch';
 // TLS utilities
 export { injectSslMode } from './tls';
 
+// Mutation detection utility
+export { isMutationStatement } from './mutation';
+
 // Types
 export type {
 	PostgresConfig,

package/src/mutation.ts

@@ -0,0 +1,245 @@
+/**
+ * Strips leading whitespace and SQL comments (block and line) from a query string.
+ * Returns the remaining query text starting at the first non-comment token.
+ *
+ * Note: This regex does NOT support nested block comments. Use
+ * {@link stripLeadingComments} for full nested comment support.
+ */
+export const LEADING_COMMENTS_RE = /^(?:\s+|\/\*[\s\S]*?\*\/|--[^\n]*\n)*/;
+
+/**
+ * Strips leading whitespace and SQL comments from a query string.
+ * Supports nested block comments.
+ * Returns the remaining query text starting at the first non-comment token.
+ */
+function stripLeadingComments(query: string): string {
+	let i = 0;
+	const len = query.length;
+	while (i < len) {
+		const ch = query[i]!;
+		// Skip whitespace
+		if (ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r') {
+			i++;
+			continue;
+		}
+		// Skip line comment: -- ...\n
+		if (ch === '-' && i + 1 < len && query[i + 1] === '-') {
+			i += 2;
+			while (i < len && query[i] !== '\n') i++;
+			if (i < len) i++; // skip newline
+			continue;
+		}
+		// Skip block comment with nesting: /* ... /* ... */ ... */
+		if (ch === '/' && i + 1 < len && query[i + 1] === '*') {
+			let commentDepth = 1;
+			i += 2;
+			while (i < len && commentDepth > 0) {
+				if (query[i] === '/' && i + 1 < len && query[i + 1] === '*') {
+					commentDepth++;
+					i += 2;
+				} else if (query[i] === '*' && i + 1 < len && query[i + 1] === '/') {
+					commentDepth--;
+					i += 2;
+				} else {
+					i++;
+				}
+			}
+			continue;
+		}
+		break;
+	}
+	return query.substring(i);
+}
+
+/** Regex matching the first keyword of a mutation statement. */
+const MUTATION_KEYWORD_RE = /^(INSERT|UPDATE|DELETE|COPY|TRUNCATE|MERGE|CALL|DO)\b/i;
+
+/**
+ * Determines whether a SQL query is a mutation that requires transaction
+ * wrapping for safe retry.
+ *
+ * Detected mutation types: INSERT, UPDATE, DELETE, COPY, TRUNCATE, MERGE,
+ * CALL, DO. EXPLAIN queries are never wrapped (read-only analysis, even
+ * when the explained statement is a mutation like `EXPLAIN INSERT INTO ...`).
+ *
+ * Mutation statements wrapped in a transaction can be safely retried because
+ * PostgreSQL guarantees that uncommitted transactions are rolled back when
+ * the connection drops. This prevents:
+ * - Duplicate rows from retried INSERTs
+ * - Double-applied changes from retried UPDATEs (e.g., counter increments)
+ * - Repeated side effects from retried DELETEs (e.g., cascade triggers)
+ *
+ * Handles three patterns:
+ * 1. Direct mutations: `INSERT INTO ...`, `UPDATE ... SET`, `DELETE FROM ...`,
+ *    `COPY ...`, `TRUNCATE ...`, `MERGE ...`, `CALL ...`, `DO ...`
+ *    (with optional leading comments/whitespace)
+ * 2. CTE mutations: `WITH cte AS (...) INSERT|UPDATE|DELETE|... ...` — scans
+ *    past the WITH clause by tracking parenthesis depth to skip CTE
+ *    subexpressions, then checks if the first top-level DML keyword is a
+ *    mutation. The scanner treats single-quoted strings, double-quoted
+ *    identifiers, dollar-quoted strings, line comments (--), and block
+ *    comments (including nested) as atomic regions so parentheses inside
+ *    them do not corrupt depth tracking.
+ * 3. Multi-statement queries: `SELECT 1; INSERT INTO items VALUES (1)` —
+ *    scans past semicolons at depth 0 to find mutation keywords in
+ *    subsequent statements.
+ *
+ * @see https://github.com/agentuity/sdk/issues/911
+ */
+export function isMutationStatement(query: string): boolean {
+	// Strip leading whitespace and SQL comments (supports nested block comments)
+	const stripped = stripLeadingComments(query);
+
+	// EXPLAIN never mutates (even EXPLAIN INSERT INTO...)
+	if (/^EXPLAIN\b/i.test(stripped)) return false;
+
+	// Fast path: direct mutation statement
+	if (MUTATION_KEYWORD_RE.test(stripped)) {
+		return true;
+	}
+
+	// Fast path: no CTE prefix and no multi-statement separator → not a mutation
+	if (!/^WITH\s/i.test(stripped) && !stripped.includes(';')) {
+		return false;
+	}
+
+	// Full scan: walk the entire query character-by-character.
+	// Track parenthesis depth and check for mutation keywords at depth 0.
+	// This handles both CTE queries (WITH ... AS (...) DML ...) and
+	// multi-statement queries (SELECT ...; INSERT ...).
+	let depth = 0;
+	let i = 0;
+	const len = stripped.length;
+
+	while (i < len) {
+		const ch = stripped[i]!;
+
+		// ── Skip atomic regions (at any depth) ──────────────────────
+		// These regions may contain parentheses that must not affect depth.
+
+		// Single-quoted string: 'it''s a (test)'
+		if (ch === "'") {
+			i++;
+			while (i < len) {
+				if (stripped[i] === "'") {
+					i++;
+					if (i < len && stripped[i] === "'") {
+						i++; // escaped '' → still inside string
+					} else {
+						break; // end of string
+					}
+				} else {
+					i++;
+				}
+			}
+			continue;
+		}
+
+		// Double-quoted identifier: "col(1)"
+		if (ch === '"') {
+			i++;
+			while (i < len) {
+				if (stripped[i] === '"') {
+					i++;
+					if (i < len && stripped[i] === '"') {
+						i++; // escaped "" → still inside identifier
+					} else {
+						break;
+					}
+				} else {
+					i++;
+				}
+			}
+			continue;
+		}
+
+		// Line comment: -- has (parens)\n
+		if (ch === '-' && i + 1 < len && stripped[i + 1] === '-') {
+			i += 2;
+			while (i < len && stripped[i] !== '\n') i++;
+			if (i < len) i++; // skip newline
+			continue;
+		}
+
+		// Block comment: /* has (parens) */ — supports nesting
+		if (ch === '/' && i + 1 < len && stripped[i + 1] === '*') {
+			let commentDepth = 1;
+			i += 2;
+			while (i < len && commentDepth > 0) {
+				if (stripped[i] === '/' && i + 1 < len && stripped[i + 1] === '*') {
+					commentDepth++;
+					i += 2;
+				} else if (stripped[i] === '*' && i + 1 < len && stripped[i + 1] === '/') {
+					commentDepth--;
+					i += 2;
+				} else {
+					i++;
+				}
+			}
+			continue;
+		}
+
+		// Dollar-quoted string: $$has (parens)$$ or $tag$...$tag$
+		if (ch === '$') {
+			let tagEnd = i + 1;
+			while (tagEnd < len && /[a-zA-Z0-9_]/.test(stripped[tagEnd]!)) tagEnd++;
+			if (tagEnd < len && stripped[tagEnd] === '$') {
+				const tag = stripped.substring(i, tagEnd + 1);
+				i = tagEnd + 1;
+				const closeIdx = stripped.indexOf(tag, i);
+				if (closeIdx !== -1) {
+					i = closeIdx + tag.length;
+				} else {
+					i = len; // unterminated — skip to end
+				}
+				continue;
+			}
+			// Not a dollar-quote tag, fall through
+		}
+
+		// ── Track parenthesis depth ─────────────────────────────────
+		if (ch === '(') {
+			depth++;
+			i++;
+			continue;
+		}
+		if (ch === ')') {
+			depth--;
+			i++;
+			continue;
+		}
+
+		// Only inspect keywords at top level (depth === 0)
+		if (depth === 0) {
+			// Skip whitespace at top level
+			if (ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r') {
+				i++;
+				continue;
+			}
+
+			// Skip semicolons and commas between CTEs or statements
+			if (ch === ';' || ch === ',') {
+				i++;
+				continue;
+			}
+
+			// Check for mutation keyword or skip other words
+			// (CTE names, AS, RECURSIVE, SELECT, WITH, etc.)
+			if (/\w/.test(ch)) {
+				const rest = stripped.substring(i);
+				if (MUTATION_KEYWORD_RE.test(rest)) {
+					return true;
+				}
+				// Skip past this word
+				while (i < len && /\w/.test(stripped[i]!)) {
+					i++;
+				}
+				continue;
+			}
+		}
+
+		i++;
+	}
+
+	return false;
+}

package/src/transaction.ts

@@ -122,6 +122,8 @@ export class Transaction {
 				phase: 'commit',
 				cause: error,
 			});
+		} finally {
+			this._releaseConnection();
 		}
 	}
 
@@ -142,6 +144,19 @@ export class Transaction {
 				phase: 'rollback',
 				cause: error,
 			});
+		} finally {
+			this._releaseConnection();
+		}
+	}
+
+	/**
+	 * Releases the underlying reserved connection back to the pool.
+	 * Called automatically on commit or rollback. Safe to call multiple times.
+	 */
+	private _releaseConnection(): void {
+		const sql = this._sql as unknown as { release?: () => void };
+		if (typeof sql.release === 'function') {
+			sql.release();
 		}
 	}
 

package/src/types.ts

@@ -1,5 +1,12 @@
 import type pg from 'pg';
 
+export type UnsafeQueryResult = {
+	then: Promise<unknown>['then'];
+	catch: Promise<unknown>['catch'];
+	finally: Promise<unknown>['finally'];
+	values: () => Promise<unknown>;
+};
+
 /**
  * TLS configuration options for PostgreSQL connections.
  */
@@ -149,20 +156,51 @@ export interface PostgresConfig {
 	username?: string;
 
 	/**
-	 * Database password.
+	 * Database password for authentication.
+	 * Can be a string or a function that returns the password (sync or async).
+	 * Using a function enables rotating credentials (e.g., AWS RDS IAM tokens,
+	 * GCP Cloud SQL IAM authentication).
 	 */
-	password?: string;
+	password?: string | (() => string | Promise<string>);
 
 	/**
 	 * Database name.
 	 */
 	database?: string;
 
+	/**
+	 * Unix domain socket path for local PostgreSQL connections.
+	 * Alternative to hostname/port for same-machine connections.
+	 *
+	 * @example '/var/run/postgresql/.s.PGSQL.5432'
+	 */
+	path?: string;
+
 	/**
 	 * TLS configuration.
 	 */
 	tls?: TLSConfig | boolean;
 
+	/**
+	 * PostgreSQL client runtime configuration parameters sent during
+	 * connection startup.
+	 *
+	 * These correspond to PostgreSQL runtime configuration settings.
+	 *
+	 * @see https://www.postgresql.org/docs/current/runtime-config-client.html
+	 *
+	 * @example
+	 * ```typescript
+	 * {
+	 *   search_path: 'myapp,public',
+	 *   statement_timeout: '30s',
+	 *   application_name: 'my-service',
+	 *   timezone: 'UTC',
+	 * }
+	 * ```
+	 */
+	connection?: Record<string, string | boolean | number>;
+
 	/**
 	 * Maximum number of connections in the pool.
 	 * @default 10
@@ -181,6 +219,43 @@ export interface PostgresConfig {
 	 */
 	idleTimeout?: number;
 
+	/**
+	 * Maximum lifetime of a connection in seconds.
+	 * After this time, the connection is closed and a new one is created.
+	 * Set to `0` for no maximum lifetime.
+	 *
+	 * This is useful in pooled environments to prevent stale connections
+	 * and coordinate with connection pooler behavior.
+	 *
+	 * @default 0 (no maximum lifetime)
+	 */
+	maxLifetime?: number;
+
+	/**
+	 * Whether to use named prepared statements.
+	 *
+	 * When `true`, Bun's SQL driver caches named prepared statements on the
+	 * server for better performance with repeated queries.
+	 *
+	 * When `false`, queries use unnamed prepared statements that are parsed
+	 * fresh each time. This is required when using connection poolers like
+	 * PGBouncer (in transaction mode) or Supavisor, where the backend
+	 * connection may change between queries, invalidating cached statements.
+	 *
+	 * @default false
+	 */
+	prepare?: boolean;
+
+	/**
+	 * Whether to return large integers as BigInt instead of strings.
+	 *
+	 * When `true`, integers outside the i32 range are returned as `BigInt`.
+	 * When `false`, they are returned as strings.
+	 *
+	 * @default false
+	 */
+	bigint?: boolean;
+
 	/**
 	 * Reconnection configuration.
 	 */
@@ -199,6 +274,12 @@ export interface PostgresConfig {
 	 */
 	preconnect?: boolean;
 
+	/**
+	 * Callback invoked when a connection attempt completes.
+	 * Receives an Error on failure, or null on success.
+	 */
+	onconnect?: (error: Error | null) => void;
+
 	/**
 	 * Callback invoked when the connection is closed.
 	 */