postgrejs 3.6.0 → 3.6.1

package/CHANGELOG.md

@@ -1,6 +1,20 @@
 ## Changelog
 
-### [v3.6.0](https://github.com/panates/postgrejs/compare/v3.5.0...v3.6.0) - 
+### [v3.6.1](https://github.com/panates/postgrejs/compare/v3.6.0...v3.6.1) - 
+
+#### 🚀 New Features
+
+- feat: report a pooled connection that dies @Eray Hanoğlu 
+
+#### 🛠 Refactoring and Updates
+
+- refactor: give a lost connection its own error type @Eray Hanoğlu 
+
+#### 💬 General Changes
+
+- ci: pin the runner image and stop naming the PostgreSQL it ships @Eray Hanoğlu 
+
+### [v3.6.0](https://github.com/panates/postgrejs/compare/v3.5.0...v3.6.0) -  20 September 2026 
 
 #### 🚀 New Features
 

package/README.md

@@ -74,7 +74,11 @@ Upgrading from 3.5? See [doc/MIGRATION-v3.5-to-v3.6.md](doc/MIGRATION-v3.5-to-v3
 ## Features
 
 - **Connection Management:** Supports both single connection and advanced pooling, providing scalability and efficient
-  resource management.
+  resource management. A connection that dies rather than being closed says so: `'close'` carries the reason, and a
+  pooled one is reported on the pool's `'destroy'` and `'error'` events - so an admin kill or a failover is
+  distinguishable from an ordinary eviction, including when the connection was sitting idle with no query to reject.
+  The reason is a `ConnectionLostError` carrying the backend's `processID`, and `code` `'08006'` so branching on it
+  needs no `instanceof`.
 - **Binary Wire Protocol:** Implements the full binary wire protocol for all PostgreSQL data types, ensuring robust and
   efficient data handling.
 - **Prepared Statements:** Named prepared statements for optimized query execution, and a per-connection cache that

package/connection/intl-connection.js

@@ -96,7 +96,9 @@ export class IntlConnection extends SafeEventEmitter {
         this._config = Object.freeze(getConnectionConfig(config));
         this.socket = new PgSocket(this._config);
         this.socket.on('error', err => this._onError(err));
-        this.socket.on('close', () => this.emit('close'));
+        // The reason travels with it: 'close' on its own cannot tell an
+        // ordinary shutdown from the backend being terminated under us.
+        this.socket.on('close', (reason) => this.emit('close', reason));
         this.socket.on('notification', payload => this.emit('notification', payload));
         this.socket.on('connecting', () => this.emit('connecting'));
         this._onErrorSavePoint = 'SP_' + Math.round(Math.random() * 100000000);
@@ -163,7 +165,7 @@ export class IntlConnection extends SafeEventEmitter {
             // IntlConnection TWICE per close() call - confirmed live: a single
             // close() left two listeners registered on the far side (e.g. two
             // NOTIFY deliveries after Pool's reconnect re-subscribed twice).
-            this.socket.once('close', resolve);
+            this.socket.once('close', () => resolve());
             this.socket.sendTerminateMessage(() => {
                 this.socket.close();
             });

package/connection/pool.d.ts

@@ -37,6 +37,14 @@ export declare class Pool extends SafeEventEmitter {
     protected readonly _notificationListeners: SafeEventEmitter;
     protected _notificationConnection?: Connection;
     protected readonly _pipelineSlots: PipelineSlot[];
+    /**
+     * Why a connection is about to be destroyed, for the ones that were not
+     * destroyed on purpose. lightning-pool's own 'destroy' carries the
+     * resource and nothing else, so the reason is recorded on the way in -
+     * when the connection reports its close - and read back out when the
+     * pool reports the removal.
+     */
+    protected readonly _destroyReasons: WeakMap<IntlConnection, Error>;
     protected _pipelineMaxQueries: number;
     protected _pipelineMaxConnections: number;
     readonly config: PoolConfiguration;
@@ -91,6 +99,20 @@ export declare class Pool extends SafeEventEmitter {
     listen(channel: string, callback: NotificationCallback): Promise<void>;
     unListen(channel: string): Promise<void>;
     unListenAll(): Promise<void>;
+    /**
+     * A pooled connection reported that its socket closed. `reason` is set
+     * only when that was not asked for - see PgSocket._handleClose().
+     */
+    protected _onConnectionClosed(intlCon: IntlConnection, reason?: Error): void;
+    /**
+     * The pool has removed a connection. `destroy` fires the same way for an
+     * ordinary eviction (idle timeout, close(), a failed validate) as for a
+     * connection that died, so the reason is what tells them apart - an
+     * admin kill, a failover and a network fault were otherwise
+     * indistinguishable from a timeout, with nothing at all reported when
+     * the connection had no query in flight to reject.
+     */
+    protected _onConnectionDestroyed(intlCon: IntlConnection): void;
     protected _canPipeline(pipeline: boolean | undefined, sql: string, autoCommit: boolean | undefined, signal: AbortSignal | undefined): boolean;
     /**
      * Picks the pooled connection a pipelined query should ride on, or

package/connection/pool.js

@@ -13,6 +13,14 @@ export class Pool extends SafeEventEmitter {
     _notificationListeners = new SafeEventEmitter();
     _notificationConnection;
     _pipelineSlots = [];
+    /**
+     * Why a connection is about to be destroyed, for the ones that were not
+     * destroyed on purpose. lightning-pool's own 'destroy' carries the
+     * resource and nothing else, so the reason is recorded on the way in -
+     * when the connection reports its close - and read back out when the
+     * pool reports the removal.
+     */
+    _destroyReasons = new WeakMap();
     _pipelineMaxQueries;
     _pipelineMaxConnections;
     config;
@@ -46,7 +54,7 @@ export class Pool extends SafeEventEmitter {
                 /* c8 ignore stop */
                 const intlCon = new IntlConnection(cfg);
                 await intlCon.connect();
-                intlCon.on('close', () => this._pool.destroy(intlCon));
+                intlCon.on('close', (reason) => this._onConnectionClosed(intlCon, reason));
                 /* c8 ignore start */
                 if (this.listenerCount('debug')) {
                     this.emit('debug', {
@@ -82,7 +90,7 @@ export class Pool extends SafeEventEmitter {
                 /* c8 ignore stop */
                 intlCon.owner = undefined;
                 intlCon.removeAllListeners();
-                intlCon.once('close', () => this._pool.destroy(intlCon));
+                intlCon.once('close', (reason) => this._onConnectionClosed(intlCon, reason));
                 intlCon._refCount = 0;
             },
             validate: async (intlCon) => {
@@ -104,7 +112,7 @@ export class Pool extends SafeEventEmitter {
         this._pool.on('return', (...args) => this.emit('release', ...args));
         this._pool.on('error', (...args) => this.emit('error', ...args));
         this._pool.on('acquire', (...args) => this.emit('acquire', ...args));
-        this._pool.on('destroy', (...args) => this.emit('destroy', ...args));
+        this._pool.on('destroy', (intlCon) => this._onConnectionDestroyed(intlCon));
     }
     /**
      * Returns the number of connections that are currently acquired
@@ -313,6 +321,40 @@ export class Pool extends SafeEventEmitter {
             await conn.close();
         }
     }
+    /**
+     * A pooled connection reported that its socket closed. `reason` is set
+     * only when that was not asked for - see PgSocket._handleClose().
+     */
+    _onConnectionClosed(intlCon, reason) {
+        if (reason)
+            this._destroyReasons.set(intlCon, reason);
+        this._pool.destroy(intlCon);
+    }
+    /**
+     * The pool has removed a connection. `destroy` fires the same way for an
+     * ordinary eviction (idle timeout, close(), a failed validate) as for a
+     * connection that died, so the reason is what tells them apart - an
+     * admin kill, a failover and a network fault were otherwise
+     * indistinguishable from a timeout, with nothing at all reported when
+     * the connection had no query in flight to reject.
+     */
+    _onConnectionDestroyed(intlCon) {
+        const reason = this._destroyReasons.get(intlCon);
+        if (reason)
+            this._destroyReasons.delete(intlCon);
+        this.emit('destroy', intlCon, reason);
+        if (!reason)
+            return;
+        // Reported on 'error' as well, which is where pg puts a pooled
+        // connection dying and where code ported from it listens. Safe to do
+        // unconditionally here: SafeEventEmitter drops an 'error' that has no
+        // listener instead of throwing, so this cannot turn a recovery the
+        // pool already made into a crashed process. The error names the pid
+        // and carries the socket error as its cause; no second argument, so
+        // the existing `(err, meta)` shape lightning-pool emits for a
+        // connection that could not be created stays unambiguous.
+        this.emit('error', reason);
+    }
     _canPipeline(pipeline, sql, autoCommit, signal) {
         return (pipeline === true &&
             !signal &&

package/index.d.ts

@@ -23,6 +23,7 @@ export * from './interfaces/query-result.js';
 export * from './interfaces/script-execute-options.js';
 export * from './interfaces/script-result.js';
 export * from './interfaces/statement-prepare-options.js';
+export * from './protocol/connection-lost-error.js';
 export * from './protocol/database-error.js';
 export * from './protocol/smart-buffer.js';
 export * from './types.js';

package/index.js

@@ -23,6 +23,7 @@ export * from './interfaces/query-result.js';
 export * from './interfaces/script-execute-options.js';
 export * from './interfaces/script-result.js';
 export * from './interfaces/statement-prepare-options.js';
+export * from './protocol/connection-lost-error.js';
 export * from './protocol/database-error.js';
 export * from './protocol/smart-buffer.js';
 export * from './types.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "postgrejs",
   "description": "Professional PostgreSQL client NodeJS",
-  "version": "3.6.0",
+  "version": "3.6.1",
   "author": "Panates",
   "license": "BSD-3-Clause",
   "dependencies": {

package/protocol/connection-lost-error.d.ts

@@ -0,0 +1,40 @@
+/**
+ * A connection whose socket closed without anyone asking it to - the
+ * backend terminated by an administrator, a failover, a network fault.
+ *
+ * Reported on `Connection`'s `'close'` event as its reason, and for a
+ * pooled connection on `Pool`'s `'destroy'` (as the second argument) and
+ * `'error'`. `Pool` emits `'error'` for this and for a connection that
+ * could not be created in the first place, and those want different
+ * handling - this class is how a listener tells them apart:
+ *
+ * ```ts
+ * pool.on('error', err => {
+ *   if (err.code === '08006') log.warn('pooled connection lost', err.processID);
+ *   else log.error('could not open a connection', err);
+ * });
+ * ```
+ *
+ * `code` is there so that branching does not have to mean `instanceof`,
+ * which fails across duplicated copies of the package and is awkward from
+ * JavaScript. It reads the same way `DatabaseError.code` does - a
+ * SQLSTATE - and `08006 connection_failure` is the one this is. The server
+ * never sends it: it cannot report that its own connection went away, so
+ * there is no ambiguity about where a code of this value came from.
+ *
+ * The message deliberately says nothing else: it matches what other
+ * drivers report for the same event, so code that branches on it keeps
+ * working. What happened to *this* connection is on the object instead -
+ * `processID` names the backend, and `cause` carries the socket error
+ * when there was one (a clean FIN leaves none).
+ */
+export declare class ConnectionLostError extends Error {
+    /**
+     * SQLSTATE 08006, `connection_failure`. Synthesized here rather than
+     * received - see the class doc.
+     */
+    readonly code: string;
+    /** The backend's process id, as it was before the connection reset. */
+    readonly processID?: number;
+    constructor(processID?: number, cause?: unknown);
+}

package/protocol/connection-lost-error.js

@@ -0,0 +1,54 @@
+/**
+ * A connection whose socket closed without anyone asking it to - the
+ * backend terminated by an administrator, a failover, a network fault.
+ *
+ * Reported on `Connection`'s `'close'` event as its reason, and for a
+ * pooled connection on `Pool`'s `'destroy'` (as the second argument) and
+ * `'error'`. `Pool` emits `'error'` for this and for a connection that
+ * could not be created in the first place, and those want different
+ * handling - this class is how a listener tells them apart:
+ *
+ * ```ts
+ * pool.on('error', err => {
+ *   if (err.code === '08006') log.warn('pooled connection lost', err.processID);
+ *   else log.error('could not open a connection', err);
+ * });
+ * ```
+ *
+ * `code` is there so that branching does not have to mean `instanceof`,
+ * which fails across duplicated copies of the package and is awkward from
+ * JavaScript. It reads the same way `DatabaseError.code` does - a
+ * SQLSTATE - and `08006 connection_failure` is the one this is. The server
+ * never sends it: it cannot report that its own connection went away, so
+ * there is no ambiguity about where a code of this value came from.
+ *
+ * The message deliberately says nothing else: it matches what other
+ * drivers report for the same event, so code that branches on it keeps
+ * working. What happened to *this* connection is on the object instead -
+ * `processID` names the backend, and `cause` carries the socket error
+ * when there was one (a clean FIN leaves none).
+ */
+export class ConnectionLostError extends Error {
+    /**
+     * SQLSTATE 08006, `connection_failure`. Synthesized here rather than
+     * received - see the class doc.
+     */
+    code = '08006';
+    /** The backend's process id, as it was before the connection reset. */
+    processID;
+    constructor(processID, cause) {
+        super('Connection terminated unexpectedly');
+        this.name = 'ConnectionLostError';
+        this.processID = processID;
+        // Assigned rather than passed to the constructor, as abortError()
+        // does - same reason, the option is newer than this package's floor.
+        if (cause !== undefined) {
+            try {
+                this.cause = cause;
+            }
+            catch {
+                /* c8 ignore next */
+            }
+        }
+    }
+}

package/protocol/pg-socket.d.ts

@@ -13,6 +13,12 @@ export interface SocketError extends Error {
 export declare class PgSocket extends SafeEventEmitter {
     options: ConnectionConfiguration;
     private _state;
+    /**
+     * The socket-level error that is about to end this connection, kept so
+     * the 'close' that follows can say what happened instead of arriving
+     * bare. Cleared by _reset().
+     */
+    private _closeReason?;
     private _socket?;
     private _backend;
     private _frontend;
@@ -282,6 +288,7 @@ export declare class PgSocket extends SafeEventEmitter {
     /** Accepts this server, or drops it and moves to the next candidate. */
     protected _applySessionAttrs(wanted: string, standby: boolean, readOnly: boolean): void;
     protected _handleClose(): void;
+    private _buildCloseReason;
     protected _handleError(err: unknown): void;
     /** Rejects and clears every still-open capture, e.g. on close/error. */
     private _failPendingCaptures;

package/protocol/pg-socket.js

@@ -8,6 +8,7 @@ import { ConnectionState } from '../constants.js';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
 import { Backend } from './backend.js';
 import { signatureHashOfCertificate } from './cert-signature.js';
+import { ConnectionLostError } from './connection-lost-error.js';
 import { DatabaseError } from './database-error.js';
 import { Frontend } from './frontend.js';
 import { Protocol } from './protocol.js';
@@ -17,6 +18,12 @@ const COMMAND_RESULT_PATTERN = /^([^\d]+)(?: (\d+)(?: (\d+))?)?$/;
 export class PgSocket extends SafeEventEmitter {
     options;
     _state = ConnectionState.CLOSED;
+    /**
+     * The socket-level error that is about to end this connection, kept so
+     * the 'close' that follows can say what happened instead of arriving
+     * bare. Cleared by _reset().
+     */
+    _closeReason;
     _socket;
     _backend = new Backend();
     _frontend;
@@ -532,6 +539,7 @@ export class PgSocket extends SafeEventEmitter {
         this._socket.removeAllListeners('close');
     }
     _reset() {
+        this._closeReason = undefined;
         this._backend.reset();
         this._sessionParameters = {};
         this._processID = undefined;
@@ -627,14 +635,30 @@ export class PgSocket extends SafeEventEmitter {
         this._connectToHost();
     }
     _handleClose() {
+        // close() is the only thing that sets CLOSING, so anything else here
+        // is the far end going away on its own - an admin terminating the
+        // backend, a failover, a network fault. Built before _reset() clears
+        // the process id, which is the one detail that makes the report
+        // actionable, and carrying the socket error as its cause when there
+        // was one (a bare FIN leaves none).
+        const reason = this._state === ConnectionState.CLOSING
+            ? undefined
+            : this._buildCloseReason();
         this._failPendingCaptures(new Error('Connection closed'));
         this._reset();
         this._socket = undefined;
         this._state = ConnectionState.CLOSED;
-        this.emit('close');
+        this.emit('close', reason);
+    }
+    _buildCloseReason() {
+        return new ConnectionLostError(this._processID, this._closeReason);
     }
     _handleError(err) {
-        this._failPendingCaptures(err instanceof Error ? err : new Error(String(err)));
+        // Kept for the 'close' that follows: the socket reports the cause
+        // here and the fact of closing separately, and only the pair together
+        // says what actually happened.
+        this._closeReason = err instanceof Error ? err : new Error(String(err));
+        this._failPendingCaptures(this._closeReason);
         if (this._state !== ConnectionState.READY) {
             this._socket?.end();
         }