postgrejs 3.8.0 → 3.9.0

package/CHANGELOG.md

@@ -1,6 +1,43 @@
 ## Changelog
 
-### [v3.8.0](https://github.com/panates/postgrejs/compare/v3.7.0...v3.8.0) - 
+### [v3.9.0](https://github.com/panates/postgrejs/compare/v3.8.0...v3.9.0) - 
+
+#### 🚀 New Features
+
+- feat: decode money, by asking the server what a minor unit is @Eray Hanoğlu 
+- feat: pipeline by default, and let a connection opt out of it @Eray Hanoğlu 
+- feat: take the transaction's modes on startTransaction() @Eray Hanoğlu 
+- feat: let a connection answer the data-mapping options once @Eray Hanoğlu 
+- feat: keep the server's own error text on serverMessage @Eray Hanoğlu 
+
+#### 🪲 Fixes
+
+- fix: read a text date in the DateStyle the server said it wrote @Eray Hanoğlu 
+- fix: let SET TRANSACTION run with rollbackOnError on @Eray Hanoğlu 
+- fix: ask for money's scale on the two paths that decoded before asking @Eray Hanoğlu 
+- fix: name a statement once, not once per caller in a burst @Eray Hanoğlu 
+- fix: keep a pooled connection unshared unless the caller asks @Eray Hanoğlu 
+- fix: type an array from the first value inside it, not from value[0] @Eray Hanoğlu 
+- fix: answer an empty statement instead of raising @Eray Hanoğlu 
+
+#### 📖 Documentation Changes
+
+- docs: list the ORM adapters that run on this client @Eray Hanoğlu 
+
+#### 🛠 Refactoring and Updates
+
+- refactor: let a row decoder declare its own rowType @Eray Hanoğlu 
+
+#### ⚡️ Performance Improvments
+
+- perf: walk fewer types to infer a parameter, and write once per statement @Eray Hanoğlu 
+- perf: stop paying for a text row twice @Eray Hanoğlu 
+
+#### 💬 General Changes
+
+- bench: regenerate the reports, and pin the adapter's options @Eray Hanoğlu 
+
+### [v3.8.0](https://github.com/panates/postgrejs/compare/v3.7.0...v3.8.0) -  21 September 2026 
 
 #### 🚀 New Features
 

package/README.md

@@ -48,6 +48,56 @@ prepared statements, server-side cursors, LISTEN/NOTIFY, bulk `COPY` streams, lo
 two-phase commit, multi-host failover, and SCRAM channel binding - all in the one package, written in
 strictly-typed TypeScript from the ground up.
 
+### 🔌 Bring Your Own ORM
+
+PostgreJS is a driver, not a framework, so what you build on top of it stays your choice:
+
+<!-- One cell per adapter, so each renders as its own card: a table because
+     GitHub strips CSS, and this is the one layout that survives everywhere
+     the README is read. The logos come from postgrejs.com rather than being
+     hotlinked from each project, and Drizzle's follows the reader's theme. -->
+<table>
+  <tr>
+    <td align="center" width="230" valign="top">
+      <a href="https://www.sqbjs.org"><img src="https://www.postgrejs.com/img/sqb-logo.svg" alt="SQB" height="60"></a><br><br>
+      <b><a href="https://www.sqbjs.org">SQB</a></b><br>
+      <a href="https://www.npmjs.com/package/@sqb/postgres"><code>@sqb/postgres</code></a><br>
+      <sub>native driver</sub>
+    </td>
+    <td align="center" width="230" valign="top">
+      <a href="https://kysely.dev"><img src="https://www.postgrejs.com/img/kysely-logo.svg" alt="Kysely" height="60"></a><br><br>
+      <b><a href="https://kysely.dev">Kysely</a></b><br>
+      <a href="https://github.com/panates/postgrejs-kysely"><code>kysely-postgrejs</code></a><br>
+      <sub>dialect</sub>
+    </td>
+    <td align="center" width="230" valign="top">
+      <a href="https://orm.drizzle.team"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.postgrejs.com/img/drizzle-logo-dark.svg"><img src="https://www.postgrejs.com/img/drizzle-logo-light.svg" alt="Drizzle ORM" height="34"></picture></a><br><br>
+      <b><a href="https://orm.drizzle.team">Drizzle ORM</a></b><br>
+      <a href="https://github.com/panates/postgrejs-drizzle"><code>drizzle-postgrejs</code></a><br>
+      <sub>driver</sub>
+    </td>
+  </tr>
+  <tr>
+    <td align="center" width="230" valign="top">
+      <a href="https://typeorm.io"><img src="https://www.postgrejs.com/img/typeorm-icon.png" alt="TypeORM" height="60"></a><br><br>
+      <b><a href="https://typeorm.io">TypeORM</a></b><br>
+      <a href="https://github.com/panates/postgrejs-typeorm"><code>typeorm-postgrejs</code></a><br>
+      <sub>driver</sub>
+    </td>
+    <td align="center" width="230" valign="top">
+      <a href="https://www.prisma.io"><img src="https://www.postgrejs.com/img/prisma-icon.svg" alt="Prisma" height="60"></a><br><br>
+      <b><a href="https://www.prisma.io">Prisma</a></b><br>
+      <a href="https://github.com/panates/postgrejs-prisma"><code>prisma-postgrejs</code></a><br>
+      <sub>driver adapter</sub>
+    </td>
+    <td width="230"></td>
+  </tr>
+</table>
+
+Each adapter hands the compiled SQL straight to this client, with no `pg` left anywhere in the chain, and each is
+compared query by query against the driver it replaces - and, where the project ships a suite of its own, run
+against that too. So adopting one is a change to how the connection is created and nothing else.
+
 ## Installation
 
 ```bash

package/connection/connection.d.ts

@@ -9,6 +9,7 @@ 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 type { DatabaseError } from '../protocol/database-error.js';
 import type { Protocol } from '../protocol/protocol.js';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
@@ -281,7 +282,7 @@ export declare class Connection extends SafeEventEmitter implements AsyncDisposa
     /**
      * Starts a transaction
      */
-    startTransaction(): Promise<void>;
+    startTransaction(options?: TransactionOptions): Promise<void>;
     /**
      * Runs `fn` inside a transaction and commits when it returns, or rolls
      * back and rethrows when it throws - the try/catch every caller of
@@ -309,7 +310,7 @@ export declare class Connection extends SafeEventEmitter implements AsyncDisposa
      * `fn` is handed this same connection: every statement it runs on it is
      * inside the transaction, and one it runs on another connection is not.
      */
-    transaction<T>(fn: (connection: this) => Promise<T>): Promise<T>;
+    transaction<T>(fn: (connection: this) => Promise<T>, options?: TransactionOptions): Promise<T>;
     /**
      * Commits current transaction.
      * @param immediate - Commits right away, ignoring how many nested
@@ -370,6 +371,11 @@ export declare class Connection extends SafeEventEmitter implements AsyncDisposa
     listen(channel: string, callback: NotificationCallback): Promise<void>;
     unListen(channel: string): Promise<void>;
     unListenAll(): Promise<void>;
+    /**
+     * Whether a statement asked for the wire to itself - `pipeline: false`
+     * on the call, or on the connection when the call says nothing.
+     */
+    protected _isExclusive(pipeline: Maybe<boolean>): boolean;
     protected _query(sql: string, options?: QueryOptions): Promise<QueryResult>;
     /**
      * A large object's descriptor is only valid inside the transaction that
@@ -381,6 +387,12 @@ export declare class Connection extends SafeEventEmitter implements AsyncDisposa
     protected _openLargeObject(oid: number, mode: number, ownsTransaction: boolean): Promise<LargeObject>;
     protected _handleNotification(msg: NotificationMessage): void;
     protected _close(): Promise<void>;
+    /**
+     * Adds the source excerpt the server's `position` points at to
+     * `message`, so an error reads in a terminal without the caller doing
+     * anything. `err.serverMessage` keeps the undecorated text for
+     * anything that parses it.
+     */
     protected _handleError(err: DatabaseError, script: string): DatabaseError;
     /**
      * Remembers where a call came from, so the error it may reject with points

package/connection/connection.js

@@ -159,9 +159,17 @@ export class Connection extends SafeEventEmitter {
             sql = sql.stringify({ ...options, typeMap: options?.typeMap });
         if (this.listenerCount('execute'))
             this.emit('execute', sql, options);
-        return withAbortSignal(options?.signal, () => this._intlCon.cancel(), () => this._captureErrorStack(this._intlCon.execute(sql, options), this.execute, options?.asyncErrorHandling).catch((e) => {
-            throw this._handleError(e, sql);
-        }));
+        let release = this._intlCon.enterWire(this._isExclusive(options?.pipeline));
+        if (typeof release !== 'function')
+            release = await release;
+        try {
+            return await withAbortSignal(options?.signal, () => this._intlCon.cancel(), () => this._captureErrorStack(this._intlCon.execute(sql, options), this.execute, options?.asyncErrorHandling).catch((e) => {
+                throw this._handleError(e, sql);
+            }));
+        }
+        finally {
+            release();
+        }
     }
     /**
      * The legacy Function Call sub-protocol - calls a function by OID
@@ -200,7 +208,15 @@ export class Connection extends SafeEventEmitter {
         /* c8 ignore stop */
         if (this.listenerCount('query'))
             this.emit('query', sql, options);
-        return withAbortSignal(options?.signal, () => this._intlCon.cancel(), () => this._query(sql, options));
+        let release = this._intlCon.enterWire(this._isExclusive(options?.pipeline));
+        if (typeof release !== 'function')
+            release = await release;
+        try {
+            return await withAbortSignal(options?.signal, () => this._intlCon.cancel(), () => this._query(sql, options));
+        }
+        finally {
+            release();
+        }
     }
     /**
      * Runs a `COPY ... TO STDOUT` and returns its output as a stream of the
@@ -479,8 +495,8 @@ export class Connection extends SafeEventEmitter {
     /**
      * Starts a transaction
      */
-    startTransaction() {
-        return this._captureErrorStack(this._intlCon.startTransaction());
+    startTransaction(options) {
+        return this._captureErrorStack(this._intlCon.startTransaction(options));
     }
     /**
      * Runs `fn` inside a transaction and commits when it returns, or rolls
@@ -509,10 +525,19 @@ export class Connection extends SafeEventEmitter {
      * `fn` is handed this same connection: every statement it runs on it is
      * inside the transaction, and one it runs on another connection is not.
      */
-    async transaction(fn) {
-        if (this._intlCon.inTransaction)
+    async transaction(fn, options) {
+        // A call inside a transaction becomes a savepoint scope, which has
+        // no BEGIN to carry modes - see startTransaction(), which refuses
+        // them for the same reason rather than applying them to somebody
+        // else's transaction.
+        if (this._intlCon.inTransaction) {
+            if (options)
+                throw new Error('transaction() cannot set transaction modes inside a transaction ' +
+                    'that is already open - the inner scope is a savepoint, and the ' +
+                    'modes belong to the BEGIN that opened the outer one');
             return await this._savepointScope(fn);
-        await this.startTransaction();
+        }
+        await this.startTransaction(options);
         try {
             const result = await fn(this);
             await this.commit();
@@ -630,6 +655,15 @@ export class Connection extends SafeEventEmitter {
             await this._captureErrorStack(this.query('UNLISTEN *'));
         }
     }
+    /**
+     * Whether a statement asked for the wire to itself - `pipeline: false`
+     * on the call, or on the connection when the call says nothing.
+     */
+    _isExclusive(pipeline) {
+        return pipeline != null
+            ? !pipeline
+            : this._intlCon.config.pipeline === false;
+    }
     async _query(sql, options) {
         const typeMap = options?.typeMap || GlobalTypeMap;
         const paramTypes = options?.params?.map(prm => prm instanceof BindParam
@@ -644,6 +678,14 @@ export class Connection extends SafeEventEmitter {
                 isUnspecifiedParam(prm)
                     ? 0
                     : typeMap.determine(prm));
+        // A money parameter is written as an int64 of minor units, so the
+        // scale has to be known before the Bind goes out - the probe fired
+        // at connect answers in time for every result, but not necessarily
+        // for the encode of the very first statement.
+        if (paramTypes &&
+            (paramTypes.includes(DataTypeOIDs.money) ||
+                paramTypes.includes(DataTypeOIDs._money)))
+            await this._intlCon.ensureMoneyFormat();
         const effectiveAutoCommit = options?.autoCommit != null
             ? options.autoCommit
             : this._intlCon.config.autoCommit;
@@ -716,6 +758,12 @@ export class Connection extends SafeEventEmitter {
             await this._captureErrorStack(this._intlCon.close());
         this._closing = false;
     }
+    /**
+     * Adds the source excerpt the server's `position` points at to
+     * `message`, so an error reads in a terminal without the caller doing
+     * anything. `err.serverMessage` keeps the undecorated text for
+     * anything that parses it.
+     */
     _handleError(err, script) {
         if (err.position != null) {
             const i1 = script.lastIndexOf('\n', err.position - 1) + 1;

package/connection/intl-connection.d.ts

@@ -2,7 +2,8 @@ import { ConnectionState } from '../constants.js';
 import type { DataTypeMap } from '../data-type-map.js';
 import type { BatchResult } from '../interfaces/batch-result.js';
 import type { CopyFromRowsOptions, CopyFromRowsResult } from '../interfaces/copy-from-rows-options.js';
-import type { ConnectionConfiguration } from '../interfaces/database-connection-params.js';
+import type { DataMappingOptions, MoneyFormat } from '../interfaces/data-mapping-options.js';
+import type { ConnectionConfiguration, ConnectionMappingDefaults } from '../interfaces/database-connection-params.js';
 import type { FieldInfo } from '../interfaces/field-info.js';
 import type { FunctionCallOptions } from '../interfaces/function-call-options.js';
 import type { FunctionCallResult } from '../interfaces/function-call-result.js';
@@ -10,13 +11,29 @@ 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 type { TransactionOptions } from '../interfaces/transaction-options.js';
 import { PgSocket } from '../protocol/pg-socket.js';
 import { Protocol } from '../protocol/protocol.js';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
 import type { AnyParseFunction, Maybe, OID } from '../types.js';
 import { type CopyRowSource } from '../util/copy-from-rows.js';
+import { type PgDateStyle } from '../util/date-style.js';
+import { type RowDecoder } from '../util/row-decoder.js';
 import type { Connection } from './connection.js';
 import { CopyFromStream, CopyToStream } from './copy-stream.js';
+interface PreparedCacheEntry {
+    name: string;
+    fields?: Protocol.RowDescription[];
+}
+/** See IntlConnection._decodeDeferredRows(). */
+interface DeferredRows {
+    target: {
+        rows?: any[];
+    };
+    raw: Protocol.DataRowMessage[];
+    parsers: AnyParseFunction[];
+    fields: any;
+}
 export declare class IntlConnection extends SafeEventEmitter {
     /**
      * Server-side prepared statements this connection has built, keyed by
@@ -29,6 +46,15 @@ export declare class IntlConnection extends SafeEventEmitter {
      * this is per connection and dies with it.
      */
     private _preparedCache;
+    /**
+     * The names being given out right now, one per SQL. A burst of the
+     * same statement arrives before any of it is prepared, and without
+     * this every call in the burst prepares its own copy: measured at 50
+     * concurrent `select $1::int4`, 25 Parse+Describe round trips and 25
+     * named statements left on the server that this map's one entry could
+     * never close again.
+     */
+    private _preparing;
     /** SQL seen once but not yet prepared - see PREPARE_AFTER_USES. */
     private _preparedCandidates;
     private _preparedCounter;
@@ -38,6 +64,24 @@ export declare class IntlConnection extends SafeEventEmitter {
     protected _savepointDepths: Map<string, number>;
     protected _config: ConnectionConfiguration;
     protected _onErrorSavePoint: string;
+    /**
+     * The data-mapping options this connection was configured with, or
+     * undefined when it was given none - which is the common case, and
+     * the one that must not pay for this.
+     */
+    protected readonly _mappingDefaults?: ConnectionMappingDefaults;
+    /** The session's DateStyle as last reported, and what it parsed to. */
+    protected _dateStyleRaw?: string;
+    protected _dateStyle?: PgDateStyle;
+    /** The server's own money rendering - see ensureMoneyFormat(). */
+    protected _moneyFormat?: MoneyFormat;
+    protected _moneyFormatPromise?: Promise<void>;
+    /** Statements currently holding the wire - see enterWire(). */
+    protected _wireUsers: number;
+    protected _wireIdleWaiters?: (() => void)[];
+    protected _wireLock?: Promise<void>;
+    /** Bound once: enterWire()'s fast path hands out this same function. */
+    protected _releaseWire: () => void;
     transactionStatus: string;
     socket: PgSocket;
     owner?: SafeEventEmitter;
@@ -74,7 +118,7 @@ export declare class IntlConnection extends SafeEventEmitter {
      * that point). A matching number of commit() calls is then needed to
      * actually commit - see commit().
      */
-    startTransaction(): Promise<void>;
+    startTransaction(options?: TransactionOptions): Promise<void>;
     /**
      * Starts a savepoint, or - if one under the same `name` is already open -
      * marks a nested level of it. Mirrors startTransaction(): only the
@@ -142,6 +186,49 @@ export declare class IntlConnection extends SafeEventEmitter {
     rollbackToSavepoint(name: string): Promise<void>;
     /** Asks the server to cancel whatever this session is running. */
     cancel(): Promise<void>;
+    /**
+     * Claims the wire for one statement, and hands back the function that
+     * releases it.
+     *
+     * Several statements share it by default: PostgreSQL correlates
+     * responses to requests by order, so a connection can carry more than
+     * one at a time and a caller that does not wait for each reply is
+     * measurably faster. `exclusive` is `pipeline: false` - the statement
+     * waits until nothing else is running here, and nothing else starts
+     * until it releases.
+     *
+     * Returns the release function itself rather than a promise of one
+     * whenever it can be taken without waiting, which is every statement
+     * on a connection nobody has asked to serialise - the common case, and
+     * the one that must not pay for this.
+     */
+    enterWire(exclusive?: boolean): (() => void) | Promise<() => void>;
+    /**
+     * Asks the server how it renders money, once per connection.
+     *
+     * `money` travels as an int64 of the smallest currency unit, and how
+     * many of those make one unit is `lc_monetary` - which the server
+     * does not report among its startup parameters, so `1234` on the wire
+     * is $12.34, ¥1234 or 1.234 KWD depending on a setting only the server
+     * knows. Asking it to render a value it already knows is the whole
+     * answer, and needs no locale data on this side.
+     *
+     * `1` is the value asked for because it cannot carry a thousands
+     * separator: whatever separator comes back can only be the decimal
+     * one, and the digits after it can only be the fraction. `$1.00` is
+     * two, `¥1` is none.
+     */
+    ensureMoneyFormat(): Promise<void>;
+    /**
+     * Whether these columns need the server's money format and this
+     * connection has not asked for it yet.
+     *
+     * The scan costs a look at each column's OID, and only until the
+     * answer is in - from then on the first test ends it.
+     */
+    needsMoneyFormat(fields: Maybe<{
+        dataTypeId: OID;
+    }[]>, options?: DataMappingOptions): boolean;
     ref(): void;
     unref(): boolean;
     assertConnected(): void;
@@ -204,11 +291,22 @@ export declare class IntlConnection extends SafeEventEmitter {
     /**
      * The savepoint rollbackOnError calls for, or undefined when this call
      * needs none: outside a transaction there is nothing to roll back to,
-     * and a statement that is itself a transaction command manages its own
-     * boundaries (wrapping COMMIT in a savepoint would be nonsense).
+     * a statement that is itself a transaction command manages its own
+     * boundaries (wrapping COMMIT in a savepoint would be nonsense), and
+     * PostgreSQL refuses `SET TRANSACTION` inside one outright.
      */
     protected _inlineSavepointFor(sql: string, options: QueryOptions): Maybe<string>;
-    protected _queryCached(sql: string, paramTypes: Maybe<Maybe<OID>[]>, params: Maybe<Maybe<any>[]>, options: QueryOptions, savepoint: Maybe<string>): Promise<QueryResult>;
+    protected _queryCached(sql: string, paramTypes: Maybe<Maybe<OID>[]>, params: Maybe<Maybe<any>[]>, options: QueryOptions, savepoint: Maybe<string>, 
+    /** Whether the CALL asked for text columns, not the connection. */
+    callWantsFields: boolean): Promise<QueryResult>;
+    /**
+     * Gives this SQL a name and caches it, once, however many callers are
+     * waiting. A Parse that fails caches nothing and reports itself; the
+     * statement is simply never reused. It runs outside the savepoint, as
+     * the prepare() the transaction path used to do ahead of its own
+     * wrapper.
+     */
+    protected _prepareForCache(key: string, sql: string, paramTypes: Maybe<Maybe<OID>[]>): Promise<PreparedCacheEntry>;
     /**
      * Counts one more use of this SQL and says whether it has now been seen
      * often enough to be worth preparing under a name.
@@ -283,6 +381,49 @@ export declare class IntlConnection extends SafeEventEmitter {
     executeBatchReused(statementName: string, cachedFields: Protocol.RowDescription[] | undefined, paramTypes: Maybe<Maybe<OID>[]>, paramSets: Maybe<any>[][], options: QueryOptions): Promise<BatchResult>;
     executeReused(statementName: string, cachedFields: Protocol.RowDescription[] | undefined, paramTypes: Maybe<Maybe<OID>[]>, params: Maybe<Maybe<any>[]>, options: QueryOptions, savepoint?: string): Promise<QueryResult>;
     emit(event: string | symbol, ...args: any[]): boolean;
+    /**
+     * The slow half of enterWire(): either an exclusive statement, or an
+     * ordinary one arriving while an exclusive statement holds the wire.
+     *
+     * The claim itself is synchronous on purpose. Each waiter wakes in its
+     * own microtask and runs to its next `await` without interruption, so
+     * re-reading `_wireLock` and assigning it in the same stretch is what
+     * makes two waiters unable to both believe they took it.
+     */
+    protected _enterWireQueued(exclusive: boolean): Promise<() => void>;
+    /**
+     * `options` with whatever this connection can answer for it: the
+     * data-mapping defaults it was configured with, and the money format
+     * it has learned.
+     *
+     * At most one shallow copy per statement, and only when there is
+     * something to fill in - a connection configured with nothing and no
+     * money in sight hands the caller's own object straight back.
+     */
+    /**
+     * Rows left raw because a money column's scale was not in yet.
+     *
+     * Two paths decode inside the message loop, where there is no longer
+     * anywhere to ask the server anything: the Simple Query protocol and
+     * a pipeline. Rather than read those against a scale nobody
+     * confirmed, they set the rows aside and this reads them once the
+     * loop is over and the question can be asked.
+     */
+    protected _decodeDeferredRows(deferred: DeferredRows[], rowDecoder: RowDecoder, options: QueryOptions): Promise<QueryOptions>;
+    withDefaults<T extends DataMappingOptions>(options: T): T;
+    /**
+     * The session's DateStyle, when it is not ISO.
+     *
+     * Read off the reported parameters rather than cached once: `SET
+     * DateStyle` is answered with a fresh ParameterStatus, so the string
+     * changes under us and a connection that changes it mid-session must
+     * not go on decoding by the old one. The comparison is against the
+     * same string the socket holds, so it costs a read and a pointer
+     * compare while nothing changes - which is always, for the ISO
+     * default that needs no parsing at all.
+     */
+    protected _currentDateStyle(): Maybe<PgDateStyle>;
     protected _onError(err: Error): void;
 }
 export declare function getIntlConnection(connection: Connection): IntlConnection;
+export {};