postgrejs 3.7.0 → 3.9.0

package/connection/pool.d.ts

@@ -5,16 +5,21 @@ 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 type { StatementPrepareOptions } from '../interfaces/statement-prepare-options.js';
+import type { TransactionOptions } from '../interfaces/transaction-options.js';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
 import { QueryRequest } from '../util/sql-tag.js';
 import { Connection, type NotificationCallback } from './connection.js';
 import { IntlConnection } from './intl-connection.js';
 import type { PreparedStatement } from './prepared-statement.js';
-export interface PoolPipelineOptions {
-    pipeline?: boolean;
-}
-export type PoolQueryOptions = QueryOptions & PoolPipelineOptions;
-export type PoolScriptExecuteOptions = ScriptExecuteOptions & PoolPipelineOptions;
+/**
+ * @deprecated `pipeline` is part of `QueryOptions` and
+ * `ScriptExecuteOptions` now, so every connection takes it too. Kept as
+ * an alias of that one field so the exported type still means what it
+ * did.
+ */
+export type PoolPipelineOptions = Pick<QueryOptions, 'pipeline'>;
+export type PoolQueryOptions = QueryOptions;
+export type PoolScriptExecuteOptions = ScriptExecuteOptions;
 /**
  * One pooled connection the pipelined path is currently borrowing.
  *
@@ -93,7 +98,7 @@ export declare class Pool extends SafeEventEmitter {
      * is free to pick a different connection, and a transaction lives on
      * one. This is the way to get several statements onto the same one.
      */
-    transaction<T>(fn: (connection: Connection) => Promise<T>): Promise<T>;
+    transaction<T>(fn: (connection: Connection) => Promise<T>, options?: TransactionOptions): Promise<T>;
     prepare(sql: string, options?: StatementPrepareOptions): Promise<PreparedStatement>;
     release(connection: Connection): Promise<void>;
     listen(channel: string, callback: NotificationCallback): Promise<void>;
@@ -113,6 +118,25 @@ export declare class Pool extends SafeEventEmitter {
      * the connection had no query in flight to reject.
      */
     protected _onConnectionDestroyed(intlCon: IntlConnection): void;
+    /**
+     * Whether a one-shot query may share a pooled connection with the
+     * queries already in flight on it.
+     *
+     * **Opt-in**, per call or with `pipeline: true` on the pool. It is
+     * worth asking for - `max` stops being a ceiling on concurrent
+     * queries and becomes one on connections, and a burst of 500 through
+     * a pool of 10 measured 12ms against 29ms - but it is not the default,
+     * because it moves the query onto a connection other callers are
+     * using and session state there stops being the caller's own.
+     *
+     * The exclusions below are not policy, they are statements that need a
+     * connection to themselves for longer than the call takes to resolve:
+     * a cursor reads from a portal afterwards, a transaction spans later
+     * statements, a COPY holds the connection mid-stream, `autoCommit:
+     * false` says a transaction is being managed by hand, and an
+     * `AbortSignal` cancels by tearing down whatever the connection is
+     * doing - which, shared, is not only this query.
+     */
     protected _canPipeline(pipeline: boolean | undefined, sql: string, autoCommit: boolean | undefined, signal: AbortSignal | undefined): boolean;
     /**
      * Picks the pooled connection a pipelined query should ride on, or

package/connection/pool.js

@@ -157,6 +157,12 @@ export class Pool extends SafeEventEmitter {
             connection.on('execute', (...args) => this.emit('execute', ...args));
         if (this.listenerCount('query'))
             connection.on('query', (...args) => this.emit('query', ...args));
+        // Forwarded with the connection that raised it, the way 'destroy'
+        // names its own subject: a caller using pool.query() never sees the
+        // Connection, so without this a notice raised by their statement has
+        // nowhere to go at all.
+        if (this.listenerCount('notice'))
+            connection.on('notice', msg => this.emit('notice', msg, connection));
         return connection;
     }
     /**
@@ -266,10 +272,10 @@ export class Pool extends SafeEventEmitter {
      * is free to pick a different connection, and a transaction lives on
      * one. This is the way to get several statements onto the same one.
      */
-    async transaction(fn) {
+    async transaction(fn, options) {
         const connection = await this.acquire();
         try {
-            return await connection.transaction(fn);
+            return await connection.transaction(fn, options);
         }
         finally {
             await this.release(connection);
@@ -355,8 +361,27 @@ export class Pool extends SafeEventEmitter {
         // connection that could not be created stays unambiguous.
         this.emit('error', reason);
     }
+    /**
+     * Whether a one-shot query may share a pooled connection with the
+     * queries already in flight on it.
+     *
+     * **Opt-in**, per call or with `pipeline: true` on the pool. It is
+     * worth asking for - `max` stops being a ceiling on concurrent
+     * queries and becomes one on connections, and a burst of 500 through
+     * a pool of 10 measured 12ms against 29ms - but it is not the default,
+     * because it moves the query onto a connection other callers are
+     * using and session state there stops being the caller's own.
+     *
+     * The exclusions below are not policy, they are statements that need a
+     * connection to themselves for longer than the call takes to resolve:
+     * a cursor reads from a portal afterwards, a transaction spans later
+     * statements, a COPY holds the connection mid-stream, `autoCommit:
+     * false` says a transaction is being managed by hand, and an
+     * `AbortSignal` cancels by tearing down whatever the connection is
+     * doing - which, shared, is not only this query.
+     */
     _canPipeline(pipeline, sql, autoCommit, signal) {
-        return (pipeline === true &&
+        return ((pipeline != null ? pipeline : this.config.pipeline === true) &&
             !signal &&
             this._pipelineMaxQueries > 1 &&
             this._pipelineMaxConnections > 0 &&

package/connection/prepared-statement.d.ts

@@ -68,6 +68,17 @@ export declare class PreparedStatement extends SafeEventEmitter implements Async
      *   takes, minus `fetchCount` and `cursor`, which a batch cannot honour.
      */
     executeBatch(paramSets: any[][], options?: QueryOptions): Promise<BatchResult>;
+    /**
+     * A notice reaches both this statement and the connection it ran on.
+     *
+     * These are the three loops the statement keeps for its own close and
+     * cancel traffic; an `execute()` runs through the connection's loop
+     * instead and is forwarded there. Without this second hop a notice
+     * arriving on one of these three would be the only kind a caller
+     * holding a `Connection` never saw. Hard to provoke - `DEALLOCATE`
+     * does not normally raise one - which is why there is no test for it.
+     */
+    protected _emitNotice(msg: any): void;
     protected _executeBatchWithTransaction(paramSets: any[][], options: QueryOptions): Promise<BatchResult>;
     protected _executeWithTransaction(options?: QueryOptions): Promise<QueryResult>;
     /**

package/connection/prepared-statement.js

@@ -1,3 +1,4 @@
+import { DataTypeOIDs } from '../constants.js';
 import { GlobalTypeMap } from '../data-type-map.js';
 import { Protocol } from '../protocol/protocol.js';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
@@ -5,6 +6,7 @@ import { withAbortSignal } from '../util/abort-signal.js';
 import { getParsers } from '../util/get-parsers.js';
 import { resolveColumnFormats } from '../util/resolve-column-formats.js';
 import { resolveRowType } from '../util/row-decoder.js';
+import { isTransactionCommand, refusesSavepoint, } from '../util/transaction-command.js';
 import { wrapRowDescription } from '../util/wrap-row-description.js';
 import { Cursor } from './cursor.js';
 import { getIntlConnection } from './intl-connection.js';
@@ -51,6 +53,9 @@ export class PreparedStatement extends SafeEventEmitter {
     }
     async execute(options = {}) {
         const intlCon = getIntlConnection(this.connection);
+        // Folded in here rather than deeper: a cursor keeps these options
+        // and decodes its own rows with them long after this call is over.
+        options = intlCon.withDefaults(options);
         if (options.signal)
             return withAbortSignal(options.signal, () => intlCon.cancel(), () => this._executeWithTransaction(options));
         return this._executeWithTransaction(options);
@@ -108,12 +113,27 @@ export class PreparedStatement extends SafeEventEmitter {
             throw new Error('executeBatch() cannot return a cursor - a batch runs every set to ' +
                 'completion under one Sync, so there is no portal left to fetch from');
         const intlCon = getIntlConnection(this.connection);
+        options = intlCon.withDefaults(options);
         if (!paramSets.length)
             return { results: [], totalRowsAffected: 0 };
         if (options.signal)
             return withAbortSignal(options.signal, () => intlCon.cancel(), () => this._executeBatchWithTransaction(paramSets, options));
         return this._executeBatchWithTransaction(paramSets, options);
     }
+    /**
+     * A notice reaches both this statement and the connection it ran on.
+     *
+     * These are the three loops the statement keeps for its own close and
+     * cancel traffic; an `execute()` runs through the connection's loop
+     * instead and is forwarded there. Without this second hop a notice
+     * arriving on one of these three would be the only kind a caller
+     * holding a `Connection` never saw. Hard to provoke - `DEALLOCATE`
+     * does not normally raise one - which is why there is no test for it.
+     */
+    _emitNotice(msg) {
+        this.emit('notice', msg);
+        getIntlConnection(this.connection).emit('notice', msg);
+    }
     _executeBatchWithTransaction(paramSets, options) {
         const intlCon = getIntlConnection(this.connection);
         return this._withTransaction(options, () => intlCon.executeBatchReused(this.name, this._fields, this.paramTypes, paramSets, options));
@@ -139,7 +159,17 @@ export class PreparedStatement extends SafeEventEmitter {
      */
     async _withTransaction(options = {}, fn, canInlineSavepoint = false) {
         const intlCon = getIntlConnection(this.connection);
-        const transactionCommand = this.sql.match(/^(\bBEGIN\b|\bCOMMIT\b|\bSTART\b|\bROLLBACK|SAVEPOINT|RELEASE\b)/i);
+        // See Connection._query(): a money parameter is written as an int64
+        // of minor units, so the server's scale has to be known before the
+        // Bind goes out.
+        if (this.paramTypes?.includes(DataTypeOIDs.money) ||
+            this.paramTypes?.includes(DataTypeOIDs._money) ||
+            // And before any of this statement's own money columns are read:
+            // a cursor and a batch both decode inside the message loop, where
+            // there is no longer anywhere to ask from.
+            intlCon.needsMoneyFormat(this._fields, options))
+            await intlCon.ensureMoneyFormat();
+        const transactionCommand = isTransactionCommand(this.sql);
         let beginFirst = false;
         let commitLast = false;
         const autoCommit = options?.autoCommit;
@@ -156,7 +186,11 @@ export class PreparedStatement extends SafeEventEmitter {
             await intlCon.execute('BEGIN');
         // See IntlConnection.execute()'s own rollbackOnError for why
         // intlCon.inTransaction goes first here but last in the checks below.
-        const rollbackOnError = !transactionCommand &&
+        const rollbackOnError = 
+        // See IntlConnection.execute(): `SET TRANSACTION` keeps the
+        // implicit BEGIN and loses only the savepoint, which PostgreSQL
+        // refuses to let it run inside.
+        !refusesSavepoint(this.sql) &&
             intlCon.inTransaction &&
             (options?.rollbackOnError ?? intlCon.config.rollbackOnError ?? true);
         // When `fn` can put the savepoint on the wire itself, SAVEPOINT and
@@ -268,7 +302,7 @@ export class PreparedStatement extends SafeEventEmitter {
             }, (code, msg, done) => {
                 switch (code) {
                     case Protocol.BackendMessageCode.NoticeResponse:
-                        this.emit('notice', msg);
+                        this._emitNotice(msg);
                         break;
                     case Protocol.BackendMessageCode.CloseComplete:
                         // Arrives twice (once per Close) - neither call is terminal.
@@ -299,7 +333,7 @@ export class PreparedStatement extends SafeEventEmitter {
             const closePromise = socket.sendCloseMessage({ type: 'S', name: this.name }, (code, msg, done) => {
                 switch (code) {
                     case Protocol.BackendMessageCode.NoticeResponse:
-                        this.emit('notice', msg);
+                        this._emitNotice(msg);
                         break;
                     case Protocol.BackendMessageCode.CloseComplete:
                         done();
@@ -314,7 +348,7 @@ export class PreparedStatement extends SafeEventEmitter {
             const syncPromise = socket.sendSyncMessage((code, msg, done) => {
                 switch (code) {
                     case Protocol.BackendMessageCode.NoticeResponse:
-                        this.emit('notice', msg);
+                        this._emitNotice(msg);
                         break;
                     case Protocol.BackendMessageCode.ReadyForQuery:
                         intoCon.transactionStatus = msg.status;

package/data-type-map.d.ts

@@ -1,6 +1,8 @@
 import type { DataType } from './interfaces/data-type.js';
 import type { OID } from './types.js';
 export declare class DataTypeMap {
+    protected _inferScalars: DataType[];
+    protected _inferArrays: DataType[];
     private _itemsByOID;
     private _items;
     /**
@@ -17,6 +19,20 @@ export declare class DataTypeMap {
     constructor(other?: DataTypeMap);
     get(oid: OID): DataType;
     register(dataTypes: DataType | DataType[]): void;
+    /**
+     * The two lists determine() actually walks, newest-registered first.
+     *
+     * A value is either an array or it is not, so half of `_items` can
+     * never match it - and the half that can is the smaller one: of 127
+     * registered types, a plain number used to be tested against 22 and
+     * skipped past 105. Rebuilt on registration, which happens at startup
+     * and hardly ever again, so the walk itself reads a list that is
+     * already only what it needs.
+     *
+     * A type that is not inferrable is left out of both: determine() may
+     * never pick it, however well its isType matches.
+     */
+    protected _rebuildInferenceLists(): void;
     determine(value: any): OID;
 }
 export declare const GlobalTypeMap: DataTypeMap;

package/data-type-map.js

@@ -21,6 +21,7 @@ import { ArrayJsonPathType, JsonPathType } from './data-types/jsonpath-type.js';
 import { ArrayLineType, LineType } from './data-types/line-type.js';
 import { ArrayLsegType, LsegType } from './data-types/lseg-type.js';
 import { ArrayMacaddr8Type, ArrayMacaddrType, Macaddr8Type, MacaddrType, } from './data-types/macaddr-type.js';
+import { ArrayMoneyType, MoneyType } from './data-types/money-type.js';
 import { ArrayNumericType, NumericType } from './data-types/numeric-type.js';
 import { ArrayOidType, OidType } from './data-types/oid-type.js';
 import { ArrayOidVectorType, OidVectorType, } from './data-types/oid-vector-type.js';
@@ -38,7 +39,10 @@ import { ArrayTsQueryType, ArrayTsVectorType, TsQueryType, TsVectorType, } from
 import { ArrayUuidType, UuidType } from './data-types/uuid-type.js';
 import { ArrayVarcharType, VarcharType } from './data-types/varchar-type.js';
 import { ArrayCidType, ArrayXid8Type, ArrayXidType, CidType, Xid8Type, XidType, } from './data-types/xid-type.js';
+import { arrayLeaf } from './util/array-leaf.js';
 export class DataTypeMap {
+    _inferScalars = [];
+    _inferArrays = [];
     _itemsByOID = {};
     _items = [];
     /**
@@ -56,6 +60,11 @@ export class DataTypeMap {
         if (other instanceof DataTypeMap) {
             this._items = [...other._items];
             this._itemsByOID = { ...other._itemsByOID };
+            // Shared, not copied: they are rebuilt wholesale by register(),
+            // so a copy that registers nothing never diverges and one that
+            // does gets its own pair then.
+            this._inferScalars = other._inferScalars;
+            this._inferArrays = other._inferArrays;
         }
     }
     get(oid) {
@@ -71,6 +80,37 @@ export class DataTypeMap {
             else
                 this._items.push(t);
         }
+        this._rebuildInferenceLists();
+    }
+    /**
+     * The two lists determine() actually walks, newest-registered first.
+     *
+     * A value is either an array or it is not, so half of `_items` can
+     * never match it - and the half that can is the smaller one: of 127
+     * registered types, a plain number used to be tested against 22 and
+     * skipped past 105. Rebuilt on registration, which happens at startup
+     * and hardly ever again, so the walk itself reads a list that is
+     * already only what it needs.
+     *
+     * A type that is not inferrable is left out of both: determine() may
+     * never pick it, however well its isType matches.
+     */
+    _rebuildInferenceLists() {
+        const scalars = [];
+        const arrays = [];
+        let i;
+        let t;
+        // Built back to front, so index 0 is the newest registration and the
+        // walk runs forward - which is the direction a JS array is fastest
+        // to read and the one that needs no length arithmetic per step.
+        for (i = this._items.length - 1; i >= 0; i--) {
+            t = this._items[i];
+            if (t.inferrable === false)
+                continue;
+            (t.elementsOID ? arrays : scalars).push(t);
+        }
+        this._inferScalars = scalars;
+        this._inferArrays = arrays;
     }
     determine(value) {
         if (value == null)
@@ -94,21 +134,22 @@ export class DataTypeMap {
                     'it at the call site (`new BindParam(oid, value)`)');
             }
         }
+        // An array is typed from the first value inside it that is actually
+        // a value: `value[0]` answers `_int2vector` for [[1, 2], [3, 4]],
+        // because the first element is itself an array and a vector is the
+        // one registered type an array of numbers matches, and answers
+        // nothing at all for [null, 2, 3].
         const valueIsArray = Array.isArray(value);
+        const candidates = valueIsArray ? this._inferArrays : this._inferScalars;
+        const v = valueIsArray ? arrayLeaf(value) : value;
+        // Newest-registered first, so a later registration of the same OID
+        // wins - see _rebuildInferenceLists() for how the order is kept.
+        const l = candidates.length;
         let i;
         let t;
-        for (i = this._items.length - 1; i >= 0; i--) {
-            t = this._items[i];
-            // Walked newest-registered first, so a later registration of the
-            // same OID wins - and a type marked `inferrable: false` is never
-            // picked here at all, however well `isType` matches.
-            if (t.inferrable === false)
-                continue;
-            if (valueIsArray) {
-                if (t.elementsOID && t.isType(value[0]))
-                    return t.oid;
-            }
-            else if (!t.elementsOID && t.isType(value))
+        for (i = 0; i < l; i++) {
+            t = candidates[i];
+            if (t.isType(v))
                 return t.oid;
         }
         return DataTypeOIDs.unknown;
@@ -121,6 +162,9 @@ GlobalTypeMap.register([JsonbType, ArrayJsonbType]);
 GlobalTypeMap.register([JsonType, ArrayJsonType]);
 GlobalTypeMap.register([BoolType, ArrayBoolType]);
 GlobalTypeMap.register([NumericType, ArrayNumericType]);
+// Registered after numeric and not inferrable: a JavaScript number is
+// never money by shape, and the type is reached by naming it.
+GlobalTypeMap.register([MoneyType, ArrayMoneyType]);
 GlobalTypeMap.register([Float4Type, ArrayFloat4Type]);
 GlobalTypeMap.register([Float8Type, ArrayFloat8Type]);
 GlobalTypeMap.register([Int2Type, ArrayInt2Type]);

package/data-types/classes/numeric.d.ts

@@ -9,10 +9,14 @@
  * to a plain number; this class is what the rest become, and it carries
  * the digits exactly as the server wrote them.
  *
- * It is a class rather than a bare string so that it can be told apart:
- * `determine()` types a bare string as `varchar`, which the server then
- * refuses to put in a numeric column, so a string could be read but not
- * written back. A `Numeric` round-trips.
+ * It is a class rather than a bare string so that the value keeps
+ * saying what it is. A bare string parameter does reach a numeric
+ * column - it goes out with no declared type and the server resolves it
+ * there (see `util/unspecified-param.ts`) - but only where there is a
+ * column to resolve it from: `determine()` answers `varchar` for it, an
+ * inlined literal is written with no cast, and a decoded one is
+ * indistinguishable from text. A `Numeric` carries the type with the
+ * digits.
  *
  * There is deliberately no `valueOf()`. Arithmetic on one of these has
  * to be an explicit decision - `Symbol.toPrimitive` hands back the exact

package/data-types/classes/numeric.js

@@ -9,10 +9,14 @@
  * to a plain number; this class is what the rest become, and it carries
  * the digits exactly as the server wrote them.
  *
- * It is a class rather than a bare string so that it can be told apart:
- * `determine()` types a bare string as `varchar`, which the server then
- * refuses to put in a numeric column, so a string could be read but not
- * written back. A `Numeric` round-trips.
+ * It is a class rather than a bare string so that the value keeps
+ * saying what it is. A bare string parameter does reach a numeric
+ * column - it goes out with no declared type and the server resolves it
+ * there (see `util/unspecified-param.ts`) - but only where there is a
+ * column to resolve it from: `determine()` answers `varchar` for it, an
+ * inlined literal is written with no cast, and a decoded one is
+ * indistinguishable from text. A `Numeric` carries the type with the
+ * digits.
  *
  * There is deliberately no `valueOf()`. Arithmetic on one of these has
  * to be an explicit decision - `Symbol.toPrimitive` hands back the exact

package/data-types/date-type.js

@@ -11,7 +11,7 @@ export const DateType = {
     },
     encodeBinary(buf, v, options) {
         if (typeof v === 'string')
-            v = parseDate(v, options.utcDates);
+            v = parseDate(v, options.utcDates, options.dateStyle);
         if (v === Infinity) {
             buf.writeInt32BE(0x7fffffff);
             return;
@@ -42,7 +42,7 @@ export const DateType = {
         return d;
     },
     decodeText(v, options) {
-        return parseDate(v, options.utcDates);
+        return parseDate(v, options.utcDates, options.dateStyle);
     },
     decodeTextBuffer(buf, offset, len, options) {
         return DateType.decodeText(buf.toString('latin1', offset, offset + len), options);

package/data-types/int2-vector-type.js

@@ -10,7 +10,10 @@ export const Int2VectorType = {
     encodeBinary(buf, v) {
         encodeBinaryArray(buf, v, DataTypeOIDs.int2, {}, (io, x) => {
             io.writeInt16BE(x);
-        });
+        }, 
+        // A vector is genuinely 0-based, unlike every ordinary array -
+        // `array_lower(pg_index.indkey, 1)` is 0 on the server.
+        undefined, 0);
     },
     encodeCalculateDim(v) {
         return [v.length];

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

@@ -0,0 +1,38 @@
+import type { MoneyFormat } from '../interfaces/data-mapping-options.js';
+import type { DataType } from '../interfaces/data-type.js';
+/**
+ * Reads the server's own rendering of `1::money` - see
+ * `IntlConnection.ensureMoneyFormat()` for why it is that value: with no
+ * thousands separator in it, any separator present can only be the
+ * decimal one, and the digits after it can only be the fraction.
+ */
+export declare function parseMoneyFormat(text: string): MoneyFormat;
+/** The exact decimal `minorUnits` stands for at `scale` fraction digits. */
+export declare function moneyToString(minorUnits: bigint, scale: number): string;
+/**
+ * PostgreSQL's fixed-point currency type.
+ *
+ * On the wire it is an int64 of the smallest currency unit - `$12.34`
+ * arrives as `1234` - and how many of those make a unit is `lc_monetary`,
+ * which the server does not report in its startup parameters. So the
+ * connection asks it once, on its way up, and every money value is read
+ * against that answer. See `IntlConnection.ensureMoneyFormat()`.
+ *
+ * The value decodes to a plain number, or a `Numeric` when a double
+ * cannot carry it. The currency symbol is *not* part of it: it is the
+ * server's rendering of the value, not the value, and
+ * `fetchAsString: [DataTypeOIDs.money]` asks for that rendering when it
+ * is what the caller wants - which is also what `pg` always returns.
+ *
+ * The question is asked the first time a money column is on its way
+ * back, while the rows are still raw bytes - so no value is ever read
+ * against a scale nobody confirmed, and a caller who never touches
+ * money never asks. `execute()` and `pipeline()` decode inside the
+ * message loop, where there is nowhere left to ask from, so those two
+ * set the rows aside and read them once the loop is over.
+ *
+ * `moneyFormat` in the options answers it in advance, for a caller who
+ * knows the server or is reading a value some other server rendered.
+ */
+export declare const MoneyType: DataType;
+export declare const ArrayMoneyType: DataType;