postgrejs 2.23.1 → 3.0.1

package/connection/intl-connection.js

@@ -1,24 +1,40 @@
-import { TaskQueue } from 'power-tasks';
+import { performance } from 'node:perf_hooks';
 import { coerceToBoolean } from 'putil-varhelpers';
-import { ConnectionState } from '../constants.js';
+import { ConnectionState, DEFAULT_COLUMN_FORMAT } from '../constants.js';
 import { GlobalTypeMap } from '../data-type-map.js';
 import { PgSocket } from '../protocol/pg-socket.js';
 import { Protocol } from '../protocol/protocol.js';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
 import { getConnectionConfig } from '../util/connection-config.js';
-import { convertRowToObject } from '../util/convert-row-to-object.js';
 import { escapeLiteral } from '../util/escape-literal.js';
 import { getParsers } from '../util/get-parsers.js';
-import { parseRow } from '../util/parse-row.js';
+import { parseObjectRow, parseRow } from '../util/parse-row.js';
 import { wrapRowDescription } from '../util/wrap-row-description.js';
+import { CopyFromStream, CopyToStream } from './copy-stream.js';
 const DataFormat = Protocol.DataFormat;
+function columnFormatsEqual(a, b) {
+    if (a === b)
+        return true;
+    if (!Array.isArray(a) || !Array.isArray(b))
+        return false;
+    if (a.length !== b.length)
+        return false;
+    const l = a.length;
+    let i;
+    for (i = 0; i < l; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
 export class IntlConnection extends SafeEventEmitter {
+    _executeReusedParserCache = new WeakMap();
     _refCount = 0;
     _config;
     _onErrorSavePoint;
     transactionStatus = 'I';
     socket;
-    statementQueue = new TaskQueue({ concurrency: 1 });
+    owner;
+    runningQueryCount = 0;
     constructor(config) {
         super();
         this._config = Object.freeze(getConnectionConfig(config));
@@ -76,58 +92,60 @@ export class IntlConnection extends SafeEventEmitter {
     async close() {
         if (this.state === ConnectionState.CLOSED)
             return;
-        this.statementQueue.clearQueue();
         return new Promise(resolve => {
             if (this.socket.state === ConnectionState.CLOSED)
                 return;
+            // 'close' is not emitted here - the constructor's own
+            // `this.socket.on('close', () => this.emit('close'))` already
+            // forwards it once the socket's real close event fires. Emitting it
+            // again right here (synchronously, before socket.close()'s
+            // destroy() has actually completed) used to fire 'close' on this
+            // IntlConnection TWICE per close() call - confirmed live: a single
+            // close() left two listeners registered on the far side (e.g. two
+            // NOTIFY deliveries after Pool's reconnect re-subscribed twice).
             this.socket.once('close', resolve);
             this.socket.sendTerminateMessage(() => {
                 this.socket.close();
-                this.emit('close');
             });
         });
     }
     async execute(sql, options, cb) {
         this.assertConnected();
-        return this.statementQueue
-            .enqueue(async () => {
-            const transactionCommand = sql.match(/^(\bBEGIN\b|\bCOMMIT\b|\bSTART\b|\bROLLBACK|SAVEPOINT|RELEASE\b)/i);
-            let beginFirst = false;
-            let commitLast = false;
-            if (!transactionCommand) {
-                if (!this.inTransaction &&
-                    (options?.autoCommit != null
-                        ? options?.autoCommit
-                        : this.config.autoCommit) === false) {
-                    beginFirst = true;
-                }
-                if (this.inTransaction && options?.autoCommit)
-                    commitLast = true;
+        const transactionCommand = sql.match(/^(\bBEGIN\b|\bCOMMIT\b|\bSTART\b|\bROLLBACK|SAVEPOINT|RELEASE\b)/i);
+        let beginFirst = false;
+        let commitLast = false;
+        if (!transactionCommand) {
+            if (!this.inTransaction &&
+                (options?.autoCommit != null
+                    ? options?.autoCommit
+                    : this.config.autoCommit) === false) {
+                beginFirst = true;
             }
-            if (beginFirst)
-                await this._execute('BEGIN');
-            const rollbackOnError = !transactionCommand &&
-                (options?.rollbackOnError != null
-                    ? options.rollbackOnError
-                    : coerceToBoolean(this.config.rollbackOnError, true));
-            if (this.inTransaction && rollbackOnError)
-                await this._execute('SAVEPOINT ' + this._onErrorSavePoint);
-            try {
-                const result = await this._execute(sql, options, cb);
-                if (commitLast)
-                    await this._execute('COMMIT');
-                else if (this.inTransaction && rollbackOnError) {
-                    await this._execute('RELEASE ' + this._onErrorSavePoint + ';');
-                }
-                return result;
-            }
-            catch (e) {
-                if (this.inTransaction && rollbackOnError)
-                    await this._execute('ROLLBACK TO ' + this._onErrorSavePoint + ';');
-                throw e;
+            if (this.inTransaction && options?.autoCommit)
+                commitLast = true;
+        }
+        if (beginFirst)
+            await this._execute('BEGIN');
+        const rollbackOnError = !transactionCommand &&
+            (options?.rollbackOnError != null
+                ? options.rollbackOnError
+                : coerceToBoolean(this.config.rollbackOnError, true));
+        if (this.inTransaction && rollbackOnError)
+            await this._execute('SAVEPOINT ' + this._onErrorSavePoint);
+        try {
+            const result = await this._execute(sql, options, cb);
+            if (commitLast)
+                await this._execute('COMMIT');
+            else if (this.inTransaction && rollbackOnError) {
+                await this._execute('RELEASE ' + this._onErrorSavePoint + ';');
             }
-        })
-            .toPromise();
+            return result;
+        }
+        catch (e) {
+            if (this.inTransaction && rollbackOnError)
+                await this._execute('ROLLBACK TO ' + this._onErrorSavePoint + ';');
+            throw e;
+        }
     }
     async startTransaction() {
         if (!this.inTransaction)
@@ -146,6 +164,31 @@ export class IntlConnection extends SafeEventEmitter {
         if (this.inTransaction)
             await this.execute('ROLLBACK');
     }
+    /**
+     * 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.
+     */
+    async prepareTransaction(name) {
+        await this._execute('PREPARE TRANSACTION ' + escapeLiteral(name));
+    }
+    /** Commits a transaction left waiting by prepareTransaction(). */
+    async commitPrepared(name) {
+        await this._execute('COMMIT PREPARED ' + escapeLiteral(name));
+    }
+    /** Discards a transaction left waiting by prepareTransaction(). */
+    async rollbackPrepared(name) {
+        await this._execute('ROLLBACK PREPARED ' + escapeLiteral(name));
+    }
     async rollbackToSavepoint(name) {
         if (!(name && name.match(/^[a-zA-Z]\w+$/)))
             throw new Error(`Invalid savepoint "${name}"`);
@@ -156,11 +199,17 @@ export class IntlConnection extends SafeEventEmitter {
             throw new Error(`Invalid savepoint "${name}"`);
         await this.execute('RELEASE SAVEPOINT ' + name, { autoCommit: false });
     }
+    /** Asks the server to cancel whatever this session is running. */
+    cancel() {
+        return this.socket.cancel();
+    }
     ref() {
         this._refCount++;
     }
     unref() {
         this._refCount--;
+        if (!this._refCount)
+            this.emit('idle');
         return !this._refCount;
     }
     assertConnected() {
@@ -169,27 +218,79 @@ export class IntlConnection extends SafeEventEmitter {
         if (this.state === ConnectionState.CLOSED)
             throw new Error('Connection closed');
     }
+    /**
+     * 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.
+     */
+    async copyTo(sql) {
+        this.assertConnected();
+        this.ref();
+        this.runningQueryCount++;
+        const stream = new CopyToStream(this.socket);
+        this.socket
+            .sendQueryMessage(sql, stream.capture)
+            .catch(err => stream.fail(err))
+            .finally(() => {
+            this.runningQueryCount--;
+            this.unref();
+        });
+        await stream.waitStarted();
+        return stream;
+    }
+    /**
+     * Runs a COPY ... FROM STDIN and hands back a stream to feed it.
+     * Resolves once the server is ready for data.
+     */
+    async copyFrom(sql) {
+        this.assertConnected();
+        this.ref();
+        this.runningQueryCount++;
+        const stream = new CopyFromStream(this.socket);
+        this.socket
+            .sendQueryMessage(sql, stream.capture)
+            .catch(err => stream.fail(err))
+            .finally(() => {
+            this.runningQueryCount--;
+            this.unref();
+        });
+        await stream.waitStarted();
+        return stream;
+    }
     async _execute(sql, options, cb) {
         this.ref();
         try {
-            const startTime = Date.now();
+            const startTime = performance.now();
             const result = {
                 totalCommands: 0,
                 totalTime: 0,
                 results: [],
             };
             const opts = options || {};
-            this.socket.sendQueryMessage(sql);
-            let currentStart = Date.now();
+            let currentStart = startTime;
             let parsers;
             let current = { command: undefined };
             let fields;
+            let error;
             const typeMap = opts.typeMap || GlobalTypeMap;
-            return await this.socket.capture(async (code, msg, done) => {
+            this.runningQueryCount++;
+            return await this.socket.sendQueryMessage(sql, (code, msg, done) => {
                 switch (code) {
-                    case Protocol.BackendMessageCode.NoticeResponse:
+                    case Protocol.BackendMessageCode.ErrorResponse:
+                        error = msg;
+                        break;
                     case Protocol.BackendMessageCode.CopyInResponse:
+                        error =
+                            error ||
+                                new Error('COPY FROM STDIN is not supported by execute() - use copyFrom() instead');
+                        this.socket.sendCopyFail(error.message);
+                        break;
                     case Protocol.BackendMessageCode.CopyOutResponse:
+                        error =
+                            error ||
+                                new Error('COPY TO STDOUT is not supported by execute() - use copyTo() instead');
+                        break;
+                    case Protocol.BackendMessageCode.NoticeResponse:
                     case Protocol.BackendMessageCode.EmptyQueryResponse:
                         break;
                     case Protocol.BackendMessageCode.RowDescription:
@@ -200,11 +301,9 @@ export class IntlConnection extends SafeEventEmitter {
                         break;
                     case Protocol.BackendMessageCode.DataRow:
                         {
-                            let row = msg.columns.map((x) => x.toString('utf8'));
-                            // The null override assumes we can trust PG to always send the RowDescription first
-                            parseRow(parsers, row, opts);
-                            if (opts.objectRows && current.fields)
-                                row = convertRowToObject(current.fields, row);
+                            const row = opts.objectRows && current.fields
+                                ? parseObjectRow(parsers, msg.data, msg.columnCount, opts, current.fields)
+                                : parseRow(parsers, msg.data, msg.columnCount, opts);
                             if (cb)
                                 cb('row', row);
                             current.rows = current.rows || [];
@@ -219,7 +318,7 @@ export class IntlConnection extends SafeEventEmitter {
                             current.command === 'UPDATE') {
                             current.rowsAffected = msg.rowCount;
                         }
-                        current.executeTime = Date.now() - currentStart;
+                        current.executeTime = performance.now() - currentStart;
                         if (current.rows)
                             current.rowType =
                                 opts.objectRows && current.fields ? 'object' : 'array';
@@ -227,11 +326,15 @@ export class IntlConnection extends SafeEventEmitter {
                         if (cb)
                             cb('command-complete', current);
                         current = { command: undefined };
-                        currentStart = Date.now();
+                        currentStart = performance.now();
                         break;
                     case Protocol.BackendMessageCode.ReadyForQuery:
                         this.transactionStatus = msg.status;
-                        result.totalTime = Date.now() - startTime;
+                        if (error) {
+                            done(error);
+                            break;
+                        }
+                        result.totalTime = performance.now() - startTime;
                         // Ignore COMMIT command that we added to sql
                         result.totalCommands = result.results.length;
                         done(undefined, result);
@@ -241,10 +344,264 @@ export class IntlConnection extends SafeEventEmitter {
                 }
             });
         }
+        finally {
+            this.runningQueryCount--;
+            this.unref();
+        }
+    }
+    /**
+     * 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).
+     */
+    async queryOnce(sql, paramTypes, params, options) {
+        this.assertConnected();
+        this.ref();
+        try {
+            const typeMap = options.typeMap || GlobalTypeMap;
+            const startTime = performance.now();
+            const result = { command: undefined };
+            const rows = [];
+            let parsers;
+            let resultFields;
+            let commandTag;
+            let error;
+            this.runningQueryCount++;
+            await this.socket
+                .sendExtendedQueryMessages({
+                parse: { sql, paramTypes },
+                bind: { typeMap, paramTypes, params, queryOptions: options },
+                describe: { type: 'P' },
+                execute: { fetchCount: options.fetchCount || 100 },
+            }, (code, msg, done) => {
+                switch (code) {
+                    case Protocol.BackendMessageCode.ParseComplete:
+                    case Protocol.BackendMessageCode.BindComplete:
+                    case Protocol.BackendMessageCode.NoData:
+                    case Protocol.BackendMessageCode.NoticeResponse:
+                    case Protocol.BackendMessageCode.PortalSuspended:
+                        break;
+                    case Protocol.BackendMessageCode.RowDescription:
+                        parsers = getParsers(typeMap, msg.fields);
+                        resultFields = wrapRowDescription(typeMap, msg.fields, options.columnFormat || DEFAULT_COLUMN_FORMAT);
+                        result.fields = resultFields;
+                        result.rowType = options.objectRows ? 'object' : 'array';
+                        break;
+                    case Protocol.BackendMessageCode.DataRow:
+                        rows.push(msg);
+                        break;
+                    case Protocol.BackendMessageCode.CommandComplete:
+                        commandTag = msg;
+                        break;
+                    case Protocol.BackendMessageCode.ErrorResponse:
+                        error = msg;
+                        break;
+                    case Protocol.BackendMessageCode.ReadyForQuery:
+                        this.transactionStatus = msg.status;
+                        done(error);
+                        break;
+                    default:
+                        done(new Error(`Server returned unexpected response message (${String.fromCharCode(code)})`));
+                }
+            })
+                .finally(() => {
+                this.runningQueryCount--;
+            });
+            if (commandTag?.command)
+                result.command = commandTag.command;
+            if (resultFields && parsers) {
+                if (!result.command)
+                    result.command = 'SELECT';
+                result.rows = rows;
+                const l = rows.length;
+                let i;
+                for (i = 0; i < l; i++) {
+                    rows[i] = options.objectRows
+                        ? parseObjectRow(parsers, rows[i].data, rows[i].columnCount, options, resultFields)
+                        : parseRow(parsers, rows[i].data, rows[i].columnCount, options);
+                }
+            }
+            if (result.command === 'DELETE' ||
+                result.command === 'INSERT' ||
+                result.command === 'UPDATE') {
+                result.rowsAffected = commandTag?.rowCount;
+            }
+            result.executeTime = performance.now() - startTime;
+            return result;
+        }
+        finally {
+            this.unref();
+        }
+    }
+    /**
+     * 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.
+     */
+    async prepareOnce(sql, paramTypes, statementName) {
+        this.assertConnected();
+        this.ref();
+        try {
+            let fields;
+            let error;
+            this.runningQueryCount++;
+            await this.socket
+                .sendPrepareMessages({
+                parse: { statement: statementName, sql, paramTypes },
+                describe: { type: 'S', name: statementName },
+            }, (code, msg, done) => {
+                switch (code) {
+                    case Protocol.BackendMessageCode.ParseComplete:
+                    case Protocol.BackendMessageCode.ParameterDescription:
+                    case Protocol.BackendMessageCode.NoData:
+                    case Protocol.BackendMessageCode.NoticeResponse:
+                        break;
+                    case Protocol.BackendMessageCode.RowDescription:
+                        fields = msg.fields;
+                        break;
+                    case Protocol.BackendMessageCode.ErrorResponse:
+                        // See queryOnce()'s ErrorResponse case for why done() must
+                        // not be called here.
+                        error = msg;
+                        break;
+                    case Protocol.BackendMessageCode.ReadyForQuery:
+                        this.transactionStatus = msg.status;
+                        done(error);
+                        break;
+                    default:
+                        done(new Error(`Server returned unexpected response message (${String.fromCharCode(code)})`));
+                }
+            })
+                .finally(() => {
+                this.runningQueryCount--;
+            });
+            return { fields };
+        }
         finally {
             this.unref();
         }
     }
+    /**
+     * 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.
+     */
+    async executeReused(statementName, cachedFields, paramTypes, params, options) {
+        this.assertConnected();
+        this.ref();
+        try {
+            const typeMap = options.typeMap || GlobalTypeMap;
+            const startTime = performance.now();
+            const result = { command: undefined };
+            const rows = [];
+            let parsers;
+            let resultFields;
+            let commandTag;
+            let error;
+            if (cachedFields) {
+                const columnFormat = options.columnFormat != null
+                    ? options.columnFormat
+                    : DEFAULT_COLUMN_FORMAT;
+                const cached = this._executeReusedParserCache.get(cachedFields);
+                if (cached &&
+                    cached.typeMap === typeMap &&
+                    columnFormatsEqual(cached.columnFormat, columnFormat)) {
+                    parsers = cached.parsers;
+                    resultFields = cached.resultFields;
+                }
+                else {
+                    const fields = cachedFields.map((f, i) => ({
+                        ...f,
+                        format: Array.isArray(columnFormat)
+                            ? columnFormat[i]
+                            : columnFormat,
+                    }));
+                    parsers = getParsers(typeMap, fields);
+                    resultFields = wrapRowDescription(typeMap, fields, columnFormat);
+                    this._executeReusedParserCache.set(cachedFields, {
+                        typeMap,
+                        columnFormat,
+                        parsers,
+                        resultFields,
+                    });
+                }
+                result.fields = resultFields;
+                result.rowType = options.objectRows ? 'object' : 'array';
+            }
+            this.runningQueryCount++;
+            await this.socket
+                .sendBindExecuteMessages({
+                bind: {
+                    typeMap,
+                    statement: statementName,
+                    paramTypes,
+                    params,
+                    queryOptions: options,
+                },
+                execute: { fetchCount: options.fetchCount || 100 },
+            }, (code, msg, done) => {
+                switch (code) {
+                    case Protocol.BackendMessageCode.BindComplete:
+                    case Protocol.BackendMessageCode.NoticeResponse:
+                    case Protocol.BackendMessageCode.PortalSuspended:
+                        break;
+                    case Protocol.BackendMessageCode.DataRow:
+                        rows.push(msg);
+                        break;
+                    case Protocol.BackendMessageCode.CommandComplete:
+                        commandTag = msg;
+                        break;
+                    case Protocol.BackendMessageCode.ErrorResponse:
+                        error = msg;
+                        break;
+                    case Protocol.BackendMessageCode.ReadyForQuery:
+                        this.transactionStatus = msg.status;
+                        done(error);
+                        break;
+                    default:
+                        done(new Error(`Server returned unexpected response message (${String.fromCharCode(code)})`));
+                }
+            })
+                .finally(() => {
+                this.runningQueryCount--;
+            });
+            if (commandTag?.command)
+                result.command = commandTag.command;
+            if (resultFields && parsers) {
+                if (!result.command)
+                    result.command = 'SELECT';
+                result.rows = rows;
+                const l = rows.length;
+                let i;
+                for (i = 0; i < l; i++) {
+                    rows[i] = options.objectRows
+                        ? parseObjectRow(parsers, rows[i].data, rows[i].columnCount, options, resultFields)
+                        : parseRow(parsers, rows[i].data, rows[i].columnCount, options);
+                }
+            }
+            if (result.command === 'DELETE' ||
+                result.command === 'INSERT' ||
+                result.command === 'UPDATE') {
+                result.rowsAffected = commandTag?.rowCount;
+            }
+            result.executeTime = performance.now() - startTime;
+            return result;
+        }
+        finally {
+            this.unref();
+        }
+    }
+    emit(event, ...args) {
+        const handled = super.emit(event, ...args);
+        return this.owner ? this.owner.emit(event, ...args) || handled : handled;
+    }
     _onError(err) {
         if (this.socket.state !== ConnectionState.READY)
             return;

package/connection/large-object.d.ts

@@ -0,0 +1,65 @@
+import { Readable, Writable } from 'node:stream';
+import type { Connection } from './connection.js';
+/** Open modes, as PostgreSQL's own INV_READ / INV_WRITE constants. */
+export declare const LargeObjectMode: {
+    readonly read: 262144;
+    readonly write: 131072;
+    readonly readWrite: 393216;
+};
+export interface LargeObjectStreamOptions {
+    /**
+     * Bytes per round trip (default 65536). Each chunk is its own `loread`
+     * or `lowrite` call, so this trades memory against the number of
+     * queries.
+     */
+    chunkSize?: number;
+}
+/**
+ * A PostgreSQL large object: binary data stored outside the row it belongs
+ * to and reached through a file-like interface, so it can be seeked into
+ * and read a piece at a time rather than loaded whole the way a `bytea`
+ * column must be. Up to 4TB, against roughly 1GB for `bytea`.
+ *
+ * ```ts
+ * const lo = await connection.createLargeObject();
+ * await pipeline(fs.createReadStream('video.mp4'), lo.writable());
+ * await lo.close();
+ * // keep lo.oid somewhere - a large object belongs to no row
+ * ```
+ *
+ * The descriptor a large object is opened with only lives as long as the
+ * transaction that opened it, so one is started if the connection is not
+ * already in one, and close() commits that one - but never a transaction
+ * the caller started, which stays theirs to finish.
+ */
+export declare class LargeObject {
+    readonly oid: number;
+    protected readonly _connection: Connection;
+    protected readonly _fd: number;
+    /** True when this object opened the transaction and so should commit it. */
+    protected readonly _ownsTransaction: boolean;
+    protected _closed: boolean;
+    constructor(connection: Connection, oid: number, fd: number, ownsTransaction: boolean);
+    /** Reads at most `length` bytes from the current position. */
+    read(length: number): Promise<Buffer>;
+    /** Writes at the current position and returns how many bytes went in. */
+    write(data: Buffer): Promise<number>;
+    /** Moves the read/write position. `whence`: 0 start, 1 current, 2 end. */
+    seek(offset: number | bigint, whence?: number): Promise<bigint>;
+    /** The current read/write position. */
+    tell(): Promise<bigint>;
+    /** Total size in bytes; leaves the position where it found it. */
+    size(): Promise<bigint>;
+    /** Cuts the object down to `length` bytes. */
+    truncate(length: number | bigint): Promise<void>;
+    /** Reads from the current position to the end. */
+    readable(options?: LargeObjectStreamOptions): Readable;
+    /** Writes from the current position onwards. */
+    writable(options?: LargeObjectStreamOptions): Writable;
+    /**
+     * Closes the descriptor, and commits the transaction if this object
+     * started it. Safe to call twice.
+     */
+    close(): Promise<void>;
+    protected _assertOpen(): void;
+}