postgrejs 3.13.0 → 3.14.1

package/README.md

@@ -98,6 +98,32 @@ Each adapter hands the compiled SQL straight to this client, with no `pg` left a
 compared query by query against the driver it replaces - and, where the project ships a suite of its own, run
 against that too. So adopting one is a change to how the connection is created and nothing else.
 
+### 🌍 Runs Where You Run
+
+<!-- Same card shape as the adapters above, for the same reason: GitHub strips CSS, and a table
+     is the one layout that survives everywhere the README is read. -->
+<table>
+  <tr>
+    <td align="center" width="230" valign="top">
+      <a href="https://www.postgrejs.com/docs/getting-started/benchmarks"><img src="https://www.postgrejs.com/img/nodejs-logo.svg" alt="Node.js" height="46"></a><br><br>
+      <b><a href="https://www.postgrejs.com/docs/getting-started/benchmarks">Node.js</a></b><br>
+    </td>
+    <td align="center" width="230" valign="top">
+      <a href="https://www.postgrejs.com/docs/getting-started/benchmarks-bun"><img src="https://www.postgrejs.com/img/bun-logo.svg" alt="Bun" height="46"></a><br><br>
+      <b><a href="https://www.postgrejs.com/docs/getting-started/benchmarks-bun">Bun</a></b><br>
+    </td>
+    <td align="center" width="230" valign="top">
+      <a href="https://www.postgrejs.com/docs/guides/cloudflare-workers"><img src="https://www.postgrejs.com/img/cloudflare-logo.svg" alt="Cloudflare Workers" height="46"></a><br><br>
+      <b><a href="https://www.postgrejs.com/docs/guides/cloudflare-workers">Cloudflare Workers</a></b><br>
+    </td>
+  </tr>
+</table>
+
+Node and Bun run **the same test suite** in CI on every push - Node across 20, 22, 24 and 26 against PostgreSQL 12,
+16 and 18, Bun against 18 - so neither is a target that merely ought to work. Workers is not in that matrix yet: it
+was measured by hand against PostgreSQL 18, a plain connection and a TLS one, and what the runtime does and does not
+allow is written down in [doc/CLOUDFLARE-WORKERS.md](doc/CLOUDFLARE-WORKERS.md).
+
 ## Installation
 
 ```bash
@@ -133,6 +159,7 @@ in · 🟡 partial or needs a separate package · ❌ not supported.
 | Packages to install               |           1            |    4 <sup>1</sup>     |        1         |
 | Module system                     |          ESM           |        ESM/CJS        |     ESM/CJS      |
 | Language                          |           TS           |    JS <sup>2</sup>    | JS <sup>3</sup>  |
+| Cloudflare Workers                |    ✅ <sup>28</sup>    |   🟡 <sup>29</sup>    | ✅ <sup>30</sup> |
 | ***Wire protocol***               |                        |                       |                  |
 | Protocol version                  |          3.2           |          3.0          |       3.0        |
 | Simple Query protocol             |           ✅           |          ✅           |        ✅        |
@@ -271,6 +298,25 @@ in · 🟡 partial or needs a separate package · ❌ not supported.
   input parser is what sorts and deduplicates a vector and what defines a query's grammar, so encoding either here
   would make the same text mean one thing written as a literal and another bound as a parameter. They are sent as
   text instead, which is exact.
+- <sup>28</sup> PostgreJS runs on workerd under `nodejs_compat` with nothing installed and no build of its own.
+  Measured end to end: a plain connection against PostgreSQL 18, and a TLS one against a managed PostgreSQL 18 whose
+  certificate comes from Let's Encrypt - the same server refusing the connection outright (`28000 connection is
+  insecure`) when `sslmode` is dropped, which is what makes the encrypted one mean something. TLS opens a socket of
+  the runtime's own and upgrades it with `startTls()`, since `tls.connect({ socket })` is not something workerd can
+  carry out. Three limits are the runtime's, and all three libraries have them: `ca`, `cert` and `rejectUnauthorized`
+  have nowhere to go (workerd's TLS options are `{ expectedServerHostname?: string }`, so a self-signed certificate
+  cannot be trusted and a local server cannot be reached over TLS at all); `sslnegotiation=direct` cannot announce the
+  `postgresql` ALPN protocol, and is refused by name here; and SCRAM channel binding has no server certificate to bind
+  to, so `channelBinding: 'require'` is refused and the default `prefer` authenticates without it. Hyperdrive is the
+  other way in, terminating TLS in Cloudflare's own network - checked here against its binding. See
+  [doc/CLOUDFLARE-WORKERS.md](doc/CLOUDFLARE-WORKERS.md).
+- <sup>29</sup> pg reaches workerd through `pg-cloudflare`, a separate package it carries as an optional dependency
+  and selects at runtime (`lib/stream.js`, on `navigator.userAgent`). That package wraps `cloudflare:sockets` and
+  upgrades with its own `startTls()`, so TLS is available where PostgreJS's is not - at the cost of a second package
+  and of nothing happening at all if it was not installed.
+- <sup>30</sup> postgres.js ships a build for the runtime: a `workerd` condition in `exports` pointing at `cf/`, whose
+  polyfills shim `net`/`tls` onto `cloudflare:sockets` including `startTls({ servername })`. One package, the right
+  code chosen by the resolver, TLS included.
 
 ## Benchmarks
 
@@ -278,10 +324,10 @@ PostgreJS implements the full PostgreSQL wire protocol from scratch, with no dep
 [`doc/BENCHMARKS.md`](doc/BENCHMARKS.md) compares it against `pg` (node-postgres) and `postgres` (postgres.js)
 across connection setup, simple/prepared queries, mixed-type decoding, bulk fetches, cursor streaming and pool
 concurrency, each library run through its own idiomatic fast path. The numbers there are reproducible on your own
-machine via `npm run bench` against the repo's own
+machine via `pnpm run bench` against the repo's own
 `docker/docker-compose.yml` Postgres instance; see [`benchmark/README.md`](./benchmark/README.md) for details.
 
-The same suite runs under Bun via `npm run bench:bun`, where it also measures Bun's own built-in `Bun.sql` client as
+The same suite runs under Bun via `pnpm run bench:bun`, where it also measures Bun's own built-in `Bun.sql` client as
 a fourth library. Those results live in [`doc/BENCHMARKS-bun.md`](doc/BENCHMARKS-bun.md) and are deliberately kept
 in a separate report rather than merged into the Node one: GC instrumentation, cursor streaming and binary-format
 control all differ enough between the two runtimes that a single table would conflate a library difference with a
@@ -302,6 +348,9 @@ you open an issue please provide version of NodeJS and PostgreSQL server.
 - Bun - the same test suite runs under Bun in CI against PostgreSQL 18 on every push, so Bun is a supported target
   rather than an untested coincidence. (Coverage is collected on the Node matrix only: `c8` instruments V8's
   coverage APIs, which JavaScriptCore doesn't have.)
+- Cloudflare Workers - with `nodejs_compat`, and without TLS: the runtime has no way to trust a server
+  certificate, so a database behind TLS is reached through Hyperdrive instead. See
+  [doc/CLOUDFLARE-WORKERS.md](doc/CLOUDFLARE-WORKERS.md).
 
 ## License
 

package/connection/intl-connection.d.ts

@@ -64,6 +64,12 @@ export declare class IntlConnection extends SafeEventEmitter {
      * never close again.
      */
     private _preparing;
+    /**
+     * Resolves when the statement submitted before this one has written its
+     * own bytes - see _holdWireOrder(). Undefined whenever nothing is on its
+     * way to the wire, which is every statement that writes without waiting.
+     */
+    private _wireOrder?;
     /** SQL seen once but not yet prepared - see PREPARE_AFTER_USES. */
     private _preparedCandidates;
     private _preparedCounter;
@@ -313,6 +319,18 @@ export declare class IntlConnection extends SafeEventEmitter {
     protected _queryCached(sql: string, paramTypes: Maybe<Maybe<OID>[]>, params: Maybe<Maybe<any>[]>, options: QueryOptions, savepoint: Maybe<string>, 
     /** Whether the CALL asked for text columns, not the connection. */
     callWantsFields: boolean): Promise<QueryResult>;
+    /**
+     * Keeps this statement's place in the wire order while it waits for
+     * something - today, the Parse round trip that names it.
+     *
+     * @returns `after`, the place held by the statement submitted before this
+     * one, to wait on before writing; and `wrote`, to call the moment this
+     * statement's own bytes are on the wire.
+     */
+    protected _holdWireOrder(): {
+        after?: Promise<void>;
+        wrote: () => void;
+    };
     /**
      * Gives this SQL a name and caches it, once, however many callers are
      * waiting. A Parse that fails caches nothing and reports itself; the

package/connection/intl-connection.js

@@ -195,6 +195,12 @@ export class IntlConnection extends SafeEventEmitter {
      * never close again.
      */
     _preparing = new Map();
+    /**
+     * Resolves when the statement submitted before this one has written its
+     * own bytes - see _holdWireOrder(). Undefined whenever nothing is on its
+     * way to the wire, which is every statement that writes without waiting.
+     */
+    _wireOrder;
     /** SQL seen once but not yet prepared - see PREPARE_AFTER_USES. */
     _preparedCandidates = new Map();
     _preparedCounter = 0;
@@ -975,8 +981,11 @@ export class IntlConnection extends SafeEventEmitter {
     /** Whether the CALL asked for text columns, not the connection. */
     callWantsFields) {
         const enabled = options.prepare ?? this.config.prepare ?? true;
-        if (!enabled)
+        if (!enabled) {
+            if (this._wireOrder)
+                await this._wireOrder;
             return this.queryOnce(sql, paramTypes, params, options, savepoint);
+        }
         const key = preparedCacheKey(sql, paramTypes);
         const cached = this._preparedCache.get(key);
         if (cached) {
@@ -984,6 +993,8 @@ export class IntlConnection extends SafeEventEmitter {
             this._preparedCache.delete(key);
             this._preparedCache.set(key, cached);
             try {
+                if (this._wireOrder)
+                    await this._wireOrder;
                 return await this.executeReused(cached.name, cached.fields, resolvedBindTypes(paramTypes, params, cached.resolvedParamTypes), params, options, savepoint);
             }
             catch (e) {
@@ -1024,8 +1035,11 @@ export class IntlConnection extends SafeEventEmitter {
         // on a statement's first run instead, and per-column codes from its
         // second, which is where the name arrives anyway.
         const needsFields = callWantsFields && options.columnFormat !== DataFormat.text;
-        if (!needsFields && !this._earnsAName(key))
+        if (!needsFields && !this._earnsAName(key)) {
+            if (this._wireOrder)
+                await this._wireOrder;
             return this.queryOnce(sql, paramTypes, params, options, savepoint);
+        }
         let preparing = this._preparing.get(key);
         if (!preparing) {
             // Registered before the first await inside, so everything that
@@ -1038,10 +1052,71 @@ export class IntlConnection extends SafeEventEmitter {
             // Someone else is already naming it. Waiting would cost a round
             // trip the one-shot path does not - the name is for the calls
             // after this burst, not for this one.
+            if (this._wireOrder)
+                await this._wireOrder;
             return this.queryOnce(sql, paramTypes, params, options, savepoint);
         }
-        const entry = await preparing;
-        return this.executeReused(entry.name, entry.fields, paramTypes, params, options, savepoint);
+        const place = this._holdWireOrder();
+        let running;
+        try {
+            const entry = await preparing;
+            if (place.after)
+                await place.after;
+            /* Called, not awaited: executeReused() runs as far as the socket
+               write before its first await, so by the time it hands back a
+               promise the bytes are away and the next statement may follow
+               them. Awaiting it here instead would hold the line until this
+               statement had its answer, which is pipelining switched off. */
+            running = this.executeReused(entry.name, entry.fields, paramTypes, params, options, savepoint);
+        }
+        finally {
+            // Also on the way out of a Parse that failed: this statement will
+            // never write, and whatever queued behind it must not wait forever.
+            place.wrote();
+        }
+        return running;
+    }
+    /**
+     * Keeps this statement's place in the wire order while it waits for
+     * something - today, the Parse round trip that names it.
+     *
+     * @returns `after`, the place held by the statement submitted before this
+     * one, to wait on before writing; and `wrote`, to call the moment this
+     * statement's own bytes are on the wire.
+     */
+    /* PostgreSQL executes what reaches it in the order it reaches it, and
+       cannot know what order the query() calls were made in. A statement
+       that has to await a Parse before it can Bind therefore lets every
+       later statement overtake it - invisibly, because the overtaking only
+       happens when one statement is cached and the other is not, which is a
+       property of the connection's history rather than of the code. Two
+       updates to one row then land in the opposite order on a connection
+       that had been running them correctly all along.
+    
+       Holding a place rather than the wire: the Parse still overlaps with
+       everything else, which is the point of pipelining. Only the Bind is
+       made to queue, and only behind calls that really were submitted
+       first.
+    
+       Nothing pending leaves `_wireOrder` undefined, so a statement that
+       writes without waiting - a cache hit, the common case - reads one
+       field and writes, paying no promise and no microtask for the
+       ordering. */
+    _holdWireOrder() {
+        const after = this._wireOrder;
+        let resolve;
+        const mine = new Promise(r => (resolve = r));
+        this._wireOrder = mine;
+        return {
+            after,
+            wrote: () => {
+                // Only if nobody queued behind this one in the meantime - their
+                // place is the one that must be waited on now.
+                if (this._wireOrder === mine)
+                    this._wireOrder = undefined;
+                resolve();
+            },
+        };
     }
     /**
      * Gives this SQL a name and caches it, once, however many callers are

package/constants.d.ts

@@ -1,6 +1,6 @@
 import { Protocol } from './protocol/protocol.js';
 import DataFormat = Protocol.DataFormat;
-export declare const version = "3.13.0";
+export declare const version = "3.14.1";
 export { DataFormat };
 /**
  * What columns come back in unless something asks otherwise.

package/constants.js

@@ -2,7 +2,7 @@ import { Protocol } from './protocol/protocol.js';
 var DataFormat = Protocol.DataFormat;
 // @ts-ignore
 Symbol.asyncDispose ??= Symbol('Symbol.asyncDispose');
-export const version = '3.13.0';
+export const version = '3.14.1';
 export { DataFormat };
 /**
  * What columns come back in unless something asks otherwise.

package/data-types/bytea-type.d.ts

@@ -1,5 +1,12 @@
 import type { DataType } from '../interfaces/data-type.js';
-/** `bytea`, as a `Buffer`. The binary format is the bytes themselves; the text one is `\\x`-prefixed hex, at two characters a byte. */
+/**
+ * `bytea`. A value read back is a `Buffer`; a value sent may be any
+ * ArrayBuffer view - a `Buffer`, a `Uint8Array` off `fetch` or `subarray`,
+ * a `DataView` - and only the bytes that view covers are sent.
+ *
+ * The binary format is the bytes themselves; the text one is `\\x`-prefixed
+ * hex, at two characters a byte.
+ */
 export declare const ByteaType: DataType;
 /** The `_bytea` array of {@link ByteaType}. */
 export declare const ArrayByteaType: DataType;

package/data-types/bytea-type.js

@@ -1,16 +1,42 @@
 import { DataTypeOIDs } from '../constants.js';
 import { parseBytea, parseByteaBuffer } from '../util/parse-bytea.js';
-/** `bytea`, as a `Buffer`. The binary format is the bytes themselves; the text one is `\\x`-prefixed hex, at two characters a byte. */
+/**
+ * Reads any ArrayBuffer view as a `Buffer` over exactly the bytes it covers.
+ *
+ * @param v The view to read.
+ * @returns It unchanged when it is already a `Buffer`, or a window onto the
+ * same memory - never a copy.
+ */
+/* `byteOffset`/`byteLength` are the whole point: a `subarray()` of a larger
+   buffer describes a window, and `Buffer.from(view.buffer)` would send
+   everything on both sides of it. */
+function asBuffer(v) {
+    return Buffer.isBuffer(v)
+        ? v
+        : Buffer.from(v.buffer, v.byteOffset, v.byteLength);
+}
+/**
+ * `bytea`. A value read back is a `Buffer`; a value sent may be any
+ * ArrayBuffer view - a `Buffer`, a `Uint8Array` off `fetch` or `subarray`,
+ * a `DataView` - and only the bytes that view covers are sent.
+ *
+ * The binary format is the bytes themselves; the text one is `\\x`-prefixed
+ * hex, at two characters a byte.
+ */
 export const ByteaType = {
     name: 'bytea',
     oid: DataTypeOIDs.bytea,
     jsType: 'Buffer',
     // The hex form PostgreSQL has emitted by default since 9.0.
     encodeText(v) {
-        return '\\x' + v.toString('hex');
+        return '\\x' + asBuffer(v).toString('hex');
     },
+    /* Through `asBuffer` rather than straight to `writeBytes`, which reaches
+       for `.copy()` - a `Buffer` method that a plain `Uint8Array` does not
+       have, and the `buffer.copy is not a function` an explicit
+       `BindParam(17, bytes)` used to fail with. */
     encodeBinary(buf, v) {
-        buf.writeBytes(v);
+        buf.writeBytes(asBuffer(v));
     },
     decodeBinary(v, offset = 0, len) {
         // A view, not a copy - the value handed back is the caller's own
@@ -20,7 +46,7 @@ export const ByteaType = {
     decodeText: parseBytea,
     decodeTextBuffer: parseByteaBuffer,
     isType(v) {
-        return v instanceof Buffer;
+        return ArrayBuffer.isView(v);
     },
 };
 /** The `_bytea` array of {@link ByteaType}. */

package/interfaces/query-options.d.ts

@@ -37,9 +37,14 @@ export interface QueryOptions extends DataMappingOptions {
      *
      * `false` asks for the wire to itself: the statement waits until
      * nothing else is running on the connection, and nothing else starts
-     * until it finishes, whichever mode those asked for. Nothing orders
-     * two pipelined statements against each other, so this is how a
-     * statement that depends on what another one left behind says so.
+     * until it finishes, whichever mode those asked for. It is not how a
+     * statement says it depends on an earlier one: pipelined statements on
+     * one connection execute in the order they were submitted. What this
+     * is for is a statement that needs the connection to itself for longer
+     * than the wire - session state another caller would see, or a result
+     * the caller has to read before it can decide what to send next.
+     * Statements on different pooled connections have no order between
+     * them at all.
      *
      * Some statements never share a *pooled* connection however this is
      * set, because they need one to themselves for longer than the call:

package/interfaces/script-execute-options.d.ts

@@ -32,9 +32,14 @@ export interface ScriptExecuteOptions extends DataMappingOptions {
      *
      * `false` asks for the wire to itself: the statement waits until
      * nothing else is running on the connection, and nothing else starts
-     * until it finishes, whichever mode those asked for. Nothing orders
-     * two pipelined statements against each other, so this is how a
-     * statement that depends on what another one left behind says so.
+     * until it finishes, whichever mode those asked for. It is not how a
+     * statement says it depends on an earlier one: pipelined statements on
+     * one connection execute in the order they were submitted. What this
+     * is for is a statement that needs the connection to itself for longer
+     * than the wire - session state another caller would see, or a result
+     * the caller has to read before it can decide what to send next.
+     * Statements on different pooled connections have no order between
+     * them at all.
      *
      * Some statements never share a *pooled* connection however this is
      * set, because they need one to themselves for longer than the call:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "postgrejs",
   "description": "Professional PostgreSQL client NodeJS",
-  "version": "3.13.0",
+  "version": "3.14.1",
   "author": "Panates",
   "license": "BSD-3-Clause",
   "dependencies": {
@@ -36,7 +36,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/panates/postgrejs.git"
+    "url": "git+https://github.com/panates/postgrejs.git"
   },
   "keywords": [
     "postgresql",
@@ -65,4 +65,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/protocol/pg-socket.d.ts

@@ -1,4 +1,3 @@
-import net from 'node:net';
 import tls from 'node:tls';
 import { ConnectionState } from '../constants.js';
 import type { ConnectionConfiguration } from '../interfaces/database-connection-params.js';
@@ -20,6 +19,29 @@ export interface SocketError extends Error {
  * is asked for, and a queue that pairs each response with whoever sent
  * the statement that caused it.
  */
+/**
+ * What this client needs a socket to be, whoever provides one.
+ *
+ * `net.Socket`, its TLS upgrade, and `WorkerdSocket` all satisfy it.
+ */
+interface ClientSocket {
+    readonly destroyed: boolean;
+    readonly writable: boolean;
+    write(data: any, cb?: (err?: Error | null) => void): boolean;
+    destroy(err?: Error): any;
+    end(...args: any[]): any;
+    pause(): any;
+    resume(): any;
+    cork(): void;
+    uncork(): void;
+    setNoDelay(enable?: boolean): any;
+    setKeepAlive(enable?: boolean): any;
+    setTimeout(ms: number, cb?: () => void): any;
+    connect(...args: any[]): any;
+    on(event: string, listener: (...args: any[]) => void): any;
+    once(event: string, listener: (...args: any[]) => void): any;
+    removeAllListeners(event?: string): any;
+}
 export declare class PgSocket extends SafeEventEmitter {
     options: ConnectionConfiguration;
     private _state;
@@ -29,6 +51,7 @@ export declare class PgSocket extends SafeEventEmitter {
      * bare. Cleared by _reset().
      */
     private _closeReason?;
+    /** Whichever kind of socket this runtime connects with. */
     private _socket?;
     private _backend;
     private _frontend;
@@ -65,10 +88,10 @@ export declare class PgSocket extends SafeEventEmitter {
      * afterwards. Resolves `onReady` with whichever socket ends up ready to
      * speak the PostgreSQL protocol: the plain one, or its TLS upgrade.
      */
-    protected _negotiateTls(socket: net.Socket, target: {
+    protected _negotiateTls(socket: ClientSocket, target: {
         host: string;
         port?: number;
-    }, onReady: (socket: net.Socket | tls.TLSSocket) => void, onError: (err: Error) => void): void;
+    }, onReady: (socket: ClientSocket) => void, onError: (err: Error) => void): void;
     /**
      * Asks the server to cancel whatever this session is currently running.
      *
@@ -337,3 +360,4 @@ export declare class PgSocket extends SafeEventEmitter {
      */
     protected _sendCopy(data: Buffer | Buffer[], cb?: Callback): boolean;
 }
+export {};

package/protocol/pg-socket.js

@@ -6,6 +6,7 @@ import DoublyLinked from 'doublylinked';
 import promisify from 'putil-promisify';
 import { ConnectionState } from '../constants.js';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
+import { isWorkerd } from '../util/runtime.js';
 import { Backend } from './backend.js';
 import { signatureHashOfCertificate } from './cert-signature.js';
 import { ConnectionLostError } from './connection-lost-error.js';
@@ -13,13 +14,20 @@ import { DatabaseError } from './database-error.js';
 import { Frontend } from './frontend.js';
 import { Protocol } from './protocol.js';
 import { SASL } from './sasl.js';
+import { WorkerdSocket } from './workerd-socket.js';
 const DEFAULT_PORT_NUMBER = 5432;
 const COMMAND_RESULT_PATTERN = /^([^\d]+)(?: (\d+)(?: (\d+))?)?$/;
 /**
- * The connected socket: the handshake, the authentication, TLS where it
- * is asked for, and a queue that pairs each response with whoever sent
- * the statement that caused it.
+ * Whether a connection is going to ask for TLS at all.
+ *
+ * @param options The connection's own options.
+ * @returns True when any of the three ways of asking is set.
  */
+/* Read in two places that have to agree: which socket to open, and
+   whether to negotiate once it is open. */
+function wantsTls(options) {
+    return (!!options.ssl || !!options.requireSSL || options.sslNegotiation === 'direct');
+}
 export class PgSocket extends SafeEventEmitter {
     options;
     _state = ConnectionState.CLOSED;
@@ -29,6 +37,7 @@ export class PgSocket extends SafeEventEmitter {
      * bare. Cleared by _reset().
      */
     _closeReason;
+    /** Whichever kind of socket this runtime connects with. */
     _socket;
     _backend = new Backend();
     _frontend;
@@ -86,7 +95,17 @@ export class PgSocket extends SafeEventEmitter {
         this._sessionAttrsChecked = false;
         this._state = ConnectionState.CONNECTING;
         const target = this._hosts[this._hostIndex];
-        const socket = (this._socket = new net.Socket());
+        /* Workerd cannot upgrade a `net.Socket`, and the socket that can be
+           upgraded has to be opened as one from the start - `secureTransport:
+           'starttls'` is a connect-time choice, not a later one. So the kind
+           of socket is decided here, by whether TLS is going to be asked for
+           at all. The plain path stays on `node:net`, which works there. */
+        const socket = (this._socket =
+            isWorkerd() &&
+                wantsTls(this.options) &&
+                this.options.sslNegotiation !== 'direct'
+                ? new WorkerdSocket(true)
+                : new net.Socket());
         const errorHandler = (err) => {
             this._state = ConnectionState.CLOSED;
             this._removeListeners();
@@ -133,7 +152,14 @@ export class PgSocket extends SafeEventEmitter {
     _negotiateTls(socket, target, onReady, onError) {
         const options = this.options;
         const startTls = () => {
-            const tlsOptions = { ...options.ssl, socket };
+            /* Only ever reached off workerd - the branch below hands that
+               runtime to its own upgrade - so the socket here is the
+               `net.Socket` `tls.connect()` wants, which the structural type
+               cannot say on its own. */
+            const tlsOptions = {
+                ...options.ssl,
+                socket: socket,
+            };
             if (target.host && net.isIP(target.host) === 0)
                 tlsOptions.servername = target.host;
             if (options.sslNegotiation === 'direct')
@@ -142,11 +168,51 @@ export class PgSocket extends SafeEventEmitter {
             tlsSocket.once('error', onError);
             tlsSocket.once('secureConnect', () => onReady(tlsSocket));
         };
-        const wantsSSL = !!options.ssl ||
-            !!options.requireSSL ||
-            options.sslNegotiation === 'direct';
-        if (!wantsSSL)
+        if (!wantsTls(options))
             return onReady(socket);
+        /* Workerd upgrades through the socket it already has rather than by
+           wrapping it: `tls.connect({ socket })` does nothing it can carry
+           out, and measured, attempting it answers "Network connection
+           lost." after the server has already agreed to TLS. The exchange
+           either side of the upgrade is the same one as below - this branch
+           exists because the call in the middle is a different call.
+    
+           One limit is the runtime's and no client escapes it: workerd's TLS
+           options are `{ expectedServerHostname?: string }` and nothing
+           else, so nothing here can say which certificate to trust, and a
+           server whose certificate does not chain to a public CA cannot be
+           reached over TLS at all - which is every local PostgreSQL with a
+           self-signed certificate. */
+        /* Direct negotiation is TLS from the first byte, and PostgreSQL 17
+           only accepts it when the client announces the `postgresql`
+           protocol over ALPN. Workerd's socket options are
+           `{ secureTransport, allowHalfOpen }` - there is nowhere to say it,
+           and the server answers by closing, which surfaces as an internal
+           error with a reference number. Refused by name instead. */
+        if (isWorkerd() && options.sslNegotiation === 'direct')
+            return onError(new Error('sslNegotiation "direct" is not available on Cloudflare Workers: it needs the ' +
+                '"postgresql" ALPN protocol, which the runtime offers no way to announce. ' +
+                'Leave sslNegotiation unset to negotiate with SSLRequest instead.'));
+        if (socket instanceof WorkerdSocket) {
+            const upgrade = () => {
+                socket.once('error', onError);
+                socket.once('secureConnect', () => onReady(socket));
+                socket.startTls(target.host && net.isIP(target.host) === 0 ? target.host : undefined);
+            };
+            socket.write(this._frontend.getSSLRequestMessage());
+            socket.readOnce((x) => {
+                const command = x?.toString();
+                if (command === 'S')
+                    return upgrade();
+                if (command === 'N') {
+                    if (options.requireSSL)
+                        return onError(new Error('Server does not support SSL connections'));
+                    return onReady(socket);
+                }
+                onError(new Error('Unexpected response from server: ' + command));
+            });
+            return;
+        }
         if (options.sslNegotiation === 'direct') {
             // Straight into the handshake: no SSLRequest, nothing in the clear.
             return startTls();
@@ -825,15 +891,28 @@ export class PgSocket extends SafeEventEmitter {
                 break;
             case Protocol.AuthenticationMessageKind.SASL: {
                 const mode = this.options.channelBinding || 'prefer';
+                /* Encrypted and "can be bound to" are two questions on workerd,
+                   where they are one on Node. Binding mixes a hash of the
+                   server's certificate into the SCRAM proof, and that runtime
+                   hands out no certificate - so a connection can be perfectly
+                   secure there and still have nothing to bind to. Saying "not
+                   using TLS" for it, which is what the one test used to answer,
+                   sends the reader looking in the wrong place. */
+                const secure = this._socket instanceof tls.TLSSocket ||
+                    (this._socket instanceof WorkerdSocket && this._socket.secure);
                 const tlsSocket = mode !== 'disable' && this._socket instanceof tls.TLSSocket
                     ? this._socket
                     : undefined;
                 const offersBinding = !!msg.mechanisms?.includes('SCRAM-SHA-256-PLUS');
                 const useBinding = !!tlsSocket && offersBinding;
                 if (mode === 'require' && !useBinding) {
-                    throw new Error(tlsSocket
-                        ? 'SASL: channelBinding is "require" but the server does not offer SCRAM-SHA-256-PLUS'
-                        : 'SASL: channelBinding is "require" but the connection is not using TLS');
+                    throw new Error(!secure
+                        ? 'SASL: channelBinding is "require" but the connection is not using TLS'
+                        : !tlsSocket
+                            ? 'SASL: channelBinding is "require", but this runtime does not expose the ' +
+                                'server certificate, so there is nothing to bind to. Cloudflare Workers is ' +
+                                'one; use "prefer", which is the default.'
+                            : 'SASL: channelBinding is "require" but the server does not offer SCRAM-SHA-256-PLUS');
                 }
                 if (!useBinding && !msg.mechanisms?.includes('SCRAM-SHA-256')) {
                     throw new Error('SASL: Only mechanisms SCRAM-SHA-256 and SCRAM-SHA-256-PLUS are supported');

package/protocol/smart-buffer.d.ts

@@ -9,11 +9,12 @@ export interface SmartBufferConfig {
     houseKeepMs?: number;
 }
 /**
- * Adds the PostgreSQL wire format's two string encodings on top of
- * flexy-buffer's `FlexyBuffer`: a NUL-terminated C string, and a
- * length-prefixed string where a `null`/`undefined` value is written as a
- * length of -1 with no bytes following.
+ * The most a buffer may ever hold, given how much memory the machine has.
+ *
+ * @param totalMemory Bytes of memory, or 0 when that cannot be known.
+ * @returns Half of it, capped - or the cap alone when it is unknown.
  */
+export declare function maxSizeFor(totalMemory: number): number;
 export declare class SmartBuffer extends FlexyBuffer {
     static DEFAULT_PAGE_SIZE: number;
     static DEFAULT_MAX_SIZE: number;

package/protocol/smart-buffer.js

@@ -6,9 +6,29 @@ import * as os from 'os';
  * length-prefixed string where a `null`/`undefined` value is written as a
  * length of -1 with no bytes following.
  */
+/** The ceiling on `maxSizeFor`, and its answer when there is no machine to measure. */
+const HARD_MAX = 1024 * 1024 * 1024 * 2; // 2 GB
+/**
+ * The most a buffer may ever hold, given how much memory the machine has.
+ *
+ * @param totalMemory Bytes of memory, or 0 when that cannot be known.
+ * @returns Half of it, capped - or the cap alone when it is unknown.
+ */
+/* `os.totalmem()` answers 0 where there is no machine to ask about:
+   measured under Cloudflare's workerd, where `node:os` resolves and
+   returns zeros rather than throwing. Taking the minimum of that was a
+   maximum size of zero, which worked only because flexy-buffer reads a
+   falsy `maxLength` as "use the default" - an accident, and one that
+   would have become a buffer refusing every write the day that default
+   changed. */
+export function maxSizeFor(totalMemory) {
+    return totalMemory > 0
+        ? Math.min(Math.floor(totalMemory / 2), HARD_MAX)
+        : HARD_MAX;
+}
 export class SmartBuffer extends FlexyBuffer {
     static DEFAULT_PAGE_SIZE = 512;
-    static DEFAULT_MAX_SIZE = Math.min(Math.floor(os.totalmem() / 2), 1024 * 1024 * 1024 * 2);
+    static DEFAULT_MAX_SIZE = maxSizeFor(typeof os.totalmem === 'function' ? os.totalmem() : 0);
     constructor(cfg) {
         super({
             pageSize: cfg?.pageSize || SmartBuffer.DEFAULT_PAGE_SIZE,

package/protocol/workerd-socket.d.ts

@@ -0,0 +1,87 @@
+import { SafeEventEmitter } from '../safe-event-emitter.js';
+/** What `cloudflare:sockets` hands back, as much of it as is used here. */
+interface CfSocket {
+    readable: ReadableStream<Uint8Array>;
+    writable: WritableStream<Uint8Array>;
+    closed: Promise<void>;
+    close(): Promise<void>;
+    startTls(options: {
+        expectedServerHostname?: string;
+    }): CfSocket;
+}
+/** The one function `cloudflare:sockets` is reached for. */
+export type CfConnect = (address: string, options?: {
+    secureTransport?: 'off' | 'on' | 'starttls';
+}) => CfSocket;
+/**
+ * A `net.Socket`-shaped view of a Cloudflare socket, for the part of it
+ * this client uses: `connect`, `write`, `destroy`, and `data`/`error`/
+ * `close` events, plus `startTls()`, which is the one thing Node's
+ * `tls.connect({ socket })` cannot do on that runtime.
+ *
+ * Reads are a loop over the stream rather than a `'data'` event the
+ * runtime emits, so the loop is what turns one into the other.
+ */
+export declare class WorkerdSocket extends SafeEventEmitter {
+    private readonly _wantsTls;
+    private readonly _connect;
+    private _cf?;
+    private _writer?;
+    private _reader?;
+    private _upgrading;
+    private _destroyed;
+    private _paused?;
+    private _resume?;
+    constructor(_wantsTls: boolean, _connect?: () => Promise<CfConnect>);
+    /** Whether a TLS upgrade has been asked for and completed. */
+    get secure(): boolean;
+    private _secure;
+    /** Whether `destroy()` has been called. */
+    get destroyed(): boolean;
+    /** Whether writes are still accepted. */
+    get writable(): boolean;
+    cork(): void;
+    uncork(): void;
+    setNoDelay(): this;
+    setKeepAlive(): this;
+    setTimeout(): this;
+    /** Stops reading, so the sender is made to wait. */
+    pause(): this;
+    /** Starts reading again. */
+    resume(): this;
+    /** Closes the connection once anything already written has gone. */
+    end(): this;
+    /**
+     * Opens the connection and emits `connect` once it is writable.
+     *
+     * @param port The port to reach.
+     * @param host The host to reach.
+     */
+    connect(port: number, host: string): void;
+    /**
+     * Reads one chunk and hands it over, without starting the loop.
+     *
+     * @param cb Called with the bytes, or with nothing if the connection
+     * ended first.
+     */
+    readOnce(cb: (data?: Buffer) => void): void;
+    /**
+     * Upgrades the connection in place.
+     *
+     * @param servername The name to check the certificate against.
+     */
+    startTls(servername?: string): void;
+    /**
+     * Writes to the connection.
+     *
+     * @param data The bytes to send.
+     * @param cb Called once they are written, or with the error.
+     * @returns True - the runtime offers no "buffer is full" answer.
+     */
+    write(data: Uint8Array, cb?: (err?: Error | null) => void): boolean;
+    /** Closes the connection; `close` follows once the runtime agrees. */
+    destroy(): this;
+    protected _attach(cf: CfSocket, readLoop: boolean): void;
+    protected _read(reader: ReadableStreamDefaultReader<Uint8Array>): Promise<void>;
+}
+export {};

package/protocol/workerd-socket.js

@@ -0,0 +1,245 @@
+import { SafeEventEmitter } from '../safe-event-emitter.js';
+/* Imported where it is called rather than at the top of the file: the
+   specifier does not resolve off workerd, and this module is reachable
+   from a Node build through `pg-socket.ts`. Nothing awaits it unless a
+   connection is actually being made on that runtime. */
+const importCfConnect = async () => (await import(/* webpackIgnore: true */ 'cloudflare:sockets'))
+    .connect;
+/**
+ * A `net.Socket`-shaped view of a Cloudflare socket, for the part of it
+ * this client uses: `connect`, `write`, `destroy`, and `data`/`error`/
+ * `close` events, plus `startTls()`, which is the one thing Node's
+ * `tls.connect({ socket })` cannot do on that runtime.
+ *
+ * Reads are a loop over the stream rather than a `'data'` event the
+ * runtime emits, so the loop is what turns one into the other.
+ */
+/* Written here rather than taken from `pg-cloudflare`, which does the
+   same job for `pg`: the adapter is a hundred lines whose lifecycle this
+   client would otherwise not control, and only the upgrade is actually
+   needed - the plain path on workerd already works through `node:net`.
+
+   The setNoDelay/setKeepAlive/setTimeout trio answers nothing because
+   the runtime exposes no equivalent; they are here so the connect path
+   above can treat both socket kinds the same way. */
+export class WorkerdSocket extends SafeEventEmitter {
+    _wantsTls;
+    _connect;
+    _cf;
+    _writer;
+    _reader;
+    /* True between startTls() and the old socket's `closed` settling: that
+       promise resolves because the socket was replaced, not because the
+       connection went away, and reporting it as a close would end the
+       session in the middle of its handshake. */
+    _upgrading = false;
+    _destroyed = false;
+    _paused;
+    _resume;
+    constructor(_wantsTls, _connect = importCfConnect) {
+        super();
+        this._wantsTls = _wantsTls;
+        this._connect = _connect;
+    }
+    /** Whether a TLS upgrade has been asked for and completed. */
+    get secure() {
+        return this._secure;
+    }
+    _secure = false;
+    /** Whether `destroy()` has been called. */
+    get destroyed() {
+        return this._destroyed;
+    }
+    /** Whether writes are still accepted. */
+    get writable() {
+        return !this._destroyed && !!this._writer;
+    }
+    /* `cork`/`uncork` gather several small writes into one syscall on
+       Node. There is no syscall to gather here - a write is a promise
+       against a stream - so the pair is accepted and does nothing, which
+       is what it means on this runtime. */
+    cork() {
+        /* nothing to gather */
+    }
+    uncork() {
+        /* nothing to gather */
+    }
+    setNoDelay() {
+        return this;
+    }
+    setKeepAlive() {
+        return this;
+    }
+    setTimeout() {
+        return this;
+    }
+    /** Stops reading, so the sender is made to wait. */
+    /* Real backpressure rather than a no-op: the read loop is what pulls
+       from the stream, so not pulling is the whole of it. `pause()` during
+       a COPY TO is the only caller, and a stream left unread is how the
+       runtime learns to stop. */
+    pause() {
+        if (!this._paused)
+            this._paused = new Promise(r => (this._resume = r));
+        return this;
+    }
+    /** Starts reading again. */
+    resume() {
+        const go = this._resume;
+        this._paused = undefined;
+        this._resume = undefined;
+        go?.();
+        return this;
+    }
+    /** Closes the connection once anything already written has gone. */
+    end() {
+        return this.destroy();
+    }
+    /**
+     * Opens the connection and emits `connect` once it is writable.
+     *
+     * @param port The port to reach.
+     * @param host The host to reach.
+     */
+    connect(port, host) {
+        void (async () => {
+            try {
+                const connect = await this._connect();
+                this._cf = connect(`${host}:${port}`, {
+                    // `starttls` leaves the connection in the clear and allows a
+                    // later upgrade, which is what the SSLRequest exchange needs.
+                    secureTransport: this._wantsTls ? 'starttls' : 'off',
+                });
+                /* No read loop yet when a TLS upgrade is coming: `releaseLock()`
+                   throws on a reader with an outstanding read, and a loop parked
+                   in `reader.read()` is exactly that. The negotiation asks for
+                   the one byte it expects through `readOnce()`, and the loop
+                   starts on the upgraded socket. */
+                this._attach(this._cf, !this._wantsTls);
+                await this._writer.ready;
+                this.emit('connect');
+            }
+            catch (e) {
+                this.emit('error', e);
+            }
+        })();
+    }
+    /**
+     * Reads one chunk and hands it over, without starting the loop.
+     *
+     * @param cb Called with the bytes, or with nothing if the connection
+     * ended first.
+     */
+    /* What the SSLRequest exchange needs: a single answer, read while no
+       loop holds the reader, so the lock can be released for the upgrade
+       that follows. */
+    readOnce(cb) {
+        const reader = this._reader;
+        if (!reader)
+            return cb();
+        reader.read().then(({ done, value }) => cb(done || !value ? undefined : Buffer.from(value)), (e) => {
+            this.emit('error', e);
+            cb();
+        });
+    }
+    /**
+     * Upgrades the connection in place.
+     *
+     * @param servername The name to check the certificate against.
+     */
+    /* The locks have to go back before the socket is replaced, and the new
+       one needs its own reader and writer and its own read loop. */
+    startTls(servername) {
+        const cf = this._cf;
+        if (!cf) {
+            this.emit('error', new Error('Cannot upgrade a socket that is not connected'));
+            return;
+        }
+        try {
+            this._writer.releaseLock();
+            this._reader.releaseLock();
+            this._upgrading = true;
+            this._cf = cf.startTls(servername ? { expectedServerHostname: servername } : {});
+            this._attach(this._cf, true);
+            void this._writer.ready.then(() => {
+                this._secure = true;
+                this.emit('secureConnect');
+            }, (e) => this.emit('error', e));
+        }
+        catch (e) {
+            this.emit('error', e);
+        }
+    }
+    /**
+     * Writes to the connection.
+     *
+     * @param data The bytes to send.
+     * @param cb Called once they are written, or with the error.
+     * @returns True - the runtime offers no "buffer is full" answer.
+     */
+    write(data, cb) {
+        const writer = this._writer;
+        if (!writer) {
+            cb?.(new Error('Socket is not connected'));
+            return true;
+        }
+        writer.write(data).then(() => cb?.(), (e) => {
+            cb?.(e);
+            this.emit('error', e);
+        });
+        return true;
+    }
+    /** Closes the connection; `close` follows once the runtime agrees. */
+    destroy() {
+        if (this._destroyed)
+            return this;
+        this._destroyed = true;
+        const cf = this._cf;
+        this._cf = undefined;
+        cf?.close().catch(() => undefined);
+        return this;
+    }
+    _attach(cf, readLoop) {
+        this._writer = cf.writable.getWriter();
+        this._reader = cf.readable.getReader();
+        if (readLoop)
+            void this._read(this._reader);
+        cf.closed.then(() => {
+            if (this._upgrading) {
+                this._upgrading = false;
+                return;
+            }
+            this.emit('close');
+        }, (e) => {
+            if (this._upgrading) {
+                this._upgrading = false;
+                return;
+            }
+            this.emit('error', e);
+        });
+    }
+    async _read(reader) {
+        try {
+            for (;;) {
+                if (this._paused)
+                    await this._paused;
+                const { done, value } = await reader.read();
+                if (done)
+                    return;
+                /* Asked again on the way out: a pause() during a read already in
+                   flight cannot un-await it, and delivering that chunk anyway
+                   would be data arriving after the consumer said stop. */
+                if (this._paused)
+                    await this._paused;
+                if (value?.length)
+                    this.emit('data', Buffer.from(value));
+            }
+        }
+        catch (e) {
+            // A read that ends because the socket was replaced is the upgrade
+            // happening, not a failure to report.
+            if (!this._upgrading && !this._destroyed)
+                this.emit('error', e);
+        }
+    }
+}

package/util/runtime.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Whether this client is running inside a Cloudflare Worker.
+ *
+ * @returns True on workerd, false on Node.js, Bun and anything else.
+ */
+export declare function isWorkerd(): boolean;

package/util/runtime.js

@@ -0,0 +1,19 @@
+/**
+ * Whether this client is running inside a Cloudflare Worker.
+ *
+ * @returns True on workerd, false on Node.js, Bun and anything else.
+ */
+/* The documented tell, and the one `pg` uses: since the
+   `global_navigator` compatibility flag went on, workerd defines
+   `navigator.userAgent` and sets it to exactly this. Node and Bun define
+   `navigator` too, with a userAgent of their own, so the test is for the
+   whole string rather than a substring of it.
+
+   Asked on each call rather than read once at load: it is reached once
+   per connection, where the cost is nothing, and a value frozen at
+   module load cannot be tested from both sides. */
+export function isWorkerd() {
+    return (typeof navigator === 'object' &&
+        navigator !== null &&
+        navigator.userAgent === 'Cloudflare-Workers');
+}