postgrejs 3.4.0 → 3.6.0

package/CHANGELOG.md

@@ -1,6 +1,48 @@
 ## Changelog
 
-### [v3.4.0](https://github.com/panates/postgrejs/compare/v3.3.0...v3.4.0) - 
+### [v3.6.0](https://github.com/panates/postgrejs/compare/v3.5.0...v3.6.0) - 
+
+#### 🚀 New Features
+
+- feat: make fetchAsString request text from the server @Eray Hanoğlu 
+
+#### 🪲 Fixes
+
+- fix: decode float4 as the number the server would print @Eray Hanoğlu 
+- fix: report rowsAffected for MERGE @Eray Hanoğlu 
+- fix: quote LISTEN channel names instead of restricting them @Eray Hanoğlu 
+- fix: stop a pooled cursor's connection going back into the pool @Eray Hanoğlu 
+- fix: stop inferring "char" for one-character strings @Eray Hanoğlu 
+- fix: copy both indexes when a DataTypeMap is built from another @Eray Hanoğlu 
+- fix: emit 'notification' once per NOTIFY @Eray Hanoğlu 
+- fix: accept single-character savepoint names @Eray Hanoğlu 
+
+#### 📖 Documentation Changes
+
+- docs: record what 3.6 changes for existing code @Eray Hanoğlu 
+
+#### 💬 General Changes
+
+- feat!: fetch every row by default instead of the first 100 @Eray Hanoğlu 
+
+### [v3.5.0](https://github.com/panates/postgrejs/compare/v3.4.0...v3.5.0) -  16 September 2026 
+
+#### 🚀 New Features
+
+- feat: add transaction(fn) and let a Cursor be iterated with for await @Eray Hanoğlu 
+
+#### 📖 Documentation Changes
+
+- docs: refresh Unit of Work after pipeline() started reusing statements @Eray Hanoğlu 
+- docs: record scoped transactions and cursor iteration in the README @Eray Hanoğlu 
+- docs: stop signing commits on the assistant's behalf @Eray Hanoğlu 
+- docs: note that pipeline() reuses cached prepared statements @Eray Hanoğlu 
+
+#### ⚡️ Performance Improvments
+
+- perf: let pipeline() bind to the connection's cached statements @Eray Hanoğlu 
+
+### [v3.4.0](https://github.com/panates/postgrejs/compare/v3.3.0...v3.4.0) -  16 September 2026 
 
 - feat: add PreparedStatement.executeBatch() for multi-set execution
 

package/README.md

@@ -59,6 +59,9 @@ $ npm install postgrejs --save
 Please read :small_orange_diamond: [DOCUMENTATION](https://www.postgrejs.com/) :small_orange_diamond: for detailed
 usage.
 
+Upgrading from 3.5? See [doc/MIGRATION-v3.5-to-v3.6.md](doc/MIGRATION-v3.5-to-v3.6.md) - `query()` no longer stops at
+100 rows, and `fetchAsString` now returns the server's own text.
+
 ## Library Overview
 
 - **Language:** Pure JavaScript, with no native/binary dependencies to compile or ship.
@@ -82,12 +85,23 @@ usage.
   statement leaves the transaction usable instead of aborting the whole block. The `SAVEPOINT`/`RELEASE` pair travels
   in the statement's own round trip rather than costing one each - 36µs for the pair, against 507µs sent separately.
   `rollbackOnError: false` to opt out.
-- **Cursors:** Features fast double-link cache cursors for efficient data retrieval.
+- **Complete Results:** `query()` returns every row the statement produced. A `fetchCount` limit is a limit rather
+  than a silent cap: the result carries `suspended: true` when the server stopped at it, so a prefix can never be
+  mistaken for the whole answer. `0` means unlimited, as it does in the protocol.
+- **Cursors:** Features fast double-link cache cursors for efficient data retrieval, iterable with `for await` a row
+  at a time and closed when the loop ends - by exhaustion, a `break`, or a throw. A cursor reads through a portal, and
+  a portal lives as long as the transaction that created it - `Pool.query()` keeps its connection out of the pool
+  until the cursor closes, and on a bare `Connection` open the cursor inside a transaction if anything else will run
+  on that connection meanwhile.
+- **Scoped Transactions:** `transaction(fn)` commits when the callback returns and rolls back when it throws, on a
+  connection or straight from the pool. A call made while a transaction is already open takes a savepoint rather than
+  a second `BEGIN`, so a nested scope that fails rolls back its own work and leaves the outer transaction standing.
 - **Batch Execution:** `executeBatch()` runs one prepared statement over many parameter sets under a single `Sync`,
   reporting each set's row count - 1000 updates in 20ms where the same calls pipelined individually take 188ms.
 - **Notifications:**  High-level implementation for PostgreSQL notifications (LISTEN/NOTIFY), enabling real-time data
-  updates.
-- **Extensibility:** Extensible data-types and type mapping to accommodate custom requirements.
+  updates. Channel names are quoted rather than pattern-matched, so any name PostgreSQL accepts works.
+- **Extensibility:** Extensible data-types and type mapping to accommodate custom requirements. A type can set
+  `inferrable: false` to stay out of parameter type inference while still decoding its own columns.
 - **Parameter Binding:**  Bind parameters with OID mappings for precise and efficient query execution.
 - **Array Handling:** Supports multidimensional arrays with fast binary encoding/decoding.
 - **Performance Optimization:**  Low memory utilization and boosted performance through the use of shared buffers.
@@ -99,7 +113,8 @@ usage.
 - **Query Pipelining:** Pooled queries can share connections so a burst is not capped by pool size - opt-in per call.
   `pipeline()` goes further for a known set of statements: several different ones travel under a single `Sync`, so they
   cost one round trip instead of one each and commit or roll back together - around 2x faster than the same calls
-  through `Promise.all()`, which is already pipelined.
+  through `Promise.all()`, which is already pipelined. Statements the connection has run before bind to their cached
+  prepared names, so a repeated set sends no `Parse` at all - worth 2.5x on twenty statements.
 - **Dynamic SQL:** A `sql` tag builds statements from composable fragments - values become parameters, names are quoted,
   and `sql.values()`/`sql.set()` write INSERT and UPDATE clauses from objects.
 - **Multiple Hosts:** A connection can list several servers and pick one by role
@@ -114,6 +129,10 @@ usage.
   `rollbackPrepared()`, from any connection.
 - **Cancellation:** Any call takes an `AbortSignal`, which also gives per-query timeouts via `AbortSignal.timeout()`.
 - **Flexible Data Retrieval:**  Can return both array and object rows to suit different data processing needs.
+- **Values as Text:** `fetchAsString: [DataTypeOIDs.int8]` asks the server for those columns in its own text format
+  and hands the bytes back unparsed - so `count(*)` arrives as `'3'`, one consistent type where a decoded `int8` is a
+  `number` or a `BigInt` depending on magnitude. Any OID, arrays included. The string is PostgreSQL's own rendering
+  rather than one reconstructed from the binary value, so it cannot drift from what the server would print.
 - **Resource Management:** Auto disposal of resources with the "using" syntax
   ([TC39 Explicit Resource Management](https://github.com/tc39/proposal-explicit-resource-management)), ensuring
   efficient resource cleanup.
@@ -162,6 +181,7 @@ in · 🟡 partial or needs a separate package · ❌ not supported.
 | Parameter type casting            |           ✅           |   🟡 <sup>10</sup>    |        ✅        |
 | Prepared statements <sup>24</sup> |     ✅ automatic      |      ✅ manual       |   ✅ automatic   |
 | Statement-level rollback <sup>25</sup> |     ✅ automatic      |          ❌           |    🟡 manual     |
+| Scoped transaction helper <sup>26</sup> |     ✅ nests      |          ❌           |        ✅        |
 | Batch execution <sup>21</sup>     |           ✅           |          ❌           |        ❌        |
 | Multi-statement round trip <sup>23</sup> |     ✅     |          ❌           |        ❌        |
 | Multi-statement scripts           |           ✅           |          ✅           |        ✅        |
@@ -265,6 +285,11 @@ in · 🟡 partial or needs a separate package · ❌ not supported.
   trip for each. postgres.js has savepoints, but as a scope the caller opens around a callback (`savepoint(name, fn)`
   in `src/index.js`), so a statement is protected only where someone wrapped it; pg has no savepoint handling in
   `lib/` at all, so a failed statement leaves the block aborted until the caller rolls back themselves.
+- <sup>26</sup> Whether the library runs a callback inside a transaction for you, committing or rolling back on the way
+  out. PostgreJS has `transaction(fn)` on both a connection and the pool, and a call made inside one already open takes
+  a savepoint, so nesting needs nothing from the caller. postgres.js has `sql.begin(fn)` (`src/index.js`), where a
+  nested scope is opened explicitly with `sql.savepoint(fn)` instead. pg has no such helper in `lib/` - `BEGIN` and
+  `COMMIT` are statements the caller sends, and getting a transaction onto one connection is the caller's problem too.
 
 
 ## Benchmarks

package/connection/connection.d.ts

@@ -282,6 +282,34 @@ export declare class Connection extends SafeEventEmitter implements AsyncDisposa
      * Starts a transaction
      */
     startTransaction(): 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
+     * startTransaction()/commit()/rollback() ends up writing by hand.
+     *
+     * ```ts
+     * const id = await connection.transaction(async tx => {
+     *   const r = await tx.query(
+     *     'insert into orders (total) values ($1) returning id',
+     *     { params: [total] },
+     *   );
+     *   await tx.query('update stock set n = n - 1 where sku = $1', {
+     *     params: [sku],
+     *   });
+     *   return r.rows![0][0];
+     * });
+     * ```
+     *
+     * A call made while a transaction is already open becomes a savepoint
+     * rather than a second BEGIN, so an inner scope that fails rolls back
+     * its own work and leaves the outer transaction to decide what to do -
+     * instead of taking everything down with it, which is what a shared
+     * BEGIN/ROLLBACK pair would do.
+     *
+     * `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>;
     /**
      * Commits current transaction.
      * @param immediate - Commits right away, ignoring how many nested
@@ -383,6 +411,15 @@ export declare class Connection extends SafeEventEmitter implements AsyncDisposa
      * microtask tick on top of the one `promise`/`.catch()` already goes
      * through - paid on every single query this wraps, disabled or not.
      */
+    /**
+     * The nested half of transaction(): a savepoint of its own, released on
+     * success and rolled back to on failure.
+     *
+     * The `inTransaction` checks are re-read rather than assumed - `fn` is
+     * free to commit or roll back the outer transaction itself, and there is
+     * no savepoint left to release once it has.
+     */
+    private _savepointScope;
     protected _captureErrorStack<T>(promise: Promise<T>, entry?: (...args: any[]) => any, asyncErrorHandling?: boolean): Promise<T>;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/connection/connection.js

@@ -2,12 +2,16 @@ import { ConnectionState, DataTypeOIDs } from '../constants.js';
 import { GlobalTypeMap } from '../data-type-map.js';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
 import { withAbortSignal } from '../util/abort-signal.js';
+import { normalizeChannelName } from '../util/channel-name.js';
+import { escapeIdentifier } from '../util/escape-identifier.js';
 import { QueryRequest } from '../util/sql-tag.js';
 import { BindParam } from './bind-param.js';
 import { IntlConnection } from './intl-connection.js';
 import { LargeObject, LargeObjectMode } from './large-object.js';
 import { PreparedStatement } from './prepared-statement.js';
 const CAPTURE_STACK_TRACE_LIMIT = 5;
+/** Names the savepoint a nested transaction() scope takes. */
+let transactionScopeCounter = 0;
 export class Connection extends SafeEventEmitter {
     _pool;
     _intlCon;
@@ -477,6 +481,50 @@ export class Connection extends SafeEventEmitter {
     startTransaction() {
         return this._captureErrorStack(this._intlCon.startTransaction());
     }
+    /**
+     * Runs `fn` inside a transaction and commits when it returns, or rolls
+     * back and rethrows when it throws - the try/catch every caller of
+     * startTransaction()/commit()/rollback() ends up writing by hand.
+     *
+     * ```ts
+     * const id = await connection.transaction(async tx => {
+     *   const r = await tx.query(
+     *     'insert into orders (total) values ($1) returning id',
+     *     { params: [total] },
+     *   );
+     *   await tx.query('update stock set n = n - 1 where sku = $1', {
+     *     params: [sku],
+     *   });
+     *   return r.rows![0][0];
+     * });
+     * ```
+     *
+     * A call made while a transaction is already open becomes a savepoint
+     * rather than a second BEGIN, so an inner scope that fails rolls back
+     * its own work and leaves the outer transaction to decide what to do -
+     * instead of taking everything down with it, which is what a shared
+     * BEGIN/ROLLBACK pair would do.
+     *
+     * `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)
+            return await this._savepointScope(fn);
+        await this.startTransaction();
+        try {
+            const result = await fn(this);
+            await this.commit();
+            return result;
+        }
+        catch (e) {
+            // A rollback that fails in turn must not replace the error that
+            // caused it: the connection is already in trouble, and the original
+            // is what the caller needs to see.
+            await this.rollback().catch(() => undefined);
+            throw e;
+        }
+    }
     /**
      * Commits current transaction.
      * @param immediate - Commits right away, ignoring how many nested
@@ -553,8 +601,7 @@ export class Connection extends SafeEventEmitter {
         return this._captureErrorStack(this._intlCon.releaseSavepoint(name, immediate));
     }
     async listen(channel, callback) {
-        if (!/^[A-Z]\w+$/i.test(channel))
-            throw new TypeError(`Invalid channel name`);
+        channel = normalizeChannelName(channel);
         if (!this._notificationListeners) {
             this._notificationListeners = new SafeEventEmitter();
             this._intlCon.on('notification', (msg) => this._handleNotification(msg));
@@ -567,14 +614,13 @@ export class Connection extends SafeEventEmitter {
         const alreadyListening = !!this._notificationListeners.listenerCount(channel);
         this._notificationListeners.on(channel, callback);
         if (!alreadyListening)
-            await this._captureErrorStack(this.query('LISTEN ' + channel));
+            await this._captureErrorStack(this.query('LISTEN ' + escapeIdentifier(channel)));
     }
     async unListen(channel) {
-        if (!/^[A-Z]\w+$/i.test(channel))
-            throw new TypeError(`Invalid channel name`);
+        channel = normalizeChannelName(channel);
         if (this._notificationListeners?.listenerCount(channel)) {
             this._notificationListeners?.removeAllListeners(channel);
-            await this._captureErrorStack(this.query('UNLISTEN ' + channel));
+            await this._captureErrorStack(this.query('UNLISTEN ' + escapeIdentifier(channel)));
         }
     }
     async unListenAll() {
@@ -636,7 +682,13 @@ export class Connection extends SafeEventEmitter {
         return new LargeObject(this, oid, Number(opened.rows?.[0][0]), ownsTransaction);
     }
     _handleNotification(msg) {
-        this.emit('notification', msg);
+        // Deliberately no `this.emit('notification', msg)` here:
+        // IntlConnection.emit() re-emits every event on its owner, which is
+        // this Connection, so the raw event has already been delivered by the
+        // time this runs. Emitting it again fired 'notification' twice for one
+        // NOTIFY - but only once listen() had been called, since that is what
+        // installs this handler, so the same listener saw one event or two
+        // depending on whether anything else had subscribed.
         this._notificationListeners?.emit(msg.channel, msg);
     }
     async _close() {
@@ -695,6 +747,32 @@ export class Connection extends SafeEventEmitter {
      * microtask tick on top of the one `promise`/`.catch()` already goes
      * through - paid on every single query this wraps, disabled or not.
      */
+    /**
+     * The nested half of transaction(): a savepoint of its own, released on
+     * success and rolled back to on failure.
+     *
+     * The `inTransaction` checks are re-read rather than assumed - `fn` is
+     * free to commit or roll back the outer transaction itself, and there is
+     * no savepoint left to release once it has.
+     */
+    async _savepointScope(fn) {
+        const name = 'txscope' + ++transactionScopeCounter;
+        await this._captureErrorStack(this._intlCon.execute('SAVEPOINT ' + name));
+        try {
+            const result = await fn(this);
+            if (this._intlCon.inTransaction)
+                await this._intlCon.execute('RELEASE SAVEPOINT ' + name);
+            return result;
+        }
+        catch (e) {
+            if (this._intlCon.inTransaction) {
+                await this._intlCon
+                    .execute('ROLLBACK TO SAVEPOINT ' + name + '; RELEASE SAVEPOINT ' + name)
+                    .catch(() => undefined);
+            }
+            throw e;
+        }
+    }
     _captureErrorStack(promise, entry, asyncErrorHandling) {
         const enabled = asyncErrorHandling ?? this._intlCon.config.asyncErrorHandling ?? true;
         if (!enabled)

package/connection/cursor.d.ts

@@ -21,5 +21,13 @@ export declare class Cursor extends SafeEventEmitter implements AsyncDisposable
     fetch(nRows: number): Promise<Row[]>;
     close(): Promise<void>;
     private _fetchRows;
+    /**
+     * Iterates the remaining rows, fetching a batch at a time, and closes
+     * the cursor when the loop ends - whether it ran out of rows, broke
+     * early, or the body threw. Nothing is decoded ahead of what is asked
+     * for, so this streams a result larger than memory the same way next()
+     * does one row at a time.
+     */
+    [Symbol.asyncIterator](): AsyncIterableIterator<Row>;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/connection/cursor.js

@@ -69,7 +69,28 @@ export class Cursor extends SafeEventEmitter {
         await this._taskQueue
             .enqueue(async () => {
             const queryOptions = this._queryOptions;
-            const r = await portal.execute(queryOptions.fetchCount || 100);
+            let r;
+            try {
+                r = await portal.execute(queryOptions.fetchCount ?? 100);
+            }
+            catch (e) {
+                // 34000 here means the portal is gone, and the only thing that
+                // takes a portal away mid-cursor is another statement on this
+                // connection: its Sync ends the implicit transaction the portal
+                // lives in. The server's own message says nothing about why, and
+                // a caller cannot act on it without knowing. Closing first keeps
+                // the statement from leaking and lets whoever is holding the
+                // connection for this cursor (Pool.query()) have it back.
+                if (e?.code === '34000') {
+                    await this.close().catch(() => undefined);
+                    e.message +=
+                        ' - the portal was destroyed by another statement running on' +
+                            ' the same connection, which ends the implicit transaction it' +
+                            ' lives in. Open the cursor inside an explicit transaction, or' +
+                            ' give it a connection of its own.';
+                }
+                throw e;
+            }
             if (r && r.rows && r.rows.length) {
                 const rows = r.rows;
                 if (this._parsers) {
@@ -92,6 +113,23 @@ export class Cursor extends SafeEventEmitter {
         })
             .toPromise();
     }
+    /**
+     * Iterates the remaining rows, fetching a batch at a time, and closes
+     * the cursor when the loop ends - whether it ran out of rows, broke
+     * early, or the body threw. Nothing is decoded ahead of what is asked
+     * for, so this streams a result larger than memory the same way next()
+     * does one row at a time.
+     */
+    async *[Symbol.asyncIterator]() {
+        try {
+            let row;
+            while ((row = await this.next()) !== undefined)
+                yield row;
+        }
+        finally {
+            await this.close();
+        }
+    }
     [Symbol.asyncDispose]() {
         return this.close();
     }

package/connection/intl-connection.d.ts

@@ -207,6 +207,11 @@ export declare class IntlConnection extends SafeEventEmitter {
      */
     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>;
+    /**
+     * Counts one more use of this SQL and says whether it has now been seen
+     * often enough to be worth preparing under a name.
+     */
+    protected _earnsAName(key: string): boolean;
     /** Closes the least recently used statement once the cache is full. */
     protected _evictPreparedIfFull(): Promise<void>;
     /**
@@ -240,7 +245,7 @@ export declare class IntlConnection extends SafeEventEmitter {
      * so repeated executes of the same statement don't rebuild them.
      * Shared by executeReused() and executeBatchReused().
      */
-    protected _resolveReusedParsers(cachedFields: Protocol.RowDescription[], typeMap: DataTypeMap, options: QueryOptions): {
+    protected _resolveReusedParsers(cachedFields: Protocol.RowDescription[], typeMap: DataTypeMap, options: QueryOptions, columnFormat: Protocol.DataFormat | Protocol.DataFormat[]): {
         parsers: AnyParseFunction[];
         resultFields: FieldInfo[];
     };