postgrejs 3.0.4 → 3.1.0

package/CHANGELOG.md

@@ -1,6 +1,17 @@
 ## Changelog
 
-### [v3.0.4](https://github.com/panates/postgrejs/compare/v3.0.3...v3.0.4) - 
+### [v3.1.0](https://github.com/panates/postgrejs/compare/v3.0.4...v3.1.0) - 
+
+#### 🚀 New Features
+
+- feat: implement the legacy Function Call sub-protocol ('F'/'V') @Eray Hanoğlu 
+- feat: support protocol 3.2's longer cancellation key (PostgreSQL 18+) @Eray Hanoğlu 
+
+#### 🪲 Fixes
+
+- fix: correctly parse NegotiateProtocolVersion and expose it on Connection @Eray Hanoğlu 
+
+### [v3.0.4](https://github.com/panates/postgrejs/compare/v3.0.3...v3.0.4) -  9 September 2026 
 
 ### [v3.0.3](https://github.com/panates/postgrejs/compare/v3.0.2...v3.0.3) -  8 September 2026 
 

package/README.md

@@ -100,12 +100,18 @@ usage.
 - **Resource Management:** Auto disposal of resources with the "using" syntax
   ([TC39 Explicit Resource Management](https://github.com/tc39/proposal-explicit-resource-management)), ensuring
   efficient resource cleanup.
+- **Long Cancel Key:** Opt in to protocol 3.2 (PostgreSQL 18+) with `longCancelKey`, so a `cancel()` in progress can't
+  be forged by an attacker guessing a short secret key.
+- **Legacy Function Call Protocol:** `callFunction()` calls a function by OID directly over the wire, bypassing SQL
+  entirely - kept for protocol completeness even though `SELECT func(...)` covers the same ground.
+- **Graceful Protocol Renegotiation:** A server that doesn't recognize a requested protocol version or startup option
+  reports back instead of erroring out, surfaced on `Connection.protocolNegotiation`.
 
 ## Feature Comparison
 
 How PostgreJS compares to [`pg`](https://github.com/brianc/node-postgres) (node-postgres) and
 [`postgres`](https://github.com/porsager/postgres) (postgres.js). Every row was checked against the libraries' own
-source rather than their documentation — versions compared: **PostgreJS 2.23.1, pg 8.23.0, postgres.js 3.4.9**. ✅ built
+source rather than their documentation — versions compared: **PostgreJS 3.1.0, pg 8.23.0, postgres.js 3.4.9**. ✅ built
 in · 🟡 partial or needs a separate package · ❌ not supported.
 
 | Feature                           |       PostgreJS        |          pg           |   postgres.js    |
@@ -115,11 +121,15 @@ in · 🟡 partial or needs a separate package · ❌ not supported.
 | Module system                     |          ESM           |        ESM/CJS        |     ESM/CJS      |
 | Language                          |           TS           |    JS <sup>2</sup>    | JS <sup>3</sup>  |
 | ***Wire protocol***               |                        |                       |                  |
+| Protocol version                  |          3.2           |          3.0          |       3.0        |
 | Simple Query protocol             |           ✅           |          ✅           |        ✅        |
 | Extended Query protocol           |           ✅           |          ✅           |        ✅        |
 | Text wire format                  |           ✅           |          ✅           |        ✅        |
 | Binary wire format                |           ✅           |    🟡 <sup>4</sup>    | ❌ <sup>5</sup>  |
 | Per-column format selection       |           ✅           |          ❌           |        ❌        |
+| Long cancel key (opt-in)          |           ✅           |          ❌           |        ❌        |
+| Legacy Function Call protocol     |           ✅           |          ❌           |        ❌        |
+| Graceful protocol renegotiation   |           ✅           |          ❌           |        ❌        |
 | ***High-level API***              |                        |                       |                  |
 | Object and array row modes        |           ✅           |          ✅           |        ✅        |
 | Dynamic SQL helpers               |      ✅ `sql` tag      |          ❌           |        ✅        |

package/connection/connection.d.ts

@@ -1,5 +1,7 @@
 import { ConnectionState } from '../constants.js';
 import type { ConnectionConfiguration } from '../interfaces/database-connection-params.js';
+import type { FunctionCallOptions } from '../interfaces/function-call-options.js';
+import type { FunctionCallResult } from '../interfaces/function-call-result.js';
 import type { QueryOptions } from '../interfaces/query-options.js';
 import type { QueryResult } from '../interfaces/query-result.js';
 import type { ScriptExecuteOptions } from '../interfaces/script-execute-options.js';
@@ -8,7 +10,7 @@ import type { StatementPrepareOptions } from '../interfaces/statement-prepare-op
 import type { DatabaseError } from '../protocol/database-error.js';
 import type { Protocol } from '../protocol/protocol.js';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
-import type { Maybe } from '../types.js';
+import type { Maybe, OID } from '../types.js';
 import { QueryRequest } from '../util/sql-tag.js';
 import type { CopyFromStream, CopyToStream } from './copy-stream.js';
 import { IntlConnection } from './intl-connection.js';
@@ -44,10 +46,20 @@ export declare class Connection extends SafeEventEmitter implements AsyncDisposa
      * Returns information parameters for the current session
      */
     get sessionParameters(): Record<string, string>;
+    /**
+     * The server's NegotiateProtocolVersion reply, if it sent one during
+     * connect() - undefined means the server fully recognized everything
+     * this client's startup packet asked for (protocol minor version, any
+     * `_pq_.*` options). Present only when the server is older/stricter
+     * than what was requested, or didn't recognize one of the options -
+     * check it after connect() if a feature gated behind such an option
+     * doesn't seem to have taken effect.
+     */
+    get protocolNegotiation(): Maybe<Protocol.NegotiateProtocolVersionMessage>;
     /**
      * Returns the secret key of the current session
      */
-    get secretKey(): Maybe<number>;
+    get secretKey(): Maybe<Buffer>;
     get runningQueryCount(): number;
     /**
      * Connects to the server
@@ -68,6 +80,23 @@ export declare class Connection extends SafeEventEmitter implements AsyncDisposa
      * @param options {ScriptExecuteOptions} - Execute options
      */
     execute(sql: string | QueryRequest, options?: ScriptExecuteOptions): Promise<ScriptResult>;
+    /**
+     * The legacy Function Call sub-protocol - calls a function by OID
+     * directly, bypassing SQL entirely. Superseded by `SELECT func(...)`
+     * over the Simple/Extended Query protocols (what `execute()`/`query()`
+     * use, and what every current PostgreSQL client uses exclusively) -
+     * kept only for wire-protocol completeness. Arguments and the result
+     * travel as raw wire-format bytes, not JS values: the caller is
+     * responsible for encoding/decoding them (see a `DataType`'s own
+     * `encodeBinary`/`decodeBinary` for the format a given OID expects).
+     *
+     * @param functionId - OID of the function to call
+     * @param args - Each argument's own already-encoded wire bytes, or
+     *   `null` for SQL NULL
+     */
+    callFunction(functionId: OID, args: Maybe<Buffer>[], options?: FunctionCallOptions & {
+        signal?: AbortSignal;
+    }): Promise<FunctionCallResult>;
     query(sql: string | QueryRequest, options?: QueryOptions): Promise<QueryResult>;
     /**
      * Runs a `COPY ... TO STDOUT` and returns its output as a stream of the

package/connection/connection.js

@@ -56,6 +56,18 @@ export class Connection extends SafeEventEmitter {
     get sessionParameters() {
         return this._intlCon.sessionParameters;
     }
+    /**
+     * The server's NegotiateProtocolVersion reply, if it sent one during
+     * connect() - undefined means the server fully recognized everything
+     * this client's startup packet asked for (protocol minor version, any
+     * `_pq_.*` options). Present only when the server is older/stricter
+     * than what was requested, or didn't recognize one of the options -
+     * check it after connect() if a feature gated behind such an option
+     * doesn't seem to have taken effect.
+     */
+    get protocolNegotiation() {
+        return this._intlCon.protocolNegotiation;
+    }
     /**
      * Returns the secret key of the current session
      */
@@ -146,6 +158,23 @@ export class Connection extends SafeEventEmitter {
             throw this._handleError(e, sql);
         }));
     }
+    /**
+     * The legacy Function Call sub-protocol - calls a function by OID
+     * directly, bypassing SQL entirely. Superseded by `SELECT func(...)`
+     * over the Simple/Extended Query protocols (what `execute()`/`query()`
+     * use, and what every current PostgreSQL client uses exclusively) -
+     * kept only for wire-protocol completeness. Arguments and the result
+     * travel as raw wire-format bytes, not JS values: the caller is
+     * responsible for encoding/decoding them (see a `DataType`'s own
+     * `encodeBinary`/`decodeBinary` for the format a given OID expects).
+     *
+     * @param functionId - OID of the function to call
+     * @param args - Each argument's own already-encoded wire bytes, or
+     *   `null` for SQL NULL
+     */
+    callFunction(functionId, args, options) {
+        return withAbortSignal(options?.signal, () => this._intlCon.cancel(), () => this._captureErrorStack(this._intlCon.callFunction(functionId, args, options), this.callFunction));
+    }
     async query(sql, options) {
         if (sql instanceof QueryRequest) {
             if (options?.params)

package/connection/intl-connection.d.ts

@@ -1,5 +1,7 @@
 import { ConnectionState } from '../constants.js';
 import type { ConnectionConfiguration } from '../interfaces/database-connection-params.js';
+import type { FunctionCallOptions } from '../interfaces/function-call-options.js';
+import type { FunctionCallResult } from '../interfaces/function-call-result.js';
 import type { QueryOptions } from '../interfaces/query-options.js';
 import type { QueryResult } from '../interfaces/query-result.js';
 import type { ScriptExecuteOptions } from '../interfaces/script-execute-options.js';
@@ -27,11 +29,25 @@ export declare class IntlConnection extends SafeEventEmitter {
     get state(): ConnectionState;
     get refCount(): number;
     get processID(): Maybe<number>;
-    get secretKey(): Maybe<number>;
+    get secretKey(): Maybe<Buffer>;
+    /** See `PgSocket.protocolNegotiation`. */
+    get protocolNegotiation(): Maybe<Protocol.NegotiateProtocolVersionMessage>;
     get sessionParameters(): Record<string, string>;
     connect(): Promise<void>;
     close(): Promise<void>;
     execute(sql: string, options?: ScriptExecuteOptions, cb?: (event: string, ...args: any[]) => void): Promise<ScriptResult>;
+    /**
+     * The legacy Function Call sub-protocol: calls a function by OID
+     * directly, bypassing SQL entirely. PostgreSQL itself calls this
+     * superseded by `SELECT func(...)` over the Simple/Extended Query
+     * protocols (what this driver uses everywhere else, and what every
+     * other current client uses exclusively) - kept only for wire-protocol
+     * completeness. Arguments and the result travel as raw wire-format
+     * bytes rather than through this driver's usual typed encode/decode
+     * pipeline - the caller is responsible for both (see a `DataType`'s own
+     * `encodeBinary`/`decodeBinary` for the format a given OID expects).
+     */
+    callFunction(functionId: OID, args: Maybe<Buffer>[], options?: FunctionCallOptions): Promise<FunctionCallResult>;
     /**
      * Starts a transaction, or - if one is already running - marks a nested
      * level of it. Each call increments `_transactionDepth`; only the

package/connection/intl-connection.js

@@ -64,6 +64,10 @@ export class IntlConnection extends SafeEventEmitter {
     get secretKey() {
         return this.socket.secretKey;
     }
+    /** See `PgSocket.protocolNegotiation`. */
+    get protocolNegotiation() {
+        return this.socket.protocolNegotiation;
+    }
     get sessionParameters() {
         return this.socket.sessionParameters;
     }
@@ -156,6 +160,53 @@ export class IntlConnection extends SafeEventEmitter {
             throw e;
         }
     }
+    /**
+     * The legacy Function Call sub-protocol: calls a function by OID
+     * directly, bypassing SQL entirely. PostgreSQL itself calls this
+     * superseded by `SELECT func(...)` over the Simple/Extended Query
+     * protocols (what this driver uses everywhere else, and what every
+     * other current client uses exclusively) - kept only for wire-protocol
+     * completeness. Arguments and the result travel as raw wire-format
+     * bytes rather than through this driver's usual typed encode/decode
+     * pipeline - the caller is responsible for both (see a `DataType`'s own
+     * `encodeBinary`/`decodeBinary` for the format a given OID expects).
+     */
+    async callFunction(functionId, args, options = {}) {
+        this.assertConnected();
+        this.ref();
+        try {
+            let result;
+            let error;
+            return await this.socket.sendFunctionCallMessage({
+                functionId,
+                args,
+                argFormats: options.argFormats,
+                resultFormat: options.resultFormat,
+            }, (code, msg, done) => {
+                switch (code) {
+                    case Protocol.BackendMessageCode.ErrorResponse:
+                        error = msg;
+                        break;
+                    case Protocol.BackendMessageCode.FunctionCallResponse:
+                        result = msg;
+                        break;
+                    case Protocol.BackendMessageCode.ReadyForQuery:
+                        this.transactionStatus = msg.status;
+                        if (error) {
+                            done(error);
+                            break;
+                        }
+                        done(undefined, result);
+                        break;
+                    default:
+                        break;
+                }
+            });
+        }
+        finally {
+            this.unref();
+        }
+    }
     /**
      * Starts a transaction, or - if one is already running - marks a nested
      * level of it. Each call increments `_transactionDepth`; only the

package/index.d.ts

@@ -13,6 +13,8 @@ export * from './interfaces/data-mapping-options.js';
 export * from './interfaces/data-type.js';
 export * from './interfaces/database-connection-params.js';
 export * from './interfaces/field-info.js';
+export * from './interfaces/function-call-options.js';
+export * from './interfaces/function-call-result.js';
 export * from './interfaces/query-options.js';
 export * from './interfaces/query-result.js';
 export * from './interfaces/script-execute-options.js';

package/index.js

@@ -13,6 +13,8 @@ export * from './interfaces/data-mapping-options.js';
 export * from './interfaces/data-type.js';
 export * from './interfaces/database-connection-params.js';
 export * from './interfaces/field-info.js';
+export * from './interfaces/function-call-options.js';
+export * from './interfaces/function-call-result.js';
 export * from './interfaces/query-options.js';
 export * from './interfaces/query-result.js';
 export * from './interfaces/script-execute-options.js';

package/interfaces/database-connection-params.d.ts

@@ -61,6 +61,18 @@ export interface DatabaseConnectionParams {
      * usual case with `sslmode=require` or a self-signed certificate.
      */
     channelBinding?: 'prefer' | 'require' | 'disable';
+    /**
+     * Requests protocol 3.2 (PostgreSQL 18+) instead of 3.0, so a
+     * `cancel()` in progress on this connection can't be forged by an
+     * attacker guessing a 4-byte secret key - 3.2 lets the server hand out
+     * one up to 256 bytes instead. Off by default: an older server simply
+     * reports back that it doesn't support 3.2 (see
+     * `Connection.protocolNegotiation`) and the session proceeds at 3.0
+     * exactly as if this had never been set, so turning it on is never a
+     * connection-breaking choice - just not something every server rewards
+     * yet.
+     */
+    longCancelKey?: boolean;
     requireSSL?: boolean;
     ssl?: TlsConnectionOptions;
     timezone?: string;

package/interfaces/function-call-options.d.ts

@@ -0,0 +1,14 @@
+import type { DataFormat } from '../constants.js';
+export interface FunctionCallOptions {
+    /**
+     * Format of each argument, applied positionally - omit for text (the
+     * default) applied to every argument, a single entry to apply it to all
+     * of them, or one entry per argument.
+     */
+    argFormats?: DataFormat[];
+    /**
+     * Format the function's return value comes back in.
+     * @default DataFormat.text
+     */
+    resultFormat?: DataFormat;
+}

package/interfaces/function-call-options.js

@@ -0,0 +1 @@
+export {};

package/interfaces/function-call-result.d.ts

@@ -0,0 +1,7 @@
+export interface FunctionCallResult {
+    /**
+     * The function's return value, in the wire format requested via
+     * `FunctionCallOptions.resultFormat` - `null` if it returned SQL NULL.
+     */
+    result: Buffer | null;
+}

package/interfaces/function-call-result.js

@@ -0,0 +1 @@
+export {};

package/package.json

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

package/protocol/backend.js

@@ -169,10 +169,13 @@ function parseAuthentication(io, code, len) {
     }
 }
 function parseBackendKeyData(io) {
-    return {
-        processID: io.readUInt32BE(),
-        secretKey: io.readUInt32BE(),
-    };
+    const processID = io.readUInt32BE();
+    // No length prefix of its own: this BufferReader is scoped to exactly
+    // this message's body (see Backend.parse()), so the secret key is
+    // simply whatever bytes remain - 4 of them before protocol 3.2, up to
+    // 256 with it (see VERSION_MINOR_LONG_CANCEL_KEY).
+    const secretKey = io.readBuffer();
+    return { processID, secretKey };
 }
 function parseCommandComplete(io) {
     return {
@@ -226,17 +229,21 @@ function parseNotificationResponse(io) {
         payload: io.readCString(),
     };
 }
-function parseFunctionCallResponse(io, code, len) {
-    return {
-        result: io.readBuffer(len - 4),
-    };
+function parseFunctionCallResponse(io) {
+    // A length prefix ahead of the value itself (-1 for SQL NULL, with no
+    // bytes following) - not deducible from the outer message length alone,
+    // unlike most fixed-shape messages this codebase parses.
+    const len = io.readInt32BE();
+    return { result: len < 0 ? null : io.readBuffer(len) };
 }
 function parseNegotiateProtocolVersion(io) {
-    return {
-        supportedVersionMinor: io.readUInt32BE(),
-        numberOfNotSupportedVersions: io.readUInt32BE(),
-        option: io.readCString('utf8'),
-    };
+    const supportedVersionMinor = io.readUInt32BE();
+    const count = io.readUInt32BE();
+    const unrecognizedOptions = new Array(count);
+    let i;
+    for (i = 0; i < count; i++)
+        unrecognizedOptions[i] = io.readCString('utf8');
+    return { supportedVersionMinor, unrecognizedOptions };
 }
 function parseParameterDescription(io) {
     const out = {

package/protocol/frontend.d.ts

@@ -1,6 +1,7 @@
 import { DataTypeMap } from '../data-type-map.js';
 import type { QueryOptions } from '../interfaces/query-options.js';
 import type { Maybe, OID } from '../types.js';
+import { Protocol } from './protocol.js';
 import type { SASL } from './sasl.js';
 import { type SmartBufferConfig } from './smart-buffer.js';
 export interface FrontendOptions {
@@ -37,19 +38,42 @@ export declare namespace Frontend {
         type: 'P' | 'S';
         name?: string;
     }
+    /**
+     * The legacy Function Call sub-protocol - calls a function by OID
+     * directly, bypassing SQL entirely. Superseded by `SELECT func(...)`
+     * over the Simple/Extended Query protocols (which every current
+     * PostgreSQL client, this one included for everything else, uses
+     * exclusively) - kept only for wire-protocol completeness. Arguments
+     * and the result travel as raw wire-format bytes, not JS values: the
+     * caller is responsible for encoding/decoding them (see a `DataType`'s
+     * own `encodeBinary`/`decodeBinary` for the format a given OID expects).
+     */
+    interface FunctionCallMessageArgs {
+        functionId: OID;
+        /**
+         * Format of each argument in `args`, applied positionally - empty
+         * means text for all of them, a single entry applies to all, or it
+         * must have exactly one entry per argument.
+         */
+        argFormats?: Protocol.DataFormat[];
+        /** `null` for an SQL NULL argument. */
+        args: Maybe<Buffer>[];
+        /** Format the function's return value comes back in. @default text */
+        resultFormat?: Protocol.DataFormat;
+    }
 }
 export declare class Frontend {
     private _io;
     constructor(options?: FrontendOptions);
     getSSLRequestMessage(): Buffer;
-    getStartupMessage(args: Frontend.StartupMessageArgs): Buffer;
+    getStartupMessage(args: Frontend.StartupMessageArgs, minorVersion?: number): Buffer;
     /**
      * Asks the server to cancel whatever the given session is currently
      * running. Sent on its own fresh connection - a backend busy with a query
      * is not reading its own socket, which is the whole reason this cannot go
      * down the normal one.
      */
-    getCancelRequestMessage(processID: number, secretKey: number): Buffer;
+    getCancelRequestMessage(processID: number, secretKey: Buffer): Buffer;
     getPasswordMessage(password: string): Buffer;
     getSASLMessage(sasl: SASL.Session): Buffer;
     getSASLFinalMessage(session: SASL.Session): Buffer;
@@ -59,6 +83,7 @@ export declare class Frontend {
     getExecuteMessage(args: Frontend.ExecuteMessageArgs): Buffer;
     getCloseMessage(args: Frontend.CloseMessageArgs): Buffer;
     getQueryMessage(sql: string): Buffer;
+    getFunctionCallMessage(args: Frontend.FunctionCallMessageArgs): Buffer;
     /**
      * Returns the CopyData header and the caller's payload as two buffers
      * rather than one, so a bulk import never copies the caller's bytes.

package/protocol/frontend.js

@@ -46,12 +46,12 @@ export class Frontend {
             .writeUInt16BE(5679)
             .flush();
     }
-    getStartupMessage(args) {
+    getStartupMessage(args, minorVersion = Protocol.VERSION_MINOR) {
         const io = this._io
             .start()
             .writeInt32BE(0) // Preserve length
             .writeInt16BE(Protocol.VERSION_MAJOR)
-            .writeInt16BE(Protocol.VERSION_MINOR);
+            .writeInt16BE(minorVersion);
         const entries = Object.entries(args);
         const l = entries.length;
         let k;
@@ -75,11 +75,11 @@ export class Frontend {
     getCancelRequestMessage(processID, secretKey) {
         return this._io
             .start()
-            .writeUInt32BE(16) // Length of message contents in bytes, including self.
+            .writeUInt32BE(12 + secretKey.length) // Length of message contents in bytes, including self.
             .writeUInt16BE(1234)
             .writeUInt16BE(5678)
             .writeUInt32BE(processID)
-            .writeUInt32BE(secretKey)
+            .writeBuffer(secretKey)
             .flush();
     }
     getPasswordMessage(password) {
@@ -273,6 +273,32 @@ export class Frontend {
             .writeCString(sql || '', 'utf8');
         return setLengthAndFlush(io, 1);
     }
+    getFunctionCallMessage(args) {
+        const { functionId, args: values, argFormats, resultFormat } = args;
+        const formats = argFormats || [];
+        const fl = formats.length;
+        const l = values.length;
+        let i;
+        const io = this._io
+            .start()
+            .writeInt8(Protocol.FrontendMessageCode.FunctionCall)
+            .writeInt32BE(0) // Preserve header
+            .writeInt32BE(functionId)
+            .writeInt16BE(fl);
+        for (i = 0; i < fl; i++)
+            io.writeInt16BE(formats[i]);
+        io.writeInt16BE(l);
+        let v;
+        for (i = 0; i < l; i++) {
+            v = values[i];
+            if (v == null)
+                io.writeInt32BE(-1);
+            else
+                io.writeInt32BE(v.length).writeBuffer(v);
+        }
+        io.writeInt16BE(resultFormat ?? DataFormat.text);
+        return setLengthAndFlush(io, 1);
+    }
     /**
      * Returns the CopyData header and the caller's payload as two buffers
      * rather than one, so a bulk import never copies the caller's bytes.

package/protocol/pg-socket.d.ts

@@ -20,6 +20,7 @@ export declare class PgSocket extends SafeEventEmitter {
     private _saslSession?;
     private _processID?;
     private _secretKey?;
+    private _protocolNegotiation?;
     private _captureQueue;
     private _pendingWrites;
     private _flushScheduled;
@@ -30,7 +31,15 @@ export declare class PgSocket extends SafeEventEmitter {
     constructor(options: ConnectionConfiguration);
     get state(): ConnectionState;
     get processID(): Maybe<number>;
-    get secretKey(): Maybe<number>;
+    get secretKey(): Maybe<Buffer>;
+    /**
+     * The server's NegotiateProtocolVersion reply, if it sent one -
+     * undefined means everything this client asked for in its startup
+     * packet (protocol minor version, any `_pq_.*` options) was fully
+     * recognized. Present only when the server is older/stricter than what
+     * was requested, or didn't recognize one of the startup options.
+     */
+    get protocolNegotiation(): Maybe<Protocol.NegotiateProtocolVersionMessage>;
     get sessionParameters(): Record<string, string>;
     connect(): void;
     protected _connectToHost(): void;
@@ -71,6 +80,8 @@ export declare class PgSocket extends SafeEventEmitter {
     close(): void;
     sendExecuteMessage(args: Frontend.ExecuteMessageArgs, cb: CaptureCallback): Promise<any>;
     sendCloseMessage(args: Frontend.CloseMessageArgs, cb: CaptureCallback): Promise<any>;
+    /** The legacy Function Call sub-protocol - see `Frontend.FunctionCallMessageArgs`. */
+    sendFunctionCallMessage(args: Frontend.FunctionCallMessageArgs, cb: CaptureCallback): Promise<any>;
     /**
      * Sends Parse+Bind+Describe+Execute+Sync as a single write with a single
      * FIFO capture entry, instead of 5 separate sendXMessage() round trips -
@@ -221,6 +232,7 @@ export declare class PgSocket extends SafeEventEmitter {
      */
     protected _channelBindingData(socket: tls.TLSSocket): Buffer;
     protected _handleParameterStatus(msg: Protocol.ParameterStatusMessage): void;
+    protected _handleNegotiateProtocolVersion(msg: Protocol.NegotiateProtocolVersionMessage): void;
     protected _handleBackendKeyData(msg: Protocol.BackendKeyDataMessage): void;
     protected _handleCommandComplete(msg: any): Protocol.CommandCompleteMessage;
     /**

package/protocol/pg-socket.js

@@ -24,6 +24,7 @@ export class PgSocket extends SafeEventEmitter {
     _saslSession;
     _processID;
     _secretKey;
+    _protocolNegotiation;
     _captureQueue = new DoublyLinked();
     _pendingWrites = [];
     _flushScheduled = false;
@@ -48,6 +49,16 @@ export class PgSocket extends SafeEventEmitter {
     get secretKey() {
         return this._secretKey;
     }
+    /**
+     * The server's NegotiateProtocolVersion reply, if it sent one -
+     * undefined means everything this client asked for in its startup
+     * packet (protocol minor version, any `_pq_.*` options) was fully
+     * recognized. Present only when the server is older/stricter than what
+     * was requested, or didn't recognize one of the startup options.
+     */
+    get protocolNegotiation() {
+        return this._protocolNegotiation;
+    }
     get sessionParameters() {
         return this._sessionParameters;
     }
@@ -216,6 +227,10 @@ export class PgSocket extends SafeEventEmitter {
     sendCloseMessage(args, cb) {
         return this._sendAndCapture(this._frontend.getCloseMessage(args), cb, 'sendCloseMessage', args);
     }
+    /** The legacy Function Call sub-protocol - see `Frontend.FunctionCallMessageArgs`. */
+    sendFunctionCallMessage(args, cb) {
+        return this._sendAndCapture(this._frontend.getFunctionCallMessage(args), cb, 'sendFunctionCallMessage', args);
+    }
     /**
      * Sends Parse+Bind+Describe+Execute+Sync as a single write with a single
      * FIFO capture entry, instead of 5 separate sendXMessage() round trips -
@@ -426,7 +441,9 @@ export class PgSocket extends SafeEventEmitter {
             ...(this.options.replication
                 ? { replication: this.options.replication }
                 : undefined),
-        }));
+        }, this.options.longCancelKey
+            ? Protocol.VERSION_MINOR_LONG_CANCEL_KEY
+            : undefined));
     }
     /**
      * Called once the server is ready. With `targetSessionAttrs` set, the
@@ -535,6 +552,9 @@ export class PgSocket extends SafeEventEmitter {
                     case Protocol.BackendMessageCode.ParameterStatus:
                         this._handleParameterStatus(payload);
                         break;
+                    case Protocol.BackendMessageCode.NegotiateProtocolVersion:
+                        this._handleNegotiateProtocolVersion(payload);
+                        break;
                     case Protocol.BackendMessageCode.BackendKeyData:
                         this._handleBackendKeyData(payload);
                         break;
@@ -688,6 +708,21 @@ export class PgSocket extends SafeEventEmitter {
     _handleParameterStatus(msg) {
         this._sessionParameters[msg.name] = msg.value;
     }
+    _handleNegotiateProtocolVersion(msg) {
+        this._protocolNegotiation = msg;
+        /* c8 ignore start */
+        if (this.listenerCount('debug')) {
+            this.emit('debug', {
+                location: 'PgSocket._handleNegotiateProtocolVersion',
+                message: `server supports protocol 3.${msg.supportedVersionMinor}` +
+                    (msg.unrecognizedOptions.length
+                        ? `; did not recognize startup option(s): ${msg.unrecognizedOptions.join(', ')}`
+                        : ''),
+                ...msg,
+            });
+        }
+        /* c8 ignore stop */
+    }
     _handleBackendKeyData(msg) {
         this._processID = msg.processID;
         this._secretKey = msg.secretKey;

package/protocol/protocol.d.ts

@@ -1,6 +1,16 @@
 export declare namespace Protocol {
     const VERSION_MAJOR = 3;
     const VERSION_MINOR = 0;
+    /**
+     * Minor version 3.2 (PostgreSQL 18+) differs from 3.0 only in that
+     * BackendKeyData's secret key - and so CancelRequest's - can be up to
+     * 256 bytes instead of always exactly 4. A server that doesn't support
+     * 3.2 replies with NegotiateProtocolVersion naming the highest minor
+     * version it does support (see `PgSocket.protocolNegotiation`) and the
+     * session simply proceeds at that version instead - requesting 3.2 is
+     * never a connection-breaking choice, only ever a possible no-op.
+     */
+    const VERSION_MINOR_LONG_CANCEL_KEY = 2;
     enum BackendMessageCode {
         Authentication = 82,// R
         BackendKeyData = 75,// K
@@ -99,7 +109,14 @@ export declare namespace Protocol {
     }
     interface BackendKeyDataMessage {
         processID: number;
-        secretKey: number;
+        /**
+         * Always 4 bytes before protocol 3.2, up to 256 with it - see
+         * `VERSION_MINOR_LONG_CANCEL_KEY`. Not a fixed-width int, unlike
+         * before: the field carries whatever bytes the server sent, in
+         * whatever order it sent them, to be relayed back to CancelRequest
+         * unchanged rather than interpreted as a number.
+         */
+        secretKey: Buffer;
     }
     interface CommandCompleteMessage {
         command: string;
@@ -145,12 +162,18 @@ export declare namespace Protocol {
         payload: string;
     }
     interface FunctionCallResponseMessage {
-        result: Buffer;
+        /** `null` when the function returned SQL NULL. */
+        result: Buffer | null;
     }
     interface NegotiateProtocolVersionMessage {
+        /** Newest minor protocol version the server supports. */
         supportedVersionMinor: number;
-        numberOfNotSupportedVersions: number;
-        option: string;
+        /**
+         * Startup packet options this client sent that the server didn't
+         * recognize - empty when the only mismatch is the protocol minor
+         * version itself.
+         */
+        unrecognizedOptions: string[];
     }
     interface ParameterDescriptionMessage {
         parameterCount: number;

package/protocol/protocol.js

@@ -2,6 +2,16 @@ export var Protocol;
 (function (Protocol) {
     Protocol.VERSION_MAJOR = 3;
     Protocol.VERSION_MINOR = 0;
+    /**
+     * Minor version 3.2 (PostgreSQL 18+) differs from 3.0 only in that
+     * BackendKeyData's secret key - and so CancelRequest's - can be up to
+     * 256 bytes instead of always exactly 4. A server that doesn't support
+     * 3.2 replies with NegotiateProtocolVersion naming the highest minor
+     * version it does support (see `PgSocket.protocolNegotiation`) and the
+     * session simply proceeds at that version instead - requesting 3.2 is
+     * never a connection-breaking choice, only ever a possible no-op.
+     */
+    Protocol.VERSION_MINOR_LONG_CANCEL_KEY = 2;
     // https://www.postgresql.org/docs/9.3/protocol-message-formats.html
     let BackendMessageCode;
     (function (BackendMessageCode) {