postgrejs 3.4.0 → 3.6.0

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.
  *
@@ -41,6 +57,14 @@ const PREPARE_AFTER_USES = 2;
  * SQL that manages transaction boundaries itself, and so must never be
  * wrapped in a savepoint or an implicit BEGIN/COMMIT of ours.
  */
+/**
+ * What the prepared statement cache is keyed on. The parameter OIDs are
+ * part of it because the server fixes them at Parse: the same SQL bound
+ * with different types is a different plan.
+ */
+function preparedCacheKey(sql, paramTypes) {
+    return paramTypes?.length ? sql + '\u0000' + paramTypes.join(',') : sql;
+}
 const TRANSACTION_COMMAND_PATTERN = /^(\bBEGIN\b|\bCOMMIT\b|\bSTART\b|\bROLLBACK|SAVEPOINT|RELEASE\b)/i;
 export class IntlConnection extends SafeEventEmitter {
     /**
@@ -259,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);
@@ -291,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) {
@@ -351,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 });
@@ -515,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:
@@ -531,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)
@@ -627,9 +651,7 @@ export class IntlConnection extends SafeEventEmitter {
         const enabled = options.prepare ?? this.config.prepare ?? true;
         if (!enabled)
             return this.queryOnce(sql, paramTypes, params, options, savepoint);
-        const key = paramTypes?.length
-            ? sql + '\u0000' + paramTypes.join(',')
-            : sql;
+        const key = preparedCacheKey(sql, paramTypes);
         const cached = this._preparedCache.get(key);
         if (cached) {
             // Re-insert to mark it most recently used.
@@ -653,12 +675,14 @@ export class IntlConnection extends SafeEventEmitter {
                 return result;
             }
         }
-        const uses = (this._preparedCandidates.get(key) || 0) + 1;
-        if (uses < PREPARE_AFTER_USES) {
-            this._preparedCandidates.set(key, uses);
+        // 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);
-        }
-        this._preparedCandidates.delete(key);
         const name = 'C_' + ++this._preparedCounter;
         // A Parse that fails caches nothing and reports itself; the statement
         // is simply never reused. It runs outside the savepoint, as the
@@ -669,6 +693,19 @@ export class IntlConnection extends SafeEventEmitter {
         this._preparedCache.set(key, entry);
         return this.executeReused(name, entry.fields, paramTypes, params, options, savepoint);
     }
+    /**
+     * Counts one more use of this SQL and says whether it has now been seen
+     * often enough to be worth preparing under a name.
+     */
+    _earnsAName(key) {
+        const uses = (this._preparedCandidates.get(key) || 0) + 1;
+        if (uses < PREPARE_AFTER_USES) {
+            this._preparedCandidates.set(key, uses);
+            return false;
+        }
+        this._preparedCandidates.delete(key);
+        return true;
+    }
     /** Closes the least recently used statement once the cache is full. */
     async _evictPreparedIfFull() {
         const max = this.config.preparedStatementCacheSize ?? 64;
@@ -719,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;
@@ -727,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) => {
@@ -738,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;
@@ -781,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;
@@ -858,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,
         });
@@ -914,94 +978,183 @@ export class IntlConnection extends SafeEventEmitter {
             const timingEnabled = options.timing ?? this.config.timing ?? false;
             const startTime = timingEnabled ? performance.now() : 0;
             const rowDecoder = resolveRowDecoder(options);
-            const columnFormat = options.columnFormat != null
-                ? options.columnFormat
-                : DEFAULT_COLUMN_FORMAT;
             const results = [];
             let pendingFields;
             let pendingRows;
             let error;
-            const statements = requests.map(r => ({
-                // Per statement, not per pipeline: the statements differ, so a
-                // single shared list of parameter OIDs could only ever be right
-                // for one of them.
-                parse: { sql: r.sql, paramTypes: r.paramTypes },
-                bind: {
-                    typeMap,
-                    paramTypes: r.paramTypes,
-                    params: r.params,
-                    queryOptions: options,
-                },
-                describe: { type: 'P' },
-                // Unlimited, never options.fetchCount: a suspended portal would
-                // break the positional statement-to-result mapping.
-                execute: { fetchCount: 0 },
-            }));
+            // Plan every statement against the prepared statement cache before
+            // writing anything: one that is already prepared binds to its name
+            // and skips both Parse and Describe, one seen often enough earns a
+            // name here, and the rest go out unnamed exactly as before.
+            const prepareEnabled = options.prepare ?? this.config.prepare ?? true;
+            const plans = [];
+            const promotions = [];
+            const cachedKeys = [];
+            const named = new Map();
+            const statements = [];
+            for (const r of requests) {
+                const key = prepareEnabled
+                    ? preparedCacheKey(r.sql, r.paramTypes)
+                    : undefined;
+                // A repeat can only skip its own Parse if the statement it binds
+                // to has a name. An unnamed one would be gone by now: any later
+                // statement's Parse replaces it.
+                let plan = key != null ? named.get(key) : undefined;
+                let sendParse = !plan;
+                let sendDescribe = !plan;
+                if (!plan) {
+                    const cached = key != null ? this._preparedCache.get(key) : undefined;
+                    if (cached && key != null) {
+                        // Re-insert to mark it most recently used.
+                        this._preparedCache.delete(key);
+                        this._preparedCache.set(key, cached);
+                        cachedKeys.push(key);
+                        plan = { name: cached.name, fields: cached.fields };
+                        sendParse = false;
+                        sendDescribe = false;
+                    }
+                    else if (key != null && this._earnsAName(key)) {
+                        plan = { name: 'C_' + ++this._preparedCounter };
+                        promotions.push({ key, plan });
+                    }
+                    else {
+                        plan = {};
+                    }
+                    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
+                    // single shared list of parameter OIDs could only ever be right
+                    // for one of them.
+                    parse: sendParse
+                        ? { sql: r.sql, paramTypes: r.paramTypes, statement: plan.name }
+                        : undefined,
+                    bind: {
+                        typeMap,
+                        statement: plan.name,
+                        paramTypes: r.paramTypes,
+                        params: r.params,
+                        queryOptions: options,
+                        columnFormat: plan.columnFormat,
+                    },
+                    describe: sendDescribe ? { type: 'P' } : undefined,
+                    // Unlimited, never options.fetchCount: a suspended portal would
+                    // break the positional statement-to-result mapping.
+                    execute: { fetchCount: 0 },
+                });
+            }
             this.runningQueryCount++;
-            await this.socket
-                .sendPipelineMessages({ statements }, (code, msg, done) => {
-                switch (code) {
-                    case Protocol.BackendMessageCode.ParseComplete:
-                    case Protocol.BackendMessageCode.BindComplete:
-                    case Protocol.BackendMessageCode.NoticeResponse:
-                        break;
-                    case Protocol.BackendMessageCode.NoData:
-                        pendingFields = undefined;
-                        break;
-                    case Protocol.BackendMessageCode.RowDescription:
-                        pendingFields = msg.fields;
-                        break;
-                    case Protocol.BackendMessageCode.DataRow:
-                        (pendingRows || (pendingRows = [])).push(msg);
-                        break;
-                    case Protocol.BackendMessageCode.EmptyQueryResponse:
-                    case Protocol.BackendMessageCode.CommandComplete: {
-                        const result = { command: msg?.command };
-                        if (pendingFields) {
-                            const parsers = getParsers(typeMap, pendingFields);
-                            const resultFields = wrapRowDescription(typeMap, pendingFields, columnFormat);
-                            result.fields = resultFields;
-                            result.rowType = resolveRowType(options);
-                            if (!result.command)
-                                result.command = 'SELECT';
-                            const rows = pendingRows || [];
-                            const l = rows.length;
-                            let i;
-                            for (i = 0; i < l; i++) {
-                                rows[i] = rowDecoder.decode(parsers, rows[i].data, rows[i].columnCount, options, resultFields);
+            try {
+                await this.socket
+                    .sendPipelineMessages({ statements }, (code, msg, done) => {
+                    switch (code) {
+                        case Protocol.BackendMessageCode.ParseComplete:
+                        case Protocol.BackendMessageCode.BindComplete:
+                        case Protocol.BackendMessageCode.NoticeResponse:
+                            break;
+                        case Protocol.BackendMessageCode.NoData:
+                            pendingFields = undefined;
+                            break;
+                        case Protocol.BackendMessageCode.RowDescription:
+                            pendingFields = msg.fields;
+                            break;
+                        case Protocol.BackendMessageCode.DataRow:
+                            (pendingRows || (pendingRows = [])).push(msg);
+                            break;
+                        case Protocol.BackendMessageCode.EmptyQueryResponse:
+                        case Protocol.BackendMessageCode.CommandComplete: {
+                            const plan = plans[results.length];
+                            // A statement bound to a cached name sent no Describe, so
+                            // its columns come from the cache entry instead; one being
+                            // prepared here records its RowDescription for the entry it
+                            // is about to become, and for any repeat behind it.
+                            if (pendingFields)
+                                plan.fields = pendingFields;
+                            const fields = pendingFields || plan.fields;
+                            const result = { command: msg?.command };
+                            if (fields) {
+                                const { parsers, resultFields } = this._resolveReusedParsers(fields, typeMap, options, plan.columnFormat ?? DEFAULT_COLUMN_FORMAT);
+                                result.fields = resultFields;
+                                result.rowType = resolveRowType(options);
+                                if (!result.command)
+                                    result.command = 'SELECT';
+                                const rows = pendingRows || [];
+                                const l = rows.length;
+                                let i;
+                                for (i = 0; i < l; i++) {
+                                    rows[i] = rowDecoder.decode(parsers, rows[i].data, rows[i].columnCount, options, resultFields);
+                                }
+                                result.rows = rows;
                             }
-                            result.rows = rows;
+                            if (reportsRowsAffected(result.command))
+                                result.rowsAffected = msg.rowCount;
+                            pendingFields = undefined;
+                            pendingRows = undefined;
+                            results.push(result);
+                            break;
                         }
-                        if (result.command === 'DELETE' ||
-                            result.command === 'INSERT' ||
-                            result.command === 'UPDATE')
-                            result.rowsAffected = msg.rowCount;
-                        pendingFields = undefined;
-                        pendingRows = undefined;
-                        results.push(result);
-                        break;
+                        case Protocol.BackendMessageCode.ErrorResponse:
+                            error = msg;
+                            break;
+                        case Protocol.BackendMessageCode.ReadyForQuery:
+                            this.transactionStatus = msg.status;
+                            done(error);
+                            break;
+                        default:
+                            done(new Error(`Server returned unexpected response message (${String.fromCharCode(code)})`));
                     }
-                    case Protocol.BackendMessageCode.ErrorResponse:
-                        error = msg;
-                        break;
-                    case Protocol.BackendMessageCode.ReadyForQuery:
-                        this.transactionStatus = msg.status;
-                        done(error);
-                        break;
-                    default:
-                        done(new Error(`Server returned unexpected response message (${String.fromCharCode(code)})`));
-                }
-            })
-                .catch((e) => {
-                // The rejected statement is the one right after everything that
-                // completed, since results only grow on CommandComplete.
-                if (e instanceof DatabaseError && error === e)
-                    e.failedIndex = results.length;
-                throw e;
-            })
-                .finally(() => {
-                this.runningQueryCount--;
-            });
+                })
+                    .catch((e) => {
+                    // The rejected statement is the one right after everything
+                    // that completed, since results only grow on CommandComplete.
+                    if (e instanceof DatabaseError && error === e)
+                        e.failedIndex = results.length;
+                    throw e;
+                })
+                    .finally(() => {
+                    this.runningQueryCount--;
+                });
+            }
+            catch (e) {
+                // A cached statement can be invalidated between two pipelines the
+                // same way a cached single query can (0A000, "cached plan must not
+                // change result type"). Drop what this pipeline reused and run it
+                // again unprepared - once, since the second attempt has nothing
+                // cached left to reuse.
+                if (e?.code !== '0A000' || !cachedKeys.length)
+                    throw e;
+                for (const k of cachedKeys)
+                    this._preparedCache.delete(k);
+                // Inside an explicit transaction there is nothing to retry into:
+                // the failed statement has already aborted the block.
+                if (this.inTransaction)
+                    throw e;
+                return await this.executePipeline(requests, options);
+            }
+            // Only now, with every Parse answered, are the new names real.
+            let promo;
+            let p;
+            const promotionCount = promotions.length;
+            for (p = 0; p < promotionCount; p++) {
+                promo = promotions[p];
+                await this._evictPreparedIfFull();
+                this._preparedCache.set(promo.key, {
+                    name: promo.plan.name,
+                    fields: promo.plan.fields,
+                });
+            }
             if (timingEnabled) {
                 const elapsed = performance.now() - startTime;
                 const l = results.length;
@@ -1025,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;
             }
@@ -1039,6 +1193,7 @@ export class IntlConnection extends SafeEventEmitter {
                 paramTypes,
                 params,
                 queryOptions: options,
+                columnFormat,
             }));
             this.runningQueryCount++;
             await this.socket
@@ -1060,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;
@@ -1130,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;
@@ -1152,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) => {
@@ -1161,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);
@@ -1202,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.d.ts

@@ -70,6 +70,22 @@ export declare class Pool extends SafeEventEmitter {
      * Executes a query
      */
     query(sql: string | QueryRequest, options?: PoolQueryOptions): Promise<QueryResult>;
+    /**
+     * Takes a connection out of the pool, runs `fn` inside a transaction on
+     * it, and gives the connection back however that ends.
+     *
+     * ```ts
+     * await pool.transaction(async tx => {
+     *   await tx.query('insert into orders (total) values ($1)', { params: [total] });
+     *   await tx.query('update stock set n = n - 1 where sku = $1', { params: [sku] });
+     * });
+     * ```
+     *
+     * A transaction cannot be spread over pool.query() calls - each of those
+     * 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>;
     prepare(sql: string, options?: StatementPrepareOptions): Promise<PreparedStatement>;
     release(connection: Connection): Promise<void>;
     listen(channel: string, callback: NotificationCallback): Promise<void>;