pg-cache 1.6.7 → 1.6.9

package/esm/pg.js

@@ -1,6 +1,8 @@
 import pg from 'pg';
 import { getPgEnvOptions } from 'pg-env';
+import { Logger } from '@pgpmjs/logger';
 import { pgCache } from './lru';
+const log = new Logger('pg-cache');
 const getDbString = (user, password, host, port, database) => `postgres://${user}:${password}@${host}:${port}/${database}`;
 export const getPgPool = (pgConfig) => {
     const config = getPgEnvOptions(pgConfig);
@@ -12,6 +14,58 @@ export const getPgPool = (pgConfig) => {
     }
     const connectionString = getDbString(user, password, host, port, database);
     const pgPool = new pg.Pool({ connectionString });
+    /**
+     * IMPORTANT: Pool-level error handler for idle connection errors.
+     *
+     * WHY THIS EXISTS:
+     * pg-pool maintains a pool of database connections. When a connection is idle
+     * (not actively running a query) and the server terminates it (e.g., during
+     * database cleanup via pg_terminate_backend), pg-pool emits an 'error' event
+     * on the pool's EventEmitter. In Node.js, an EventEmitter 'error' event with
+     * no listeners is FATAL and crashes the entire process with an unhelpful
+     * stack trace showing internal pg-pool/pg-protocol objects.
+     *
+     * WHY THIS IS SAFE (does NOT swallow real errors):
+     * This handler ONLY catches errors emitted on IDLE pooled connections via
+     * the EventEmitter pattern. It does NOT intercept errors from active queries.
+     *
+     * Error paths in pg-pool:
+     * 1. QUERY ERRORS (pool.query(), client.query()):
+     *    - Returned via Promise rejection
+     *    - Bubble up through async/await as normal exceptions
+     *    - NOT affected by this handler - they still throw as expected
+     *    - Examples: syntax errors, constraint violations, connection refused
+     *
+     * 2. IDLE CONNECTION ERRORS (this handler):
+     *    - Emitted via EventEmitter when server kills an idle connection
+     *    - Without a handler: crashes Node.js process
+     *    - With this handler: logged and process continues
+     *    - Examples: pg_terminate_backend during cleanup, server restart
+     *
+     * WHEN THIS FIRES:
+     * - pgpm test-packages creates temp databases, deploys, then drops them
+     * - Dropping requires pg_terminate_backend() to kill active connections
+     * - Idle connections in the pool receive PostgreSQL error 57P01
+     * - This handler catches that expected cleanup error
+     *
+     * PostgreSQL error codes handled:
+     * - 57P01: admin_shutdown (terminating connection due to administrator command)
+     *   This is EXPECTED during database teardown and logged at debug level.
+     *
+     * All other error codes are logged at error level for visibility but do not
+     * crash the process, allowing the test harness to continue and report results.
+     */
+    pgPool.on('error', (err) => {
+        if (err.code === '57P01') {
+            // Expected during database cleanup - log at debug level
+            log.debug(`Pool ${database} connection terminated (expected during cleanup): ${err.message}`);
+        }
+        else {
+            // Unexpected pool error - log at error level for visibility
+            // Note: This does NOT swallow query errors - those still throw via Promise rejection
+            log.error(`Pool ${database} unexpected idle connection error [${err.code || 'unknown'}]: ${err.message}`);
+        }
+    });
     pgCache.set(database, pgPool);
     return pgPool;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pg-cache",
-  "version": "1.6.7",
+  "version": "1.6.9",
   "author": "Constructive <developers@constructive.io>",
   "description": "PostgreSQL connection pool LRU cache manager",
   "main": "index.js",
@@ -30,7 +30,7 @@
   },
   "dependencies": {
     "@pgpmjs/logger": "^1.3.5",
-    "@pgpmjs/types": "^2.12.5",
+    "@pgpmjs/types": "^2.12.6",
     "lru-cache": "^11.2.4",
     "pg": "^8.16.3",
     "pg-env": "^1.2.4"
@@ -48,5 +48,5 @@
     "connection",
     "constructive"
   ],
-  "gitHead": "e45ec95404e48d0c0542da882a3baea0cd6de1c7"
+  "gitHead": "fc182ff9e4c4745a3e86eda6d58e3b0061f36564"
 }

package/pg.js

@@ -6,7 +6,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getPgPool = void 0;
 const pg_1 = __importDefault(require("pg"));
 const pg_env_1 = require("pg-env");
+const logger_1 = require("@pgpmjs/logger");
 const lru_1 = require("./lru");
+const log = new logger_1.Logger('pg-cache');
 const getDbString = (user, password, host, port, database) => `postgres://${user}:${password}@${host}:${port}/${database}`;
 const getPgPool = (pgConfig) => {
     const config = (0, pg_env_1.getPgEnvOptions)(pgConfig);
@@ -18,6 +20,58 @@ const getPgPool = (pgConfig) => {
     }
     const connectionString = getDbString(user, password, host, port, database);
     const pgPool = new pg_1.default.Pool({ connectionString });
+    /**
+     * IMPORTANT: Pool-level error handler for idle connection errors.
+     *
+     * WHY THIS EXISTS:
+     * pg-pool maintains a pool of database connections. When a connection is idle
+     * (not actively running a query) and the server terminates it (e.g., during
+     * database cleanup via pg_terminate_backend), pg-pool emits an 'error' event
+     * on the pool's EventEmitter. In Node.js, an EventEmitter 'error' event with
+     * no listeners is FATAL and crashes the entire process with an unhelpful
+     * stack trace showing internal pg-pool/pg-protocol objects.
+     *
+     * WHY THIS IS SAFE (does NOT swallow real errors):
+     * This handler ONLY catches errors emitted on IDLE pooled connections via
+     * the EventEmitter pattern. It does NOT intercept errors from active queries.
+     *
+     * Error paths in pg-pool:
+     * 1. QUERY ERRORS (pool.query(), client.query()):
+     *    - Returned via Promise rejection
+     *    - Bubble up through async/await as normal exceptions
+     *    - NOT affected by this handler - they still throw as expected
+     *    - Examples: syntax errors, constraint violations, connection refused
+     *
+     * 2. IDLE CONNECTION ERRORS (this handler):
+     *    - Emitted via EventEmitter when server kills an idle connection
+     *    - Without a handler: crashes Node.js process
+     *    - With this handler: logged and process continues
+     *    - Examples: pg_terminate_backend during cleanup, server restart
+     *
+     * WHEN THIS FIRES:
+     * - pgpm test-packages creates temp databases, deploys, then drops them
+     * - Dropping requires pg_terminate_backend() to kill active connections
+     * - Idle connections in the pool receive PostgreSQL error 57P01
+     * - This handler catches that expected cleanup error
+     *
+     * PostgreSQL error codes handled:
+     * - 57P01: admin_shutdown (terminating connection due to administrator command)
+     *   This is EXPECTED during database teardown and logged at debug level.
+     *
+     * All other error codes are logged at error level for visibility but do not
+     * crash the process, allowing the test harness to continue and report results.
+     */
+    pgPool.on('error', (err) => {
+        if (err.code === '57P01') {
+            // Expected during database cleanup - log at debug level
+            log.debug(`Pool ${database} connection terminated (expected during cleanup): ${err.message}`);
+        }
+        else {
+            // Unexpected pool error - log at error level for visibility
+            // Note: This does NOT swallow query errors - those still throw via Promise rejection
+            log.error(`Pool ${database} unexpected idle connection error [${err.code || 'unknown'}]: ${err.message}`);
+        }
+    });
     lru_1.pgCache.set(database, pgPool);
     return pgPool;
 };