neonctl 2.37.1 → 2.38.1

package/dist/psql/wire/connection.js

@@ -1,2857 +0,0 @@
-/**
- * PgConnection — the wire-layer Connection implementation (WP-02 + WP-16).
- *
- * Implements `Connection` (frozen WP-00 interface in
- * `src/psql/types/connection.ts`) on top of a single TCP / TLS socket. The
- * class is essentially a state machine:
- *
- *   auth        → drive Authentication* messages
- *   await-ready → collect ParameterStatus + BackendKeyData
- *   idle        → ready for a Query / extended-protocol cycle
- *   in-query    → simple Query in flight, accumulating ResultSets
- *   in-copy-in  → COPY FROM STDIN data transfer in progress (WP-16)
- *   in-copy-out → COPY TO STDOUT data transfer in progress (WP-16)
- *   closed      → socket gone
- *
- * What this module owns:
- *   - Socket lifecycle (open, optional TLS, Terminate, close).
- *   - Auth: Cleartext, MD5, SASL/SCRAM (delegating to ./sasl.ts).
- *   - Tracking server `serverVersion` from ParameterStatus.
- *   - Simple-query path (`execSimple`) — collect RowDescription/DataRow/
- *     CommandComplete tuples into ResultSet[].
- *   - Async messages (Notice, Notification) routed through ./notify.ts.
- *   - ErrorResponse → rejected promise mapped to ConnectError shape.
- *   - Async cancel via a side connection (CancelRequest).
- *   - COPY streaming (WP-16): `startCopyIn` returns a `CopyInStream` that
- *     wires CopyData / CopyDone / CopyFail; `startCopyOut` returns an
- *     `AsyncIterable<Buffer>` that drains CopyData messages from the wire.
- *     The state machine threads through `in-copy-in` / `in-copy-out`.
- *
- * What is stubbed / deferred:
- *   - Extended-query protocol (Parse/Bind/Execute/Sync). The framing is in
- *     protocol.ts but the high-level path (parameterised `query()`, prepared
- *     statements, pipeline) is WP-21. We throw clearly when called.
- */
-import { Buffer } from "node:buffer";
-import { createHash } from "node:crypto";
-import * as dns from "node:dns/promises";
-import * as net from "node:net";
-import * as tls from "node:tls";
-import { NoticeMultiplexer } from "./notify.js";
-import { PipelineSession } from "./pipeline.js";
-import { Bind, CancelRequest, Close, CopyData, CopyDone, CopyFail, Describe, Execute, fieldsToNotice, MessageParser, Parse, PasswordMessage, Query, SASLInitialResponse, SASLResponse, StartupMessage, Sync, Terminate, } from "./protocol.js";
-import { createScramClient } from "./sasl.js";
-import { negotiateTls } from "./tls.js";
-/**
- * Map a Notice-flavoured fields map into a `ConnectError` that includes a
- * recognizable `message` plus a `cause` slot for the raw record.
- */
-function fieldsToConnectError(fields) {
-    return { ...fieldsToNotice(fields), cause: fields };
-}
-/**
- * Synthetic ConnectError used as the rejection reason for queued
- * pipeline ops that the server skipped after a preceding ErrorResponse.
- * Mirrors libpq's `PGRES_PIPELINE_ABORTED` result — the message text
- * matches the string libpq stamps onto skipped ops so the cmd layer
- * can render it byte-identically with vanilla psql's `\getresults` /
- * `\endpipeline` output.
- */
-function pipelineAbortedError() {
-    return {
-        severity: "ERROR",
-        code: "",
-        message: "Pipeline aborted, command did not run",
-        pipelineAborted: true,
-    };
-}
-/** Parse "PostgreSQL 16.2 …" into a numeric `major * 10000 + minor * 100`. */
-function parseServerVersion(value) {
-    // libpq's PQserverVersion returns NNNNNN (e.g. 160002 for 16.2). For
-    // pre-10 versions the layout was NNMMSS (e.g. 90608 for 9.6.8). Our
-    // consumers only need monotonic comparability and a major-version
-    // accessor; the libpq formula is the simplest match.
-    const m = /^([0-9]+)(?:\.([0-9]+))?(?:\.([0-9]+))?/.exec(value);
-    if (!m)
-        return 0;
-    const major = parseInt(m[1], 10);
-    const minor = m[2] !== undefined ? parseInt(m[2], 10) : 0;
-    if (major >= 10) {
-        return major * 10000 + minor;
-    }
-    const patch = m[3] !== undefined ? parseInt(m[3], 10) : 0;
-    return major * 10000 + minor * 100 + patch;
-}
-/**
- * MD5 auth: `'md5' + md5( md5(password + user) || salt )`. Inner hash uses
- * the username; outer is salted. PG uses lowercase hex everywhere.
- */
-function md5AuthPayload(user, password, salt) {
-    const inner = createHash("md5")
-        .update(password + user, "utf8")
-        .digest("hex");
-    const outer = createHash("md5")
-        .update(inner, "utf8")
-        .update(salt)
-        .digest("hex");
-    return "md5" + outer;
-}
-/**
- * Fisher-Yates in-place shuffle of the candidate hosts list. Used by
- * `load_balance_hosts=random`. Hook the random source so tests can inject a
- * deterministic permutation.
- */
-function shuffleInPlace(arr, rng = Math.random) {
-    for (let i = arr.length - 1; i > 0; i -= 1) {
-        const j = Math.floor(rng() * (i + 1));
-        const tmp = arr[i];
-        arr[i] = arr[j];
-        arr[j] = tmp;
-    }
-}
-/**
- * After a successful handshake, decide whether this connection matches the
- * caller's `target_session_attrs` constraint by running
- * `SELECT pg_is_in_recovery()`. Returns `true` if the connection is
- * acceptable, `false` if it should be torn down and the next host tried.
- *
- *   - 'any' (or undefined) — always accepts.
- *   - 'read-write' / 'primary' — accepts when NOT in recovery.
- *   - 'read-only' / 'standby' — accepts when IN recovery.
- *
- * If the probe query itself fails we treat the connection as unacceptable
- * (returns false) so the orchestrator falls through to the next candidate
- * rather than handing the caller a half-broken connection.
- */
-async function checkSessionAttrs(conn, tsa) {
-    if (tsa === undefined || tsa === "any")
-        return true;
-    let inRecovery;
-    try {
-        const sets = await conn.execSimple("SELECT pg_is_in_recovery()");
-        if (sets.length === 0 || sets[0].rows.length === 0) {
-            return false;
-        }
-        const raw = sets[0].rows[0][0];
-        // pg_is_in_recovery returns boolean; text-format rows surface as
-        // 't' / 'f'. Be liberal: also handle 'true' / 'false'.
-        if (raw === true) {
-            inRecovery = true;
-        }
-        else if (raw === false) {
-            inRecovery = false;
-        }
-        else if (typeof raw === "string") {
-            inRecovery = raw === "t" || raw.toLowerCase() === "true";
-        }
-        else {
-            return false;
-        }
-    }
-    catch {
-        return false;
-    }
-    switch (tsa) {
-        case "read-write":
-        case "primary":
-            return !inRecovery;
-        case "read-only":
-        case "standby":
-            return inRecovery;
-        // 'prefer-standby' is unwrapped by the orchestrator into two passes
-        // ('standby' then 'any'), so we never see it here. Fall through to
-        // accept-any for safety.
-        default:
-            return true;
-    }
-}
-/**
- * COPY-OUT backpressure thresholds (bytes). When buffered data exceeds the
- * high-water mark we pause the socket; the consumer's `next()` resumes it once
- * it drains below the low-water mark. Bounds RSS for a server that produces
- * rows faster than the sink consumes them (review item #11).
- */
-const COPY_OUT_HWM = 8 * 1024 * 1024;
-const COPY_OUT_LWM = 1 * 1024 * 1024;
-export class PgConnection {
-    /**
-     * Queue one COPY-FROM-STDIN data block. Call once per expected
-     * CopyInResponse, in the order they will arrive during the upcoming
-     * `execSimple`. The mainloop owns the parsing of `\.`-terminated stdin
-     * blocks; we just buffer the raw bytes and ship them when the server is
-     * ready.
-     */
-    queueCopyInData(data) {
-        this.copyInMidBatchQueue.push(data);
-    }
-    /** Drop any queued COPY-FROM-STDIN data blocks. */
-    clearCopyInDataQueue() {
-        this.copyInMidBatchQueue.length = 0;
-    }
-    constructor(socket, opts, channelBindingData) {
-        this.parser = new MessageParser();
-        // -- Backend state
-        this.serverVersion = 0;
-        this.params = new Map();
-        this.processId = 0;
-        this.secretKey = 0;
-        this.txStatus = "I";
-        // -- Connection state machine
-        this.state = "auth";
-        this.pendingQuery = null;
-        this.extDriver = null;
-        /** True when `pipeline()` has handed out a PipelineSession (WP-21). */
-        this._extPipelineActive = false;
-        this.copyIn = null;
-        this.copyOut = null;
-        /**
-         * Resolver for `startCopyIn` / `startCopyOut`. Captured when the caller has
-         * already wired the `Query(COPY …)` and is now waiting for the server's
-         * CopyInResponse / CopyOutResponse to confirm that the protocol switched.
-         */
-        this.copyStartResolve = null;
-        this.copyStartReject = null;
-        /**
-         * Last-COPY command tag (e.g. `"COPY 17"`), or `null` if no COPY has run
-         * since connection startup. Used by the `\copy` command runner to print the
-         * upstream-style "COPY N" footer.
-         */
-        this.lastCopyTag = null;
-        /**
-         * Pre-buffered CopyData payloads keyed to the order of CopyInResponse
-         * messages we expect to see during the next `execSimple`. Used to drive
-         * `COPY ... FROM STDIN` segments that appear as part of a `\;`-chained
-         * simple-query batch — the mainloop pre-scans its input for `\.`-terminated
-         * COPY data blocks, hands the bytes in here, and the in-query dispatcher
-         * pops the head buffer when a CopyInResponse arrives. Each buffer becomes
-         * one CopyData frame followed by CopyDone (the upstream wire shape).
-         *
-         * If the queue is empty when CopyInResponse arrives, the wire layer falls
-         * back to CopyFail so the connection doesn't deadlock.
-         */
-        this.copyInMidBatchQueue = [];
-        /**
-         * Sink for COPY-TO-STDOUT mid-batch data. When `COPY ... TO STDOUT` is one
-         * segment of a `\;`-chained simple-query batch, the server pushes CopyData
-         * messages to us mid-`execSimple`. With no `startCopyOut` driver active,
-         * upstream `handleCopyOut` would write the bytes verbatim to the caller's
-         * output stream. We expose a settable sink so the mainloop can wire stdout
-         * (or any other WritableStream); if unset, the bytes are dropped (matching
-         * libpq's behaviour when `PQexec` lacks a copy handler — the data still
-         * gets consumed off the wire so the protocol stays in sync, but is
-         * silently discarded).
-         */
-        this.copyOutMidBatchSink = null;
-        /**
-         * Mid-batch COPY-OUT state. While `true`, CopyData/CopyDone messages
-         * arriving in `handleQueryMessage` are routed to the sink rather than
-         * triggering the "unexpected message" diagnostic. Flipped on by
-         * CopyOutResponse and off again when CopyDone arrives.
-         */
-        this.copyOutMidBatchActive = false;
-        /**
-         * Set to `true` once we actually respond to a server password challenge
-         * (cleartext, MD5, or the SASL/SCRAM exchange). Mirrors libpq's
-         * `conn->password_needed`, which `\conninfo` reports as "Password Used".
-         * A trust/cert/peer login leaves this `false` — the password may have been
-         * supplied but was never sent.
-         */
-        this.passwordUsed = false;
-        // -- Async messages
-        this.notify = new NoticeMultiplexer();
-        // -- Auth state (only used during state=auth)
-        this.scram = null;
-        /**
-         * True once the server has sent ANY authentication challenge (Cleartext,
-         * MD5, SASL, ...). Used by the AuthenticationOk handler to distinguish
-         * "server picked trust/cert auth" (no challenge, method=`none`) from
-         * "server just completed a SASL exchange" (challenge seen, method
-         * already validated when the challenge arrived).
-         */
-        this.authChallengeSeen = false;
-        /**
-         * True once `AuthenticationSASLFinal` arrived AND `scram.finish()` verified
-         * the server signature (RFC 5802 §3 mutual auth). Used to reject an
-         * `AuthenticationOk` that skips SASLFinal — a rogue/MITM server that doesn't
-         * know the password could otherwise send SASLContinue then jump straight to
-         * AuthenticationOk and never have its signature checked (review item #8).
-         */
-        this.saslFinalSeen = false;
-        // -- Error-after-close guard
-        this.socketError = null;
-        this.startupResolve = null;
-        this.startupReject = null;
-        this.socket = socket;
-        this.opts = opts;
-        this.channelBindingData = channelBindingData;
-        this._password = opts.password ?? null;
-        socket.on("data", (chunk) => {
-            this.onData(chunk);
-        });
-        socket.on("error", (err) => {
-            this.socketError = err;
-            this.failPending(err);
-        });
-        socket.on("close", () => {
-            if (this.state !== "closed") {
-                this.state = "closed";
-                this.failPending(this.socketError ?? new Error("Socket closed"));
-            }
-        });
-    }
-    /**
-     * Open a Postgres connection. Supports multi-host (`opts.hosts`) with
-     * sequential or random iteration, a `target_session_attrs` filter, and the
-     * libpq-style `prefer-standby` two-pass fallback.
-     *
-     * Iteration semantics:
-     *   1. Build the candidate list from `opts.hosts` (preferred) or
-     *      `[{host: opts.host, port: opts.port}]`.
-     *   2. If `loadBalanceHosts === 'random'`, Fisher-Yates shuffle in place.
-     *   3. For each candidate (in order), attempt: openSocket → TLS → auth →
-     *      startup. On failure, record the error and try the next.
-     *   4. On successful handshake, if `target_session_attrs` is restrictive,
-     *      run `SELECT pg_is_in_recovery()`. If the role doesn't match, close
-     *      this connection and try the next.
-     *   5. `prefer-standby` runs TWO passes: first accepting only standbys,
-     *      second falling back to any host.
-     *   6. If no candidate succeeds, throw the LAST encountered error
-     *      (preserves the most-recent failure mode for diagnostics).
-     */
-    static async connect(opts) {
-        const seed = opts.hosts !== undefined && opts.hosts.length > 0
-            ? [...opts.hosts]
-            : [{ host: opts.host, port: opts.port }];
-        // DNS fan-out: a single hostname can resolve to multiple A/AAAA records,
-        // and libpq treats each resulting IP as its own candidate so the
-        // iteration walks the FLAT (ip, port) list, not the (hostname, port)
-        // list. Each candidate carries BOTH the original hostname (for TLS
-        // SNI / SAN verification + `conn.host` reporting) AND the resolved
-        // address (used only by `net.connect`). Unix-domain socket paths
-        // and IP literals bypass the lookup — they become `{host, port}`
-        // with no address override.
-        //
-        // Active for every mode, not just `load_balance_hosts=random`: even
-        // `disable` benefits from the fall-through behaviour when the first
-        // A record is dead. Mirrors upstream `004_load_balance_dns.pl`.
-        //
-        // `hostaddr` short-circuits the lookup entirely: libpq connects to the
-        // fixed IP without consulting DNS while still using `host` for TLS SNI /
-        // certificate hostname verification. We map this onto the same
-        // `addressOverride` seam the DNS fan-out uses — the literal IP becomes
-        // the candidate's `address`, and `host` (the user-typed name) is
-        // preserved for SNI / `conn.host`. Only the single-host form carries a
-        // `hostaddr`; libpq does not support a hostaddr-per-host list here.
-        const candidates = opts.hostaddr !== undefined && opts.hostaddr !== ""
-            ? seed.map((c) => ({
-                host: c.host,
-                address: opts.hostaddr,
-                port: c.port,
-            }))
-            : await expandHostsViaDns(seed);
-        if (opts.loadBalanceHosts === "random") {
-            shuffleInPlace(candidates, PgConnection._loadBalanceRng ?? Math.random);
-        }
-        const tsa = opts.targetSessionAttrs ?? "any";
-        // `prefer-standby` runs two passes: first 'standby', then 'any'. Every
-        // other mode runs a single pass with the literal target.
-        const passes = tsa === "prefer-standby" ? ["standby", "any"] : [tsa];
-        let lastErr = null;
-        for (const passTsa of passes) {
-            for (const candidate of candidates) {
-                const candidateOpts = {
-                    ...opts,
-                    host: candidate.host,
-                    port: candidate.port,
-                };
-                let conn;
-                try {
-                    conn = await PgConnection.connectSingle(candidateOpts, candidate.address);
-                }
-                catch (err) {
-                    lastErr = err;
-                    continue;
-                }
-                // Apply target_session_attrs filter via pg_is_in_recovery().
-                const accepted = await checkSessionAttrs(conn, passTsa);
-                if (accepted) {
-                    return conn;
-                }
-                // Mismatch: close this connection and move on.
-                try {
-                    await conn.close();
-                }
-                catch {
-                    // ignore
-                }
-                lastErr = new Error(`target_session_attrs=${String(passTsa)} did not match host ${candidate.host}:${String(candidate.port)}`);
-            }
-        }
-        if (lastErr !== null) {
-            // `throw lastErr` would trip the `only-throw-error` lint rule because
-            // `lastErr` is typed `unknown`. Normalise to an Error for the throw
-            // while preserving the original via `cause` so callers can introspect.
-            if (lastErr instanceof Error)
-                throw lastErr;
-            let message;
-            if (typeof lastErr === "object" &&
-                lastErr !== null &&
-                "message" in lastErr &&
-                typeof lastErr.message === "string") {
-                message = lastErr.message;
-            }
-            else if (typeof lastErr === "string" ||
-                typeof lastErr === "number" ||
-                typeof lastErr === "boolean") {
-                message = String(lastErr);
-            }
-            else {
-                message = "PgConnection.connect: unknown error";
-            }
-            const wrapped = new Error(message);
-            wrapped.cause = lastErr;
-            throw wrapped;
-        }
-        throw new Error("PgConnection.connect: no candidate hosts configured");
-    }
-    /**
-     * Per-host connect attempt: open the socket, negotiate TLS, run the auth
-     * dance, complete startup. Same shape as the pre-multihost `connect()`;
-     * the multi-host orchestrator above wraps this for each candidate.
-     */
-    static async connectSingle(opts, 
-    /**
-     * Optional resolved IP address. When set, `openSocket` uses it for the
-     * actual `net.connect({host: address})`. `opts.host` remains the
-     * user-typed hostname so TLS SNI / SAN verification and `conn.host`
-     * report the original identity. Set by the DNS fan-out in `connect()`.
-     */
-    addressOverride) {
-        // TLS over Unix-domain sockets is meaningless (the kernel guarantees
-        // the channel) and libpq refuses `sslmode=require|verify-*` for socket
-        // connections. We mirror the early rejection so a misconfigured caller
-        // gets a clear diagnostic instead of a confused TLS handshake.
-        if (isUnixSocketHost(opts.host) &&
-            (opts.ssl === "require" ||
-                opts.ssl === "verify-ca" ||
-                opts.ssl === "verify-full")) {
-            throw new Error(`sslmode=${opts.ssl} is not supported over Unix-domain sockets (host=${opts.host})`);
-        }
-        // libpq `requirepeer`: for Unix-domain sockets, libpq verifies the server
-        // process runs as the named OS user via peer credentials (getpeereid /
-        // SO_PEERCRED). Node exposes NO portable peer-credential API for Unix
-        // sockets, so we CANNOT enforce this. We honestly do NOT verify it — to
-        // avoid pretending a security check passed, we reject the connection with
-        // a clear diagnostic when `requirepeer` is set on a socket connection,
-        // rather than silently connecting as if the check had succeeded. (TCP
-        // connections ignore `requirepeer`, matching libpq.)
-        if (isUnixSocketHost(opts.host) &&
-            opts.requirepeer !== undefined &&
-            opts.requirepeer !== "") {
-            throw new Error(`requirepeer="${opts.requirepeer}" cannot be enforced: Node provides no ` +
-                `Unix-domain socket peer-credential API; refusing to connect rather ` +
-                `than skip the check`);
-        }
-        const rawSocket = await openSocket(opts, addressOverride);
-        let socket = rawSocket;
-        let channelBindingData = null;
-        try {
-            // verify-ca skips hostname check; verify-full = default Node behavior.
-            // require/prefer/allow accept any cert chain (libpq default).
-            // NOTE: do NOT set `checkServerIdentity: undefined` — newer Node
-            // versions reject that with "must be of type function". Omit the
-            // property when verify-full so the default validator runs.
-            // libpq `sslsni=0` suppresses the TLS SNI extension: omit `servername`
-            // entirely so no hostname is sent in the ClientHello. Default (unset /
-            // true) sends SNI = the connection host, as libpq does.
-            const servername = tlsServername(opts);
-            const tlsConnectionOptions = {
-                ...(servername !== undefined ? { servername } : {}),
-                rejectUnauthorized: opts.ssl === "verify-ca" || opts.ssl === "verify-full",
-                // PG 17+ advertises ALPN for the 'postgresql' protocol; libpq sets
-                // this so a future-proof TLS proxy can route on ALPN instead of
-                // probing the wire. Always offer it — older servers ignore.
-                ALPNProtocols: ["postgresql"],
-                // Cipher preference is left to the runtime's TLS library. Our
-                // ClientHello offers the byte-identical TLS-1.3 ciphersuite list and
-                // order as libpq (AES-256-GCM, ChaCha20, AES-128-GCM), so the suite
-                // is the server's choice from an identical offer. Under Node
-                // (OpenSSL) that lands on AES-256-GCM, matching vanilla psql; under
-                // Bun (BoringSSL) it lands on AES-128-GCM. Both are TLS-1.3 AEAD
-                // suites with no practical security difference, and neither runtime
-                // exposes a client-side knob to steer TLS-1.3 selection (`ciphers`
-                // is TLS-1.2-only; `ciphersuites`/secureContext are ignored for the
-                // client offer), so this is left as-is.
-            };
-            if (opts.ssl !== "verify-full") {
-                tlsConnectionOptions.checkServerIdentity = () => undefined;
-            }
-            else if (opts.sslsni === false) {
-                // verify-full still verifies the peer name against `host`, but with
-                // SNI suppressed Node has no `servername` to drive its default
-                // identity check — so verify explicitly against the connection host.
-                // (libpq decouples SNI (sslsni) from peer-name verification (sslmode);
-                // we mirror that here.)
-                tlsConnectionOptions.checkServerIdentity = (_host, cert) => tls.checkServerIdentity(opts.host, cert);
-            }
-            applyTlsProtocolVersionRange(tlsConnectionOptions, opts);
-            const tlsResult = await negotiateTls(rawSocket, 
-            // libpq refuses TLS on a socket connection even for sslmode=allow /
-            // prefer — instead of negotiating it just stays plain. We short-
-            // circuit by passing 'disable' to negotiateTls; the caller's
-            // requested sslmode is preserved on opts for error reporting.
-            isUnixSocketHost(opts.host) ? "disable" : opts.ssl, tlsConnectionOptions, {
-                sslcert: opts.sslcert,
-                sslkey: opts.sslkey,
-                sslcertmode: opts.sslcertmode,
-                sslpassword: opts.sslpassword,
-                sslrootcert: opts.sslrootcert,
-                sslcrl: opts.sslcrl,
-                sslcrldir: opts.sslcrldir,
-                sslkeylogfile: opts.sslkeylogfile,
-            }, 
-            // libpq `sslnegotiation=direct` (PG 17+): start TLS without the
-            // SSLRequest probe. Never reached for Unix-domain sockets (forced to
-            // sslmode 'disable' above) — direct SSL is a TCP-only concept. The
-            // ALPN protocol is already on `tlsConnectionOptions` for both paths.
-            isUnixSocketHost(opts.host)
-                ? "postgres"
-                : (opts.sslnegotiation ?? "postgres"));
-            if (tlsResult.kind === "tls") {
-                socket = tlsResult.socket;
-                channelBindingData = tlsResult.channelBindingData;
-            }
-            else {
-                socket = tlsResult.socket;
-            }
-        }
-        catch (err) {
-            try {
-                rawSocket.destroy();
-            }
-            catch {
-                // ignore
-            }
-            throw err;
-        }
-        const conn = new PgConnection(socket, opts, channelBindingData);
-        await conn.startup();
-        return conn;
-    }
-    // -------------------------------------------------------------------------
-    // Connection interface — public methods
-    // -------------------------------------------------------------------------
-    parameterStatus(name) {
-        return this.params.get(name);
-    }
-    /**
-     * Expose the connection target as `meta.database` / `meta.user` / `meta.host`
-     * / `meta.port` / `meta.pid` so the prompt renderer (which duck-types these
-     * via `MaybeWithMeta`) can render `%/`, `%n`, `%m`, `%>`, `%p` without
-     * additional plumbing. Postgres doesn't emit a `database` ParameterStatus,
-     * so these come from the connect opts / BackendKeyData.
-     */
-    get database() {
-        return this.opts.database;
-    }
-    get user() {
-        return this.opts.user;
-    }
-    get host() {
-        return this.opts.host;
-    }
-    get port() {
-        return this.opts.port;
-    }
-    get pid() {
-        return this.processId;
-    }
-    /**
-     * The password supplied at connect time (or `null`). Mirrors libpq's
-     * retention of the password on the live `PGconn` so `\c <newdb>` can
-     * reconnect transparently. Read-only by design — the field is set once in
-     * the constructor and never mutated.
-     */
-    get password() {
-        return this._password;
-    }
-    /**
-     * If the connection was upgraded to TLS during negotiation, return the
-     * cipher info for the active session. Returns `null` for plain-text
-     * connections. Used by the startup banner to render an `SSL connection
-     * (protocol: …, cipher: …)` line that mirrors upstream psql, and by
-     * `\conninfo` (PG18 connection-information table) to fill the SSL rows.
-     */
-    getTlsInfo() {
-        const s = this.socket;
-        if (typeof s.getCipher !== "function")
-            return null;
-        try {
-            const cipher = s.getCipher();
-            const protocol = s.getProtocol?.() ?? cipher.version ?? "unknown";
-            if (!cipher.name)
-                return null;
-            // TLS compression has been disabled by every modern stack since CRIME
-            // (2012); Node's TLS doesn't expose a compression accessor, so we
-            // always report "off". libpq does the same.
-            const compression = "off";
-            // Node exposes the negotiated ALPN protocol on TLSSocket.alpnProtocol
-            // (string when negotiated, false when not). Postgres 17+ uses
-            // 'postgresql' here.
-            const alpnRaw = s
-                .alpnProtocol;
-            const alpn = typeof alpnRaw === "string" && alpnRaw.length > 0
-                ? alpnRaw
-                : null;
-            return {
-                protocol: String(protocol),
-                cipher: cipher.standardName ?? cipher.name,
-                standardName: cipher.standardName,
-                compression,
-                alpn,
-                library: "OpenSSL",
-                keyBits: sslKeyBitsFromCipher(cipher.standardName ?? cipher.name),
-            };
-        }
-        catch {
-            return null;
-        }
-    }
-    /**
-     * Static connection facts for the PG18 `\conninfo` table, sourced from the
-     * connect opts and the live socket (no SQL is issued):
-     *
-     *   - `host` / `port` / `options`: from the connect opts.
-     *   - `hostaddr`: the resolved peer IP — `opts.hostaddr` if the caller
-     *     fixed one, else the TCP socket's `remoteAddress` (undefined for a
-     *     Unix-domain socket → `null`).
-     *   - `backendPid`: the backend process id from BackendKeyData.
-     *   - `passwordUsed`: whether a password was actually sent during auth.
-     *   - `gssapiUsed`: always `false` — we have no GSSAPI support.
-     */
-    getConnectionInfo() {
-        const remote = this.opts.hostaddr !== undefined && this.opts.hostaddr !== ""
-            ? this.opts.hostaddr
-            : (this.socket.remoteAddress ?? null);
-        return {
-            host: this.opts.host,
-            hostaddr: remote,
-            port: this.opts.port,
-            options: this.opts.options ?? null,
-            backendPid: this.processId,
-            passwordUsed: this.passwordUsed,
-            gssapiUsed: false,
-        };
-    }
-    async query(sql, params) {
-        // `params === undefined` → caller has no intent to use extended protocol
-        // (e.g. a buffered SQL run without `\bind`). Use the simple-query path so
-        // chained `\;`-separated statements still work via `PQexec`-shaped
-        // semantics.
-        //
-        // `params` defined (even as `[]`) → caller staged a `\bind` (or a
-        // describe-formatter explicitly asking for the extended path). The
-        // extended protocol sends a single Parse message verbatim; the server
-        // rejects multi-statement SQL with SQLSTATE 42601 / "cannot insert
-        // multiple commands into a prepared statement", which is the upstream
-        // contract for `\bind`/`\parse`. Switching on length === 0 would silently
-        // fall back to simple-query and mask that diagnostic.
-        if (params === undefined) {
-            const sets = await this.execSimple(sql);
-            if (sets.length === 0) {
-                throw new Error("PgConnection.query: server returned no result sets");
-            }
-            return sets[sets.length - 1];
-        }
-        // Extended-protocol single-shot: Parse('', sql, []) → Bind('', '', [],
-        // text-encoded params, [text]) → Describe('P', '') → Execute('', 0) →
-        // Sync. Every param goes out in text format and the server coerces.
-        this.ensureIdle();
-        const encoded = encodeParams(params);
-        this.startExtendedBatch();
-        const parseP = this.enqueueParse();
-        const bindP = this.enqueueBind();
-        const descP = this.enqueueDescribePortalIntoNextExecute();
-        const execP = this.enqueueExecute();
-        const syncP = this.enqueueSync();
-        this.socket.write(Parse("", sql, []));
-        this.socket.write(Bind("", "", [], encoded, [0]));
-        this.socket.write(Describe("P", ""));
-        this.socket.write(Execute("", 0));
-        this.socket.write(Sync());
-        let firstErr = null;
-        const cap = (e) => {
-            if (firstErr === null)
-                firstErr = e;
-        };
-        parseP.catch(cap);
-        bindP.catch(cap);
-        descP.catch(cap);
-        let result = null;
-        execP.then((rs) => {
-            result = rs;
-        }, cap);
-        await syncP.catch(cap);
-        if (firstErr !== null)
-            throw asThrowable(firstErr);
-        if (result === null) {
-            throw new Error("PgConnection.query: server returned no result");
-        }
-        return result;
-    }
-    async execSimple(sql) {
-        this.ensureIdle();
-        return new Promise((resolve, reject) => {
-            this.pendingQuery = {
-                resolve,
-                reject,
-                current: null,
-                finished: [],
-                notices: [],
-                error: null,
-            };
-            this.state = "in-query";
-            this.socket.write(Query(sql));
-        });
-    }
-    async prepare(name, sql, paramTypes) {
-        this.ensureIdle();
-        const oids = paramTypes ?? [];
-        this.startExtendedBatch();
-        const parseP = this.enqueueParse();
-        const descP = this.enqueueDescribeStatement();
-        const syncP = this.enqueueSync();
-        this.socket.write(Parse(name, sql, oids));
-        this.socket.write(Describe("S", name));
-        this.socket.write(Sync());
-        let firstErr = null;
-        const cap = (e) => {
-            if (firstErr === null)
-                firstErr = e;
-        };
-        parseP.catch(cap);
-        let descResult = null;
-        descP.then((r) => {
-            descResult = r;
-        }, cap);
-        await syncP.catch(cap);
-        if (firstErr !== null)
-            throw asThrowable(firstErr);
-        if (descResult === null) {
-            throw new Error("PgConnection.prepare: server returned no parameter description");
-        }
-        const { paramOids, fields } = descResult;
-        const conn = this;
-        return {
-            name,
-            paramTypes: paramOids,
-            async bind(values, paramFormats) {
-                conn.ensureIdle();
-                const encoded = encodeParams(values);
-                conn.startExtendedBatch();
-                const bP = conn.enqueueBind();
-                const sP = conn.enqueueSync();
-                conn.socket.write(Bind("", name, paramFormats ?? [], encoded, [0]));
-                conn.socket.write(Sync());
-                let err = null;
-                bP.catch((e) => {
-                    if (err === null)
-                        err = e;
-                });
-                await sP.catch((e) => {
-                    if (err === null)
-                        err = e;
-                });
-                if (err !== null)
-                    throw asThrowable(err);
-            },
-            describe() {
-                return Promise.resolve(fields);
-            },
-            async execute(maxRows) {
-                conn.ensureIdle();
-                conn.startExtendedBatch();
-                const eP = conn.enqueueExecuteWithFields(fields);
-                const sP = conn.enqueueSync();
-                conn.socket.write(Execute("", maxRows ?? 0));
-                conn.socket.write(Sync());
-                let err = null;
-                let rs = null;
-                eP.then((r) => {
-                    rs = r;
-                }, (e) => {
-                    if (err === null)
-                        err = e;
-                });
-                await sP.catch((e) => {
-                    if (err === null)
-                        err = e;
-                });
-                if (err !== null)
-                    throw asThrowable(err);
-                if (rs === null) {
-                    throw new Error("PgConnection.prepare.execute: server returned no result");
-                }
-                return rs;
-            },
-            async bindAndExecute(values, maxRows, paramFormats) {
-                conn.ensureIdle();
-                const encoded = encodeParams(values);
-                conn.startExtendedBatch();
-                const bP = conn.enqueueBind();
-                const eP = conn.enqueueExecuteWithFields(fields);
-                const sP = conn.enqueueSync();
-                conn.socket.write(Bind("", name, paramFormats ?? [], encoded, [0]));
-                conn.socket.write(Execute("", maxRows ?? 0));
-                conn.socket.write(Sync());
-                let err = null;
-                let rs = null;
-                bP.catch((e) => {
-                    if (err === null)
-                        err = e;
-                });
-                eP.then((r) => {
-                    rs = r;
-                }, (e) => {
-                    if (err === null)
-                        err = e;
-                });
-                await sP.catch((e) => {
-                    if (err === null)
-                        err = e;
-                });
-                if (err !== null)
-                    throw asThrowable(err);
-                if (rs === null) {
-                    throw new Error("PgConnection.prepare.bindAndExecute: server returned no result");
-                }
-                return rs;
-            },
-            async close() {
-                conn.ensureIdle();
-                conn.startExtendedBatch();
-                const cP = conn.enqueueClose();
-                const sP = conn.enqueueSync();
-                conn.socket.write(Close("S", name));
-                conn.socket.write(Sync());
-                let err = null;
-                cP.catch((e) => {
-                    if (err === null)
-                        err = e;
-                });
-                await sP.catch((e) => {
-                    if (err === null)
-                        err = e;
-                });
-                if (err !== null)
-                    throw asThrowable(err);
-            },
-        };
-    }
-    /**
-     * Issue `Close('S', name) + Sync` directly, without a preceding Parse.
-     * The server responds with CloseComplete + ReadyForQuery (even when
-     * the named statement doesn't exist — PG treats unknown-name Close as
-     * a no-op). Used by `\close_prepared NAME` so we don't have to fake a
-     * Parse just to reach the Close step.
-     */
-    async closePreparedStatement(name) {
-        this.ensureIdle();
-        this.startExtendedBatch();
-        const cP = this.enqueueClose();
-        const sP = this.enqueueSync();
-        this.socket.write(Close("S", name));
-        this.socket.write(Sync());
-        let err = null;
-        cP.catch((e) => {
-            if (err === null)
-                err = e;
-        });
-        await sP.catch((e) => {
-            if (err === null)
-                err = e;
-        });
-        if (err !== null)
-            throw asThrowable(err);
-    }
-    startCopyIn(sql) {
-        this.ensureIdle();
-        // COPY mid-pipeline is rejected by libpq with a fixed diagnostic; we
-        // mirror that synchronously so callers don't need a round-trip to learn
-        // their command is invalid. The wire-level dispatch also guards this
-        // (see handleCopyStartMessage) for any path that bypasses this check.
-        if (this._extPipelineActive) {
-            this.abortForCopyInPipeline();
-            return Promise.reject(Object.assign(new Error("COPY in a pipeline is not supported, aborting connection"), { severity: "FATAL" }));
-        }
-        // The driver waits in `in-query` state until CopyInResponse arrives — at
-        // which point the protocol switches and we move to `in-copy-in`. The
-        // server can also reply with an ErrorResponse (e.g. "no such table"),
-        // which we surface as a rejected promise.
-        return new Promise((resolve, reject) => {
-            this.copyIn = {
-                resolveDone: null,
-                rejectDone: null,
-                error: null,
-                commandTag: null,
-                closed: false,
-            };
-            this.copyStartResolve = () => {
-                // The protocol-switch landed; hand the caller a usable stream.
-                resolve(this.makeCopyInStream());
-            };
-            this.copyStartReject = reject;
-            this.state = "in-query";
-            this.socket.write(Query(sql));
-        });
-    }
-    startCopyOut(sql) {
-        this.ensureIdle();
-        if (this._extPipelineActive) {
-            this.abortForCopyInPipeline();
-            return Promise.reject(Object.assign(new Error("COPY in a pipeline is not supported, aborting connection"), { severity: "FATAL" }));
-        }
-        return new Promise((resolve, reject) => {
-            this.copyOut = {
-                queue: [],
-                queuedBytes: 0,
-                waker: null,
-                done: false,
-                abandoned: false,
-                error: null,
-                commandTag: null,
-            };
-            this.copyStartResolve = () => {
-                resolve(this.makeCopyOutStream());
-            };
-            this.copyStartReject = reject;
-            this.state = "in-query";
-            this.socket.write(Query(sql));
-        });
-    }
-    pipeline() {
-        this.ensureIdle();
-        return new PipelineSession(this);
-    }
-    /**
-     * Cancel whatever the connection is currently doing.
-     *
-     * The routing is state-aware so the mainloop SIGINT handler can call this
-     * blindly without knowing the protocol phase:
-     *
-     * - `in-copy-in`: we hold the writing end of the data stream, so the
-     *   correct action is a client-initiated CopyFail on the *same* socket.
-     *   Sending a side CancelRequest would race with our own pending writes;
-     *   CopyFail is the spec-blessed abort path. The server replies with
-     *   ErrorResponse + ReadyForQuery and we transition back to idle.
-     * - `in-copy-out`: the server is pushing data at us. CopyFail is not a
-     *   valid client message here, so we fall back to the side CancelRequest
-     *   path that normal queries use. PG will surface an ErrorResponse and
-     *   tear the COPY down.
-     * - everything else: side CancelRequest, the historical behaviour.
-     *
-     * Best-effort. We don't reject if BackendKeyData hasn't arrived yet
-     * during the auth dance — there's nothing to cancel; we just return.
-     */
-    async cancel() {
-        // In-copy-in: send CopyFail on the live socket so the server returns
-        // to ReadyForQuery cleanly. This is the same abort path the upstream
-        // SIGINT handler in `copy.c::handleCopyIn` triggers via longjmp.
-        if (this.state === "in-copy-in" && this.copyIn && !this.copyIn.closed) {
-            this.copyIn.closed = true;
-            try {
-                this.socket.write(CopyFail("canceled by user"));
-            }
-            catch {
-                // Socket may have died — failPending() will surface that.
-            }
-            return;
-        }
-        if (this.processId === 0) {
-            // Nothing to cancel — startup hasn't reached BackendKeyData. Be
-            // forgiving: the mainloop SIGINT handler shouldn't crash on cancel
-            // during a half-open connection.
-            return;
-        }
-        // Per the PG protocol, CancelRequest is sent on a *fresh* connection,
-        // not the one running the query. We TLS-negotiate against the same
-        // sslmode but we don't auth — we just write the request and close.
-        // Honour `hostaddr` on the cancel connection too: dial the fixed IP while
-        // keeping the user-typed host for SNI / cert verification, mirroring the
-        // primary connect path's `addressOverride`.
-        const cancelSocket = await openSocket(this.opts, this.opts.hostaddr !== undefined && this.opts.hostaddr !== ""
-            ? this.opts.hostaddr
-            : undefined);
-        let writeSocket = cancelSocket;
-        try {
-            // sslsni=0 suppresses SNI on the cancel connection too (mirrors the
-            // primary connect path).
-            const cancelServername = tlsServername(this.opts);
-            const cancelTlsOpts = {
-                ...(cancelServername !== undefined
-                    ? { servername: cancelServername }
-                    : {}),
-                rejectUnauthorized: this.opts.ssl === "verify-ca" ||
-                    this.opts.ssl === "verify-full",
-                ALPNProtocols: ["postgresql"],
-            };
-            if (this.opts.ssl !== "verify-full") {
-                cancelTlsOpts.checkServerIdentity = () => undefined;
-            }
-            else if (this.opts.sslsni === false) {
-                const host = this.opts.host;
-                cancelTlsOpts.checkServerIdentity = (_h, cert) => tls.checkServerIdentity(host, cert);
-            }
-            applyTlsProtocolVersionRange(cancelTlsOpts, this.opts);
-            const t = await negotiateTls(cancelSocket, 
-            // Unix-domain socket: no TLS, regardless of caller's sslmode.
-            isUnixSocketHost(this.opts.host) ? "disable" : this.opts.ssl, cancelTlsOpts, {
-                sslcert: this.opts.sslcert,
-                sslkey: this.opts.sslkey,
-                sslcertmode: this.opts.sslcertmode,
-                sslpassword: this.opts.sslpassword,
-                sslrootcert: this.opts.sslrootcert,
-                sslcrl: this.opts.sslcrl,
-                sslcrldir: this.opts.sslcrldir,
-                sslkeylogfile: this.opts.sslkeylogfile,
-            }, 
-            // Mirror the primary connect path's negotiation mode so a server
-            // configured for direct SSL also accepts the cancel connection.
-            isUnixSocketHost(this.opts.host)
-                ? "postgres"
-                : (this.opts.sslnegotiation ?? "postgres"));
-            writeSocket = t.kind === "tls" ? t.socket : t.socket;
-            await new Promise((resolve, reject) => {
-                writeSocket.write(CancelRequest(this.processId, this.secretKey), (err) => {
-                    if (err)
-                        reject(err);
-                    else
-                        resolve();
-                });
-            });
-        }
-        finally {
-            try {
-                writeSocket.end();
-            }
-            catch {
-                // ignore
-            }
-            try {
-                cancelSocket.destroy();
-            }
-            catch {
-                // ignore
-            }
-        }
-    }
-    escapeIdentifier(value) {
-        return '"' + value.replace(/"/g, '""') + '"';
-    }
-    escapeLiteral(value) {
-        // Per PG docs: doubled single-quotes always; if the string contains a
-        // backslash, use the E'...' escape-string syntax so backslashes don't
-        // depend on `standard_conforming_strings`.
-        const doubled = value.replace(/'/g, "''");
-        if (value.includes("\\")) {
-            return "E'" + doubled.replace(/\\/g, "\\\\") + "'";
-        }
-        return "'" + doubled + "'";
-    }
-    async setClientEncoding(name) {
-        // libpq's PQsetClientEncoding sends `SET client_encoding TO '<value>'`
-        // down the wire (see fe-connect.c). We do the same via the simple-query
-        // path, quoting the value as a string literal so encoding names are
-        // never mistaken for SQL tokens. On success the server emits a
-        // `client_encoding` ParameterStatus which the message loop folds into
-        // `this.params` (see the ParameterStatus cases), so
-        // `parameterStatus('client_encoding')` is up to date afterwards.
-        //
-        // We keep no separate client-side decoder state: text-format values are
-        // always decoded as UTF-8 in `decodeDataRow`, matching how the rest of
-        // this client treats backend text. Tracking only the ParameterStatus is
-        // therefore sufficient. A non-zero `SET` failure (e.g. a name the server
-        // rejects) surfaces as a thrown ConnectError from `execSimple`.
-        await this.execSimple(`SET client_encoding TO ${this.escapeLiteral(name)}`);
-    }
-    onNotice(handler) {
-        return this.notify.onNotice(handler);
-    }
-    onNotification(handler) {
-        return this.notify.onNotification(handler);
-    }
-    async close() {
-        if (this.state === "closed")
-            return;
-        try {
-            this.socket.write(Terminate());
-        }
-        catch {
-            // socket may already be dead; we still want to mark closed
-        }
-        this.state = "closed";
-        this.notify.clear();
-        await new Promise((resolve) => {
-            this.socket.once("close", () => {
-                resolve();
-            });
-            try {
-                this.socket.end();
-            }
-            catch {
-                resolve();
-            }
-        });
-    }
-    isClosed() {
-        return this.state === "closed";
-    }
-    // -------------------------------------------------------------------------
-    // Startup / auth state machine
-    // -------------------------------------------------------------------------
-    startup() {
-        return new Promise((resolve, reject) => {
-            const params = {
-                user: this.opts.user,
-                database: this.opts.database,
-                // psql sends client_encoding=UTF8 by default; we follow.
-                client_encoding: this.opts.clientEncoding ?? "UTF8",
-            };
-            if (this.opts.applicationName !== undefined) {
-                params.application_name = this.opts.applicationName;
-            }
-            if (this.opts.options !== undefined) {
-                params.options = this.opts.options;
-            }
-            // Walsender (replication) mode: the server enters a restricted
-            // command set (IDENTIFY_SYSTEM, START_REPLICATION, etc.) keyed off
-            // this startup parameter. Values mirror libpq's normalisation:
-            // 'true' for physical, 'database' for logical. We do not stream the
-            // CopyBoth phase — the Query path still surfaces ErrorResponse and
-            // any pre-streaming ResultSet, which is enough for the negative
-            // conformance test (`psql -c 'START_REPLICATION 0/1'` must exit
-            // non-zero with a syntax error from the server).
-            if (this.opts.replication !== undefined) {
-                params.replication = this.opts.replication;
-            }
-            this.startupResolve = resolve;
-            this.startupReject = reject;
-            this.socket.write(StartupMessage(params));
-        });
-    }
-    /**
-     * Enforce `require_auth` against an observed server-requested method.
-     * Returns true when the connection should proceed; false (with
-     * {@link failStartup} already called) when the policy was violated.
-     */
-    checkRequireAuth(observed) {
-        const policy = this.opts.requireAuth;
-        if (policy === undefined)
-            return true;
-        const hit = policy.methods.has(observed);
-        const allowed = policy.negated ? !hit : hit;
-        if (!allowed) {
-            this.failStartup(new Error(`auth method "${observed}" requirement failed`));
-            return false;
-        }
-        return true;
-    }
-    handleAuthMessage(msg) {
-        switch (msg.type) {
-            case "AuthenticationOk": {
-                // libpq parity: channel_binding=require demands that some prior
-                // auth step actually negotiated channel binding. A bare
-                // AuthenticationOk after no challenge ("trust") or after a cert
-                // exchange ("cert" HBA, clientcert=verify-full) means no SCRAM
-                // happened and we must refuse.
-                if (this.opts.channelBinding === "require" &&
-                    (this.scram === null ||
-                        this.scram.mechanism !== "SCRAM-SHA-256-PLUS")) {
-                    this.failStartup(new Error("channel binding required, but server authenticated client without channel binding"));
-                    return;
-                }
-                // Mutual-auth integrity: if a SCRAM exchange was started it MUST have
-                // completed via AuthenticationSASLFinal (where the server signature is
-                // verified). A server that sends SASLContinue then jumps to
-                // AuthenticationOk never proves it knows the password (review #8).
-                if (this.scram !== null && !this.saslFinalSeen) {
-                    this.failStartup(new Error("server sent AuthenticationOk without completing SCRAM " +
-                        "authentication (server signature not verified)"));
-                    return;
-                }
-                // require_auth=none allows trust auth; anything else is rejected
-                // here. If a prior challenge was sent and validated, skip — that
-                // method was already accepted by the check at its own branch.
-                if (!this.authChallengeSeen && !this.checkRequireAuth("none")) {
-                    return;
-                }
-                this.state = "await-ready";
-                return;
-            }
-            case "AuthenticationCleartextPassword": {
-                this.authChallengeSeen = true;
-                if (this.opts.channelBinding === "require") {
-                    this.failStartup(new Error("channel binding required but not supported by server's authentication request"));
-                    return;
-                }
-                if (!this.checkRequireAuth("password"))
-                    return;
-                if (this.opts.password === undefined) {
-                    this.failStartup(new Error("Server requested cleartext password but no password was provided"));
-                    return;
-                }
-                this.passwordUsed = true;
-                this.socket.write(PasswordMessage(this.opts.password));
-                return;
-            }
-            case "AuthenticationMD5Password": {
-                this.authChallengeSeen = true;
-                if (this.opts.channelBinding === "require") {
-                    this.failStartup(new Error("channel binding required but not supported by server's authentication request"));
-                    return;
-                }
-                if (!this.checkRequireAuth("md5"))
-                    return;
-                if (this.opts.password === undefined) {
-                    this.failStartup(new Error("Server requested MD5 password but no password was provided"));
-                    return;
-                }
-                const payload = md5AuthPayload(this.opts.user, this.opts.password, msg.salt);
-                this.passwordUsed = true;
-                this.socket.write(PasswordMessage(payload));
-                return;
-            }
-            case "AuthenticationSASL": {
-                this.authChallengeSeen = true;
-                if (this.opts.password === undefined) {
-                    this.failStartup(new Error("Server requested SASL auth but no password was provided"));
-                    return;
-                }
-                if (!this.checkRequireAuth("scram-sha-256"))
-                    return;
-                // channel_binding=require AND server didn't offer the PLUS
-                // variant — refuse before the SASL handshake starts. The check
-                // is split between here (no PLUS in the mechanism list) and
-                // chooseMechanism's fallback (PLUS present but no binding data).
-                if (this.opts.channelBinding === "require" &&
-                    !msg.mechanisms.includes("SCRAM-SHA-256-PLUS")) {
-                    this.failStartup(new Error("channel binding required but not supported by server's authentication request"));
-                    return;
-                }
-                if (this.opts.channelBinding === "require" &&
-                    this.channelBindingData === null) {
-                    this.failStartup(new Error("channel binding required but not supported by server's authentication request"));
-                    return;
-                }
-                try {
-                    this.scram = createScramClient({
-                        user: this.opts.user,
-                        password: this.opts.password,
-                        mechanisms: msg.mechanisms,
-                        channelBinding: this.channelBindingData !== null &&
-                            this.opts.channelBinding !== "disable"
-                            ? {
-                                type: "tls-server-end-point",
-                                data: this.channelBindingData,
-                            }
-                            : undefined,
-                    });
-                    const { mechanism, clientFirstMessage } = this.scram.start();
-                    this.passwordUsed = true;
-                    this.socket.write(SASLInitialResponse(mechanism, clientFirstMessage));
-                }
-                catch (err) {
-                    this.failStartup(err);
-                }
-                return;
-            }
-            case "AuthenticationSASLContinue": {
-                if (!this.scram) {
-                    this.failStartup(new Error("Received AuthenticationSASLContinue without an active SCRAM client"));
-                    return;
-                }
-                try {
-                    const reply = this.scram.continue(msg.data);
-                    this.socket.write(SASLResponse(reply));
-                }
-                catch (err) {
-                    this.failStartup(err);
-                }
-                return;
-            }
-            case "AuthenticationSASLFinal": {
-                if (!this.scram) {
-                    this.failStartup(new Error("Received AuthenticationSASLFinal without an active SCRAM client"));
-                    return;
-                }
-                try {
-                    this.scram.finish(msg.data);
-                    this.saslFinalSeen = true;
-                }
-                catch (err) {
-                    this.failStartup(err);
-                }
-                return;
-            }
-            case "ErrorResponse":
-                this.failStartup(fieldsToConnectError(msg.fields));
-                return;
-            case "NoticeResponse":
-                this.notify.emit(fieldsToNotice(msg.fields));
-                return;
-            default:
-                // ParameterStatus / BackendKeyData / ReadyForQuery may arrive in
-                // `await-ready`; auth state shouldn't see them, but we tolerate by
-                // forwarding to the post-auth handler if so.
-                this.handleAwaitReady(msg);
-                return;
-        }
-    }
-    handleAwaitReady(msg) {
-        switch (msg.type) {
-            case "ParameterStatus":
-                this.params.set(msg.name, msg.value);
-                if (msg.name === "server_version") {
-                    this.serverVersion = parseServerVersion(msg.value);
-                }
-                return;
-            case "BackendKeyData":
-                this.processId = msg.processId;
-                this.secretKey = msg.secretKey;
-                return;
-            case "ReadyForQuery":
-                this.txStatus = msg.status;
-                this.state = "idle";
-                if (this.startupResolve) {
-                    const r = this.startupResolve;
-                    this.startupResolve = null;
-                    this.startupReject = null;
-                    r();
-                }
-                return;
-            case "ErrorResponse":
-                this.failStartup(fieldsToConnectError(msg.fields));
-                return;
-            case "NoticeResponse":
-                this.notify.emit(fieldsToNotice(msg.fields));
-                return;
-            default:
-                this.failStartup(new Error(`Unexpected message ${msg.type} during connection startup`));
-                return;
-        }
-    }
-    failStartup(err) {
-        if (this.startupReject) {
-            const r = this.startupReject;
-            this.startupResolve = null;
-            this.startupReject = null;
-            r(err);
-        }
-        try {
-            this.socket.destroy();
-        }
-        catch {
-            // ignore
-        }
-        this.state = "closed";
-    }
-    // -------------------------------------------------------------------------
-    // COPY state machine (WP-16).
-    //
-    // The frontend transitions through:
-    //   idle → in-query (after writing Query("COPY …"))
-    //   in-query → in-copy-in  on CopyInResponse
-    //   in-query → in-copy-out on CopyOutResponse
-    //   in-copy-in  → idle on ReadyForQuery (after our CopyDone/CopyFail +
-    //                                        server CommandComplete)
-    //   in-copy-out → idle on ReadyForQuery (after server CopyDone +
-    //                                        CommandComplete)
-    //
-    // ErrorResponse may arrive at any point; we drain until ReadyForQuery and
-    // then surface as a rejected promise.
-    // -------------------------------------------------------------------------
-    makeCopyInStream() {
-        const driver = this.copyIn;
-        if (!driver) {
-            throw new Error("PgConnection: makeCopyInStream called without driver");
-        }
-        return {
-            write: (chunk) => {
-                if (this.state === "closed") {
-                    return Promise.reject(new Error("Connection closed"));
-                }
-                if (driver.closed) {
-                    return Promise.reject(new Error("CopyInStream already closed"));
-                }
-                const data = typeof chunk === "string"
-                    ? Buffer.from(chunk, "utf8")
-                    : chunk;
-                return new Promise((resolve, reject) => {
-                    this.socket.write(CopyData(data), (err) => {
-                        if (err)
-                            reject(err);
-                        else
-                            resolve();
-                    });
-                });
-            },
-            end: () => {
-                if (driver.closed) {
-                    return Promise.reject(new Error("CopyInStream already closed"));
-                }
-                driver.closed = true;
-                return new Promise((resolve, reject) => {
-                    driver.resolveDone = resolve;
-                    driver.rejectDone = reject;
-                    this.socket.write(CopyDone());
-                });
-            },
-            fail: (reason) => {
-                if (driver.closed) {
-                    return Promise.reject(new Error("CopyInStream already closed"));
-                }
-                driver.closed = true;
-                return new Promise((resolve, reject) => {
-                    // The server is expected to reject with an ErrorResponse echoing
-                    // our reason; we still resolve so callers can move on. We wire the
-                    // resolver after the socket flush so a fast-close error surfaces.
-                    driver.resolveDone = () => {
-                        resolve();
-                    };
-                    driver.rejectDone = reject;
-                    this.socket.write(CopyFail(reason));
-                });
-            },
-        };
-    }
-    makeCopyOutStream() {
-        const driver = this.copyOut;
-        if (!driver) {
-            throw new Error("PgConnection: makeCopyOutStream called without driver");
-        }
-        // Capture the state-getter as a closure so the iterator can observe
-        // connection close without holding a `this` alias (no-this-alias rule).
-        const isClosed = () => this.state === "closed";
-        // Resume reading once the buffered data drains — paired with the
-        // pause() the CopyData handler applies at the high-water mark (#11).
-        const resumeSocket = () => {
-            this.socket.resume?.();
-        };
-        return {
-            [Symbol.asyncIterator]() {
-                return {
-                    async next() {
-                        for (;;) {
-                            if (driver.queue.length > 0) {
-                                const next = driver.queue.shift();
-                                if (next === undefined)
-                                    continue;
-                                driver.queuedBytes -= next.length;
-                                if (driver.queuedBytes <= COPY_OUT_LWM)
-                                    resumeSocket();
-                                return { value: next, done: false };
-                            }
-                            if (driver.error) {
-                                // ConnectError isn't strictly an Error instance; the rule
-                                // wants a real Error. Wrap once before throwing.
-                                const ce = driver.error;
-                                const wrapped = new Error(ce.message);
-                                wrapped.cause =
-                                    ce;
-                                throw wrapped;
-                            }
-                            if (driver.done) {
-                                return { value: undefined, done: true };
-                            }
-                            if (isClosed()) {
-                                throw new Error("Connection closed mid-COPY-OUT");
-                            }
-                            await new Promise((resolve) => {
-                                driver.waker = resolve;
-                            });
-                        }
-                    },
-                    return() {
-                        // Consumer broke early. We must keep reading the wire until
-                        // ReadyForQuery to clear the protocol state, but we mark the
-                        // stream abandoned (so the handler DROPS further CopyData rather
-                        // than buffering it) and free what's queued — otherwise RSS grows
-                        // to the full result size (review item #11). Resume in case the
-                        // socket was paused at the high-water mark.
-                        driver.abandoned = true;
-                        driver.queue.length = 0;
-                        driver.queuedBytes = 0;
-                        resumeSocket();
-                        return Promise.resolve({
-                            value: undefined,
-                            done: true,
-                        });
-                    },
-                };
-            },
-        };
-    }
-    /**
-     * Handle messages arriving in `in-query` state when there is no
-     * `pendingQuery` — i.e. the caller invoked `startCopyIn` / `startCopyOut`
-     * and is waiting for the server to switch into copy mode.
-     */
-    handleCopyStartMessage(msg) {
-        switch (msg.type) {
-            case "CopyInResponse":
-                // COPY-in-pipeline: libpq aborts the connection with this exact
-                // diagnostic (matching upstream psql's behaviour). The `\copy`
-                // command layer detects pipeline-active and fails fast before
-                // reaching the wire, but if anything else slips through we abort
-                // here as a defence-in-depth.
-                if (this._extPipelineActive) {
-                    this.abortForCopyInPipeline();
-                    return;
-                }
-                if (this.copyIn) {
-                    this.state = "in-copy-in";
-                    const r = this.copyStartResolve;
-                    this.copyStartResolve = null;
-                    this.copyStartReject = null;
-                    if (r)
-                        r();
-                }
-                return;
-            case "CopyOutResponse":
-                if (this._extPipelineActive) {
-                    this.abortForCopyInPipeline();
-                    return;
-                }
-                if (this.copyOut) {
-                    this.state = "in-copy-out";
-                    const r = this.copyStartResolve;
-                    this.copyStartResolve = null;
-                    this.copyStartReject = null;
-                    if (r)
-                        r();
-                }
-                return;
-            case "ErrorResponse": {
-                const err = fieldsToConnectError(msg.fields);
-                if (this.copyIn) {
-                    if (this.copyStartReject)
-                        this.copyStartReject(err);
-                    this.copyStartResolve = null;
-                    this.copyStartReject = null;
-                    this.copyIn = null;
-                }
-                if (this.copyOut) {
-                    if (this.copyStartReject)
-                        this.copyStartReject(err);
-                    this.copyStartResolve = null;
-                    this.copyStartReject = null;
-                    this.copyOut = null;
-                }
-                // Stay in `in-query` until ReadyForQuery, then return to idle below.
-                return;
-            }
-            case "ReadyForQuery":
-                // ReadyForQuery without a prior CopyXxxResponse means the server
-                // immediately rejected the COPY (we surfaced the ErrorResponse just
-                // above) — return to idle so the next command can fire.
-                this.txStatus = msg.status;
-                this.state = "idle";
-                return;
-            case "NoticeResponse":
-                this.notify.emit(fieldsToNotice(msg.fields));
-                return;
-            case "ParameterStatus":
-                this.params.set(msg.name, msg.value);
-                return;
-            default:
-                if (this.copyStartReject) {
-                    this.copyStartReject(new Error(`Unexpected backend message before COPY response: ${msg.type}`));
-                }
-                this.copyStartResolve = null;
-                this.copyStartReject = null;
-                return;
-        }
-    }
-    handleCopyInMessage(msg) {
-        const driver = this.copyIn;
-        if (!driver)
-            return;
-        switch (msg.type) {
-            case "CommandComplete":
-                driver.commandTag = msg.tag;
-                this.lastCopyTag = msg.tag;
-                return;
-            case "ErrorResponse":
-                driver.error = fieldsToConnectError(msg.fields);
-                return;
-            case "NoticeResponse":
-                this.notify.emit(fieldsToNotice(msg.fields));
-                return;
-            case "ParameterStatus":
-                this.params.set(msg.name, msg.value);
-                return;
-            case "ReadyForQuery":
-                this.txStatus = msg.status;
-                this.state = "idle";
-                this.copyIn = null;
-                if (driver.error) {
-                    if (driver.rejectDone)
-                        driver.rejectDone(driver.error);
-                }
-                else if (driver.resolveDone) {
-                    driver.resolveDone();
-                }
-                return;
-            default:
-                // Unknown messages mid-COPY-IN are protocol errors; record and let
-                // the trailing ReadyForQuery flush the state.
-                driver.error = {
-                    severity: "ERROR",
-                    message: `Unexpected backend message during COPY IN: ${msg.type}`,
-                };
-                return;
-        }
-    }
-    handleCopyOutMessage(msg) {
-        const driver = this.copyOut;
-        if (!driver)
-            return;
-        switch (msg.type) {
-            case "CopyData": {
-                // Consumer broke early: drop instead of buffering (review item #11).
-                if (driver.abandoned)
-                    return;
-                driver.queue.push(msg.data);
-                driver.queuedBytes += msg.data.length;
-                // Apply backpressure when the sink falls behind: pause the socket so
-                // the server stops flooding us. `next()` resumes at the low-water
-                // mark. (No-op if the socket doesn't expose pause(), e.g. a mock.)
-                if (driver.queuedBytes >= COPY_OUT_HWM) {
-                    this.socket.pause?.();
-                }
-                if (driver.waker) {
-                    const w = driver.waker;
-                    driver.waker = null;
-                    w();
-                }
-                return;
-            }
-            case "CopyDone":
-                // Server signals it's done sending — we now expect CommandComplete +
-                // ReadyForQuery. Stay in in-copy-out until ReadyForQuery; the queue
-                // may still drain via the consumer.
-                return;
-            case "CommandComplete":
-                driver.commandTag = msg.tag;
-                this.lastCopyTag = msg.tag;
-                return;
-            case "ErrorResponse":
-                driver.error = fieldsToConnectError(msg.fields);
-                return;
-            case "NoticeResponse":
-                this.notify.emit(fieldsToNotice(msg.fields));
-                return;
-            case "ParameterStatus":
-                this.params.set(msg.name, msg.value);
-                return;
-            case "ReadyForQuery":
-                this.txStatus = msg.status;
-                this.state = "idle";
-                driver.done = true;
-                this.copyOut = null;
-                if (driver.waker) {
-                    const w = driver.waker;
-                    driver.waker = null;
-                    w();
-                }
-                return;
-            default:
-                driver.error = {
-                    severity: "ERROR",
-                    message: `Unexpected backend message during COPY OUT: ${msg.type}`,
-                };
-                if (driver.waker) {
-                    const w = driver.waker;
-                    driver.waker = null;
-                    w();
-                }
-                return;
-        }
-    }
-    // -------------------------------------------------------------------------
-    // Query state machine
-    // -------------------------------------------------------------------------
-    handleQueryMessage(msg) {
-        const q = this.pendingQuery;
-        if (!q) {
-            // No active execSimple — we must be in the "starting a COPY" phase
-            // where the caller wrote Query("COPY …") via startCopyIn/startCopyOut.
-            this.handleCopyStartMessage(msg);
-            return;
-        }
-        switch (msg.type) {
-            case "RowDescription":
-                q.current = {
-                    command: "",
-                    rowCount: null,
-                    oid: null,
-                    fields: msg.fields,
-                    rows: [],
-                    notices: [],
-                };
-                return;
-            case "DataRow": {
-                if (!q.current) {
-                    // Server sent rows without a prior description — extremely rare
-                    // (only for some legacy COPY error paths). Treat as empty desc.
-                    q.current = {
-                        command: "",
-                        rowCount: null,
-                        oid: null,
-                        fields: [],
-                        rows: [],
-                        notices: [],
-                    };
-                }
-                q.current.rows.push(decodeDataRow(msg.values, q.current.fields));
-                return;
-            }
-            case "CommandComplete": {
-                const { command, rowCount, oid } = parseCommandTag(msg.tag);
-                const set = q.current ?? {
-                    command,
-                    rowCount: rowCount,
-                    oid,
-                    fields: [],
-                    rows: [],
-                    notices: [],
-                };
-                set.command = command;
-                set.rowCount = rowCount;
-                set.oid = oid;
-                set.notices = q.notices.splice(0);
-                q.finished.push(set);
-                q.current = null;
-                return;
-            }
-            case "EmptyQueryResponse": {
-                const set = {
-                    command: "",
-                    rowCount: null,
-                    oid: null,
-                    fields: [],
-                    rows: [],
-                    notices: q.notices.splice(0),
-                };
-                q.finished.push(set);
-                q.current = null;
-                return;
-            }
-            case "ParameterStatus":
-                this.params.set(msg.name, msg.value);
-                if (msg.name === "server_version") {
-                    this.serverVersion = parseServerVersion(msg.value);
-                }
-                return;
-            case "NoticeResponse": {
-                const notice = fieldsToNotice(msg.fields);
-                q.notices.push(notice);
-                this.notify.emit(notice);
-                return;
-            }
-            case "NotificationResponse":
-                this.notify.emitNotification(msg.channel, msg.payload, msg.processId);
-                return;
-            case "ErrorResponse": {
-                q.error = fieldsToConnectError(msg.fields);
-                // Don't reject yet — ReadyForQuery will arrive shortly and we want
-                // to drain queued NoticeResponse messages first.
-                return;
-            }
-            case "ReadyForQuery": {
-                this.txStatus = msg.status;
-                this.state = "idle";
-                this.pendingQuery = null;
-                if (q.error) {
-                    // Mirror libpq's behaviour: the result list contains every
-                    // PGresult the server produced before the ErrorResponse — for
-                    // a `\;`-chained simple-query batch, that's all the statements
-                    // before the failing one. We surface them by attaching the
-                    // accumulated `finished[]` to the thrown Error so callers
-                    // (`executeAndPrint`) can render the pre-error rows in order
-                    // before printing the error itself.
-                    const err = asThrowable(q.error);
-                    err.partialResults = q.finished;
-                    q.reject(err);
-                }
-                else {
-                    q.resolve(q.finished);
-                }
-                return;
-            }
-            case "CopyInResponse": {
-                // PG 17 added pipeline + COPY support but libpq still rejects the
-                // combination ("COPY in a pipeline is not supported, aborting
-                // connection"). Upstream psql surfaces that diagnostic and tears down
-                // the connection. We mirror the behaviour: if the user fires a COPY
-                // statement via execSimple while a pipeline is active, abort.
-                if (this._extPipelineActive) {
-                    this.abortForCopyInPipeline();
-                    return;
-                }
-                // CopyInResponse during execSimple (no active CopyIn driver) — the
-                // common path is `COPY ... FROM STDIN` as one segment of a `\;`-chained
-                // simple-query batch. Upstream psql pumps stdin lines until `\.`; the
-                // mainloop pre-scans its input and buffers the bytes into
-                // `copyInMidBatchQueue` before calling execSimple. We pop the head
-                // buffer and ship it as CopyData + CopyDone. If no buffer is queued
-                // (caller forgot to seed, or scan was inaccurate), CopyFail so the
-                // server returns to ReadyForQuery rather than blocking.
-                const data = this.copyInMidBatchQueue.shift();
-                if (data !== undefined) {
-                    try {
-                        // Empty payload still needs a CopyDone — the server transitions
-                        // back to CopyIn-done state on CopyDone regardless of byte
-                        // count. Wrapping a zero-length CopyData is harmless.
-                        if (data.length > 0) {
-                            this.socket.write(CopyData(data));
-                        }
-                        this.socket.write(CopyDone());
-                    }
-                    catch {
-                        // Write failures are surfaced via socket 'error' / 'close'
-                        // handlers which will fail the pending query.
-                    }
-                    return;
-                }
-                q.error = {
-                    severity: "ERROR",
-                    message: "COPY FROM STDIN not supported via execSimple — use \\copy or startCopyIn",
-                };
-                try {
-                    this.socket.write(CopyFail("COPY FROM STDIN not driven by client"));
-                }
-                catch {
-                    // Write failures are surfaced via socket 'error' / 'close' handlers
-                    // which will fail the pending query — nothing to do here.
-                }
-                return;
-            }
-            case "CopyOutResponse": {
-                if (this._extPipelineActive) {
-                    this.abortForCopyInPipeline();
-                    return;
-                }
-                // CopyOutResponse during execSimple (no active CopyOut driver) — the
-                // common path is `COPY ... TO STDOUT` as one segment of a `\;`-chained
-                // simple-query batch. We accumulate the CopyData payloads onto the
-                // current ResultSet's `copyOutBytes` so the renderer emits them at
-                // the result's position in the chain — instead of streaming them
-                // straight to a sink at receive time, which would hoist the COPY
-                // bytes above any tuples-producing results that haven't been
-                // rendered yet (see hunk 5722-5730 in regress/psql).
-                this.copyOutMidBatchActive = true;
-                q.current = q.current ?? {
-                    command: "",
-                    rowCount: null,
-                    oid: null,
-                    fields: [],
-                    rows: [],
-                    notices: [],
-                };
-                q.current.copyOutBytes = q.current.copyOutBytes ?? [];
-                return;
-            }
-            case "CopyData": {
-                // CopyData arrives during execSimple only when we're in the mid-batch
-                // COPY-OUT phase (CopyOutResponse flipped the flag above). Stash the
-                // payload on the current result's `copyOutBytes` so the caller can
-                // render in order. Anything else is a protocol error.
-                if (this.copyOutMidBatchActive) {
-                    const cur = q.current;
-                    if (cur) {
-                        cur.copyOutBytes = cur.copyOutBytes ?? [];
-                        cur.copyOutBytes.push(msg.data);
-                    }
-                    return;
-                }
-                q.error = {
-                    severity: "ERROR",
-                    message: "Unexpected backend message during query: CopyData",
-                };
-                return;
-            }
-            case "CopyDone": {
-                // Server signals end of COPY-OUT data — next message will be
-                // CommandComplete for the COPY statement, then the batch resumes.
-                if (this.copyOutMidBatchActive) {
-                    this.copyOutMidBatchActive = false;
-                    return;
-                }
-                q.error = {
-                    severity: "ERROR",
-                    message: "Unexpected backend message during query: CopyDone",
-                };
-                return;
-            }
-            case "CopyBothResponse": {
-                // Walsender (`replication=database` / `replication=true`) commands
-                // such as `START_REPLICATION` transition the connection into a
-                // CopyBoth streaming phase (WAL records flowing from server +
-                // keepalive replies flowing from client). This client does not
-                // implement WAL streaming — upstream libpq's `PQexec` similarly
-                // refuses to handle PGRES_COPY_BOTH and surfaces a diagnostic. We
-                // mirror that: reject the pending query with a "syntax error" style
-                // message (matching the conformance assertion) and tear the socket
-                // down so the next query / process exit is clean.
-                const cbErr = {
-                    severity: "ERROR",
-                    code: "0A000",
-                    message: "syntax error: unexpected CopyBothResponse from server (replication streaming is not supported by this client)",
-                };
-                q.error = cbErr;
-                q.reject(asThrowable(cbErr));
-                this.pendingQuery = null;
-                this.socketError = new Error(cbErr.message);
-                try {
-                    this.socket.destroy();
-                }
-                catch {
-                    // ignore
-                }
-                this.state = "closed";
-                return;
-            }
-            default:
-                // Unknown messages during a query are protocol errors but not fatal
-                // for the connection — record them.
-                q.error = {
-                    severity: "ERROR",
-                    message: `Unexpected backend message during query: ${msg.type}`,
-                };
-                return;
-        }
-    }
-    // -------------------------------------------------------------------------
-    // Socket → parser → state dispatch
-    // -------------------------------------------------------------------------
-    onData(chunk) {
-        let messages;
-        try {
-            messages = this.parser.feed(chunk);
-        }
-        catch (err) {
-            this.socketError =
-                err instanceof Error ? err : new Error(String(err));
-            this.failPending(this.socketError);
-            try {
-                this.socket.destroy();
-            }
-            catch {
-                // ignore
-            }
-            this.state = "closed";
-            return;
-        }
-        for (const msg of messages) {
-            this.dispatch(msg);
-            if (this.state === "closed")
-                break;
-        }
-    }
-    dispatch(msg) {
-        // Async backend messages always allowed. NotificationResponse can arrive
-        // in *any* state since LISTEN payloads come in whenever a NOTIFY fires.
-        if (msg.type === "NotificationResponse") {
-            this.notify.emitNotification(msg.channel, msg.payload, msg.processId);
-            return;
-        }
-        switch (this.state) {
-            case "auth":
-                this.handleAuthMessage(msg);
-                return;
-            case "await-ready":
-                this.handleAwaitReady(msg);
-                return;
-            case "idle":
-                // ParameterStatus changes can arrive asynchronously (SET).
-                if (msg.type === "ParameterStatus") {
-                    this.params.set(msg.name, msg.value);
-                    if (msg.name === "server_version") {
-                        this.serverVersion = parseServerVersion(msg.value);
-                    }
-                    return;
-                }
-                if (msg.type === "NoticeResponse") {
-                    this.notify.emit(fieldsToNotice(msg.fields));
-                    return;
-                }
-                // (NotificationResponse is handled by the early-out above.)
-                // Anything else in idle is unexpected.
-                this.socketError = new Error(`Unexpected ${msg.type} in idle state`);
-                try {
-                    this.socket.destroy();
-                }
-                catch {
-                    // ignore
-                }
-                this.state = "closed";
-                return;
-            case "in-query":
-                this.handleQueryMessage(msg);
-                return;
-            case "in-extended":
-                this.handleExtendedMessage(msg);
-                return;
-            case "in-copy-in":
-                this.handleCopyInMessage(msg);
-                return;
-            case "in-copy-out":
-                this.handleCopyOutMessage(msg);
-                return;
-            case "closed":
-                return;
-        }
-    }
-    failPending(err) {
-        if (this.pendingQuery) {
-            const q = this.pendingQuery;
-            this.pendingQuery = null;
-            // If the server delivered an ErrorResponse just before the socket
-            // closed (e.g. a FATAL "terminating connection due to administrator
-            // command" when the backend is killed mid-query), prefer that
-            // structured error over the generic "Socket closed" fallback so the
-            // diagnostic carries the server's wording. Mirrors libpq's behaviour
-            // where `PQexec` surfaces the FATAL message and `PQerrorMessage`
-            // returns the server-supplied text.
-            //
-            // `q.error` is initialised to `null` by `execSimple`; only a non-null
-            // value indicates a server-side ErrorResponse was actually captured.
-            q.reject(q.error != null ? asThrowable(q.error) : err);
-        }
-        if (this.extDriver) {
-            const d = this.extDriver;
-            this.extDriver = null;
-            for (const op of d.queue)
-                op.reject(err);
-        }
-        if (this.startupReject) {
-            const r = this.startupReject;
-            this.startupResolve = null;
-            this.startupReject = null;
-            r(err);
-        }
-        if (this.copyStartReject) {
-            const r = this.copyStartReject;
-            this.copyStartResolve = null;
-            this.copyStartReject = null;
-            r(err);
-        }
-        if (this.copyIn) {
-            const d = this.copyIn;
-            this.copyIn = null;
-            if (d.rejectDone)
-                d.rejectDone(err);
-        }
-        if (this.copyOut) {
-            const d = this.copyOut;
-            this.copyOut = null;
-            d.error =
-                err instanceof Error
-                    ? { severity: "ERROR", message: err.message }
-                    : { severity: "ERROR", message: String(err) };
-            if (d.waker) {
-                const w = d.waker;
-                d.waker = null;
-                w();
-            }
-        }
-    }
-    ensureIdle() {
-        if (this.state === "closed") {
-            throw new Error("PgConnection: connection is closed");
-        }
-        if (this.state !== "idle" && this.state !== "in-extended") {
-            throw new Error(`PgConnection: cannot start query in state ${this.state}`);
-        }
-    }
-    // -------------------------------------------------------------------------
-    // Extended-protocol driver (WP-21).
-    //
-    // Each public enqueueX method appends one op to `extDriver.queue` and
-    // returns a Promise that resolves when the op's terminator backend message
-    // arrives. The caller is responsible for writing the matching wire frame
-    // (Parse/Bind/Describe/Execute/Close/Sync) to the socket.
-    // -------------------------------------------------------------------------
-    startExtendedBatch() {
-        if (this.state === "idle") {
-            this.state = "in-extended";
-            this.extDriver = { queue: [], error: null };
-        }
-        else if (this.state !== "in-extended") {
-            throw new Error(`PgConnection: cannot start extended batch in state ${this.state}`);
-        }
-        else if (!this.extDriver) {
-            this.extDriver = { queue: [], error: null };
-        }
-    }
-    writeRaw(buf) {
-        this.socket.write(buf);
-    }
-    enqueueParse() {
-        return this.enqueueOp({
-            kind: "parse",
-            resolve: () => undefined,
-            reject: () => undefined,
-        });
-    }
-    enqueueBind() {
-        return this.enqueueOp({
-            kind: "bind",
-            resolve: () => undefined,
-            reject: () => undefined,
-        });
-    }
-    enqueueDescribeStatement() {
-        return this.enqueueOp({
-            kind: "describeS",
-            resolve: () => undefined,
-            reject: () => undefined,
-            paramOids: null,
-        });
-    }
-    enqueueDescribePortal() {
-        return this.enqueueOp({
-            kind: "describeP",
-            resolve: () => undefined,
-            reject: () => undefined,
-        });
-    }
-    /**
-     * Variant of {@link enqueueDescribePortal} that pipes the resolved fields
-     * onto the very next `execute` op already (or yet to be) on the queue.
-     */
-    enqueueDescribePortalIntoNextExecute() {
-        const driver = this.extDriver;
-        if (!driver) {
-            return Promise.reject(new Error("enqueueDescribePortalIntoNextExecute: not in extended state"));
-        }
-        return new Promise((resolve, reject) => {
-            driver.queue.push({
-                kind: "describeP",
-                resolve: (v) => {
-                    const fields = v;
-                    for (const op of driver.queue) {
-                        if (op.kind === "execute" && op.fields === null) {
-                            op.fields = fields;
-                            break;
-                        }
-                    }
-                    resolve();
-                },
-                reject,
-            });
-        });
-    }
-    enqueueExecute() {
-        return this.enqueueOp({
-            kind: "execute",
-            resolve: () => undefined,
-            reject: () => undefined,
-            current: null,
-            notices: [],
-            fields: null,
-        });
-    }
-    enqueueExecuteWithFields(fields) {
-        return this.enqueueOp({
-            kind: "execute",
-            resolve: () => undefined,
-            reject: () => undefined,
-            current: null,
-            notices: [],
-            fields,
-        });
-    }
-    enqueueClose() {
-        return this.enqueueOp({
-            kind: "close",
-            resolve: () => undefined,
-            reject: () => undefined,
-        });
-    }
-    enqueueSync() {
-        return this.enqueueOp({
-            kind: "sync",
-            resolve: () => undefined,
-            reject: () => undefined,
-        });
-    }
-    enqueueOp(opSkeleton) {
-        if (!this.extDriver) {
-            return Promise.reject(new Error("enqueueOp: not in extended state"));
-        }
-        const driver = this.extDriver;
-        return new Promise((resolve, reject) => {
-            const op = opSkeleton;
-            op.resolve = resolve;
-            op.reject = reject;
-            driver.queue.push(op);
-        });
-    }
-    handleExtendedMessage(msg) {
-        const driver = this.extDriver;
-        if (!driver)
-            return;
-        if (msg.type === "ParameterStatus") {
-            this.params.set(msg.name, msg.value);
-            if (msg.name === "server_version") {
-                this.serverVersion = parseServerVersion(msg.value);
-            }
-            return;
-        }
-        if (msg.type === "NoticeResponse") {
-            const notice = fieldsToNotice(msg.fields);
-            this.notify.emit(notice);
-            const head = driver.queue[0];
-            if (head && head.kind === "execute")
-                head.notices.push(notice);
-            return;
-        }
-        if (msg.type === "NotificationResponse") {
-            this.notify.emitNotification(msg.channel, msg.payload, msg.processId);
-            return;
-        }
-        if (msg.type === "ErrorResponse") {
-            driver.error = fieldsToConnectError(msg.fields);
-            // Reject ALL queued non-sync ops eagerly. Upstream server semantics:
-            // once a P/B/D/E op errors, the server skips every subsequent message
-            // until the next Sync. If the client (e.g. `\flushrequest` + `\getresults`
-            // after an aborted bind) doesn't issue Sync next, no further wire
-            // messages will arrive — so we must cascade-reject the rest of the
-            // queue NOW or those promises hang forever.
-            //
-            // Mirror libpq's `PGRES_PIPELINE_ABORTED` marker for follow-on ops:
-            // the FIRST failing op carries the real `ErrorResponse` payload,
-            // every subsequent op gets a synthetic "Pipeline aborted, command
-            // did not run" error so `\getresults` / `\endpipeline` can
-            // distinguish the originating ERROR from the cascaded skips. See
-            // upstream `pqPipelineProcessQueue` in `fe-exec.c`.
-            let first = true;
-            while (driver.queue.length > 0) {
-                const head = driver.queue[0];
-                if (head.kind === "sync")
-                    break;
-                driver.queue.shift();
-                if (first) {
-                    head.reject(driver.error);
-                    first = false;
-                }
-                else {
-                    head.reject(pipelineAbortedError());
-                }
-            }
-            return;
-        }
-        // COPY-in-pipeline: when an `Execute` in pipeline mode hits a
-        // `COPY ... FROM STDIN` / `COPY ... TO STDOUT`, the server replies
-        // with `CopyInResponse` / `CopyOutResponse` instead of the usual
-        // result-stream messages. Upstream libpq refuses the combination
-        // with "COPY in a pipeline is not supported, aborting connection"
-        // and tears the connection down. Mirror that so `\startpipeline +
-        // COPY ...` surfaces the expected fatal error rather than hanging
-        // on a response the extended driver doesn't know how to consume.
-        if (msg.type === "CopyInResponse" || msg.type === "CopyOutResponse") {
-            this.abortForCopyInPipeline();
-            return;
-        }
-        // Drain any ops added to the queue AFTER the initial cascade-reject
-        // (e.g. a `\sendpipeline` issued by the user once `\getresults`
-        // returned the first ErrorResponse) — those ops were never visible
-        // to the original cascade loop, but the server skipped them too
-        // because it stays in PIPELINE_ABORTED until the next Sync. Mark
-        // them as cascaded (`pipelineAborted`) rather than the real error:
-        // libpq surfaces the real error only on the OP that actually
-        // failed, and stamps every subsequent skipped op with the
-        // PGRES_PIPELINE_ABORTED marker. The cmd layer's `\getresults` /
-        // `\endpipeline` paths render the marker as
-        // `Pipeline aborted, command did not run` (no `ERROR:` prefix).
-        while (driver.error !== null) {
-            const head = driver.queue[0];
-            if (!head || head.kind === "sync")
-                break;
-            driver.queue.shift();
-            head.reject(pipelineAbortedError());
-        }
-        const head = driver.queue[0];
-        if (!head) {
-            this.protocolFail(new Error(`Unexpected backend message ${msg.type} in in-extended`));
-            return;
-        }
-        switch (msg.type) {
-            case "ParseComplete":
-                if (head.kind !== "parse") {
-                    this.protocolFail(new Error("ParseComplete arrived but head op is " + head.kind));
-                    return;
-                }
-                driver.queue.shift();
-                head.resolve(undefined);
-                return;
-            case "BindComplete":
-                if (head.kind !== "bind") {
-                    this.protocolFail(new Error("BindComplete arrived but head op is " + head.kind));
-                    return;
-                }
-                driver.queue.shift();
-                head.resolve(undefined);
-                return;
-            case "CloseComplete":
-                if (head.kind !== "close") {
-                    this.protocolFail(new Error("CloseComplete arrived but head op is " + head.kind));
-                    return;
-                }
-                driver.queue.shift();
-                head.resolve(undefined);
-                return;
-            case "ParameterDescription":
-                if (head.kind !== "describeS") {
-                    this.protocolFail(new Error("ParameterDescription arrived but head op is " +
-                        head.kind));
-                    return;
-                }
-                head.paramOids = msg.oids;
-                return;
-            case "RowDescription":
-                if (head.kind === "describeS") {
-                    driver.queue.shift();
-                    head.resolve({
-                        paramOids: head.paramOids ?? [],
-                        fields: msg.fields,
-                    });
-                    return;
-                }
-                if (head.kind === "describeP") {
-                    driver.queue.shift();
-                    head.resolve(msg.fields);
-                    return;
-                }
-                if (head.kind === "execute") {
-                    head.current = {
-                        command: "",
-                        rowCount: null,
-                        oid: null,
-                        fields: msg.fields,
-                        rows: [],
-                        notices: [],
-                    };
-                    head.fields = msg.fields;
-                    return;
-                }
-                this.protocolFail(new Error("Unexpected RowDescription at head op " + head.kind));
-                return;
-            case "NoData":
-                if (head.kind === "describeS") {
-                    driver.queue.shift();
-                    head.resolve({
-                        paramOids: head.paramOids ?? [],
-                        fields: [],
-                    });
-                    return;
-                }
-                if (head.kind === "describeP") {
-                    driver.queue.shift();
-                    head.resolve([]);
-                    return;
-                }
-                this.protocolFail(new Error("Unexpected NoData at head op " + head.kind));
-                return;
-            case "DataRow": {
-                if (head.kind !== "execute") {
-                    this.protocolFail(new Error("DataRow at head op " + head.kind));
-                    return;
-                }
-                const fields = head.fields ?? head.current?.fields ?? [];
-                if (!head.current) {
-                    head.current = {
-                        command: "",
-                        rowCount: null,
-                        oid: null,
-                        fields,
-                        rows: [],
-                        notices: [],
-                    };
-                }
-                head.current.rows.push(decodeDataRow(msg.values, fields));
-                return;
-            }
-            case "CommandComplete": {
-                if (head.kind !== "execute") {
-                    this.protocolFail(new Error("CommandComplete at head op " + head.kind));
-                    return;
-                }
-                const { command, rowCount, oid } = parseCommandTag(msg.tag);
-                const set = head.current ?? {
-                    command,
-                    rowCount,
-                    oid,
-                    fields: head.fields ?? [],
-                    rows: [],
-                    notices: [],
-                };
-                set.command = command;
-                set.rowCount = rowCount;
-                set.oid = oid;
-                set.notices = head.notices.splice(0);
-                driver.queue.shift();
-                head.resolve(set);
-                return;
-            }
-            case "EmptyQueryResponse": {
-                if (head.kind !== "execute") {
-                    this.protocolFail(new Error("EmptyQueryResponse at head op " + head.kind));
-                    return;
-                }
-                const set = {
-                    command: "",
-                    rowCount: null,
-                    oid: null,
-                    fields: [],
-                    rows: [],
-                    notices: head.notices.splice(0),
-                };
-                driver.queue.shift();
-                head.resolve(set);
-                return;
-            }
-            case "PortalSuspended": {
-                if (head.kind !== "execute") {
-                    this.protocolFail(new Error("PortalSuspended at head op " + head.kind));
-                    return;
-                }
-                const set = head.current ?? {
-                    command: "",
-                    rowCount: null,
-                    oid: null,
-                    fields: head.fields ?? [],
-                    rows: [],
-                    notices: head.notices.splice(0),
-                };
-                set.notices = head.notices.splice(0);
-                driver.queue.shift();
-                head.resolve(set);
-                return;
-            }
-            case "ReadyForQuery": {
-                this.txStatus = msg.status;
-                if (head.kind !== "sync") {
-                    this.protocolFail(new Error("ReadyForQuery but head op is " + head.kind));
-                    return;
-                }
-                driver.queue.shift();
-                const stickyErr = driver.error;
-                driver.error = null;
-                if (stickyErr) {
-                    head.reject(stickyErr);
-                }
-                else {
-                    head.resolve(undefined);
-                }
-                if (driver.queue.length === 0 && !this._extPipelineActive) {
-                    this.state = "idle";
-                    this.extDriver = null;
-                }
-                return;
-            }
-            default:
-                this.protocolFail(new Error(`Unexpected ${msg.type} in in-extended state`));
-                return;
-        }
-    }
-    protocolFail(err) {
-        this.socketError = err;
-        this.failPending(err);
-        try {
-            this.socket.destroy();
-        }
-        catch {
-            // ignore
-        }
-        this.state = "closed";
-    }
-    /**
-     * Abort the connection because the server replied with CopyInResponse /
-     * CopyOutResponse while a pipeline (`_extPipelineActive`) was active.
-     * Upstream libpq emits the exact diagnostic
-     * `"COPY in a pipeline is not supported, aborting connection"` and tears
-     * the socket down — we mirror that. Pending operations are rejected; the
-     * connection is left in `closed` so subsequent commands fail cleanly
-     * (matching the "aborting connection" promise).
-     */
-    abortForCopyInPipeline() {
-        const err = {
-            severity: "FATAL",
-            message: "COPY in a pipeline is not supported, aborting connection",
-        };
-        this.socketError = new Error(err.message);
-        this.failPending(err);
-        try {
-            this.socket.destroy();
-        }
-        catch {
-            // ignore
-        }
-        this.state = "closed";
-    }
-}
-// -------------------------------------------------------------------------
-// Public factory
-// -------------------------------------------------------------------------
-/**
- * Pluggable random source for `load_balance_hosts=random`. Public so tests
- * can inject a deterministic permutation; production code leaves it `null`
- * and falls back to `Math.random`. NOT part of the connection's external
- * contract — internal-only escape hatch.
- */
-PgConnection._loadBalanceRng = null;
-/**
- * Pluggable DNS resolver for the multi-IP host fan-out (libpq's
- * `getaddrinfo`-then-iterate behaviour, exercised by upstream's
- * `004_load_balance_dns.pl`). Tests inject a fake to drive a hostname
- * through a fixed IP set without touching the real resolver; production
- * code leaves it `null` and falls back to `dns.lookup(host, {all: true})`.
- * Returning an empty array signals "treat as unresolvable" and the
- * candidate is dropped from the iteration set (matching libpq's "no
- * results from getaddrinfo" path).
- */
-PgConnection._dnsLookupAll = null;
-// ---------------------------------------------------------------------------
-// Socket open helper. Supports TCP (default) and Unix-domain sockets when
-// `opts.host` starts with `/` — matching libpq's `pqUnixSocketPath()` which
-// reads the directory from PGHOST and builds `<dir>/.s.PGSQL.<port>` as the
-// actual filesystem socket path.
-// ---------------------------------------------------------------------------
-/**
- * `true` if the host value should be interpreted as a Unix-domain socket
- * directory. libpq's rule: any value starting with `/` is a path.
- */
-export function isUnixSocketHost(host) {
-    return host.startsWith("/");
-}
-/**
- * Build the actual filesystem path Postgres listens on under a socket
- * directory: `<dir>/.s.PGSQL.<port>`. Mirrors the libpq layout so any
- * server started with `unix_socket_directories=<dir>` is reachable.
- */
-export function unixSocketPath(dir, port) {
-    return `${dir}/.s.PGSQL.${String(port)}`;
-}
-/**
- * Expand the configured (host, port) list by resolving each hostname to
- * its full set of A/AAAA records. Mirrors libpq's `getaddrinfo`-then-
- * iterate-all behaviour exercised by upstream's
- * `src/interfaces/libpq/t/004_load_balance_dns.pl`. Without this step a
- * single hostname that resolves to N IPs would only ever produce one
- * candidate (Node's `net.connect({host})` picks one address from the
- * lookup result), so `load_balance_hosts=random` couldn't shuffle across
- * the DNS-returned set.
- *
- *   - Unix-domain socket paths (`/var/run/postgres`) are passed through
- *     unchanged — they don't participate in DNS at all.
- *   - IPv4/IPv6 literals are passed through unchanged — DNS resolution
- *     would just round-trip them.
- *   - Hostnames are resolved via `dns.lookup(host, {all: true})`. The
- *     test seam `PgConnection._dnsLookupAll` overrides the resolver so
- *     unit tests can drive a hostname through a fixed IP set without
- *     touching the real DNS.
- *   - A hostname that fails to resolve (or returns zero records) is
- *     dropped from the iteration set. The connect loop's `lastErr`
- *     surfaces the original error if every host fails.
- */
-async function expandHostsViaDns(seed) {
-    const out = [];
-    for (const c of seed) {
-        if (isUnixSocketHost(c.host) || net.isIP(c.host) !== 0) {
-            // Unix-domain socket paths and IP literals don't go through DNS.
-            // Leave `address` undefined so `openSocket` uses `host` directly.
-            out.push({ host: c.host, port: c.port });
-            continue;
-        }
-        let addrs;
-        try {
-            addrs = PgConnection._dnsLookupAll
-                ? await PgConnection._dnsLookupAll(c.host)
-                : await dns.lookup(c.host, { all: true, family: 0 });
-        }
-        catch {
-            // dns.lookup rejects with ENOTFOUND / EAI_AGAIN / EAI_NONAME on
-            // resolution failure. Skip this host; the outer connect loop will
-            // surface the failure via `lastErr` if every candidate is dropped.
-            continue;
-        }
-        for (const a of addrs) {
-            // Keep the ORIGINAL hostname on `host` so TLS SNI / verify-full
-            // and `conn.host` see the user-typed name. The IP goes on
-            // `address`, used only by `openSocket` for the actual TCP connect.
-            out.push({ host: c.host, address: a.address, port: c.port });
-        }
-    }
-    return out;
-}
-/**
- * Map a libpq protocol-version string (`TLSv1` / `TLSv1.1` / `TLSv1.2` /
- * `TLSv1.3`) to Node's `SecureVersion` literal. Returns `undefined` for
- * unset / empty input. Unknown values shouldn't reach here (the parsing
- * layer in `index.ts` validates them), but we return `undefined` rather than
- * casting so a stray value can't smuggle a bogus literal into Node's TLS
- * options.
- */
-function toSecureVersion(value) {
-    switch (value) {
-        case "TLSv1":
-        case "TLSv1.1":
-        case "TLSv1.2":
-        case "TLSv1.3":
-            return value;
-        default:
-            return undefined;
-    }
-}
-/**
- * Map libpq's `ssl_min_protocol_version` / `ssl_max_protocol_version` onto
- * Node's `tls.connect` `minVersion` / `maxVersion`. Unset values leave Node's
- * compiled-in defaults in place.
- */
-function applyTlsProtocolVersionRange(tlsOpts, opts) {
-    const min = toSecureVersion(opts.sslMinProtocolVersion);
-    if (min !== undefined)
-        tlsOpts.minVersion = min;
-    const max = toSecureVersion(opts.sslMaxProtocolVersion);
-    if (max !== undefined)
-        tlsOpts.maxVersion = max;
-}
-/**
- * libpq `sslsni`: the TLS SNI servername to send, or `undefined` to suppress
- * the SNI extension entirely. `sslsni=0` (`opts.sslsni === false`) suppresses
- * it; unset / `sslsni=1` sends `opts.host` (libpq's default). Returned value
- * is spread into the `tls.connect` options as `servername`.
- *
- * Exported for unit tests.
- */
-export function tlsServername(opts) {
-    return opts.sslsni === false ? undefined : opts.host;
-}
-/**
- * Translate libpq's `keepalives` / `keepalives_idle` into the arguments for
- * Node's `socket.setKeepAlive(enable, initialDelay)`:
- *   - `enable`: `false` only when `keepalives === false` (libpq `keepalives=0`);
- *     unset / `true` keeps keepalives on (libpq default).
- *   - `initialDelayMs`: `keepalives_idle` seconds → milliseconds, or
- *     `undefined` to leave the OS default.
- *
- * libpq's `keepalives_interval` and `keepalives_count` have NO Node net API
- * equivalent (`setKeepAlive` exposes only enable + initial delay), so they are
- * intentionally not represented here.
- *
- * Exported for unit tests.
- */
-export function keepAliveArgs(opts) {
-    return {
-        enable: opts.keepalives !== false,
-        initialDelayMs: opts.keepalivesIdle !== undefined
-            ? opts.keepalivesIdle * 1000
-            : undefined,
-    };
-}
-/**
- * Derive the symmetric key length (in bits) from a negotiated TLS cipher
- * name, for the PG18 `\conninfo` "SSL Key Bits" row. Node's TLS API doesn't
- * expose the key length directly, so we parse it out of the cipher name the
- * way upstream's `SSL_CIPHER_get_bits` effectively reports it:
- *
- *   - `AES_256` / `CHACHA20` → 256
- *   - `AES_128`              → 128
- *   - otherwise, the first run of digits in the standard name (`…128…` etc.)
- *   - `null` when no length can be determined.
- *
- * Both the OpenSSL standard name (`TLS_AES_256_GCM_SHA384`,
- * `ECDHE-RSA-AES128-GCM-SHA256`) and Node's IANA-style name are handled by
- * uppercasing and matching the keyword forms first. Exported for unit tests.
- */
-export function sslKeyBitsFromCipher(name) {
-    const upper = name.toUpperCase();
-    if (upper.includes("CHACHA20"))
-        return 256;
-    if (upper.includes("AES_256") || upper.includes("AES256"))
-        return 256;
-    if (upper.includes("AES_128") || upper.includes("AES128"))
-        return 128;
-    if (upper.includes("AES_192") || upper.includes("AES192"))
-        return 192;
-    const digits = /(\d{2,4})/.exec(upper);
-    if (digits) {
-        const n = parseInt(digits[1], 10);
-        if (Number.isFinite(n) && n > 0)
-            return n;
-    }
-    return null;
-}
-function openSocket(opts, 
-/**
- * Pre-resolved IP. When set, used for `net.connect({host})` instead
- * of `opts.host` — lets DNS fan-out direct the TCP connect to a
- * specific A record while keeping the user-typed hostname elsewhere
- * (TLS SNI / `conn.host`). Ignored for Unix-domain socket paths,
- * which take their address from `opts.host` directly.
- */
-addressOverride) {
-    return new Promise((resolve, reject) => {
-        const isUnix = isUnixSocketHost(opts.host);
-        const socket = isUnix
-            ? net.connect({ path: unixSocketPath(opts.host, opts.port) })
-            : net.connect({
-                host: addressOverride ?? opts.host,
-                port: opts.port,
-            });
-        // libpq TCP keepalives (no-op for Unix-domain sockets, matching libpq,
-        // which only applies SO_KEEPALIVE on TCP).
-        if (!isUnix) {
-            const { enable, initialDelayMs } = keepAliveArgs(opts);
-            if (initialDelayMs !== undefined) {
-                socket.setKeepAlive(enable, initialDelayMs);
-            }
-            else {
-                socket.setKeepAlive(enable);
-            }
-        }
-        const timeout = opts.connectTimeoutMs;
-        let timer = null;
-        if (timeout !== undefined && timeout > 0) {
-            timer = setTimeout(() => {
-                socket.destroy(new Error(`Connect timed out after ${String(timeout)} ms`));
-            }, timeout);
-        }
-        const cleanup = () => {
-            if (timer)
-                clearTimeout(timer);
-            socket.removeListener("error", onError);
-            socket.removeListener("connect", onConnect);
-        };
-        const onError = (err) => {
-            cleanup();
-            reject(err);
-        };
-        const onConnect = () => {
-            cleanup();
-            resolve(socket);
-        };
-        socket.once("error", onError);
-        socket.once("connect", onConnect);
-    });
-}
-// ---------------------------------------------------------------------------
-// Result decoding helpers
-// ---------------------------------------------------------------------------
-/**
- * Decode a wire-protocol DataRow into JS values. We follow the simple psql
- * policy: text format → utf-8 string, binary format → Buffer. Type-aware
- * decoding (timestamps, arrays, etc.) is the caller's responsibility — that
- * matches `psql` which prints raw server text.
- */
-function decodeDataRow(values, fields) {
-    const out = new Array(values.length);
-    for (let i = 0; i < values.length; i++) {
-        const v = values[i];
-        if (v === null) {
-            out[i] = null;
-            continue;
-        }
-        const fmt = fields[i]?.format ?? 0;
-        out[i] = fmt === 1 ? v : v.toString("utf8");
-    }
-    return out;
-}
-/**
- * Parse the CommandComplete tag — examples:
- *   "SELECT 17"
- *   "INSERT 0 1"       (oid is 0 in modern PG; second number is rowCount)
- *   "UPDATE 3"
- *   "CREATE TABLE"     (no rowCount)
- *
- * Anything that doesn't match → command = the whole tag, rowCount = null.
- */
-function parseCommandTag(tag) {
-    const trimmed = tag.trim();
-    // INSERT is the only tag with the legacy oid + rowCount layout.
-    const insertMatch = /^INSERT (\d+) (\d+)$/.exec(trimmed);
-    if (insertMatch) {
-        return {
-            command: "INSERT",
-            oid: parseInt(insertMatch[1], 10),
-            rowCount: parseInt(insertMatch[2], 10),
-        };
-    }
-    const m = /^([A-Z][A-Z ]*?)(?: (\d+))?$/.exec(trimmed);
-    if (!m)
-        return { command: trimmed, rowCount: null, oid: null };
-    return {
-        command: m[1],
-        rowCount: m[2] !== undefined ? parseInt(m[2], 10) : null,
-        oid: null,
-    };
-}
-/**
- * Encode JS values into the (Buffer | string | null)[] format that
- * {@link Bind} accepts. Text-format only — server coerces. Matches psql's
- * default `\bind` behaviour.
- */
-export function encodeParams(values) {
-    return values.map((v) => {
-        if (v === null || v === undefined)
-            return null;
-        if (Buffer.isBuffer(v))
-            return v;
-        if (typeof v === "string")
-            return v;
-        if (typeof v === "boolean")
-            return v ? "t" : "f";
-        if (typeof v === "number" || typeof v === "bigint")
-            return v.toString();
-        try {
-            return JSON.stringify(v);
-        }
-        catch {
-            return "";
-        }
-    });
-}
-/**
- * Coerce arbitrary rejection values to a thrown `Error`.
- *
- * For our `ConnectError` shape (`{ severity, code, message, … }`), the
- * resulting Error preserves every enumerable field of the source object as
- * own properties — so callers can still read `.code`, `.severity`, `.hint`,
- * `.position`, etc. directly off the thrown value while also getting a proper
- * `Error` instance (so `instanceof Error` works and `.message` / `.stack` are
- * populated for generic loggers).
- */
-function asThrowable(v) {
-    if (v instanceof Error)
-        return v;
-    if (typeof v === "object" &&
-        v !== null &&
-        "message" in v &&
-        typeof v.message === "string") {
-        const source = v;
-        const err = new Error(source.message);
-        // Copy every own enumerable field (severity, code, detail, hint, …) onto
-        // the Error so structural consumers keep working.
-        for (const key of Object.keys(source)) {
-            if (key === "message")
-                continue;
-            err[key] = source[key];
-        }
-        err.cause = v;
-        return err;
-    }
-    return new Error(String(v));
-}