postgrejs 3.1.3 → 3.4.0

package/protocol/frontend.js

@@ -39,31 +39,31 @@ export class Frontend {
         this._io = new SmartBuffer(options?.buffer);
     }
     getSSLRequestMessage() {
-        return this._io
-            .start()
-            .writeUInt32BE(8) // Length of message contents in bytes, including self.
-            .writeUInt16BE(1234)
-            .writeUInt16BE(5679)
-            .flush();
+        const io = this._io.start();
+        io.writeUInt32BE(8); // Length of message contents in bytes, including self.
+        io.writeUInt16BE(1234);
+        io.writeUInt16BE(5679);
+        return io.flush();
     }
     getStartupMessage(args, minorVersion = Protocol.VERSION_MINOR) {
-        const io = this._io
-            .start()
-            .writeInt32BE(0) // Preserve length
-            .writeInt16BE(Protocol.VERSION_MAJOR)
-            .writeInt16BE(minorVersion);
+        const io = this._io.start();
+        io.writeInt32BE(0); // Preserve length
+        io.writeInt16BE(Protocol.VERSION_MAJOR);
+        io.writeInt16BE(minorVersion);
         const entries = Object.entries(args);
         const l = entries.length;
         let k;
         let v;
         for (let i = 0; i < l; i++) {
             [k, v] = entries[i];
-            if (k !== 'client_encoding')
-                io.writeCString(k, 'utf8').writeCString(v, 'utf8');
+            if (k !== 'client_encoding') {
+                io.writeCString(k, 'utf8');
+                io.writeCString(v, 'utf8');
+            }
         }
-        io.writeCString('client_encoding', 'utf8')
-            .writeCString('UTF8', 'utf8')
-            .writeUInt8(0);
+        io.writeCString('client_encoding', 'utf8');
+        io.writeCString('UTF8', 'utf8');
+        io.writeUInt8(0);
         return setLengthAndFlush(io, 0);
     }
     /**
@@ -73,51 +73,46 @@ export class Frontend {
      * down the normal one.
      */
     getCancelRequestMessage(processID, secretKey) {
-        return this._io
-            .start()
-            .writeUInt32BE(12 + secretKey.length) // Length of message contents in bytes, including self.
-            .writeUInt16BE(1234)
-            .writeUInt16BE(5678)
-            .writeUInt32BE(processID)
-            .writeBuffer(secretKey)
-            .flush();
+        const io = this._io.start();
+        io.writeUInt32BE(12 + secretKey.length); // Length of message contents in bytes, including self.
+        io.writeUInt16BE(1234);
+        io.writeUInt16BE(5678);
+        io.writeUInt32BE(processID);
+        io.writeBytes(secretKey);
+        return io.flush();
     }
     getPasswordMessage(password) {
-        const io = this._io
-            .start()
-            .writeInt8(Protocol.FrontendMessageCode.PasswordMessage)
-            .writeInt32BE(0) // Preserve header
-            .writeCString(password, 'utf8');
+        const io = this._io.start();
+        io.writeInt8(Protocol.FrontendMessageCode.PasswordMessage);
+        io.writeInt32BE(0); // Preserve header
+        io.writeCString(password, 'utf8');
         return setLengthAndFlush(io, 1);
     }
     getSASLMessage(sasl) {
-        const io = this._io
-            .start()
-            .writeInt8(Protocol.FrontendMessageCode.PasswordMessage)
-            .writeInt32BE(0) // Preserve header
-            .writeCString(sasl.mechanism, 'utf8')
-            .writeLString(sasl.clientFirstMessage);
+        const io = this._io.start();
+        io.writeInt8(Protocol.FrontendMessageCode.PasswordMessage);
+        io.writeInt32BE(0); // Preserve header
+        io.writeCString(sasl.mechanism, 'utf8');
+        io.writeLString(sasl.clientFirstMessage);
         return setLengthAndFlush(io, 1);
     }
     getSASLFinalMessage(session) {
-        const io = this._io
-            .start()
-            .writeInt8(Protocol.FrontendMessageCode.PasswordMessage)
-            .writeInt32BE(0) // Preserve header
-            .writeString(session.clientFinalMessage);
+        const io = this._io.start();
+        io.writeInt8(Protocol.FrontendMessageCode.PasswordMessage);
+        io.writeInt32BE(0); // Preserve header
+        io.writeString(session.clientFinalMessage);
         return setLengthAndFlush(io, 1);
     }
     getParseMessage(args) {
         if (args.statement && args.statement.length > 63)
             throw new Error('Query name length must be lower than 63');
         const { paramTypes } = args;
-        const io = this._io
-            .start()
-            .writeInt8(Protocol.FrontendMessageCode.Parse)
-            .writeInt32BE(0) // Preserve header
-            .writeCString(args.statement || '', 'utf8')
-            .writeCString(args.sql, 'utf8')
-            .writeUInt16BE(paramTypes?.length || 0);
+        const io = this._io.start();
+        io.writeInt8(Protocol.FrontendMessageCode.Parse);
+        io.writeInt32BE(0); // Preserve header
+        io.writeCString(args.statement || '', 'utf8');
+        io.writeCString(args.sql, 'utf8');
+        io.writeUInt16BE(paramTypes?.length || 0);
         if (paramTypes) {
             let i;
             const l = paramTypes.length;
@@ -132,19 +127,18 @@ export class Frontend {
             throw new Error('Portal name length must be lower than 63');
         if (args.statement && args.statement.length > 63)
             throw new Error('Query name length must be lower than 63');
-        const io = this._io
-            .start()
-            .writeInt8(Protocol.FrontendMessageCode.Bind)
-            .writeInt32BE(0) // Preserve header
-            .writeCString(args.portal || '', 'utf8')
-            .writeCString(args.statement || '', 'utf8');
+        const io = this._io.start();
+        io.writeInt8(Protocol.FrontendMessageCode.Bind);
+        io.writeInt32BE(0); // Preserve header
+        io.writeCString(args.portal || '', 'utf8');
+        io.writeCString(args.statement || '', 'utf8');
         const { params, paramTypes, queryOptions } = args;
         const columnFormat = queryOptions.columnFormat != null
             ? queryOptions.columnFormat
             : DEFAULT_COLUMN_FORMAT;
         if (params && params.length) {
             io.writeInt16BE(params.length);
-            const formatOffset = io.offset;
+            const formatOffset = io.position;
             const l = params.length;
             let i;
             for (i = 0; i < l; i++) {
@@ -172,7 +166,7 @@ export class Frontend {
                         io.buffer.writeInt16BE(Protocol.DataFormat.binary, formatOffset + i * 2);
                         // Preserve data length
                         io.writeInt32BE(0);
-                        const dataOffset = io.offset;
+                        const dataOffset = io.position;
                         if (dt.elementsOID) {
                             // If data type is array
                             v = Array.isArray(v) ? v : [v];
@@ -181,7 +175,7 @@ export class Frontend {
                         else {
                             dt.encodeBinary(io, v, queryOptions);
                         }
-                        io.buffer.writeInt32BE(io.length - dataOffset, dataOffset - 4); // Update length
+                        io.buffer.writeInt32BE(io.size - dataOffset, dataOffset - 4); // Update length
                     }
                     else if (typeof dt.encodeText === 'function') {
                         v = dt.elementsOID
@@ -195,9 +189,9 @@ export class Frontend {
                     io.buffer.writeInt16BE(Protocol.DataFormat.binary, formatOffset + i * 2);
                     // Preserve data length
                     io.writeInt32BE(0);
-                    const dataOffset = io.offset;
-                    io.writeBuffer(v);
-                    io.buffer.writeInt32BE(io.length - dataOffset, dataOffset - 4); // Update length
+                    const dataOffset = io.position;
+                    io.writeBytes(v);
+                    io.buffer.writeInt32BE(io.size - dataOffset, dataOffset - 4); // Update length
                 }
                 else {
                     io.writeLString('' + v, 'utf8');
@@ -230,12 +224,11 @@ export class Frontend {
                 ? 'Portal'
                 : 'Statement name length must be lower than 63');
         }
-        const io = this._io
-            .start()
-            .writeInt8(Protocol.FrontendMessageCode.Describe)
-            .writeInt32BE(0) // Preserve header
-            .writeUInt8(args.type.charCodeAt(0))
-            .writeCString(args.name || '', 'utf8');
+        const io = this._io.start();
+        io.writeInt8(Protocol.FrontendMessageCode.Describe);
+        io.writeInt32BE(0); // Preserve header
+        io.writeUInt8(args.type.charCodeAt(0));
+        io.writeCString(args.name || '', 'utf8');
         return setLengthAndFlush(io, 1);
     }
     getExecuteMessage(args) {
@@ -243,12 +236,11 @@ export class Frontend {
             (args.fetchCount < 0 || args.fetchCount > 4294967295)) {
             throw new Error('fetchCount can be between 0 and 4294967295');
         }
-        const io = this._io
-            .start()
-            .writeInt8(Protocol.FrontendMessageCode.Execute)
-            .writeInt32BE(0) // Preserve header
-            .writeCString(args.portal || '', 'utf8')
-            .writeUInt32BE(args.fetchCount || 0);
+        const io = this._io.start();
+        io.writeInt8(Protocol.FrontendMessageCode.Execute);
+        io.writeInt32BE(0); // Preserve header
+        io.writeCString(args.portal || '', 'utf8');
+        io.writeUInt32BE(args.fetchCount || 0);
         return setLengthAndFlush(io, 1);
     }
     getCloseMessage(args) {
@@ -257,20 +249,18 @@ export class Frontend {
                 ? 'Portal'
                 : 'Statement name length must be lower than 63');
         }
-        const io = this._io
-            .start()
-            .writeInt8(Protocol.FrontendMessageCode.Close)
-            .writeInt32BE(0) // Preserve header
-            .writeUInt8(args.type.charCodeAt(0))
-            .writeCString(args.name || '', 'utf8');
+        const io = this._io.start();
+        io.writeInt8(Protocol.FrontendMessageCode.Close);
+        io.writeInt32BE(0); // Preserve header
+        io.writeUInt8(args.type.charCodeAt(0));
+        io.writeCString(args.name || '', 'utf8');
         return setLengthAndFlush(io, 1);
     }
     getQueryMessage(sql) {
-        const io = this._io
-            .start()
-            .writeInt8(Protocol.FrontendMessageCode.Query)
-            .writeInt32BE(0) // Preserve header
-            .writeCString(sql || '', 'utf8');
+        const io = this._io.start();
+        io.writeInt8(Protocol.FrontendMessageCode.Query);
+        io.writeInt32BE(0); // Preserve header
+        io.writeCString(sql || '', 'utf8');
         return setLengthAndFlush(io, 1);
     }
     getFunctionCallMessage(args) {
@@ -279,12 +269,11 @@ export class Frontend {
         const fl = formats.length;
         const l = values.length;
         let i;
-        const io = this._io
-            .start()
-            .writeInt8(Protocol.FrontendMessageCode.FunctionCall)
-            .writeInt32BE(0) // Preserve header
-            .writeInt32BE(functionId)
-            .writeInt16BE(fl);
+        const io = this._io.start();
+        io.writeInt8(Protocol.FrontendMessageCode.FunctionCall);
+        io.writeInt32BE(0); // Preserve header
+        io.writeInt32BE(functionId);
+        io.writeInt16BE(fl);
         for (i = 0; i < fl; i++)
             io.writeInt16BE(formats[i]);
         io.writeInt16BE(l);
@@ -293,8 +282,10 @@ export class Frontend {
             v = values[i];
             if (v == null)
                 io.writeInt32BE(-1);
-            else
-                io.writeInt32BE(v.length).writeBuffer(v);
+            else {
+                io.writeInt32BE(v.length);
+                io.writeBytes(v);
+            }
         }
         io.writeInt16BE(resultFormat ?? DataFormat.text);
         return setLengthAndFlush(io, 1);
@@ -315,11 +306,10 @@ export class Frontend {
         return StaticCopyDoneBuffer;
     }
     getCopyFailMessage(message) {
-        const io = this._io
-            .start()
-            .writeInt8(Protocol.FrontendMessageCode.CopyFail)
-            .writeInt32BE(0) // Preserve header
-            .writeCString(message || '', 'utf8');
+        const io = this._io.start();
+        io.writeInt8(Protocol.FrontendMessageCode.CopyFail);
+        io.writeInt32BE(0); // Preserve header
+        io.writeCString(message || '', 'utf8');
         return setLengthAndFlush(io, 1);
     }
     getFlushMessage() {
@@ -333,6 +323,6 @@ export class Frontend {
     }
 }
 function setLengthAndFlush(io, lengthOffset) {
-    io.buffer.writeUInt32BE(io.length - lengthOffset, lengthOffset);
+    io.buffer.writeUInt32BE(io.size - lengthOffset, lengthOffset);
     return io.flush();
 }

package/protocol/pg-socket.d.ts

@@ -22,8 +22,6 @@ export declare class PgSocket extends SafeEventEmitter {
     private _secretKey?;
     private _protocolNegotiation?;
     private _captureQueue;
-    private _pendingWrites;
-    private _flushScheduled;
     private _hosts;
     private _hostIndex;
     private _sessionAttrsChecked;
@@ -95,6 +93,37 @@ export declare class PgSocket extends SafeEventEmitter {
         bind: Frontend.BindMessageArgs;
         describe: Frontend.DescribeMessageArgs;
         execute: Frontend.ExecuteMessageArgs;
+        before?: string;
+        after?: string;
+    }, cb: CaptureCallback): Promise<any>;
+    /**
+     * Parse + Bind + Describe(portal) + Execute per statement, then a SINGLE
+     * Sync for the lot - the wire shape behind Connection.pipeline().
+     *
+     * The same framing as sendBatchBindExecuteMessages(), and the same
+     * consequences, except that each statement carries its own Parse rather
+     * than reusing one prepared statement: the statements share one implicit
+     * transaction, and PostgreSQL discards everything between an error and
+     * the Sync, so a rejected statement stops the ones behind it.
+     *
+     * Describe is not optional here even though nothing caches its answer.
+     * Without it the server sends DataRows for a row-returning statement with
+     * no RowDescription in front of them, leaving the column names and types
+     * unknown - the reason the one-shot path in sendExtendedQueryMessages()
+     * includes it too. It costs about a quarter of a millisecond across
+     * twenty statements, measured.
+     *
+     * Every Execute is unlimited (fetchCount 0): a portal that suspended
+     * mid-pipeline would answer PortalSuspended instead of CommandComplete
+     * and desynchronise the positional statement-to-result mapping.
+     */
+    sendPipelineMessages(args: {
+        statements: {
+            parse: Frontend.ParseMessageArgs;
+            bind: Frontend.BindMessageArgs;
+            describe: Frontend.DescribeMessageArgs;
+            execute: Frontend.ExecuteMessageArgs;
+        }[];
     }, cb: CaptureCallback): Promise<any>;
     /**
      * Parse + Describe(statement) + Sync as a single round trip - used by
@@ -119,6 +148,33 @@ export declare class PgSocket extends SafeEventEmitter {
     sendBindExecuteMessages(args: {
         bind: Frontend.BindMessageArgs;
         execute: Frontend.ExecuteMessageArgs;
+        before?: string;
+        after?: string;
+    }, cb: CaptureCallback): Promise<any>;
+    /**
+     * One Bind+Execute pair per parameter set against the same prepared
+     * statement, then a SINGLE Sync for the lot - the wire shape behind
+     * PreparedStatement.executeBatch().
+     *
+     * The single Sync is the whole point, and it is also what gives the
+     * batch its semantics. Sending Bind/Execute/Sync per set (what N
+     * separate execute() calls do, even pipelined) makes the server finish
+     * an implicit transaction and answer ReadyForQuery every time; one Sync
+     * at the end collapses that to one, which is where the bulk of the
+     * speedup comes from. It also means the sets share one implicit
+     * transaction, and that PostgreSQL discards everything between an error
+     * and the Sync - so a set that fails stops the ones behind it from
+     * running at all. Both of those are inherent to this framing rather
+     * than choices made above it.
+     *
+     * Every Execute here must be unlimited (fetchCount 0): a portal that
+     * suspends mid-batch would answer PortalSuspended instead of
+     * CommandComplete and desynchronise the positional set-to-result
+     * mapping the caller relies on.
+     */
+    sendBatchBindExecuteMessages(args: {
+        binds: Frontend.BindMessageArgs[];
+        execute: Frontend.ExecuteMessageArgs;
     }, cb: CaptureCallback): Promise<any>;
     /**
      * Bind + Describe(portal) + Flush as a single round trip (NOT Sync - see
@@ -195,6 +251,24 @@ export declare class PgSocket extends SafeEventEmitter {
      * "start listening" step to race or misuse.
      */
     private _sendAndCapture;
+    /**
+     * Parse + Bind + Execute for a parameterless utility statement, appended
+     * to a message list that is about to be closed by one Sync - how
+     * sendBindExecuteMessages() and sendExtendedQueryMessages() carry their
+     * `before`/`after` SQL (today, SAVEPOINT and RELEASE) in the same round
+     * trip as the statement itself rather than as a round trip each.
+     *
+     * Everything here goes through the unnamed statement and the unnamed
+     * portal. That is safe in this order: the caller's own Bind names a
+     * prepared statement rather than the unnamed one, and PostgreSQL
+     * processes the messages in sequence, so each Bind only ever discards an
+     * unnamed portal whose Execute has already run.
+     *
+     * No Describe: neither statement returns rows, so there is no
+     * RowDescription worth asking for. Result formats come from the caller's
+     * own Bind args, which likewise cost nothing against no columns.
+     */
+    private _pushUtilityStatement;
     protected _removeListeners(): void;
     protected _reset(): void;
     protected _handleConnect(): void;
@@ -235,39 +309,14 @@ export declare class PgSocket extends SafeEventEmitter {
     protected _handleNegotiateProtocolVersion(msg: Protocol.NegotiateProtocolVersionMessage): void;
     protected _handleBackendKeyData(msg: Protocol.BackendKeyDataMessage): void;
     protected _handleCommandComplete(msg: any): Protocol.CommandCompleteMessage;
-    /**
-     * Queues `data` for the socket instead of writing it straight through:
-     * everything handed to _send() during the same synchronous burst (e.g.
-     * many concurrent query() calls fired via Promise.all over one
-     * connection) is flushed together on the next tick, corked, so Node
-     * turns the whole batch into a single underlying writev rather than one
-     * socket write per call. Measured against postgres.js, which coalesces
-     * the same way at the application level (its connection.js write()/
-     * nextWrite() pair, flushing on a 1KB threshold or setImmediate): 50
-     * concurrent prepared executes cost it 3 socket writes where this cost
-     * us 50, and that write path was the single largest non-idle item in a
-     * CPU profile of the scenario.
-     *
-     * nextTick rather than setImmediate, deliberately: it still batches a
-     * whole synchronous burst, but a lone query doesn't have to wait for the
-     * event loop's check phase before its bytes go out - which would trade
-     * away the sequential/single-query scenarios to win the concurrent ones.
-     *
-     * Returns whether the socket could accept the data at all; the write
-     * itself is reported through `cb` (and a socket that dies before the
-     * flush rejects every pending capture via _failPendingCaptures()).
-     */
     protected _send(data: Buffer | Buffer[], cb?: Callback): boolean;
     /**
-     * Writes COPY bytes straight through instead of queueing them for the
-     * next tick like _send() does. Two reasons: during a copy the capture
-     * queue holds exactly one entry (the Query that opened it), so _send()'s
-     * "batch only when more than one request is in flight" test would never
-     * fire and every chunk would be written on its own anyway; and the
-     * caller needs write()'s own return value to know when to stop, which a
-     * deferred write cannot give it.
+     * Same write as _send(), but reporting backpressure instead of
+     * writability: a COPY IN producer needs write()'s own return value to
+     * know when to stop pushing, whereas _send()'s callers only need to know
+     * whether the socket could take the bytes at all. Kept separate rather
+     * than folded into _send() precisely so those two meanings of `false`
+     * cannot be confused at a call site.
      */
     protected _sendCopy(data: Buffer | Buffer[], cb?: Callback): boolean;
-    /** Arrow property, not a method: used as a bare process.nextTick callback. */
-    private _flushPendingWrites;
 }