postgrejs 2.23.1 → 3.0.1

package/connection/copy-stream.js

@@ -0,0 +1,244 @@
+import { Readable, Writable } from 'node:stream';
+import { Protocol } from '../protocol/protocol.js';
+const BackendMessageCode = Protocol.BackendMessageCode;
+/**
+ * A COPY ... TO STDOUT in progress, as a Readable of the raw bytes the
+ * server sends - text, CSV or binary, whichever the statement asked for.
+ * No decoding happens here: the payload is handed on exactly as it arrived,
+ * without a copy.
+ *
+ * The stream must be consumed (or destroyed): until the copy finishes the
+ * connection is still mid-statement, and an unread stream pauses the socket
+ * rather than buffering the whole export in memory.
+ */
+export class CopyToStream extends Readable {
+    /** Format of the copy as a whole, from CopyOutResponse. */
+    overallFormat;
+    /** Per-column formats, from CopyOutResponse. */
+    columnFormats;
+    /**
+     * Rows the server reported for the copy. Set before 'end' is emitted, so
+     * it is always readable once the stream has finished.
+     */
+    rowCount;
+    _socket;
+    _error;
+    _started;
+    _discarding = false;
+    _settled = false;
+    _paused = false;
+    constructor(socket) {
+        super();
+        this._socket = socket;
+    }
+    /**
+     * Handles the copy's backend messages. Passed straight to
+     * PgSocket.sendQueryMessage() by IntlConnection.copyTo().
+     */
+    capture = (code, msg, done) => {
+        switch (code) {
+            case BackendMessageCode.CopyOutResponse:
+                this.overallFormat = msg.overallFormat;
+                this.columnFormats = msg.columnFormats;
+                this._started?.();
+                this._started = undefined;
+                break;
+            case BackendMessageCode.CopyData:
+                if (this._discarding)
+                    break;
+                if (!this.push(msg.data) && !this._paused) {
+                    this._paused = true;
+                    this._socket.pause();
+                }
+                break;
+            case BackendMessageCode.CopyDone:
+                break;
+            case BackendMessageCode.CommandComplete:
+                this.rowCount = msg.rowCount;
+                break;
+            case BackendMessageCode.ErrorResponse:
+                this._error = msg;
+                break;
+            case BackendMessageCode.ReadyForQuery:
+                this._finish(done);
+                break;
+            default:
+                if (!this._error && !this.overallFormat)
+                    this._error = new Error('Statement did not start a COPY TO STDOUT - use query() or execute() instead');
+                break;
+        }
+    };
+    /**
+     * Resolves once the server has accepted the copy, rejects if it never
+     * starts one.
+     */
+    waitStarted() {
+        if (this.overallFormat != null)
+            return Promise.resolve();
+        if (this._error)
+            return Promise.reject(this._error);
+        return new Promise((resolve, reject) => {
+            this._started = (err) => (err ? reject(err) : resolve());
+        });
+    }
+    /**
+     * Reports a failure that happened outside the message flow (the socket
+     * dying, say). A no-op once the copy has already settled, so the normal
+     * error path is never reported twice.
+     */
+    fail(err) {
+        if (this._settled)
+            return;
+        this._settled = true;
+        this._error = this._error || err;
+        const started = this._started;
+        this._started = undefined;
+        if (started)
+            started(this._error);
+        else if (!this.destroyed)
+            this.destroy(this._error);
+    }
+    _read() {
+        if (!this._paused)
+            return;
+        this._paused = false;
+        this._socket.resume();
+    }
+    _destroy(err, callback) {
+        this._discarding = true;
+        this._paused = false;
+        this._socket.resume();
+        callback(err);
+    }
+    _finish(done) {
+        this._settled = true;
+        const err = this._error;
+        const started = this._started;
+        this._started = undefined;
+        done(err);
+        if (started) {
+            started(err || new Error('Copy ended before it started'));
+            return;
+        }
+        if (this._discarding)
+            return;
+        if (err)
+            this.destroy(err);
+        else
+            this.push(null);
+    }
+}
+/**
+ * A COPY ... FROM STDIN in progress, as a Writable. Whatever is written is
+ * forwarded as CopyData without being copied or reinterpreted, so the
+ * caller decides the encoding by the format its statement asked for.
+ *
+ * 'finish' means the server accepted the whole copy: the stream waits for
+ * CommandComplete rather than for the last byte to leave, so rowCount is
+ * set by the time a `pipeline()` over it resolves. Destroying the stream
+ * (which `pipeline()` does when the source fails) sends CopyFail, leaving
+ * the connection usable rather than stuck waiting for data.
+ */
+export class CopyFromStream extends Writable {
+    /** Rows the server accepted. Set before 'finish' is emitted. */
+    rowCount;
+    _socket;
+    _error;
+    _started;
+    _completed;
+    _copyEnded = false;
+    _settled = false;
+    constructor(socket) {
+        super();
+        this._socket = socket;
+    }
+    /**
+     * Handles the copy's backend messages. Passed straight to
+     * PgSocket.sendQueryMessage() by IntlConnection.copyFrom().
+     */
+    capture = (code, msg, done) => {
+        switch (code) {
+            case BackendMessageCode.CopyInResponse:
+                this._started?.();
+                this._started = undefined;
+                break;
+            case BackendMessageCode.CommandComplete:
+                this.rowCount = msg.rowCount;
+                break;
+            case BackendMessageCode.ErrorResponse:
+                this._error = msg;
+                if (!this._copyEnded && !this.destroyed)
+                    this.destroy(this._error);
+                break;
+            case BackendMessageCode.ReadyForQuery:
+                this._finish(done);
+                break;
+            default:
+                if (!this._error && !this._copyEnded && this._started)
+                    this._error = new Error('Statement did not start a COPY FROM STDIN - use query() or execute() instead');
+                break;
+        }
+    };
+    /**
+     * Resolves once the server is ready for data, rejects if it never asks
+     * for any.
+     */
+    waitStarted() {
+        if (this._error)
+            return Promise.reject(this._error);
+        return new Promise((resolve, reject) => {
+            this._started = (err) => (err ? reject(err) : resolve());
+        });
+    }
+    /** See CopyToStream.fail(). */
+    fail(err) {
+        if (this._settled)
+            return;
+        this._settled = true;
+        this._error = this._error || err;
+        const started = this._started;
+        this._started = undefined;
+        const completed = this._completed;
+        this._completed = undefined;
+        if (started)
+            started(this._error);
+        else if (completed)
+            completed(this._error);
+        else if (!this.destroyed)
+            this.destroy(this._error);
+    }
+    _write(chunk, encoding, callback) {
+        if (this._error)
+            return callback(this._error);
+        this._socket.sendCopyData(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, encoding), callback);
+    }
+    _final(callback) {
+        if (this._error)
+            return callback(this._error);
+        this._copyEnded = true;
+        this._socket.sendCopyDone();
+        this._completed = callback;
+    }
+    _destroy(err, callback) {
+        if (this._copyEnded)
+            return callback(err);
+        this._copyEnded = true;
+        this._socket.sendCopyFail(err ? err.message : 'aborted by client');
+        callback(err);
+    }
+    _finish(done) {
+        this._settled = true;
+        const err = this._error;
+        const started = this._started;
+        this._started = undefined;
+        const completed = this._completed;
+        this._completed = undefined;
+        done(err);
+        if (started)
+            return started(err || new Error('Copy ended before it started'));
+        if (completed)
+            return completed(err);
+        if (err && !this.destroyed)
+            this.destroy(err);
+    }
+}

package/connection/cursor.js

@@ -1,8 +1,7 @@
 import DoublyLinked from 'doublylinked';
 import { TaskQueue } from 'power-tasks';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
-import { convertRowToObject } from '../util/convert-row-to-object.js';
-import { parseRow } from '../util/parse-row.js';
+import { parseObjectRow, parseRow } from '../util/parse-row.js';
 export class Cursor extends SafeEventEmitter {
     _statement;
     _portal;
@@ -38,7 +37,8 @@ export class Cursor extends SafeEventEmitter {
         const out = [];
         if (this._closed)
             return out;
-        for (let i = 0; i < nRows; i++) {
+        let i;
+        for (i = 0; i < nRows; i++) {
             if (!this._rows.length)
                 await this._fetchRows();
             if (this._rows.length)
@@ -51,12 +51,16 @@ export class Cursor extends SafeEventEmitter {
     async close() {
         if (this._closed)
             return;
-        await this._portal.close();
-        await this._statement.close();
+        const combined = await this._statement._maybeCloseWithPortal(this._portal.name);
+        if (!combined)
+            await this._portal.close();
         this.emit('close');
         this._closed = true;
     }
     async _fetchRows() {
+        // Both callers (next()/fetch()) already gate on _closed with no await
+        // in between, so this can't currently observe a change - kept as a
+        // defensive backstop for this private method's own contract.
         if (this._closed)
             return;
         const portal = this._portal;
@@ -65,19 +69,22 @@ export class Cursor extends SafeEventEmitter {
             const queryOptions = this._queryOptions;
             const r = await portal.execute(queryOptions.fetchCount || 100);
             if (r && r.rows && r.rows.length) {
+                const rows = r.rows;
                 if (this._parsers) {
                     const objectRows = queryOptions.objectRows;
                     const fields = this.fields;
-                    const rows = r.rows;
-                    for (let i = 0; i < rows.length; i++) {
-                        const row = rows[i];
-                        parseRow(this._parsers, row, this._queryOptions);
-                        if (objectRows)
-                            rows[i] = convertRowToObject(fields, row);
+                    const parsers = this._parsers;
+                    const rowLen = rows.length;
+                    let i;
+                    for (i = 0; i < rowLen; i++) {
+                        const { data, columnCount } = rows[i];
+                        rows[i] = objectRows
+                            ? parseObjectRow(parsers, data, columnCount, this._queryOptions, fields)
+                            : parseRow(parsers, data, columnCount, this._queryOptions);
                     }
                 }
-                this._rows.push(...r.rows);
-                this.emit('fetch', r.rows);
+                this._rows.push(...rows);
+                this.emit('fetch', rows);
             }
             else {
                 await this.close();

package/connection/intl-connection.d.ts

@@ -1,19 +1,24 @@
-import { TaskQueue } from 'power-tasks';
 import { ConnectionState } from '../constants.js';
 import type { ConnectionConfiguration } from '../interfaces/database-connection-params.js';
+import type { QueryOptions } from '../interfaces/query-options.js';
+import type { QueryResult } from '../interfaces/query-result.js';
 import type { ScriptExecuteOptions } from '../interfaces/script-execute-options.js';
 import type { ScriptResult } from '../interfaces/script-result.js';
 import { PgSocket } from '../protocol/pg-socket.js';
+import { Protocol } from '../protocol/protocol.js';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
-import type { Maybe } from '../types.js';
+import type { Maybe, OID } from '../types.js';
 import type { Connection } from './connection.js';
+import { CopyFromStream, CopyToStream } from './copy-stream.js';
 export declare class IntlConnection extends SafeEventEmitter {
+    private _executeReusedParserCache;
     protected _refCount: number;
     protected _config: ConnectionConfiguration;
     protected _onErrorSavePoint: string;
     transactionStatus: string;
     socket: PgSocket;
-    statementQueue: TaskQueue;
+    owner?: SafeEventEmitter;
+    runningQueryCount: number;
     constructor(config?: ConnectionConfiguration | string);
     get config(): ConnectionConfiguration;
     get inTransaction(): boolean;
@@ -29,12 +34,72 @@ export declare class IntlConnection extends SafeEventEmitter {
     savepoint(name: string): Promise<void>;
     commit(): Promise<void>;
     rollback(): Promise<void>;
+    /**
+     * Ends the current transaction as a prepared one: it stops being tied to
+     * this session and waits under `name` until some connection - not
+     * necessarily this one, and not necessarily this process - finishes it
+     * with commitPrepared() or rollbackPrepared().
+     *
+     * Goes through _execute() rather than execute(): PREPARE TRANSACTION is
+     * not in the latter's list of transaction commands, so it would be
+     * wrapped in a savepoint whose RELEASE then fails, the session no longer
+     * being in a transaction by that point.
+     *
+     * Requires `max_prepared_transactions` above zero on the server, which is
+     * not the default; the server's own error says so if it is not.
+     */
+    prepareTransaction(name: string): Promise<void>;
+    /** Commits a transaction left waiting by prepareTransaction(). */
+    commitPrepared(name: string): Promise<void>;
+    /** Discards a transaction left waiting by prepareTransaction(). */
+    rollbackPrepared(name: string): Promise<void>;
     rollbackToSavepoint(name: string): Promise<void>;
     releaseSavepoint(name: string): Promise<void>;
+    /** Asks the server to cancel whatever this session is running. */
+    cancel(): Promise<void>;
     ref(): void;
     unref(): boolean;
     assertConnected(): void;
+    /**
+     * Runs a COPY ... TO STDOUT and hands back its bytes as they arrive.
+     * Resolves once the server has accepted the copy, not once it has
+     * finished - the whole point is not to hold the export in memory.
+     */
+    copyTo(sql: string): Promise<CopyToStream>;
+    /**
+     * Runs a COPY ... FROM STDIN and hands back a stream to feed it.
+     * Resolves once the server is ready for data.
+     */
+    copyFrom(sql: string): Promise<CopyFromStream>;
     protected _execute(sql: string, options?: ScriptExecuteOptions, cb?: (event: string, ...args: any[]) => void): Promise<ScriptResult>;
+    /**
+     * One-shot Extended Query fast path: Parse+Bind+Describe+Execute+Sync as
+     * a single round trip (unnamed statement/portal, no Close needed), used
+     * by Connection.query() instead of prepare()+PreparedStatement.execute()
+     * +close()'s 7 round trips whenever there's no cursor and no explicit/
+     * active transaction to wrap (see Connection.query() for that gating).
+     */
+    queryOnce(sql: string, paramTypes: Maybe<Maybe<OID>[]>, params: Maybe<Maybe<any>[]>, options: QueryOptions): Promise<QueryResult>;
+    /**
+     * Parse+Describe(statement)+Sync as a single round trip - used by
+     * PreparedStatement.prepare() instead of a separately-awaited Parse then
+     * a separately-awaited Sync, and fetches the RowDescription/NoData in the
+     * same round trip so the caller can cache it (see executeReused()) rather
+     * than every later execute() re-Describing its own portal.
+     */
+    prepareOnce(sql: string, paramTypes: Maybe<Maybe<OID>[]>, statementName: string): Promise<{
+        fields?: Protocol.RowDescription[];
+    }>;
+    /**
+     * Bind+Execute+Sync as a single round trip against an unnamed portal, for
+     * an already-prepared (named) statement - used by
+     * PreparedStatement._execute()'s non-cursor path instead of the 4-round-
+     * trip Portal.bind()/retrieveFields()/execute()/close() sequence. Takes
+     * the RowDescription fields prepareOnce() already fetched instead of
+     * re-Describing a fresh portal on every call.
+     */
+    executeReused(statementName: string, cachedFields: Protocol.RowDescription[] | undefined, paramTypes: Maybe<Maybe<OID>[]>, params: Maybe<Maybe<any>[]>, options: QueryOptions): Promise<QueryResult>;
+    emit(event: string | symbol, ...args: any[]): boolean;
     protected _onError(err: Error): void;
 }
 export declare function getIntlConnection(connection: Connection): IntlConnection;