@agentuity/postgres 0.1.41

package/AGENTS.md

@@ -0,0 +1,124 @@
+# Agent Guidelines for @agentuity/postgres
+
+## Package Overview
+
+Resilient PostgreSQL client with automatic reconnection for Agentuity projects. Wraps Bun's native SQL driver and adds connection resilience.
+
+## Commands
+
+- **Build**: `bun run build`
+- **Typecheck**: `bun run typecheck`
+- **Clean**: `bun run clean`
+
+## Architecture
+
+- **Runtime**: Bun (required for native SQL driver)
+- **Dependencies**: `@agentuity/core` only
+- **Features**: Automatic reconnection, exponential backoff, transactions, connection pooling
+
+## Code Conventions
+
+- **Tagged template literals**: Primary query interface
+- **Exponential backoff**: With jitter for reconnection
+- **Error handling**: Use StructuredError from @agentuity/core
+- **Type safety**: Full TypeScript support
+
+## Usage Pattern
+
+```typescript
+import { postgres } from '@agentuity/postgres';
+
+// Create client (uses DATABASE_URL by default)
+const sql = postgres();
+
+// Or with explicit config
+const sql = postgres({
+	hostname: 'localhost',
+	port: 5432,
+	database: 'mydb',
+	reconnect: {
+		maxAttempts: 5,
+		initialDelayMs: 100,
+	},
+});
+
+// Query using tagged template literals
+const users = await sql`SELECT * FROM users WHERE active = ${true}`;
+
+// Transactions
+const tx = await sql.begin();
+try {
+	await tx`INSERT INTO users (name) VALUES (${name})`;
+	await tx.commit();
+} catch (error) {
+	await tx.rollback();
+	throw error;
+}
+```
+
+## Error Handling
+
+```typescript
+import { isRetryableError, ConnectionClosedError } from '@agentuity/postgres';
+
+try {
+	const result = await sql`SELECT * FROM users`;
+} catch (error) {
+	if (error instanceof ConnectionClosedError) {
+		// Connection was closed, client will auto-reconnect
+	}
+	if (isRetryableError(error)) {
+		// This error type triggers automatic reconnection
+	}
+}
+```
+
+## Connection Behavior
+
+### Lazy Connections
+
+By default, the actual TCP connection is established lazily on first query. The `connected` property will be `false` until a query is executed or `waitForConnection()` is called. Set `preconnect: true` in config to establish the connection immediately.
+
+### Automatic Reconnection
+
+The client automatically reconnects when:
+
+- Connection is closed unexpectedly
+- Network errors occur (ECONNRESET, ETIMEDOUT, etc.)
+- PostgreSQL server restarts
+
+Reconnection uses exponential backoff with jitter to prevent thundering herd.
+
+### Graceful Shutdown
+
+The client detects SIGTERM/SIGINT signals and prevents reconnection during shutdown. You can also call `shutdown()` manually to prevent reconnection while allowing in-flight queries to complete.
+
+## Global Registry
+
+All clients are automatically registered in a global registry for coordinated shutdown:
+
+```typescript
+import { shutdownAll, getClientCount, hasActiveClients } from '@agentuity/postgres';
+
+// Check active clients
+console.log(getClientCount());
+console.log(hasActiveClients());
+
+// Shutdown all clients
+await shutdownAll(5000); // 5 second timeout
+```
+
+## Runtime Integration
+
+When `@agentuity/runtime` is available, the package automatically registers a shutdown hook. This means all postgres clients are closed during graceful shutdown without any additional code.
+
+## Testing
+
+- Tests require a running PostgreSQL instance
+- Use `@agentuity/test-utils` for mocking
+- When running tests, prefer using a subagent (Task tool) to avoid context bloat
+
+## Publishing
+
+1. Run build and typecheck
+2. Publish **after** `@agentuity/core`

package/README.md

@@ -0,0 +1,297 @@
+# @agentuity/postgres
+
+Resilient PostgreSQL client with automatic reconnection for Agentuity projects.
+
+## Features
+
+- 🔄 **Automatic Reconnection** - Exponential backoff with jitter
+- 🏷️ **Tagged Template Literals** - Clean, SQL-injection-safe queries
+- 💼 **Transaction Support** - Full transaction and savepoint support
+- 📊 **Connection Stats** - Track connection health and reconnection history
+- 🔌 **Bun Native** - Wraps Bun's high-performance SQL driver
+
+## Installation
+
+```bash
+bun add @agentuity/postgres
+```
+
+## Quick Start
+
+```typescript
+import { postgres } from '@agentuity/postgres';
+
+// Create a client (uses DATABASE_URL environment variable by default)
+const sql = postgres();
+
+// Execute queries using tagged template literals
+const users = await sql`SELECT * FROM users WHERE active = ${true}`;
+
+// Parameterized queries are safe from SQL injection
+const userId = 123;
+const user = await sql`SELECT * FROM users WHERE id = ${userId}`;
+
+// Close when done
+await sql.close();
+```
+
+## Configuration
+
+```typescript
+import { postgres } from '@agentuity/postgres';
+
+const sql = postgres({
+	// Connection options
+	url: 'postgres://user:pass@localhost:5432/mydb',
+	// Or individual options:
+	hostname: 'localhost',
+	port: 5432,
+	username: 'user',
+	password: 'pass',
+	database: 'mydb',
+
+	// Connection pool
+	max: 10, // Maximum connections
+	idleTimeout: 30, // Seconds before idle connection is closed
+	connectionTimeout: 30, // Seconds to wait for connection
+
+	// TLS
+	tls: true, // or { rejectUnauthorized: false } for self-signed certs
+
+	// Reconnection
+	reconnect: {
+		enabled: true, // Enable auto-reconnect (default: true)
+		maxAttempts: 10, // Maximum reconnection attempts
+		initialDelayMs: 100, // Initial delay before first retry
+		maxDelayMs: 30000, // Maximum delay between retries
+		multiplier: 2, // Exponential backoff multiplier
+		jitterMs: 1000, // Random jitter to prevent thundering herd
+	},
+
+	// Callbacks
+	onclose: (error) => console.log('Connection closed', error),
+	onreconnect: (attempt) => console.log(`Reconnecting... attempt ${attempt}`),
+	onreconnected: () => console.log('Reconnected!'),
+	onreconnectfailed: (error) => console.error('Reconnection failed', error),
+});
+```
+
+## Transactions
+
+```typescript
+const tx = await sql.begin();
+
+try {
+	await tx`INSERT INTO users (name, email) VALUES (${name}, ${email})`;
+	await tx`UPDATE accounts SET balance = balance - ${amount} WHERE id = ${fromId}`;
+	await tx`UPDATE accounts SET balance = balance + ${amount} WHERE id = ${toId}`;
+	await tx.commit();
+} catch (error) {
+	await tx.rollback();
+	throw error;
+}
+```
+
+### Transaction Options
+
+```typescript
+const tx = await sql.begin({
+	isolationLevel: 'serializable', // 'read uncommitted' | 'read committed' | 'repeatable read' | 'serializable'
+	readOnly: true,
+	deferrable: true, // Only for serializable read-only
+});
+```
+
+### Savepoints
+
+```typescript
+const tx = await sql.begin();
+
+await tx`INSERT INTO users (name) VALUES ('Alice')`;
+
+const savepoint = await tx.savepoint();
+await tx`INSERT INTO users (name) VALUES ('Bob')`;
+
+// Oops, rollback Bob but keep Alice
+await savepoint.rollback();
+
+await tx.commit(); // Only Alice is committed
+```
+
+## Graceful Shutdown
+
+The client automatically detects application shutdown signals (SIGTERM, SIGINT) and prevents reconnection attempts during shutdown:
+
+```typescript
+// Automatic: SIGTERM/SIGINT will prevent reconnection
+
+// Manual: For graceful shutdown with connection draining
+process.on('SIGTERM', async () => {
+	sql.shutdown(); // Prevent reconnection
+	// Wait for in-flight queries to complete...
+	await sql.close(); // Then close
+	process.exit(0);
+});
+```
+
+## Waiting for Connection
+
+If you need to ensure the connection is established before proceeding:
+
+```typescript
+// Wait for connection (useful after reconnection)
+await sql.waitForConnection();
+
+// With timeout
+await sql.waitForConnection(5000); // 5 second timeout
+```
+
+## Connection Stats
+
+```typescript
+const stats = sql.stats;
+
+console.log({
+	connected: stats.connected,
+	reconnecting: stats.reconnecting,
+	totalConnections: stats.totalConnections,
+	reconnectAttempts: stats.reconnectAttempts,
+	failedReconnects: stats.failedReconnects,
+	lastConnectedAt: stats.lastConnectedAt,
+	lastDisconnectedAt: stats.lastDisconnectedAt,
+});
+```
+
+## Error Handling
+
+```typescript
+import {
+	postgres,
+	ConnectionClosedError,
+	ReconnectFailedError,
+	TransactionError,
+	isRetryableError,
+} from '@agentuity/postgres';
+
+try {
+	const result = await sql`SELECT * FROM users`;
+} catch (error) {
+	if (error instanceof ConnectionClosedError) {
+		// Connection was closed - client will auto-reconnect
+		console.log('Connection closed, waiting for reconnect...');
+	}
+
+	if (error instanceof ReconnectFailedError) {
+		// All reconnection attempts failed
+		console.error(`Failed after ${error.attempts} attempts`);
+	}
+
+	if (error instanceof TransactionError) {
+		// Transaction operation failed
+		console.error(`Transaction ${error.phase} failed`);
+	}
+
+	if (isRetryableError(error)) {
+		// This error type would trigger automatic reconnection
+	}
+}
+```
+
+## Raw SQL Access
+
+For advanced use cases, you can execute unparameterized queries:
+
+```typescript
+// Execute unsafe (unparameterized) queries - use with caution!
+// This bypasses SQL injection protection
+const result = await sql.unsafe('SELECT * FROM users WHERE id = 1');
+
+// Access the underlying Bun.SQL instance for advanced operations
+const rawSql = sql.raw;
+```
+
+## API Reference
+
+### `postgres(config?)`
+
+Creates a new PostgreSQL client.
+
+- `config` - Connection URL string or configuration object
+- Returns: `CallablePostgresClient`
+
+### `PostgresClient`
+
+The main client class with the following methods:
+
+- `query(strings, ...values)` - Execute a parameterized query
+- `begin(options?)` - Start a transaction
+- `close()` - Close all connections
+- `shutdown()` - Signal shutdown (prevents reconnection)
+- `waitForConnection(timeoutMs?)` - Wait for connection to be established
+- `unsafe(query)` - Execute an unparameterized query
+
+Properties:
+
+- `connected` - Whether currently connected
+- `reconnecting` - Whether reconnection is in progress
+- `shuttingDown` - Whether shutdown has been signaled
+- `stats` - Connection statistics
+- `raw` - Underlying Bun.SQL instance
+
+### `Transaction`
+
+Returned by `begin()`:
+
+- `query(strings, ...values)` - Execute query in transaction
+- `savepoint(name?)` - Create a savepoint
+- `commit()` - Commit the transaction
+- `rollback()` - Rollback the transaction
+
+### `Savepoint`
+
+Returned by `transaction.savepoint()`:
+
+- `rollback()` - Rollback to this savepoint
+- `release()` - Release the savepoint
+
+## Global Registry and Runtime Integration
+
+All PostgreSQL clients are automatically registered in a global registry. When used with `@agentuity/runtime`, clients are automatically closed during graceful shutdown.
+
+### Manual Shutdown (without runtime)
+
+```typescript
+import { shutdownAll, getClientCount } from '@agentuity/postgres';
+
+// Check how many clients are active
+console.log(`Active clients: ${getClientCount()}`);
+
+// Shut down all clients (with optional timeout)
+process.on('SIGTERM', async () => {
+	await shutdownAll(5000); // 5 second timeout
+	process.exit(0);
+});
+```
+
+### With @agentuity/runtime
+
+When using `@agentuity/runtime`, postgres clients are automatically closed during graceful shutdown - no additional code needed:
+
+```typescript
+import { createApp } from '@agentuity/runtime';
+import { postgres } from '@agentuity/postgres';
+
+// Create postgres client - it auto-registers with the runtime
+const sql = postgres();
+
+const app = await createApp({
+	// ... your app config
+});
+
+// When the runtime shuts down (SIGTERM/SIGINT), all postgres
+// clients are automatically closed via the shutdown hook system
+```
+
+## License
+
+Apache-2.0

package/dist/client.d.ts

@@ -0,0 +1,224 @@
+import { SQL as BunSQL, type SQLQuery } from 'bun';
+import type { PostgresConfig, ConnectionStats, TransactionOptions, ReserveOptions } from './types';
+import { Transaction, ReservedConnection } from './transaction';
+/**
+ * A resilient PostgreSQL client with automatic reconnection.
+ *
+ * Wraps Bun's native SQL driver and adds:
+ * - Automatic reconnection with exponential backoff
+ * - Connection state tracking
+ * - Transaction support
+ * - Reserved connection support
+ *
+ * Can be used as a tagged template literal for queries:
+ *
+ * @example
+ * ```typescript
+ * const client = new PostgresClient();
+ *
+ * // Simple query
+ * const users = await client`SELECT * FROM users`;
+ *
+ * // Parameterized query
+ * const user = await client`SELECT * FROM users WHERE id = ${userId}`;
+ *
+ * // Transaction
+ * const tx = await client.begin();
+ * await tx`INSERT INTO users (name) VALUES (${name})`;
+ * await tx.commit();
+ * ```
+ */
+export declare class PostgresClient {
+    private _sql;
+    private _config;
+    private _initialized;
+    private _connected;
+    private _reconnecting;
+    private _closed;
+    private _shuttingDown;
+    private _signalHandlers;
+    private _reconnectPromise;
+    private _connectPromise;
+    private _stats;
+    /**
+     * Creates a new PostgresClient.
+     *
+     * Note: By default, the actual TCP connection is established lazily on first query.
+     * The `connected` property will be `false` until a query is executed or
+     * `waitForConnection()` is called. Set `preconnect: true` in config to
+     * establish the connection immediately.
+     *
+     * @param config - Connection configuration. Can be a connection URL string or a config object.
+     *                 If not provided, uses `process.env.DATABASE_URL`.
+     */
+    constructor(config?: string | PostgresConfig);
+    /**
+     * Whether the client is currently connected.
+     */
+    get connected(): boolean;
+    /**
+     * Whether the client is shutting down (won't attempt reconnection).
+     */
+    get shuttingDown(): boolean;
+    /**
+     * Whether a reconnection attempt is in progress.
+     */
+    get reconnecting(): boolean;
+    /**
+     * Connection statistics.
+     */
+    get stats(): Readonly<ConnectionStats>;
+    /**
+     * Execute a query using tagged template literal syntax.
+     * If reconnection is in progress, waits for it to complete before executing.
+     * Automatically retries on retryable errors.
+     *
+     * @example
+     * ```typescript
+     * const users = await client`SELECT * FROM users WHERE active = ${true}`;
+     * ```
+     */
+    query(strings: TemplateStringsArray, ...values: unknown[]): Promise<unknown[]>;
+    /**
+     * Begin a new transaction.
+     *
+     * @param options - Transaction options (isolation level, read-only, deferrable)
+     * @returns A Transaction object for executing queries within the transaction
+     *
+     * @example
+     * ```typescript
+     * const tx = await client.begin();
+     * try {
+     *   await tx`INSERT INTO users (name) VALUES (${name})`;
+     *   await tx`UPDATE accounts SET balance = balance - ${amount} WHERE id = ${fromId}`;
+     *   await tx.commit();
+     * } catch (error) {
+     *   await tx.rollback();
+     *   throw error;
+     * }
+     * ```
+     */
+    begin(options?: TransactionOptions): Promise<Transaction>;
+    /**
+     * Reserve an exclusive connection from the pool.
+     *
+     * **Note:** This feature is not currently supported because Bun's SQL driver
+     * does not expose connection-level pooling APIs. The underlying driver manages
+     * connections internally and does not allow reserving a specific connection.
+     *
+     * @param _options - Reserve options (unused)
+     * @throws {UnsupportedOperationError} Always throws - this operation is not supported
+     *
+     * @example
+     * ```typescript
+     * // This will throw UnsupportedOperationError
+     * const conn = await client.reserve();
+     * ```
+     */
+    reserve(_options?: ReserveOptions): Promise<ReservedConnection>;
+    /**
+     * Signal that the application is shutting down.
+     * This prevents reconnection attempts but doesn't immediately close the connection.
+     * Use this when you want to gracefully drain connections before calling close().
+     */
+    shutdown(): void;
+    /**
+     * Close the client and release all connections.
+     */
+    close(): Promise<void>;
+    /**
+     * Access to raw SQL methods for advanced use cases.
+     * Returns the underlying Bun.SQL instance.
+     */
+    get raw(): InstanceType<typeof BunSQL>;
+    /**
+     * Execute an unsafe (unparameterized) query.
+     * Use with caution - this bypasses SQL injection protection.
+     *
+     * @param query - The raw SQL query string
+     */
+    unsafe(query: string): SQLQuery;
+    /**
+     * Registers signal handlers to detect application shutdown.
+     * When shutdown is detected, reconnection is disabled.
+     */
+    private _registerShutdownHandlers;
+    /**
+     * Removes signal handlers registered for shutdown detection.
+     */
+    private _removeShutdownHandlers;
+    /**
+     * Initializes the internal Bun.SQL client.
+     * Note: This creates the SQL client but doesn't establish the TCP connection yet.
+     * Bun's SQL driver uses lazy connections - the actual TCP connection is made on first query.
+     */
+    private _initializeSql;
+    /**
+     * Warms the connection by executing a test query.
+     * This establishes the actual TCP connection and verifies it's working.
+     */
+    private _warmConnection;
+    /**
+     * Re-initializes the SQL client for reconnection.
+     * Used internally during the reconnection loop.
+     */
+    private _reinitializeSql;
+    /**
+     * Handles connection close events.
+     */
+    private _handleClose;
+    /**
+     * Starts the reconnection process.
+     */
+    private _startReconnect;
+    /**
+     * The main reconnection loop with exponential backoff.
+     */
+    private _reconnectLoop;
+    /**
+     * Ensures the client is initialized and returns the SQL instance.
+     * This is the synchronous version - use _ensureConnectedAsync when you can await.
+     *
+     * Note: This returns the SQL instance even if `_connected` is false because
+     * Bun's SQL uses lazy connections. The actual connection will be established
+     * on first query. Use this for synchronous access to the SQL instance.
+     */
+    private _ensureConnected;
+    /**
+     * Ensures the client is connected and returns the SQL instance.
+     * If reconnection is in progress, waits for it to complete.
+     * If connection hasn't been established yet, warms it first.
+     */
+    private _ensureConnectedAsync;
+    /**
+     * Executes an operation with retry logic for retryable errors.
+     * Waits for reconnection if one is in progress.
+     */
+    private _executeWithRetry;
+    /**
+     * Wait for the connection to be established.
+     * If the connection hasn't been established yet (lazy connection), this will
+     * warm the connection by executing a test query.
+     * If reconnection is in progress, waits for it to complete.
+     *
+     * @param timeoutMs - Optional timeout in milliseconds
+     * @throws {ConnectionClosedError} If the client has been closed or connection fails
+     */
+    waitForConnection(timeoutMs?: number): Promise<void>;
+}
+/**
+ * Type for the callable PostgresClient that supports tagged template literals.
+ */
+export type CallablePostgresClient = PostgresClient & {
+    (strings: TemplateStringsArray, ...values: unknown[]): Promise<unknown[]>;
+};
+/**
+ * Creates a PostgresClient that can be called as a tagged template literal.
+ *
+ * @param config - Connection configuration
+ * @returns A callable PostgresClient
+ *
+ * @internal
+ */
+export declare function createCallableClient(config?: string | PostgresConfig): CallablePostgresClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,IAAI,MAAM,EAAE,KAAK,QAAQ,EAAY,MAAM,KAAK,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAUnG,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAShE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,cAAc;IAC1B,OAAO,CAAC,IAAI,CAA4C;IACxD,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,eAAe,CAAiD;IACxE,OAAO,CAAC,iBAAiB,CAA8B;IACvD,OAAO,CAAC,eAAe,CAA8B;IAErD,OAAO,CAAC,MAAM,CASZ;IAEF;;;;;;;;;;OAUG;gBACS,MAAM,CAAC,EAAE,MAAM,GAAG,cAAc;IA0B5C;;OAEG;IACH,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;OAEG;IACH,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED;;OAEG;IACH,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED;;OAEG;IACH,IAAI,KAAK,IAAI,QAAQ,CAAC,eAAe,CAAC,CAMrC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAO9E;;;;;;;;;;;;;;;;;;OAkBG;IACG,KAAK,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC;IA8B/D;;;;;;;;;;;;;;;OAeG;IACG,OAAO,CAAC,QAAQ,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,kBAAkB,CAAC;IASrE;;;;OAIG;IACH,QAAQ,IAAI,IAAI;IAIhB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB5B;;;OAGG;IACH,IAAI,GAAG,IAAI,YAAY,CAAC,OAAO,MAAM,CAAC,CAErC;IAED;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ;IAK/B;;;OAGG;IACH,OAAO,CAAC,yBAAyB;IAajC;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAO/B;;;;OAIG;IACH,OAAO,CAAC,cAAc;IA6CtB;;;OAGG;YACW,eAAe;IAiB7B;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAMxB;;OAEG;IACH,OAAO,CAAC,YAAY;IA+BpB;;OAEG;IACH,OAAO,CAAC,eAAe;IASvB;;OAEG;YACW,cAAc;IAqE5B;;;;;;;OAOG;IACH,OAAO,CAAC,gBAAgB;IAiBxB;;;;OAIG;YACW,qBAAqB;IAsCnC;;;OAGG;YACW,iBAAiB;IA4D/B;;;;;;;;OAQG;IACG,iBAAiB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAgE1D;AAED;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,cAAc,GAAG;IACrD,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;CAC1E,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,cAAc,GAAG,sBAAsB,CAgD7F"}