@agentuity/postgres 1.0.1 → 1.0.2

package/dist/registry.d.ts

@@ -1,56 +1,73 @@
 /**
- * Global registry for PostgreSQL clients.
+ * Global registry for PostgreSQL clients and pools.
  *
- * This module provides a way to track all active PostgreSQL clients
+ * This module provides a way to track all active PostgreSQL clients and pools
  * so they can be gracefully shut down together (e.g., on process exit).
  *
- * The runtime can use `shutdownAll()` to close all registered clients
+ * The runtime can use `shutdownAll()` to close all registered clients/pools
  * during graceful shutdown.
  *
  * When @agentuity/runtime is available, this module automatically registers
- * a shutdown hook so all postgres clients are closed during graceful shutdown.
+ * a shutdown hook so all postgres clients/pools are closed during graceful shutdown.
  */
-import type { PostgresClient } from './client';
 /**
- * Registers a client in the global registry.
- * Called automatically when a client is created.
+ * Common interface for registrable PostgreSQL connections.
+ * Both PostgresClient and PostgresPool implement this interface.
+ */
+export interface Registrable {
+    /**
+     * Whether the connection is shutting down.
+     */
+    readonly shuttingDown: boolean;
+    /**
+     * Signal that the connection is shutting down.
+     */
+    shutdown(): void;
+    /**
+     * Close the connection.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Registers a client or pool in the global registry.
+ * Called automatically when a client or pool is created.
  *
- * @param client - The client to register
+ * @param connection - The client or pool to register
  * @internal
  */
-export declare function registerClient(client: PostgresClient): void;
+export declare function registerClient(connection: Registrable): void;
 /**
- * Unregisters a client from the global registry.
- * Called automatically when a client is closed.
+ * Unregisters a client or pool from the global registry.
+ * Called automatically when a client or pool is closed.
  *
- * @param client - The client to unregister
+ * @param connection - The client or pool to unregister
  * @internal
  */
-export declare function unregisterClient(client: PostgresClient): void;
+export declare function unregisterClient(connection: Registrable): void;
 /**
- * Returns the number of registered clients.
+ * Returns the number of registered clients and pools.
  * Useful for debugging and testing.
  */
 export declare function getClientCount(): number;
 /**
- * Returns all registered clients.
+ * Returns all registered clients and pools.
  * Useful for debugging and monitoring.
  */
-export declare function getClients(): ReadonlySet<PostgresClient>;
+export declare function getClients(): ReadonlySet<Registrable>;
 /**
- * Shuts down all registered PostgreSQL clients gracefully.
+ * Shuts down all registered PostgreSQL clients and pools gracefully.
  *
  * This function:
- * 1. Signals shutdown to all clients (prevents reconnection)
- * 2. Closes all clients in parallel
+ * 1. Signals shutdown to all clients/pools (prevents reconnection)
+ * 2. Closes all clients/pools in parallel
  * 3. Clears the registry
  *
  * This is intended to be called by the runtime during graceful shutdown.
  *
  * @param timeoutMs - Optional timeout in milliseconds. If provided, the function
- *                    will resolve after the timeout even if some clients haven't
+ *                    will resolve after the timeout even if some connections haven't
  *                    finished closing. Default: no timeout.
- * @returns A promise that resolves when all clients are closed (or timeout)
+ * @returns A promise that resolves when all connections are closed (or timeout)
  *
  * @example
  * ```typescript
@@ -64,7 +81,7 @@ export declare function getClients(): ReadonlySet<PostgresClient>;
  */
 export declare function shutdownAll(timeoutMs?: number): Promise<void>;
 /**
- * Checks if there are any active (non-shutdown) clients.
+ * Checks if there are any active (non-shutdown) clients or pools.
  * Useful for health checks.
  */
 export declare function hasActiveClients(): boolean;

package/dist/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAuB/C;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAE3D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAE7D;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,WAAW,CAAC,cAAc,CAAC,CAExD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,WAAW,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAyCnE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAQ1C"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC3B;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAE/B;;OAEG;IACH,QAAQ,IAAI,IAAI,CAAC;IAEjB;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAuBD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,WAAW,GAAG,IAAI,CAE5D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,WAAW,GAAG,IAAI,CAE9D;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,WAAW,CAAC,WAAW,CAAC,CAErD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,WAAW,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAyCnE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAQ1C"}

package/dist/registry.js

@@ -1,14 +1,14 @@
 /**
- * Global registry for PostgreSQL clients.
+ * Global registry for PostgreSQL clients and pools.
  *
- * This module provides a way to track all active PostgreSQL clients
+ * This module provides a way to track all active PostgreSQL clients and pools
  * so they can be gracefully shut down together (e.g., on process exit).
  *
- * The runtime can use `shutdownAll()` to close all registered clients
+ * The runtime can use `shutdownAll()` to close all registered clients/pools
  * during graceful shutdown.
  *
  * When @agentuity/runtime is available, this module automatically registers
- * a shutdown hook so all postgres clients are closed during graceful shutdown.
+ * a shutdown hook so all postgres clients/pools are closed during graceful shutdown.
  */
 /**
  * Symbol used to store the registry in globalThis to avoid conflicts.
@@ -19,7 +19,7 @@ const REGISTRY_KEY = Symbol.for('@agentuity/postgres:registry');
  */
 const RUNTIME_HOOK_REGISTERED = Symbol.for('@agentuity/postgres:runtime-hook-registered');
 /**
- * Gets the global client registry, creating it if it doesn't exist.
+ * Gets the global registry, creating it if it doesn't exist.
  */
 function getRegistry() {
     const global = globalThis;
@@ -29,53 +29,53 @@ function getRegistry() {
     return global[REGISTRY_KEY];
 }
 /**
- * Registers a client in the global registry.
- * Called automatically when a client is created.
+ * Registers a client or pool in the global registry.
+ * Called automatically when a client or pool is created.
  *
- * @param client - The client to register
+ * @param connection - The client or pool to register
  * @internal
  */
-export function registerClient(client) {
-    getRegistry().add(client);
+export function registerClient(connection) {
+    getRegistry().add(connection);
 }
 /**
- * Unregisters a client from the global registry.
- * Called automatically when a client is closed.
+ * Unregisters a client or pool from the global registry.
+ * Called automatically when a client or pool is closed.
  *
- * @param client - The client to unregister
+ * @param connection - The client or pool to unregister
  * @internal
  */
-export function unregisterClient(client) {
-    getRegistry().delete(client);
+export function unregisterClient(connection) {
+    getRegistry().delete(connection);
 }
 /**
- * Returns the number of registered clients.
+ * Returns the number of registered clients and pools.
  * Useful for debugging and testing.
  */
 export function getClientCount() {
     return getRegistry().size;
 }
 /**
- * Returns all registered clients.
+ * Returns all registered clients and pools.
  * Useful for debugging and monitoring.
  */
 export function getClients() {
     return getRegistry();
 }
 /**
- * Shuts down all registered PostgreSQL clients gracefully.
+ * Shuts down all registered PostgreSQL clients and pools gracefully.
  *
  * This function:
- * 1. Signals shutdown to all clients (prevents reconnection)
- * 2. Closes all clients in parallel
+ * 1. Signals shutdown to all clients/pools (prevents reconnection)
+ * 2. Closes all clients/pools in parallel
  * 3. Clears the registry
  *
  * This is intended to be called by the runtime during graceful shutdown.
  *
  * @param timeoutMs - Optional timeout in milliseconds. If provided, the function
- *                    will resolve after the timeout even if some clients haven't
+ *                    will resolve after the timeout even if some connections haven't
  *                    finished closing. Default: no timeout.
- * @returns A promise that resolves when all clients are closed (or timeout)
+ * @returns A promise that resolves when all connections are closed (or timeout)
  *
  * @example
  * ```typescript
@@ -89,18 +89,18 @@ export function getClients() {
  */
 export async function shutdownAll(timeoutMs) {
     const registry = getRegistry();
-    const clients = Array.from(registry);
-    if (clients.length === 0) {
+    const connections = Array.from(registry);
+    if (connections.length === 0) {
         return;
     }
-    // Signal shutdown to all clients first (prevents reconnection attempts)
-    for (const client of clients) {
-        client.shutdown();
+    // Signal shutdown to all connections first (prevents reconnection attempts)
+    for (const connection of connections) {
+        connection.shutdown();
     }
-    // Close all clients in parallel
-    const closePromises = clients.map(async (client) => {
+    // Close all connections in parallel
+    const closePromises = connections.map(async (connection) => {
         try {
-            await client.close();
+            await connection.close();
         }
         catch {
             // Ignore close errors during shutdown
@@ -128,13 +128,13 @@ export async function shutdownAll(timeoutMs) {
     registry.clear();
 }
 /**
- * Checks if there are any active (non-shutdown) clients.
+ * Checks if there are any active (non-shutdown) clients or pools.
  * Useful for health checks.
  */
 export function hasActiveClients() {
     const registry = getRegistry();
-    for (const client of registry) {
-        if (!client.shuttingDown) {
+    for (const connection of registry) {
+        if (!connection.shuttingDown) {
             return true;
         }
     }

package/dist/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -210,4 +210,159 @@ export interface ReserveOptions {
      */
     timeout?: number;
 }
+/**
+ * SSL configuration for pg.Pool connections.
+ */
+export interface PoolSSLConfig {
+    /**
+     * Whether to reject unauthorized certificates.
+     * Set to `false` to allow self-signed certificates.
+     */
+    rejectUnauthorized?: boolean;
+    /**
+     * CA certificate(s) for verifying the server certificate.
+     */
+    ca?: string | Buffer | (string | Buffer)[];
+    /**
+     * Client certificate for mutual TLS authentication.
+     */
+    cert?: string | Buffer;
+    /**
+     * Client private key for mutual TLS authentication.
+     */
+    key?: string | Buffer;
+}
+/**
+ * Configuration options for PostgresPool.
+ * Extends standard pg.Pool options with reconnection support.
+ */
+export interface PoolConfig {
+    /**
+     * PostgreSQL connection URL.
+     * If not provided, uses `process.env.DATABASE_URL`.
+     */
+    connectionString?: string;
+    /**
+     * Database hostname.
+     */
+    host?: string;
+    /**
+     * Database port.
+     * @default 5432
+     */
+    port?: number;
+    /**
+     * Database username.
+     */
+    user?: string;
+    /**
+     * Database password.
+     */
+    password?: string;
+    /**
+     * Database name.
+     */
+    database?: string;
+    /**
+     * Maximum number of connections in the pool.
+     * @default 10
+     */
+    max?: number;
+    /**
+     * Number of milliseconds a client must sit idle before being disconnected.
+     * Set to 0 to disable idle timeout.
+     * @default 10000
+     */
+    idleTimeoutMillis?: number;
+    /**
+     * Number of milliseconds to wait when connecting a new client before timing out.
+     * Set to 0 to disable connection timeout.
+     * @default 0
+     */
+    connectionTimeoutMillis?: number;
+    /**
+     * SSL configuration.
+     * Set to `true` to enable SSL with default settings.
+     * Set to an object to configure SSL options.
+     * Set to `false` or omit to disable SSL.
+     */
+    ssl?: boolean | PoolSSLConfig;
+    /**
+     * Reconnection configuration.
+     */
+    reconnect?: ReconnectConfig;
+    /**
+     * Whether to establish a connection immediately on pool creation.
+     * If true, the pool will verify connectivity by acquiring and releasing a client.
+     * If false (default), the first connection is made lazily on first query.
+     *
+     * @default false
+     */
+    preconnect?: boolean;
+    /**
+     * Callback invoked when the pool encounters an error.
+     */
+    onclose?: (error?: Error) => void;
+    /**
+     * Callback invoked when reconnection starts.
+     */
+    onreconnect?: (attempt: number) => void;
+    /**
+     * Callback invoked when reconnection succeeds.
+     */
+    onreconnected?: () => void;
+    /**
+     * Callback invoked when reconnection fails permanently.
+     */
+    onreconnectfailed?: (error: Error) => void;
+}
+/**
+ * Statistics about the pool state and reconnection history.
+ */
+export interface PoolStats {
+    /**
+     * Whether the pool is currently connected.
+     */
+    connected: boolean;
+    /**
+     * Whether a reconnection attempt is in progress.
+     */
+    reconnecting: boolean;
+    /**
+     * Total number of clients in the pool.
+     */
+    totalCount: number;
+    /**
+     * Number of idle clients in the pool.
+     */
+    idleCount: number;
+    /**
+     * Number of clients currently waiting to be acquired.
+     */
+    waitingCount: number;
+    /**
+     * Total number of successful connections (including reconnections).
+     */
+    totalConnections: number;
+    /**
+     * Total number of reconnection attempts.
+     */
+    reconnectAttempts: number;
+    /**
+     * Total number of failed reconnection attempts.
+     */
+    failedReconnects: number;
+    /**
+     * Timestamp of the last successful connection.
+     */
+    lastConnectedAt: Date | null;
+    /**
+     * Timestamp of the last disconnection.
+     */
+    lastDisconnectedAt: Date | null;
+    /**
+     * Timestamp of the last reconnection attempt.
+     */
+    lastReconnectAttemptAt: Date | null;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agentuity/postgres",
-	"version": "1.0.1",
+	"version": "1.0.2",
 	"license": "Apache-2.0",
 	"author": "Agentuity employees and contributors",
 	"type": "module",
@@ -31,10 +31,11 @@
 		"prepublishOnly": "bun run clean && bun run build"
 	},
 	"dependencies": {
-		"@agentuity/core": "1.0.1"
+		"@agentuity/core": "1.0.2",
+		"pg": "^8.13.1"
 	},
 	"peerDependencies": {
-		"@agentuity/runtime": "1.0.1"
+		"@agentuity/runtime": "1.0.2"
 	},
 	"peerDependenciesMeta": {
 		"@agentuity/runtime": {
@@ -42,10 +43,12 @@
 		}
 	},
 	"devDependencies": {
-		"@agentuity/runtime": "1.0.1",
-		"@agentuity/test-utils": "1.0.1",
+		"@agentuity/runtime": "1.0.2",
+		"@agentuity/test-utils": "1.0.2",
 		"@types/bun": "latest",
+		"@types/pg": "^8.11.14",
 		"bun-types": "latest",
+		"kysely": "^0.27.6",
 		"typescript": "^5.9.0"
 	},
 	"publishConfig": {

package/src/index.ts

@@ -37,6 +37,9 @@ export { postgres, default } from './postgres';
 // Client class for advanced usage
 export { PostgresClient, createCallableClient, type CallablePostgresClient } from './client';
 
+// Pool class for pg.Pool-based connections
+export { PostgresPool, Pool, createPool } from './pool';
+
 // Transaction and reserved connection classes
 export { Transaction, Savepoint, ReservedConnection } from './transaction';
 
@@ -51,6 +54,9 @@ export type {
 	TLSConfig,
 	TransactionOptions,
 	ReserveOptions,
+	PoolConfig,
+	PoolStats,
+	PoolSSLConfig,
 } from './types';
 
 // Errors
@@ -68,4 +74,10 @@ export {
 export { computeBackoff, sleep, mergeReconnectConfig, DEFAULT_RECONNECT_CONFIG } from './reconnect';
 
 // Global registry for coordinated shutdown
-export { shutdownAll, getClientCount, getClients, hasActiveClients } from './registry';
+export {
+	shutdownAll,
+	getClientCount,
+	getClients,
+	hasActiveClients,
+	type Registrable,
+} from './registry';