postgrejs 3.5.0 → 3.6.0

package/CHANGELOG.md

@@ -1,6 +1,31 @@
 ## Changelog
 
-### [v3.5.0](https://github.com/panates/postgrejs/compare/v3.4.0...v3.5.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
 

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,16 +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.
+- **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.
+  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.
@@ -119,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.

package/connection/connection.js

@@ -2,6 +2,8 @@ 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';
@@ -599,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));
@@ -613,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() {
@@ -682,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() {

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) {

package/connection/intl-connection.d.ts

@@ -245,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[];
     };

package/connection/intl-connection.js

@@ -9,6 +9,7 @@ import { getConnectionConfig } from '../util/connection-config.js';
 import { buildCopySql, buildProbeSql, writeCopyBinaryRows, } from '../util/copy-from-rows.js';
 import { escapeLiteral } from '../util/escape-literal.js';
 import { getParsers } from '../util/get-parsers.js';
+import { fetchAsStringEqual, resolveColumnFormats, } from '../util/resolve-column-formats.js';
 import { resolveRowDecoder, resolveRowType } from '../util/row-decoder.js';
 import { wrapRowDescription } from '../util/wrap-row-description.js';
 import { CopyFromStream, CopyToStream } from './copy-stream.js';
@@ -27,6 +28,21 @@ function columnFormatsEqual(a, b) {
             return false;
     return true;
 }
+/**
+ * Whether a command tag's row count describes rows the statement changed,
+ * rather than rows it returned or moved. SELECT, FETCH, MOVE and COPY all
+ * carry a count of their own that would be misleading as `rowsAffected`.
+ *
+ * MERGE has reported its own total (inserted + updated + deleted) since
+ * PostgreSQL 15; _handleCommandComplete() has always parsed it, and this
+ * is what stops it being dropped on the floor.
+ */
+function reportsRowsAffected(command) {
+    return (command === 'INSERT' ||
+        command === 'UPDATE' ||
+        command === 'DELETE' ||
+        command === 'MERGE');
+}
 /**
  * Uses of the same SQL before it is worth preparing.
  *
@@ -267,7 +283,7 @@ export class IntlConnection extends SafeEventEmitter {
      * nesting the existing one.
      */
     async savepoint(name) {
-        if (!(name && name.match(/^[a-zA-Z]\w+$/)))
+        if (!(name && name.match(/^[a-zA-Z]\w*$/)))
             throw new Error(`Invalid savepoint "${name}"`);
         const depth = (this._savepointDepths.get(name) || 0) + 1;
         this._savepointDepths.set(name, depth);
@@ -299,7 +315,7 @@ export class IntlConnection extends SafeEventEmitter {
      * @param immediate - Ignores the tracked depth and releases right away.
      */
     async releaseSavepoint(name, immediate) {
-        if (!(name && name.match(/^[a-zA-Z]\w+$/)))
+        if (!(name && name.match(/^[a-zA-Z]\w*$/)))
             throw new Error(`Invalid savepoint "${name}"`);
         const depth = this._savepointDepths.get(name) || 0;
         if (!immediate && depth > 1) {
@@ -359,7 +375,7 @@ export class IntlConnection extends SafeEventEmitter {
      * unwind.
      */
     async rollbackToSavepoint(name) {
-        if (!(name && name.match(/^[a-zA-Z]\w+$/)))
+        if (!(name && name.match(/^[a-zA-Z]\w*$/)))
             throw new Error(`Invalid savepoint "${name}"`);
         this._savepointDepths.delete(name);
         await this.execute('ROLLBACK TO SAVEPOINT ' + name, { autoCommit: false });
@@ -523,8 +539,11 @@ export class IntlConnection extends SafeEventEmitter {
                         break;
                     case Protocol.BackendMessageCode.RowDescription:
                         fields = msg.fields;
-                        parsers = getParsers(typeMap, fields);
-                        current.fields = wrapRowDescription(typeMap, fields, DataFormat.text);
+                        // Simple Query has no Bind at all, so every column is
+                        // already text - a fetchAsString column simply comes back
+                        // unparsed.
+                        parsers = getParsers(typeMap, fields, options);
+                        current.fields = wrapRowDescription(typeMap, fields, DataFormat.text, options);
                         current.rows = [];
                         break;
                     case Protocol.BackendMessageCode.DataRow:
@@ -539,11 +558,8 @@ export class IntlConnection extends SafeEventEmitter {
                     case Protocol.BackendMessageCode.CommandComplete:
                         // Ignore BEGIN command that we added to sql
                         current.command = msg.command;
-                        if (current.command === 'DELETE' ||
-                            current.command === 'INSERT' ||
-                            current.command === 'UPDATE') {
+                        if (reportsRowsAffected(current.command))
                             current.rowsAffected = msg.rowCount;
-                        }
                         if (timingEnabled)
                             current.executeTime = performance.now() - currentStart;
                         if (current.rows)
@@ -659,7 +675,13 @@ export class IntlConnection extends SafeEventEmitter {
                 return result;
             }
         }
-        if (!this._earnsAName(key))
+        // A fetchAsString query needs its RowDescription before the Bind that
+        // asks for those columns as text, and only a named statement has one
+        // in hand ahead of time. Preparing on first sight pays a single
+        // Parse+Describe round trip per connection instead of leaving every
+        // call until the statement earns a name asking for the whole row as
+        // text (what queryOnce() falls back to).
+        if (!options.fetchAsString?.length && !this._earnsAName(key))
             return this.queryOnce(sql, paramTypes, params, options, savepoint);
         const name = 'C_' + ++this._preparedCounter;
         // A Parse that fails caches nothing and reports itself; the statement
@@ -734,7 +756,24 @@ export class IntlConnection extends SafeEventEmitter {
             let resultFields;
             let commandTag;
             let error;
+            let suspended = false;
             const rowDecoder = resolveRowDecoder(options);
+            // fetchAsString names OIDs, but Bind's result format codes are
+            // positional - and this path's Describe answers only after the Bind
+            // that would have to carry them. With no column types to map the
+            // list onto, the whole row is asked for as text instead: the listed
+            // columns then arrive exactly as the server renders them, which is
+            // what was asked for, and the rest cost a text decode.
+            //
+            // Only `prepare: false` normally reaches here with a list set -
+            // _queryCached() prepares a fetchAsString query on first sight
+            // precisely so it can send per-column codes from the second call on
+            // (from the first, for every connection that has seen the SQL).
+            const columnFormat = options.fetchAsString?.length
+                ? DataFormat.text
+                : options.columnFormat != null
+                    ? options.columnFormat
+                    : DEFAULT_COLUMN_FORMAT;
             // See executeReused() for what a savepoint riding along does to the
             // CommandComplete stream.
             let leadingCommandTags = savepoint ? 1 : 0;
@@ -742,9 +781,15 @@ export class IntlConnection extends SafeEventEmitter {
             await this.socket
                 .sendExtendedQueryMessages({
                 parse: { sql, paramTypes },
-                bind: { typeMap, paramTypes, params, queryOptions: options },
+                bind: {
+                    typeMap,
+                    paramTypes,
+                    params,
+                    queryOptions: options,
+                    columnFormat,
+                },
                 describe: { type: 'P' },
-                execute: { fetchCount: options.fetchCount || 100 },
+                execute: { fetchCount: options.fetchCount ?? 0 },
                 before: savepoint ? 'SAVEPOINT ' + savepoint : undefined,
                 after: savepoint ? 'RELEASE ' + savepoint : undefined,
             }, (code, msg, done) => {
@@ -753,11 +798,17 @@ export class IntlConnection extends SafeEventEmitter {
                     case Protocol.BackendMessageCode.BindComplete:
                     case Protocol.BackendMessageCode.NoData:
                     case Protocol.BackendMessageCode.NoticeResponse:
+                        break;
+                    // The server stopped at the fetchCount limit rather than
+                    // running out of rows. The Sync that closes this call
+                    // discards the portal, so the rest is gone - all that can be
+                    // done is say the result is a prefix.
                     case Protocol.BackendMessageCode.PortalSuspended:
+                        suspended = true;
                         break;
                     case Protocol.BackendMessageCode.RowDescription:
-                        parsers = getParsers(typeMap, msg.fields);
-                        resultFields = wrapRowDescription(typeMap, msg.fields, options.columnFormat || DEFAULT_COLUMN_FORMAT);
+                        parsers = getParsers(typeMap, msg.fields, options);
+                        resultFields = wrapRowDescription(typeMap, msg.fields, columnFormat, options);
                         result.fields = resultFields;
                         result.rowType = resolveRowType(options);
                         break;
@@ -796,11 +847,10 @@ export class IntlConnection extends SafeEventEmitter {
                     rows[i] = rowDecoder.decode(parsers, rows[i].data, rows[i].columnCount, options, resultFields);
                 }
             }
-            if (result.command === 'DELETE' ||
-                result.command === 'INSERT' ||
-                result.command === 'UPDATE') {
+            if (suspended)
+                result.suspended = true;
+            if (reportsRowsAffected(result.command))
                 result.rowsAffected = commandTag?.rowCount;
-            }
             if (timingEnabled)
                 result.executeTime = performance.now() - startTime;
             return result;
@@ -873,25 +923,24 @@ export class IntlConnection extends SafeEventEmitter {
      * so repeated executes of the same statement don't rebuild them.
      * Shared by executeReused() and executeBatchReused().
      */
-    _resolveReusedParsers(cachedFields, typeMap, options) {
-        const columnFormat = options.columnFormat != null
-            ? options.columnFormat
-            : DEFAULT_COLUMN_FORMAT;
+    _resolveReusedParsers(cachedFields, typeMap, options, columnFormat) {
         const cached = this._executeReusedParserCache.get(cachedFields);
         if (cached &&
             cached.typeMap === typeMap &&
-            columnFormatsEqual(cached.columnFormat, columnFormat)) {
+            columnFormatsEqual(cached.columnFormat, columnFormat) &&
+            fetchAsStringEqual(cached.fetchAsString, options.fetchAsString)) {
             return { parsers: cached.parsers, resultFields: cached.resultFields };
         }
         const fields = cachedFields.map((f, i) => ({
             ...f,
             format: Array.isArray(columnFormat) ? columnFormat[i] : columnFormat,
         }));
-        const parsers = getParsers(typeMap, fields);
-        const resultFields = wrapRowDescription(typeMap, fields, columnFormat);
+        const parsers = getParsers(typeMap, fields, options);
+        const resultFields = wrapRowDescription(typeMap, fields, columnFormat, options);
         this._executeReusedParserCache.set(cachedFields, {
             typeMap,
             columnFormat,
+            fetchAsString: options.fetchAsString,
             parsers,
             resultFields,
         });
@@ -974,6 +1023,16 @@ export class IntlConnection extends SafeEventEmitter {
                     if (key != null && plan.name)
                         named.set(key, plan);
                 }
+                // Only a statement whose columns are already known can carry
+                // per-column codes; the rest fall back to asking for the whole row
+                // as text, exactly as queryOnce() does and for the same reason.
+                plan.columnFormat = plan.fields
+                    ? resolveColumnFormats(plan.fields, options)
+                    : options.fetchAsString?.length
+                        ? DataFormat.text
+                        : options.columnFormat != null
+                            ? options.columnFormat
+                            : DEFAULT_COLUMN_FORMAT;
                 plans.push(plan);
                 statements.push({
                     // Per statement, not per pipeline: the statements differ, so a
@@ -988,6 +1047,7 @@ export class IntlConnection extends SafeEventEmitter {
                         paramTypes: r.paramTypes,
                         params: r.params,
                         queryOptions: options,
+                        columnFormat: plan.columnFormat,
                     },
                     describe: sendDescribe ? { type: 'P' } : undefined,
                     // Unlimited, never options.fetchCount: a suspended portal would
@@ -1025,7 +1085,7 @@ export class IntlConnection extends SafeEventEmitter {
                             const fields = pendingFields || plan.fields;
                             const result = { command: msg?.command };
                             if (fields) {
-                                const { parsers, resultFields } = this._resolveReusedParsers(fields, typeMap, options);
+                                const { parsers, resultFields } = this._resolveReusedParsers(fields, typeMap, options, plan.columnFormat ?? DEFAULT_COLUMN_FORMAT);
                                 result.fields = resultFields;
                                 result.rowType = resolveRowType(options);
                                 if (!result.command)
@@ -1038,9 +1098,7 @@ export class IntlConnection extends SafeEventEmitter {
                                 }
                                 result.rows = rows;
                             }
-                            if (result.command === 'DELETE' ||
-                                result.command === 'INSERT' ||
-                                result.command === 'UPDATE')
+                            if (reportsRowsAffected(result.command))
                                 result.rowsAffected = msg.rowCount;
                             pendingFields = undefined;
                             pendingRows = undefined;
@@ -1120,8 +1178,9 @@ export class IntlConnection extends SafeEventEmitter {
             const rowDecoder = resolveRowDecoder(options);
             let parsers;
             let resultFields;
+            const columnFormat = resolveColumnFormats(cachedFields, options);
             if (cachedFields) {
-                const resolved = this._resolveReusedParsers(cachedFields, typeMap, options);
+                const resolved = this._resolveReusedParsers(cachedFields, typeMap, options, columnFormat);
                 parsers = resolved.parsers;
                 resultFields = resolved.resultFields;
             }
@@ -1134,6 +1193,7 @@ export class IntlConnection extends SafeEventEmitter {
                 paramTypes,
                 params,
                 queryOptions: options,
+                columnFormat,
             }));
             this.runningQueryCount++;
             await this.socket
@@ -1155,9 +1215,7 @@ export class IntlConnection extends SafeEventEmitter {
                         const item = {};
                         if (msg?.command)
                             item.command = msg.command;
-                        if (item.command === 'DELETE' ||
-                            item.command === 'INSERT' ||
-                            item.command === 'UPDATE')
+                        if (reportsRowsAffected(item.command))
                             item.rowsAffected = msg.rowCount;
                         if (pendingRows && parsers && resultFields) {
                             const l = pendingRows.length;
@@ -1225,9 +1283,15 @@ export class IntlConnection extends SafeEventEmitter {
             let resultFields;
             let commandTag;
             let error;
+            let suspended = false;
             const rowDecoder = resolveRowDecoder(options);
+            // The whole point of reusing a prepared statement here: its
+            // RowDescription is already in hand, so fetchAsString's OID list can
+            // become the per-column result format codes this Bind carries, with
+            // no extra round trip to find out what the columns are.
+            const columnFormat = resolveColumnFormats(cachedFields, options);
             if (cachedFields) {
-                const resolved = this._resolveReusedParsers(cachedFields, typeMap, options);
+                const resolved = this._resolveReusedParsers(cachedFields, typeMap, options, columnFormat);
                 parsers = resolved.parsers;
                 resultFields = resolved.resultFields;
                 result.fields = resultFields;
@@ -1247,8 +1311,9 @@ export class IntlConnection extends SafeEventEmitter {
                     paramTypes,
                     params,
                     queryOptions: options,
+                    columnFormat,
                 },
-                execute: { fetchCount: options.fetchCount || 100 },
+                execute: { fetchCount: options.fetchCount ?? 0 },
                 before: savepoint ? 'SAVEPOINT ' + savepoint : undefined,
                 after: savepoint ? 'RELEASE ' + savepoint : undefined,
             }, (code, msg, done) => {
@@ -1256,7 +1321,10 @@ export class IntlConnection extends SafeEventEmitter {
                     case Protocol.BackendMessageCode.ParseComplete:
                     case Protocol.BackendMessageCode.BindComplete:
                     case Protocol.BackendMessageCode.NoticeResponse:
+                        break;
+                    // See queryOnce() for what a suspended portal means here.
                     case Protocol.BackendMessageCode.PortalSuspended:
+                        suspended = true;
                         break;
                     case Protocol.BackendMessageCode.DataRow:
                         rows.push(msg);
@@ -1297,11 +1365,10 @@ export class IntlConnection extends SafeEventEmitter {
                     rows[i] = rowDecoder.decode(parsers, rows[i].data, rows[i].columnCount, options, resultFields);
                 }
             }
-            if (result.command === 'DELETE' ||
-                result.command === 'INSERT' ||
-                result.command === 'UPDATE') {
+            if (suspended)
+                result.suspended = true;
+            if (reportsRowsAffected(result.command))
                 result.rowsAffected = commandTag?.rowCount;
-            }
             if (timingEnabled)
                 result.executeTime = performance.now() - startTime;
             return result;

package/connection/pool.js

@@ -2,6 +2,7 @@ import { Pool as LightningPool, } from 'lightning-pool';
 import { coerceToBoolean, coerceToInt } from 'putil-varhelpers';
 import { ConnectionState } from '../constants.js';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
+import { normalizeChannelName } from '../util/channel-name.js';
 import { getConnectionConfig } from '../util/connection-config.js';
 import { QueryRequest } from '../util/sql-tag.js';
 import { startsCopy, startsTransaction } from '../util/starts-transaction.js';
@@ -205,12 +206,32 @@ export class Pool extends SafeEventEmitter {
             : undefined;
         if (!slot) {
             const connection = await this.acquire();
+            let result;
             try {
-                return await connection.query(sql, options);
+                result = await connection.query(sql, options);
             }
-            finally {
+            catch (e) {
                 await this.release(connection);
+                throw e;
+            }
+            // A portal lives only as long as the transaction it was created in,
+            // and outside an explicit one that is the implicit transaction any
+            // other statement's Sync ends. So a connection carrying an open
+            // cursor cannot go back in the pool when this call returns - handing
+            // it to the next caller would destroy the cursor's portal, and did
+            // ("portal ... does not exist", nondeterministically, depending on
+            // which connection that caller happened to get). It goes back when
+            // the cursor closes instead, which for-await and `await using` both
+            // do on their own; a cursor that is never closed holds its
+            // connection until the pool itself is closed.
+            if (result.cursor) {
+                result.cursor.once('close', () => {
+                    this.release(connection).catch(e => this.emit('error', e));
+                });
+                return result;
             }
+            await this.release(connection);
+            return result;
         }
         try {
             const shared = slot.connection || (await slot.promise);
@@ -256,8 +277,10 @@ export class Pool extends SafeEventEmitter {
         return this._pool.releaseAsync(getIntlConnection(connection));
     }
     async listen(channel, callback) {
-        if (!/^[A-Z]\w+$/i.test(channel))
-            throw new TypeError(`Invalid channel name`);
+        // Folded here as well as in Connection.listen(): this emitter's keys
+        // have to be the same strings the inner connection registers, or
+        // unListen() would miss them.
+        channel = normalizeChannelName(channel);
         // Bug: _initNotificationConnection() only ever bootstraps the shared
         // connection and registers every channel known at that moment - it
         // returns immediately once that connection already exists, so a second,
@@ -274,8 +297,7 @@ export class Pool extends SafeEventEmitter {
         }
     }
     async unListen(channel) {
-        if (!/^[A-Z]\w+$/i.test(channel))
-            throw new TypeError(`Invalid channel name`);
+        channel = normalizeChannelName(channel);
         this._notificationListeners.removeAllListeners(channel);
         if (!this._notificationListeners.eventNames().length) {
             await this.unListenAll();

package/connection/portal.d.ts

@@ -23,7 +23,7 @@ export declare class Portal {
      * no explicit BEGIN left transactionStatus 'I' and a later Execute on the
      * same named portal failed with "portal ... does not exist").
      */
-    bindAndRetrieveFields(params: Maybe<any[]>, queryOptions: QueryOptions): Promise<Protocol.RowDescription[]>;
+    bindAndRetrieveFields(params: Maybe<any[]>, queryOptions: QueryOptions, columnFormat?: Protocol.DataFormat | Protocol.DataFormat[]): Promise<Protocol.RowDescription[]>;
     execute(fetchCount?: number): Promise<PortalExecuteResult>;
     /**
      * Close + Sync as one request (see PgSocket.sendCloseAndSyncMessages()

package/connection/portal.js

@@ -22,7 +22,7 @@ export class Portal {
      * no explicit BEGIN left transactionStatus 'I' and a later Execute on the
      * same named portal failed with "portal ... does not exist").
      */
-    async bindAndRetrieveFields(params, queryOptions) {
+    async bindAndRetrieveFields(params, queryOptions, columnFormat) {
         const intoCon = getIntlConnection(this.connection);
         intoCon.ref();
         try {
@@ -35,6 +35,7 @@ export class Portal {
                     paramTypes: this._statement.paramTypes,
                     params,
                     queryOptions,
+                    columnFormat,
                 },
                 describe: { type: 'P', name: this.name },
             }, (code, msg, done) => {
@@ -68,7 +69,7 @@ export class Portal {
             const rows = [];
             const executePromise = socket.sendExecuteMessage({
                 portal: this.name,
-                fetchCount: fetchCount || 100,
+                fetchCount: fetchCount ?? 100,
             }, (code, msg, done) => {
                 switch (code) {
                     case Protocol.BackendMessageCode.NoticeResponse:

package/connection/prepared-statement.js

@@ -1,9 +1,9 @@
-import { DEFAULT_COLUMN_FORMAT } from '../constants.js';
 import { GlobalTypeMap } from '../data-type-map.js';
 import { Protocol } from '../protocol/protocol.js';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
 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 { wrapRowDescription } from '../util/wrap-row-description.js';
 import { Cursor } from './cursor.js';
@@ -208,10 +208,14 @@ export class PreparedStatement extends SafeEventEmitter {
             intlCon.ref();
             let portal = new Portal(this, 'P_' + ++portalCounter);
             try {
-                const fields = await portal.bindAndRetrieveFields(options.params, options);
+                // prepare() already fetched this statement's RowDescription, so
+                // fetchAsString's OID list can become per-column result format
+                // codes on the Bind below with no round trip of its own.
+                const columnFormat = resolveColumnFormats(this._fields, options);
+                const fields = await portal.bindAndRetrieveFields(options.params, options, columnFormat);
                 const typeMap = options.typeMap || GlobalTypeMap;
-                const parsers = getParsers(typeMap, fields);
-                const resultFields = wrapRowDescription(typeMap, fields, options.columnFormat || DEFAULT_COLUMN_FORMAT);
+                const parsers = getParsers(typeMap, fields, options);
+                const resultFields = wrapRowDescription(typeMap, fields, columnFormat, options);
                 const result = {
                     command: undefined,
                     fields: resultFields,