postgrejs 2.23.0 → 3.0.1

package/protocol/buffer-reader.d.ts

@@ -11,7 +11,5 @@ export declare class BufferReader {
     readCString(encoding?: BufferEncoding): string;
     readLString(len: number, encoding?: BufferEncoding): string | null;
     readBuffer(len?: number): Buffer;
-    moveBy(n: number): this;
-    moveTo(pos: number): this;
     private _checkReadable;
 }

package/protocol/buffer-reader.js

@@ -39,6 +39,8 @@ export class BufferReader {
     }
     readCString(encoding) {
         const idx = this.buffer.indexOf(0, this.offset);
+        if (idx === -1)
+            throw new Error('Eof in buffer detected (readCString)');
         const v = this.buffer.toString(encoding, this.offset, idx);
         this.offset = idx + 1;
         return v;
@@ -55,19 +57,10 @@ export class BufferReader {
         if (len)
             this._checkReadable(len);
         const end = len !== undefined ? this.offset + len : this.length;
-        const buf = this.buffer.slice(this.offset, end);
+        const buf = this.buffer.subarray(this.offset, end);
         this.offset = end;
         return buf;
     }
-    moveBy(n) {
-        return this.moveTo(this.offset + n);
-    }
-    moveTo(pos) {
-        if (pos >= this.length)
-            throw new Error('Eof in buffer detected');
-        this.offset = pos;
-        return this;
-    }
     _checkReadable(size) {
         if (this.offset + size - 1 >= this.length)
             throw new Error('Eof in buffer detected');

package/protocol/cert-signature.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Finds the hash a certificate was signed with, which is the hash
+ * `tls-server-end-point` channel binding has to use (RFC 5929).
+ *
+ * Node exposes a certificate's SHA-1, SHA-256 and SHA-512 fingerprints but
+ * not the algorithm it was signed with, and X509Certificate.toLegacyObject()
+ * does not carry it either - so the DER has to be read. Only as far as the
+ * signature algorithm's OID: a Certificate is a SEQUENCE of tbsCertificate,
+ * signatureAlgorithm and signatureValue, so this skips the first and reads
+ * the OID out of the second.
+ */
+export declare function signatureHashOfCertificate(der: Buffer): string;

package/protocol/cert-signature.js

@@ -0,0 +1,114 @@
+/**
+ * Finds the hash a certificate was signed with, which is the hash
+ * `tls-server-end-point` channel binding has to use (RFC 5929).
+ *
+ * Node exposes a certificate's SHA-1, SHA-256 and SHA-512 fingerprints but
+ * not the algorithm it was signed with, and X509Certificate.toLegacyObject()
+ * does not carry it either - so the DER has to be read. Only as far as the
+ * signature algorithm's OID: a Certificate is a SEQUENCE of tbsCertificate,
+ * signatureAlgorithm and signatureValue, so this skips the first and reads
+ * the OID out of the second.
+ */
+function readLength(data, index) {
+    let length = data[index++];
+    if (length < 0x80)
+        return { length, index };
+    const lengthBytes = length & 0x7f;
+    if (lengthBytes > 4)
+        throw certError('length field too large', data);
+    length = 0;
+    for (let i = 0; i < lengthBytes; i++)
+        length = (length << 8) | data[index++];
+    return { length, index };
+}
+function expectSequence(data, index) {
+    if (data[index++] !== 0x30)
+        throw certError('expected a SEQUENCE', data);
+    return { index: readLength(data, index).index };
+}
+function readOID(data, index) {
+    if (data[index++] !== 0x06)
+        throw certError('expected an OID', data);
+    const { length, index: start } = readLength(data, index);
+    index = start;
+    const end = index + length;
+    // The first byte packs the first two arcs as 40 * a + b.
+    const first = data[index++];
+    let oid = Math.floor(first / 40) + '.' + (first % 40);
+    let value = 0;
+    while (index < end) {
+        const byte = data[index++];
+        value = (value << 7) | (byte & 0x7f);
+        // The high bit marks a continuation, so an arc ends when it is clear.
+        if (!(byte & 0x80)) {
+            oid += '.' + value;
+            value = 0;
+        }
+    }
+    return { oid, index };
+}
+function certError(message, data) {
+    return new Error(`Channel binding: ${message} while reading the server certificate (${data.length} bytes)`);
+}
+// OID -> the Node hash name to feed createHash().
+const SIGNATURE_HASHES = {
+    // RSA
+    '1.2.840.113549.1.1.4': 'md5',
+    '1.2.840.113549.1.1.5': 'sha1',
+    '1.2.840.113549.1.1.11': 'sha256',
+    '1.2.840.113549.1.1.12': 'sha384',
+    '1.2.840.113549.1.1.13': 'sha512',
+    '1.2.840.113549.1.1.14': 'sha224',
+    '1.2.840.113549.1.1.15': 'sha512-224',
+    '1.2.840.113549.1.1.16': 'sha512-256',
+    // ECDSA
+    '1.2.840.10045.4.1': 'sha1',
+    '1.2.840.10045.4.3.1': 'sha224',
+    '1.2.840.10045.4.3.2': 'sha256',
+    '1.2.840.10045.4.3.3': 'sha384',
+    '1.2.840.10045.4.3.4': 'sha512',
+    // Ed25519, whose signature hashes with SHA-512.
+    '1.3.101.110': 'sha512',
+    '1.3.101.112': 'sha512',
+};
+// RSASSA-PSS names its hash separately, in the algorithm parameters.
+const PSS_HASHES = {
+    '1.2.840.113549.2.5': 'md5',
+    '1.3.14.3.2.26': 'sha1',
+    '2.16.840.1.101.3.4.2.1': 'sha256',
+    '2.16.840.1.101.3.4.2.2': 'sha384',
+    '2.16.840.1.101.3.4.2.3': 'sha512',
+};
+export function signatureHashOfCertificate(der) {
+    let index = expectSequence(der, 0).index; // Certificate
+    const tbs = readLength(der, index + 1); // tbsCertificate's own header
+    if (der[index] !== 0x30)
+        throw certError('expected tbsCertificate', der);
+    index = tbs.index + tbs.length; // skip it whole
+    index = expectSequence(der, index).index; // AlgorithmIdentifier
+    const { oid, index: afterOID } = readOID(der, index);
+    if (oid === '1.2.840.113549.1.1.10') {
+        // RSASSA-PSS: parameters SEQUENCE, then [0] holding the hash algorithm.
+        let i = expectSequence(der, afterOID).index;
+        if (der[i++] !== 0xa0)
+            throw certError('expected the PSS hash tag', der);
+        i = readLength(der, i).index;
+        i = expectSequence(der, i).index;
+        const { oid: hashOID } = readOID(der, i);
+        const hash = PSS_HASHES[hashOID];
+        if (!hash)
+            throw certError(`unknown PSS hash OID ${hashOID}`, der);
+        return upgradeWeak(hash);
+    }
+    const hash = SIGNATURE_HASHES[oid];
+    if (!hash) {
+        if (oid === '1.3.101.111' || oid === '1.3.101.113')
+            throw certError('Ed448 certificates are not supported by PostgreSQL', der);
+        throw certError(`unknown signature algorithm OID ${oid}`, der);
+    }
+    return upgradeWeak(hash);
+}
+/** RFC 5929: a certificate signed with MD5 or SHA-1 binds with SHA-256. */
+function upgradeWeak(hash) {
+    return hash === 'md5' || hash === 'sha1' ? 'sha256' : hash;
+}

package/protocol/database-error.js

@@ -1,3 +1,4 @@
+import { Protocol } from './protocol.js';
 export class DatabaseError extends Error {
     severity;
     code;

package/protocol/frontend.d.ts

@@ -43,6 +43,13 @@ export declare class Frontend {
     constructor(options?: FrontendOptions);
     getSSLRequestMessage(): Buffer;
     getStartupMessage(args: Frontend.StartupMessageArgs): 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;
     getPasswordMessage(password: string): Buffer;
     getSASLMessage(sasl: SASL.Session): Buffer;
     getSASLFinalMessage(session: SASL.Session): Buffer;
@@ -52,6 +59,15 @@ export declare class Frontend {
     getExecuteMessage(args: Frontend.ExecuteMessageArgs): Buffer;
     getCloseMessage(args: Frontend.CloseMessageArgs): Buffer;
     getQueryMessage(sql: string): 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.
+     * PgSocket writes an array of buffers as a single corked write anyway,
+     * so this costs nothing on the wire.
+     */
+    getCopyDataMessage(data: Buffer): Buffer[];
+    getCopyDoneMessage(): Buffer;
+    getCopyFailMessage(message: string): Buffer;
     getFlushMessage(): Buffer;
     getTerminateMessage(): Buffer;
     getSyncMessage(): Buffer;

package/protocol/frontend.js

@@ -1,4 +1,5 @@
 import { DEFAULT_COLUMN_FORMAT } from '../constants.js';
+import { DataTypeMap } from '../data-type-map.js';
 import { encodeBinaryArray } from '../util/encode-binaryarray.js';
 import { stringifyArrayLiteral } from '../util/stringify-arrayliteral.js';
 import { Protocol } from './protocol.js';
@@ -25,6 +26,13 @@ const StaticSyncBuffer = Buffer.from([
     0x00,
     0x04,
 ]);
+const StaticCopyDoneBuffer = Buffer.from([
+    Protocol.FrontendMessageCode.CopyDone,
+    0x00,
+    0x00,
+    0x00,
+    0x04,
+]);
 export class Frontend {
     _io;
     constructor(options) {
@@ -53,6 +61,22 @@ export class Frontend {
             .writeUInt8(0);
         return setLengthAndFlush(io, 0);
     }
+    /**
+     * 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, secretKey) {
+        return this._io
+            .start()
+            .writeUInt32BE(16) // Length of message contents in bytes, including self.
+            .writeUInt16BE(1234)
+            .writeUInt16BE(5678)
+            .writeUInt32BE(processID)
+            .writeUInt32BE(secretKey)
+            .flush();
+    }
     getPasswordMessage(password) {
         const io = this._io
             .start()
@@ -113,13 +137,16 @@ export class Frontend {
         if (params && params.length) {
             io.writeInt16BE(params.length);
             const formatOffset = io.offset;
-            for (let i = 0; i < params.length; i++) {
+            const l = params.length;
+            let i;
+            for (i = 0; i < l; i++) {
                 io.writeInt16BE(0); // Preserve
             }
             // Write parameter values
-            io.writeUInt16BE(params.length);
-            for (let i = 0; i < params?.length; i++) {
-                let v = params[i];
+            io.writeUInt16BE(l);
+            let v;
+            for (i = 0; i < l; i++) {
+                v = params[i];
                 if (v === null || v === undefined) {
                     io.writeInt32BE(-1);
                     continue;
@@ -174,8 +201,10 @@ export class Frontend {
             io.writeUInt16BE(0);
         }
         if (Array.isArray(columnFormat)) {
-            io.writeUInt16BE(columnFormat.length);
-            for (let i = 0; i < columnFormat.length; i++) {
+            const l = columnFormat.length;
+            io.writeUInt16BE(l);
+            let i;
+            for (i = 0; i < l; i++) {
                 io.writeUInt16BE(columnFormat[i]);
             }
         }
@@ -236,6 +265,29 @@ export class Frontend {
             .writeCString(sql || '', 'utf8');
         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.
+     * PgSocket writes an array of buffers as a single corked write anyway,
+     * so this costs nothing on the wire.
+     */
+    getCopyDataMessage(data) {
+        const header = Buffer.allocUnsafe(5);
+        header[0] = Protocol.FrontendMessageCode.CopyData;
+        header.writeUInt32BE(data.length + 4, 1);
+        return [header, data];
+    }
+    getCopyDoneMessage() {
+        return StaticCopyDoneBuffer;
+    }
+    getCopyFailMessage(message) {
+        const io = this._io
+            .start()
+            .writeInt8(Protocol.FrontendMessageCode.CopyFail)
+            .writeInt32BE(0) // Preserve header
+            .writeCString(message || '', 'utf8');
+        return setLengthAndFlush(io, 1);
+    }
     getFlushMessage() {
         return StaticFlushBuffer;
     }

package/protocol/pg-socket.d.ts

@@ -1,7 +1,9 @@
+import net from 'node:net';
+import tls from 'node:tls';
 import { ConnectionState } from '../constants.js';
 import type { ConnectionConfiguration } from '../interfaces/database-connection-params.js';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
-import { Callback, Maybe } from '../types.js';
+import type { Callback, Maybe } from '../types.js';
 import { Frontend } from './frontend.js';
 import { Protocol } from './protocol.js';
 export type CaptureCallback = (code: Protocol.BackendMessageCode, msg: any, done: (err: Maybe<Error>, result?: any) => void) => void | Promise<void>;
@@ -18,33 +20,242 @@ export declare class PgSocket extends SafeEventEmitter {
     private _saslSession?;
     private _processID?;
     private _secretKey?;
+    private _captureQueue;
+    private _pendingWrites;
+    private _flushScheduled;
+    private _hosts;
+    private _hostIndex;
+    private _sessionAttrsChecked;
+    private _standbyState?;
     constructor(options: ConnectionConfiguration);
     get state(): ConnectionState;
     get processID(): Maybe<number>;
     get secretKey(): Maybe<number>;
     get sessionParameters(): Record<string, string>;
     connect(): void;
+    protected _connectToHost(): void;
+    /**
+     * Negotiates TLS on an already TCP-connected `socket`, if configured -
+     * shared between the long-lived connection above (_connectToHost) and
+     * cancel() below, which needs the exact same host/TLS handling for its
+     * own short-lived socket, just without ever sending a StartupMessage
+     * afterwards. Resolves `onReady` with whichever socket ends up ready to
+     * speak the PostgreSQL protocol: the plain one, or its TLS upgrade.
+     */
+    protected _negotiateTls(socket: net.Socket, target: {
+        host: string;
+        port?: number;
+    }, onReady: (socket: net.Socket | tls.TLSSocket) => void, onError: (err: Error) => void): void;
+    /**
+     * Asks the server to cancel whatever this session is currently running.
+     *
+     * Opens its own short-lived connection and closes it again: a backend busy
+     * with a query is not reading its own socket, so the request cannot travel
+     * down the connection it is meant to interrupt. The server answers nothing
+     * - it either finds a matching session and signals it or does not - so
+     * this resolves once the bytes are out, and the cancelled query reports
+     * the outcome itself, as an ordinary error on its own connection.
+     *
+     * No StartupMessage or authentication is ever sent here - the
+     * CancelRequest is the only message this socket carries, and it is
+     * self-authorized by the processID/secretKey pair BackendKeyData handed
+     * out to the session being cancelled, not by a separate login. TLS is
+     * still negotiated via _negotiateTls() when configured, because a
+     * `hostssl` pg_hba.conf rule can reject a plaintext connection outright
+     * before the server ever reads what request it carries - and the target
+     * is `_hosts[_hostIndex]`, the host this session actually ended up
+     * connected to, not `options.host`, which after a multi-host failover may
+     * name a candidate this session never used.
+     */
+    cancel(): Promise<void>;
     close(): void;
-    sendParseMessage(args: Frontend.ParseMessageArgs, cb?: Callback): void;
-    sendBindMessage(args: Frontend.BindMessageArgs, cb?: Callback): void;
-    sendDescribeMessage(args: Frontend.DescribeMessageArgs, cb?: Callback): void;
-    sendExecuteMessage(args: Frontend.ExecuteMessageArgs, cb?: Callback): void;
-    sendCloseMessage(args: Frontend.CloseMessageArgs, cb?: Callback): void;
-    sendQueryMessage(sql: string, cb?: Callback): void;
+    sendExecuteMessage(args: Frontend.ExecuteMessageArgs, cb: CaptureCallback): Promise<any>;
+    sendCloseMessage(args: Frontend.CloseMessageArgs, 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 -
+     * the one-shot Extended Query fast path (IntlConnection.queryOnce()).
+     * Callers pass unnamed statement/portal (omit statement/portal/name) so
+     * no Close message is needed at all: PostgreSQL auto-clears an unnamed
+     * statement/portal at the next Parse/Bind referencing the unnamed name.
+     */
+    sendExtendedQueryMessages(args: {
+        parse: Frontend.ParseMessageArgs;
+        bind: Frontend.BindMessageArgs;
+        describe: Frontend.DescribeMessageArgs;
+        execute: Frontend.ExecuteMessageArgs;
+    }, cb: CaptureCallback): Promise<any>;
+    /**
+     * Parse + Describe(statement) + Sync as a single round trip - used by
+     * PreparedStatement.prepare() instead of a separate awaited Parse then a
+     * separate awaited Sync, and fetches the RowDescription/NoData in the
+     * same round trip so PreparedStatement can cache it instead of every
+     * later execute() re-Describing its own portal.
+     */
+    sendPrepareMessages(args: {
+        parse: Frontend.ParseMessageArgs;
+        describe: Frontend.DescribeMessageArgs;
+    }, cb: CaptureCallback): Promise<any>;
+    /**
+     * Bind + Execute + Sync as a single round trip, against an UNNAMED
+     * portal (args.bind.portal/args.execute.portal left unset) - used by
+     * PreparedStatement._execute() to reuse an already-prepared (named)
+     * statement without the per-call Describe/Close that Portal's own
+     * bind()/retrieveFields()/execute()/close() sequence needs for a
+     * freshly-created named portal. No Close message is needed: PostgreSQL
+     * auto-clears an unnamed portal at the next Bind naming it.
+     */
+    sendBindExecuteMessages(args: {
+        bind: Frontend.BindMessageArgs;
+        execute: Frontend.ExecuteMessageArgs;
+    }, cb: CaptureCallback): Promise<any>;
+    /**
+     * Bind + Describe(portal) + Flush as a single round trip (NOT Sync - see
+     * Portal.bindAndRetrieveFields()'s doc comment for why a Sync here would
+     * be unsafe: it would commit an implicit/autocommit transaction and
+     * destroy the just-bound named portal before any fetch() could use it).
+     * Used by PreparedStatement._execute()'s cursor branch instead of two
+     * separately-awaited Portal.bind()/retrieveFields() round trips.
+     */
+    sendBindDescribeMessages(args: {
+        bind: Frontend.BindMessageArgs;
+        describe: Frontend.DescribeMessageArgs;
+    }, cb: CaptureCallback): Promise<any>;
+    /**
+     * Close + Sync under ONE capture, rather than a Close capture followed by
+     * a separate Sync capture. That split is unsafe after an ErrorResponse:
+     * the server then skips every message until Sync, so the only reply is
+     * the Sync's ReadyForQuery - which the FIFO hands to the *Close* capture
+     * (the older entry), making it fail with "unexpected response message
+     * (Z)" and leaving the Sync capture orphaned, to silently swallow the
+     * first message of whatever request comes next. With one capture,
+     * ReadyForQuery is simply this request's end marker whether or not the
+     * Close itself was honoured.
+     */
+    sendCloseAndSyncMessages(args: Frontend.CloseMessageArgs, cb: CaptureCallback): Promise<any>;
+    /**
+     * Close(portal) + Close(statement) + Sync as a single round trip - used
+     * by PreparedStatement._maybeCloseWithPortal() when a Cursor's close()
+     * brings the owning PreparedStatement's refcount to 0, instead of two
+     * separately-batched Close+Sync round trips (Portal.close() then
+     * PreparedStatement._close()). Sync here is safe/intended: this is final
+     * teardown, no portal needs to survive past it.
+     */
+    sendClosePortalAndStatementMessages(args: {
+        portal: Frontend.CloseMessageArgs;
+        statement: Frontend.CloseMessageArgs;
+    }, cb: CaptureCallback): Promise<any>;
+    sendQueryMessage(sql: string, cb: CaptureCallback): Promise<any>;
+    /**
+     * COPY IN data. Unlike every other send*() here this pushes nothing onto
+     * the capture queue: while a COPY is in progress the server answers no
+     * individual CopyData message, so the response still belongs to the
+     * Query capture that opened the copy.
+     *
+     * Returns false when the socket's buffer is full, exactly as
+     * net.Socket.write() does - the caller is expected to stop writing until
+     * `cb` fires, which is what CopyFromStream hands straight to its own
+     * Writable callback.
+     */
+    sendCopyData(data: Buffer, cb?: Callback): boolean;
+    /** Ends a COPY IN normally; the server replies CommandComplete. */
+    sendCopyDone(cb?: Callback): boolean;
+    /**
+     * Aborts a COPY IN. The server discards the copy, reports `message` as an
+     * ErrorResponse and returns to its normal state - without this a failed
+     * import would leave the connection waiting for data forever.
+     */
+    sendCopyFail(message: string, cb?: Callback): boolean;
+    /**
+     * Stops reading from the socket, so a COPY OUT consumer that cannot keep
+     * up doesn't buffer the whole export in memory. Safe to call repeatedly.
+     */
+    pause(): void;
+    resume(): void;
     sendFlushMessage(cb?: Callback): void;
     sendTerminateMessage(cb?: Callback): void;
-    sendSyncMessage(): void;
-    capture(callback: CaptureCallback): Promise<any>;
+    sendSyncMessage(cb: CaptureCallback): Promise<any>;
+    /**
+     * The only way anything outside this class can receive a correlated
+     * backend response. Sends `data` and pushes `cb` onto the FIFO capture
+     * queue in the same call, so a response can never arrive before its
+     * capturer is registered, and a capturer can never be registered without
+     * a message actually going out for it - there is no separate, decoupled
+     * "start listening" step to race or misuse.
+     */
+    private _sendAndCapture;
     protected _removeListeners(): void;
     protected _reset(): void;
     protected _handleConnect(): void;
+    /**
+     * Called once the server is ready. With `targetSessionAttrs` set, the
+     * session has to be checked before it is handed over: a server that does
+     * not match is dropped and the next candidate tried, which is how
+     * `read-write` finds whichever node is currently the primary.
+     */
+    protected _finishConnect(): void;
+    /** Accepts this server, or drops it and moves to the next candidate. */
+    protected _applySessionAttrs(wanted: string, standby: boolean, readOnly: boolean): void;
     protected _handleClose(): void;
     protected _handleError(err: unknown): void;
+    /** Rejects and clears every still-open capture, e.g. on close/error. */
+    private _failPendingCaptures;
     protected _handleData(data: Buffer): void;
+    /**
+     * Routes one backend message to the capture at the front of the FIFO -
+     * the oldest still-open request, i.e. the one whose turn it is given the
+     * order messages were written to the socket. This *is* the request/
+     * response correlation, since the wire protocol has no id of its own.
+     * The same entry keeps receiving messages (ParseComplete, BindComplete,
+     * RowDescription, DataRow*, CommandComplete, ReadyForQuery, ...) until
+     * its callback calls `done()`, at which point it is dequeued and the
+     * next entry becomes the one messages are routed to.
+     */
+    private _dispatch;
     protected _resolvePassword(cb: (password: string) => void): void;
     protected _handleAuthenticationMessage(msg?: any): void;
+    /**
+     * tls-server-end-point: the server certificate hashed with the algorithm
+     * its own signature used (RFC 5929), which is why the DER has to be read
+     * rather than one of Node's fixed fingerprints taken.
+     */
+    protected _channelBindingData(socket: tls.TLSSocket): Buffer;
     protected _handleParameterStatus(msg: Protocol.ParameterStatusMessage): void;
     protected _handleBackendKeyData(msg: Protocol.BackendKeyDataMessage): void;
     protected _handleCommandComplete(msg: any): Protocol.CommandCompleteMessage;
-    protected _send(data: Buffer, cb?: Callback): void;
+    /**
+     * Queues `data` for the socket instead of writing it straight through:
+     * everything handed to _send() during the same synchronous burst (e.g.
+     * many concurrent query() calls fired via Promise.all over one
+     * connection) is flushed together on the next tick, corked, so Node
+     * turns the whole batch into a single underlying writev rather than one
+     * socket write per call. Measured against postgres.js, which coalesces
+     * the same way at the application level (its connection.js write()/
+     * nextWrite() pair, flushing on a 1KB threshold or setImmediate): 50
+     * concurrent prepared executes cost it 3 socket writes where this cost
+     * us 50, and that write path was the single largest non-idle item in a
+     * CPU profile of the scenario.
+     *
+     * nextTick rather than setImmediate, deliberately: it still batches a
+     * whole synchronous burst, but a lone query doesn't have to wait for the
+     * event loop's check phase before its bytes go out - which would trade
+     * away the sequential/single-query scenarios to win the concurrent ones.
+     *
+     * Returns whether the socket could accept the data at all; the write
+     * itself is reported through `cb` (and a socket that dies before the
+     * flush rejects every pending capture via _failPendingCaptures()).
+     */
+    protected _send(data: Buffer | Buffer[], cb?: Callback): boolean;
+    /**
+     * Writes COPY bytes straight through instead of queueing them for the
+     * next tick like _send() does. Two reasons: during a copy the capture
+     * queue holds exactly one entry (the Query that opened it), so _send()'s
+     * "batch only when more than one request is in flight" test would never
+     * fire and every chunk would be written on its own anyway; and the
+     * caller needs write()'s own return value to know when to stop, which a
+     * deferred write cannot give it.
+     */
+    protected _sendCopy(data: Buffer | Buffer[], cb?: Callback): boolean;
+    /** Arrow property, not a method: used as a bare process.nextTick callback. */
+    private _flushPendingWrites;
 }