@tejasanik/postgres-mcp-server 2.1.0 → 2.2.0

package/README.md

@@ -2,6 +2,8 @@
 
 A Model Context Protocol (MCP) server for PostgreSQL database management and analysis. This server provides comprehensive tools for exploring database schemas, executing queries, analyzing performance, and monitoring database health.
 
+---
+
 ## Installation
 
 ```bash
@@ -264,6 +266,15 @@ Switch to a different PostgreSQL server and optionally a specific database and s
 - `database` (optional): Name of the database to connect to (uses server's defaultDatabase or "postgres")
 - `schema` (optional): Default schema to use (uses server's defaultSchema or "public")
 
+**Returns:**
+
+- `success`: Whether the switch was successful
+- `message`: Success message
+- `currentServer`: Name of the connected server
+- `currentDatabase`: Name of the connected database
+- `currentSchema`: Name of the current schema
+- `context`: (If configured) AI context/guidance for the connected server
+
 #### `get_current_connection`
 
 Returns details about the current database connection including server, database, schema, access mode, user, and AI context.
@@ -289,6 +300,7 @@ Lists all database schemas in the current PostgreSQL database.
 **Parameters:**
 
 - `includeSystemSchemas` (optional): Include system schemas
+- `server`, `database`, `schema` (optional): One-time connection override
 
 #### `list_objects`
 
@@ -299,6 +311,7 @@ Lists database objects within a specified schema.
 - `schema` (required): Schema name to list objects from
 - `objectType` (optional): Type of objects to list (table, view, sequence, extension, all)
 - `filter` (optional): Filter objects by name
+- `server`, `database`, `targetSchema` (optional): One-time connection override
 
 #### `get_object_details`
 
@@ -309,6 +322,7 @@ Provides detailed information about a database object including columns, constra
 - `schema` (required): Schema name containing the object
 - `objectName` (required): Name of the object
 - `objectType` (optional): Type of the object
+- `server`, `database`, `targetSchema` (optional): One-time connection override
 
 ### Query Execution
 
@@ -326,6 +340,7 @@ Executes SQL statements on the database. Supports pagination and parameterized q
 - `includeSchemaHint` (optional): Include schema information (columns, primary keys, foreign keys) for tables referenced in the query.
 - `allowMultipleStatements` (optional): Allow multiple SQL statements separated by semicolons. Returns results for each statement with line numbers.
 - `transactionId` (optional): Execute within an active transaction. Get this from `begin_transaction`.
+- `server`, `database`, `schema` (optional): One-time connection override. Execute on a different server/database/schema without changing the main connection. Cannot be used with `transactionId`.
 
 **Returns:**
 
@@ -526,6 +541,7 @@ mutation_dry_run({ sql: "INSERT INTO users (id) VALUES (nextval('users_id_seq'))
 **Transaction-based dry-run for SQL files.** Actually executes ALL statements within a transaction, captures **REAL** results for each statement (row counts, errors with line numbers, constraint violations), then ROLLBACK so nothing persists. Perfect for testing migrations before deploying.
 
 **Non-Rollbackable Operations:** The following operations are automatically **skipped** (not executed):
+
 - **VACUUM, CLUSTER, REINDEX CONCURRENTLY**: Cannot run inside a transaction
 - **CREATE INDEX CONCURRENTLY**: Cannot run inside a transaction
 - **CREATE/DROP DATABASE**: Cannot run inside a transaction
@@ -606,16 +622,16 @@ dry_run_sql_file({ filePath: "/path/to/migration.sql", stripPatterns: ["/"] })
 
 **When to use `dry_run_sql_file` vs `preview_sql_file`:**
 
-| Feature | `preview_sql_file` | `dry_run_sql_file` |
-|---------|-------------------|-------------------|
-| Speed | Fast (just parsing) | Slower (actual execution) |
-| Detects syntax errors | Basic | **Actual PostgreSQL errors** |
-| Detects constraint violations | No | **Yes** |
-| Detects trigger effects | No | **Yes** |
-| Accurate row counts | No (estimates) | **Yes (actual)** |
-| Shows error details | No | **Yes (code, constraint, hint)** |
-| Consumes sequences | No | **No (NEXTVAL/SETVAL skipped)** |
-| Shows query plan for skipped ops | N/A | **Yes (EXPLAIN)** |
+| Feature                          | `preview_sql_file`  | `dry_run_sql_file`               |
+| -------------------------------- | ------------------- | -------------------------------- |
+| Speed                            | Fast (just parsing) | Slower (actual execution)        |
+| Detects syntax errors            | Basic               | **Actual PostgreSQL errors**     |
+| Detects constraint violations    | No                  | **Yes**                          |
+| Detects trigger effects          | No                  | **Yes**                          |
+| Accurate row counts              | No (estimates)      | **Yes (actual)**                 |
+| Shows error details              | No                  | **Yes (code, constraint, hint)** |
+| Consumes sequences               | No                  | **No (NEXTVAL/SETVAL skipped)**  |
+| Shows query plan for skipped ops | N/A                 | **Yes (EXPLAIN)**                |
 
 #### `batch_execute`
 
@@ -704,6 +720,70 @@ Gets the execution plan for a SQL query.
 - `buffers` (optional): Include buffer usage statistics
 - `format` (optional): Output format (text, json, yaml, xml)
 - `hypotheticalIndexes` (optional): Simulate indexes (requires hypopg extension)
+- `server`, `database`, `schema` (optional): One-time connection override (see below)
+
+### Connection Override (One-Time Execution)
+
+Most query execution tools support **one-time connection override** parameters that allow executing a query on a different server/database/schema without changing the main connection. This is useful for:
+
+- Querying multiple databases in a single workflow
+- Running read queries against a replica while keeping the main connection to primary
+- Comparing schemas across different servers
+
+**Supported tools:** `execute_sql`, `explain_query`, `list_schemas`, `list_objects`, `get_object_details`, `execute_sql_file`, `mutation_preview`, `mutation_dry_run`, `dry_run_sql_file`, `batch_execute`
+
+**Override Parameters:**
+
+- `server` (optional): Execute on this server instead of the current one
+- `database` (optional): Execute on this database instead of the current one
+- `schema` (optional): Set search_path to this schema for this execution only
+
+**Important Notes:**
+
+1. The main connection remains unchanged after the query completes
+2. Connection override cannot be used with transactions (`transactionId`)
+3. Override connections use a separate connection pool with LRU eviction
+4. Maximum 10 cached override pools, each limited to 2 connections
+5. Total connections across all pools limited to 50
+
+**Examples:**
+
+```
+# Query another database without switching
+execute_sql({
+  sql: "SELECT * FROM users LIMIT 10",
+  database: "analytics_db"
+})
+
+# Query a different server entirely
+execute_sql({
+  sql: "SELECT COUNT(*) FROM orders",
+  server: "reporting",
+  database: "warehouse"
+})
+
+# List schemas on a different server
+list_schemas({
+  server: "production",
+  database: "myapp"
+})
+
+# Compare table structure across environments
+get_object_details({
+  schema: "public",
+  objectName: "users",
+  server: "staging"
+})
+```
+
+**Connection Pool Management:**
+
+Override connections are managed efficiently:
+
+- Pools are cached and reused for repeated queries to the same server/database
+- LRU eviction removes oldest pools when limit (10) is reached
+- Connections are properly released after each query
+- Global connection limit prevents resource exhaustion
 
 ### Performance Analysis
 
@@ -806,6 +886,7 @@ The server automatically handles stale database connections. When a connection e
 4. Retry the operation once
 
 This is particularly useful for:
+
 - Staging/development servers that go idle
 - Cloud databases with connection timeouts
 - Network interruptions
@@ -888,6 +969,101 @@ When `execute_sql_file` or multi-statement execution encounters errors, line num
 - Optional: `pg_stat_statements` extension for query performance analysis
 - Optional: `hypopg` extension for hypothetical index simulation
 
+## 🤖 Agent Experience (AX) - Claude Code Review
+
+**Tested by:** Claude Code (Sonnet 4.5)
+**Use Case:** Database deployment, schema exploration, and SQL migration
+**Rating:** ⭐⭐⭐⭐⭐ (9.5/10)
+
+### What I Loved
+
+**1. Clear, Structured Responses**
+Every response includes connection context (`server`, `database`, `schema`), making it crystal clear which environment I'm working in. This is essential when managing multiple databases - I never have to guess where a query ran.
+
+**2. Excellent Error Handling**
+When I encountered a syntax error with Liquibase's `/` delimiter, the error message showed:
+
+- Exact line number (151)
+- The failing statement
+- Transaction rollback confirmation
+
+This made troubleshooting instant. No digging through logs or guessing what failed.
+
+**3. Server Management is Intuitive**
+
+- `list_servers` → Shows all available servers with connection status
+- `list_databases` → Filters databases by server name
+- `switch_server_db` → Seamless switching with immediate confirmation
+
+The flow is natural: discover → select → connect → execute.
+
+**4. SQL File Deployment Made Easy**
+The `stripPatterns` feature solved my exact problem:
+
+```javascript
+execute_sql_file({
+  filePath: "/path/to/liquibase.sql",
+  stripPatterns: ["/"], // Removes Liquibase delimiters
+});
+```
+
+Before this feature, I had to manually remove delimiters or use raw `execute_sql`. Now it's one clean call.
+
+**5. Dry-Run Capabilities are Outstanding**
+`dry_run_sql_file` is a game-changer:
+
+- Executes ALL statements in a transaction
+- Shows REAL errors with PostgreSQL error codes and constraint names
+- Automatically skips non-rollbackable operations (VACUUM, NEXTVAL)
+- Provides EXPLAIN plans for skipped statements
+- Then rolls back everything
+
+This is _way_ better than just parsing - I can catch constraint violations, trigger issues, and get exact row counts before deployment.
+
+**6. Security by Default**
+
+- Credentials never appear in responses
+- Host/port intentionally hidden (only server names visible)
+- Readonly mode available for production safety
+- Connection context always visible
+
+### Improvements Based on My Feedback
+
+The developer implemented several features after I tested the MCP:
+
+✅ **SQL File Delimiter Support** - Added `stripPatterns` for Liquibase `/`, SQL Server `GO`, etc.
+✅ **Validate-Only Mode** - `execute_sql_file({ validateOnly: true })` previews without execution
+✅ **Enhanced Connection Info** - `get_current_connection` now returns `user` and AI `context`
+✅ **Comprehensive Dry-Run** - `dry_run_sql_file` provides real execution + rollback
+✅ **Better Error Details** - PostgreSQL error codes, constraint names, hints included
+
+### Real-World Experience
+
+**Task:** Deploy a PostgreSQL function to two databases (dev + GraphQL-Intro-DB)
+
+1. **Discovery**: `list_servers` showed all configured servers
+2. **Preview**: Used `preview_sql_file` to check the file structure
+3. **Issue**: Got syntax error from Liquibase's `/` delimiter
+4. **Solution**: Switched to direct `execute_sql` to bypass the delimiter
+5. **Deployment**: Successfully deployed to both databases
+6. **Verification**: Used `get_current_connection` to confirm each deployment
+
+Total time: ~3 minutes. The structured responses and clear errors made it feel effortless.
+
+### Minor Suggestions for Future
+
+1. **Batch Cross Servers Deployment** - Deploy same script to multiple servers at once
+2. **Recent Connections** - Quick-switch to recently used databases
+3. **Statement Progress** - Show progress for large SQL files (e.g., "Executing statement 15/100...")
+
+### Bottom Line
+
+This MCP is production-ready and developer-friendly. The combination of clear responses, robust error handling, and powerful features like dry-run make it an essential tool for database work. The developer clearly understands the needs of both AI agents and human operators.
+
+**Recommended for:** Database migrations, schema exploration, multi-environment management, and production deployments.
+
+---
+
 ## License
 
 MIT

package/dist/db-manager/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Database Manager Utilities
+ *
+ * Re-exports all utility modules for the database manager.
+ */
+export * from './validation.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/db-manager/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/db-manager/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,iBAAiB,CAAC"}

package/dist/db-manager/index.js

@@ -0,0 +1,7 @@
+/**
+ * Database Manager Utilities
+ *
+ * Re-exports all utility modules for the database manager.
+ */
+export * from './validation.js';
+//# sourceMappingURL=index.js.map

package/dist/db-manager/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/db-manager/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,iBAAiB,CAAC"}

package/dist/db-manager/validation.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Database Manager Validation Utilities
+ *
+ * Centralized validation functions for database and schema names.
+ * Prevents SQL injection and ensures PostgreSQL-compatible identifiers.
+ */
+/**
+ * Validates a database name for PostgreSQL compatibility and SQL injection prevention.
+ *
+ * @param name - The database name to validate
+ * @throws Error if the database name is invalid
+ */
+export declare function validateDatabaseName(name: string): void;
+/**
+ * Validates a schema name for PostgreSQL compatibility.
+ *
+ * @param name - The schema name to validate
+ * @throws Error if the schema name is invalid
+ */
+export declare function validateSchemaName(name: string): void;
+/**
+ * Checks if a database name is valid without throwing.
+ *
+ * @param name - The database name to check
+ * @returns true if valid, false otherwise
+ */
+export declare function isValidDatabaseName(name: string): boolean;
+/**
+ * Checks if a schema name is valid without throwing.
+ *
+ * @param name - The schema name to check
+ * @returns true if valid, false otherwise
+ */
+export declare function isValidSchemaName(name: string): boolean;
+//# sourceMappingURL=validation.d.ts.map

package/dist/db-manager/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/db-manager/validation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAOvD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAIrD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvD"}

package/dist/db-manager/validation.js

@@ -0,0 +1,54 @@
+/**
+ * Database Manager Validation Utilities
+ *
+ * Centralized validation functions for database and schema names.
+ * Prevents SQL injection and ensures PostgreSQL-compatible identifiers.
+ */
+/** Pattern for valid database names: start with letter/underscore, alphanumeric/underscore/hyphen */
+const DATABASE_NAME_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_-]*$/;
+/** Pattern for SQL injection characters that must not appear in database names */
+const SQL_INJECTION_PATTERN = /--|;|'|"|`/;
+/** Pattern for valid schema names: start with letter/underscore, alphanumeric/underscore only */
+const SCHEMA_NAME_PATTERN = /^[a-zA-Z_]\w*$/;
+/**
+ * Validates a database name for PostgreSQL compatibility and SQL injection prevention.
+ *
+ * @param name - The database name to validate
+ * @throws Error if the database name is invalid
+ */
+export function validateDatabaseName(name) {
+    if (!DATABASE_NAME_PATTERN.test(name) || SQL_INJECTION_PATTERN.test(name)) {
+        throw new Error('Invalid database name. Allowed: letters, digits, underscores, hyphens. ' +
+            'Cannot contain SQL characters (;, --, quotes).');
+    }
+}
+/**
+ * Validates a schema name for PostgreSQL compatibility.
+ *
+ * @param name - The schema name to validate
+ * @throws Error if the schema name is invalid
+ */
+export function validateSchemaName(name) {
+    if (!SCHEMA_NAME_PATTERN.test(name)) {
+        throw new Error('Invalid schema name. Only alphanumeric characters and underscores are allowed.');
+    }
+}
+/**
+ * Checks if a database name is valid without throwing.
+ *
+ * @param name - The database name to check
+ * @returns true if valid, false otherwise
+ */
+export function isValidDatabaseName(name) {
+    return DATABASE_NAME_PATTERN.test(name) && !SQL_INJECTION_PATTERN.test(name);
+}
+/**
+ * Checks if a schema name is valid without throwing.
+ *
+ * @param name - The schema name to check
+ * @returns true if valid, false otherwise
+ */
+export function isValidSchemaName(name) {
+    return SCHEMA_NAME_PATTERN.test(name);
+}
+//# sourceMappingURL=validation.js.map

package/dist/db-manager/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/db-manager/validation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,qGAAqG;AACrG,MAAM,qBAAqB,GAAG,2BAA2B,CAAC;AAE1D,kFAAkF;AAClF,MAAM,qBAAqB,GAAG,YAAY,CAAC;AAE3C,iGAAiG;AACjG,MAAM,mBAAmB,GAAG,gBAAgB,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1E,MAAM,IAAI,KAAK,CACb,yEAAyE;YACvE,gDAAgD,CACnD,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,gFAAgF,CAAC,CAAC;IACpG,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,OAAO,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC/E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACxC,CAAC"}

package/dist/db-manager.d.ts

@@ -1,5 +1,17 @@
 import { PoolClient, QueryResult, QueryResultRow } from "pg";
-import { ServerConfig, ServersConfig, ConnectionState, ConnectionInfo, DatabaseInfo, ConnectionContext, TransactionInfo } from "./types.js";
+import { ServerConfig, ServersConfig, ConnectionState, ConnectionInfo, DatabaseInfo, ConnectionContext, TransactionInfo, ConnectionOverride } from "./types.js";
+/**
+ * Result from getClientWithOverride containing the client, release function, and resolved schema
+ */
+export interface OverrideClientResult {
+    client: PoolClient;
+    release: () => void;
+    server: string;
+    database: string;
+    schema: string;
+    context?: string;
+    isOverride: boolean;
+}
 export declare class DatabaseManager {
     private serversConfig;
     private connectionState;
@@ -7,7 +19,57 @@ export declare class DatabaseManager {
     private readOnlyMode;
     private queryTimeoutMs;
     private activeTransactions;
+    private poolCache;
+    private poolCleanupInterval;
+    private transactionCleanupInterval;
+    private poolCreationPromises;
+    private totalActiveConnections;
+    private mainPoolActiveConnections;
     constructor(readOnlyMode?: boolean, queryTimeoutMs?: number);
+    /**
+     * Starts the periodic cleanup of idle cached pools
+     */
+    private startPoolCleanup;
+    /**
+     * Cleans up pools that have been idle for too long
+     */
+    private cleanupIdlePools;
+    /**
+     * Starts the periodic cleanup of abandoned transactions.
+     * Transactions older than TRANSACTION_CLEANUP_TIMEOUT_MS (45 minutes) are
+     * automatically rolled back to prevent connection leaks.
+     */
+    private startTransactionCleanup;
+    /**
+     * Cleans up transactions that have been open for too long.
+     * Rolls back and releases the client for any transaction older than
+     * TRANSACTION_CLEANUP_TIMEOUT_MS (45 minutes).
+     *
+     * @returns Array of cleaned up transaction IDs with their info
+     */
+    private cleanupAbandonedTransactions;
+    /**
+     * Gets the age of a transaction in milliseconds.
+     *
+     * @param transactionId - The transaction ID
+     * @returns Age in milliseconds or null if transaction not found
+     */
+    getTransactionAge(transactionId: string): number | null;
+    /**
+     * Gets the remaining time before a transaction is auto-cleaned in milliseconds.
+     *
+     * @param transactionId - The transaction ID
+     * @returns Remaining time in milliseconds or null if transaction not found
+     */
+    getTransactionTimeRemaining(transactionId: string): number | null;
+    /**
+     * Generates a cache key for a server/database combination
+     */
+    private getPoolCacheKey;
+    /**
+     * Evicts the least recently used pool when cache is full
+     */
+    private evictLruPool;
     private loadServersConfig;
     getServersConfig(): ServersConfig;
     getServerNames(): string[];
@@ -23,6 +85,103 @@ export declare class DatabaseManager {
     listDatabases(): Promise<DatabaseInfo[]>;
     query<T extends QueryResultRow = any>(sql: string, params?: any[]): Promise<QueryResult<T>>;
     getClient(): Promise<PoolClient>;
+    /**
+     * Checks if we can acquire a new connection without exceeding global limits
+     */
+    private canAcquireConnection;
+    /**
+     * Acquires a client from the main pool with proper tracking
+     */
+    private acquireMainPoolClient;
+    /**
+     * Acquires a client from a cached pool with proper tracking
+     */
+    private acquireCachedPoolClient;
+    /**
+     * Creates a new cached pool. This method handles concurrent creation requests
+     * by storing the creation promise so multiple callers wait for the same pool.
+     */
+    private getOrCreateCachedPool;
+    /**
+     * Gets a client with optional connection override for one-time execution.
+     * Handles concurrent calls efficiently by:
+     * - Reusing existing pools for the same server/database
+     * - Preventing duplicate pool creation through promise caching
+     * - Tracking active connections for resource management
+     * - Enforcing global connection limits
+     *
+     * @param override - Optional connection override parameters
+     * @returns Object containing the client, release function, and resolved connection info
+     * @throws Error if no connection and no override, or if override server not found
+     */
+    getClientWithOverride(override?: ConnectionOverride): Promise<OverrideClientResult>;
+    /**
+     * Executes a query with optional connection override.
+     * Convenience method that handles client lifecycle automatically.
+     *
+     * @param sql - SQL query to execute
+     * @param params - Query parameters
+     * @param override - Optional connection override parameters
+     * @returns Query result with connection info
+     */
+    queryWithOverride<T extends QueryResultRow = any>(sql: string, params?: any[], override?: ConnectionOverride): Promise<QueryResult<T> & {
+        connectionInfo: {
+            server: string;
+            database: string;
+            schema: string;
+        };
+    }>;
+    /**
+     * Escapes a PostgreSQL identifier to prevent SQL injection
+     */
+    private escapeIdentifier;
+    /**
+     * Closes all cached pools and cleans up resources
+     */
+    closeAllCachedPools(): Promise<void>;
+    /**
+     * Gets comprehensive statistics about all connection pools (for monitoring/debugging)
+     */
+    getConnectionStats(): {
+        totalActiveConnections: number;
+        maxTotalConnections: number;
+        mainPool: {
+            activeConnections: number;
+            maxSize: number;
+            isConnected: boolean;
+        };
+        cachedPools: {
+            count: number;
+            maxCount: number;
+            totalActiveConnections: number;
+            pools: Array<{
+                key: string;
+                serverName: string;
+                database: string;
+                activeConnections: number;
+                maxSize: number;
+                lastUsed: Date;
+                createdAt: Date;
+                idleTimeRemaining: number;
+            }>;
+        };
+        pendingPoolCreations: number;
+    };
+    /**
+     * @deprecated Use getConnectionStats() instead
+     * Gets statistics about cached pools (for monitoring/debugging)
+     */
+    getCachedPoolStats(): {
+        count: number;
+        maxSize: number;
+        pools: Array<{
+            key: string;
+            serverName: string;
+            database: string;
+            lastUsed: Date;
+            createdAt: Date;
+        }>;
+    };
     close(): Promise<void>;
     /**
      * Invalidates the current connection without clearing the connection state.
@@ -64,13 +223,24 @@ export declare class DatabaseManager {
      */
     queryInTransaction<T extends QueryResultRow = any>(transactionId: string, sql: string, params?: any[]): Promise<QueryResult<T>>;
     /**
-     * Gets information about an active transaction
+     * Gets information about an active transaction, including time remaining.
+     *
+     * @param transactionId - The transaction ID
+     * @returns Transaction info with age and time remaining, or null if not found
      */
-    getTransactionInfo(transactionId: string): TransactionInfo | null;
+    getTransactionInfo(transactionId: string): (TransactionInfo & {
+        ageMs: number;
+        timeRemainingMs: number;
+    }) | null;
     /**
-     * Lists all active transactions
+     * Lists all active transactions with age and time remaining.
+     *
+     * @returns Array of transaction info objects with age and time remaining
      */
-    listActiveTransactions(): TransactionInfo[];
+    listActiveTransactions(): Array<TransactionInfo & {
+        ageMs: number;
+        timeRemainingMs: number;
+    }>;
 }
 /**
  * Gets the singleton DatabaseManager instance.

package/dist/db-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"db-manager.d.ts","sourceRoot":"","sources":["../src/db-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,IAAI,CAAC;AAEnE,OAAO,EACL,YAAY,EACZ,aAAa,EACb,eAAe,EACf,cAAc,EACd,YAAY,EACZ,iBAAiB,EACjB,eAAe,EAChB,MAAM,YAAY,CAAC;AAyKpB,qBAAa,eAAe;IAC1B,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,YAAY,CAAU;IAC9B,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,kBAAkB,CAAyE;gBAGjG,YAAY,GAAE,OAAc,EAC5B,cAAc,GAAE,MAAiC;IAYnD,OAAO,CAAC,iBAAiB;IAiBlB,gBAAgB,IAAI,aAAa;IAKjC,cAAc,IAAI,MAAM,EAAE;IAI1B,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAOxD,eAAe,IAAI,eAAe;IAIlC,WAAW,IAAI,OAAO;IAItB,oBAAoB,IAAI,MAAM,GAAG,IAAI;IAW/B,YAAY,CACvB,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC;IAkET,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAStC,iBAAiB,IAAI,cAAc;IAe7B,gBAAgB,IAAI,OAAO,CAAC,OAAO,CAAC;IAepC,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ/C,aAAa,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAcxC,KAAK,CAAC,CAAC,SAAS,cAAc,GAAG,GAAG,EAC/C,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,GAAG,EAAE,GACb,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IA8Bb,SAAS,IAAI,OAAO,CAAC,UAAU,CAAC;IAShC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAUnC;;;OAGG;IACU,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC;IAWlD;;;;OAIG;IACU,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAiC1C;;OAEG;WACW,iBAAiB,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO;IAyD7C,UAAU,IAAI,OAAO;IAIrB,eAAe,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI;IAIxC,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAO/C;;OAEG;IACI,oBAAoB,IAAI,iBAAiB;IAQhD;;;OAGG;IACU,gBAAgB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IA8BtE;;OAEG;IACU,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcpE;;OAEG;IACU,mBAAmB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IActE;;OAEG;IACU,kBAAkB,CAAC,CAAC,SAAS,cAAc,GAAG,GAAG,EAC5D,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,GAAG,EAAE,GACb,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAiB1B;;OAEG;IACI,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI;IAKxE;;OAEG;IACI,sBAAsB,IAAI,eAAe,EAAE;CAKnD;AAKD;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI,eAAe,CAS9C;AAED,wBAAgB,cAAc,IAAI,IAAI,CAKrC"}
+{"version":3,"file":"db-manager.d.ts","sourceRoot":"","sources":["../src/db-manager.ts"],"names":[],"mappings":"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"}