postgrejs 3.3.0 → 3.5.0

package/connection/intl-connection.js

@@ -1,10 +1,12 @@
 import { performance } from 'node:perf_hooks';
 import { ConnectionState, DEFAULT_COLUMN_FORMAT } from '../constants.js';
 import { GlobalTypeMap } from '../data-type-map.js';
+import { DatabaseError } from '../protocol/database-error.js';
 import { PgSocket } from '../protocol/pg-socket.js';
 import { Protocol } from '../protocol/protocol.js';
 import { SafeEventEmitter } from '../safe-event-emitter.js';
 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 { resolveRowDecoder, resolveRowType } from '../util/row-decoder.js';
@@ -25,7 +27,44 @@ function columnFormatsEqual(a, b) {
             return false;
     return true;
 }
+/**
+ * Uses of the same SQL before it is worth preparing.
+ *
+ * Preparing on first sight, as postgres.js does, pays Parse plus Describe
+ * and leaves a named statement behind for SQL that may never run again;
+ * waiting for the second use keeps a genuinely one-shot query at exactly
+ * today's cost. The repeated query pays one extra unprepared call before
+ * it starts saving, which it makes back immediately.
+ */
+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 {
+    /**
+     * Server-side prepared statements this connection has built, keyed by
+     * the SQL text and its parameter OIDs - both, because the OIDs are part
+     * of what was parsed, not just how it is bound.
+     *
+     * A Map, relied on for its insertion order: re-inserting on every hit
+     * makes the first entry the least recently used, which is what gets
+     * closed when the cache is full. Statements belong to the session, so
+     * this is per connection and dies with it.
+     */
+    _preparedCache = new Map();
+    /** SQL seen once but not yet prepared - see PREPARE_AFTER_USES. */
+    _preparedCandidates = new Map();
+    _preparedCounter = 0;
     _executeReusedParserCache = new WeakMap();
     _refCount = 0;
     _transactionDepth = 0;
@@ -116,7 +155,7 @@ export class IntlConnection extends SafeEventEmitter {
     }
     async execute(sql, options = {}, cb) {
         this.assertConnected();
-        const transactionCommand = sql.match(/^(\bBEGIN\b|\bCOMMIT\b|\bSTART\b|\bROLLBACK|SAVEPOINT|RELEASE\b)/i);
+        const transactionCommand = TRANSACTION_COMMAND_PATTERN.test(sql);
         let beginFirst = false;
         let commitLast = false;
         const { autoCommit } = options;
@@ -368,6 +407,69 @@ export class IntlConnection extends SafeEventEmitter {
      * Runs a COPY ... FROM STDIN and hands back a stream to feed it.
      * Resolves once the server is ready for data.
      */
+    /**
+     * Streams rows into a table with `COPY ... FROM STDIN (FORMAT binary)`,
+     * encoding each value with its own type's binary encoder.
+     *
+     * Binary COPY performs no conversion server-side, so the destination
+     * column types have to be known exactly. They are read from the server
+     * unless the caller supplies them: a Describe of `select <columns> from
+     * <table> where false` against the unnamed statement returns a
+     * RowDescription carrying each column's OID, which costs one round trip
+     * and leaves nothing to close (the next Parse replaces the unnamed
+     * statement). Letting PostgreSQL resolve the name is the reason to do it
+     * this way rather than reading the catalog here - schemas, quoting,
+     * search_path and views then behave exactly as they will for the COPY.
+     */
+    async copyFromRows(table, source, options = {}) {
+        this.assertConnected();
+        let columns = options.columns;
+        let dataTypeIds = options.columnTypes;
+        if (!dataTypeIds || !columns) {
+            const { fields } = await this.prepareOnce(buildProbeSql(table, columns), undefined, '');
+            if (!fields?.length)
+                throw new Error(`Cannot determine columns of "${table}" - it returned no column descriptions`);
+            columns = columns || fields.map(f => f.fieldName);
+            dataTypeIds = dataTypeIds || fields.map(f => f.dataTypeId);
+        }
+        if (columns.length !== dataTypeIds.length)
+            throw new Error(`columnTypes has ${dataTypeIds.length} entries but ${columns.length} columns were given`);
+        const stream = await this.copyFrom(buildCopySql(table, columns));
+        // The CopyFail sent below comes back as an ErrorResponse, which the
+        // stream emits as 'error'. Node turns an 'error' with no listener into
+        // an uncaught exception and takes the process down - so a value this
+        // method already rejected cleanly would kill the caller instead.
+        // Recorded rather than ignored, since the same listener covers a
+        // socket that dies mid-copy.
+        let streamError;
+        stream.on('error', e => {
+            streamError = streamError || e;
+        });
+        try {
+            const result = await writeCopyBinaryRows(source, {
+                columns,
+                dataTypeIds,
+                options,
+                write: chunk => new Promise((resolve, reject) => {
+                    const accepted = this.socket.sendCopyData(chunk, err => err ? reject(err) : resolve());
+                    // Taken without buffering - no reason to wait for the write
+                    // callback, which would add a turn of latency per chunk.
+                    if (accepted)
+                        resolve();
+                }),
+            });
+            await new Promise(resolve => stream.end(resolve));
+            if (streamError)
+                throw streamError;
+            return result;
+        }
+        catch (e) {
+            // Tell the server to abandon the copy rather than leaving it waiting
+            // for a stream that will never arrive.
+            this.socket.sendCopyFail(e instanceof Error ? e.message : 'copyFromRows() failed');
+            throw e;
+        }
+    }
     async copyFrom(sql) {
         this.assertConnected();
         this.ref();
@@ -482,7 +584,144 @@ export class IntlConnection extends SafeEventEmitter {
      * +close()'s 7 round trips whenever there's no cursor and no explicit/
      * active transaction to wrap (see Connection.query() for that gating).
      */
-    async queryOnce(sql, paramTypes, params, options) {
+    /**
+     * Runs a one-shot extended query, reusing a server-side prepared
+     * statement when this connection has run the same SQL before.
+     *
+     * A repeated query then costs Bind/Execute instead of
+     * Parse/Bind/Describe/Execute, which the server can answer without
+     * planning again - fifty concurrent calls of one statement measured
+     * 0.97ms against 3.13ms, and socket reads dropped from 38 to 8.
+     *
+     * Nothing is prepared on first sight: SQL has to be seen
+     * PREPARE_AFTER_USES times before it earns a name, so a query that runs
+     * once costs exactly what it costs today.
+     *
+     * A cached statement can be invalidated under us - `alter table` between
+     * two calls makes PostgreSQL answer 0A000, "cached plan must not change
+     * result type". That is caught here: the entry is dropped and the query
+     * runs again unprepared, so a migration against a live connection
+     * recovers instead of failing every call from then on.
+     */
+    async queryCached(sql, paramTypes, params, options) {
+        const savepoint = this._inlineSavepointFor(sql, options);
+        try {
+            return await this._queryCached(sql, paramTypes, params, options, savepoint);
+        }
+        catch (e) {
+            // PostgreSQL throws away everything between a failed statement and
+            // the Sync, so an inlined RELEASE never ran and the savepoint is
+            // still standing. Rolling back to it leaves the transaction usable,
+            // which is the whole point of rollbackOnError - and it is left
+            // standing afterwards, as the separate-round-trip wrapper left it.
+            if (savepoint)
+                await this._execute('ROLLBACK TO ' + savepoint);
+            throw e;
+        }
+    }
+    /**
+     * The savepoint rollbackOnError calls for, or undefined when this call
+     * needs none: outside a transaction there is nothing to roll back to,
+     * and a statement that is itself a transaction command manages its own
+     * boundaries (wrapping COMMIT in a savepoint would be nonsense).
+     */
+    _inlineSavepointFor(sql, options) {
+        if (!this.inTransaction || TRANSACTION_COMMAND_PATTERN.test(sql))
+            return undefined;
+        const on = options.rollbackOnError ?? this.config.rollbackOnError ?? true;
+        return on ? this._onErrorSavePoint : undefined;
+    }
+    async _queryCached(sql, paramTypes, params, options, savepoint) {
+        const enabled = options.prepare ?? this.config.prepare ?? true;
+        if (!enabled)
+            return this.queryOnce(sql, paramTypes, params, options, savepoint);
+        const key = preparedCacheKey(sql, paramTypes);
+        const cached = this._preparedCache.get(key);
+        if (cached) {
+            // Re-insert to mark it most recently used.
+            this._preparedCache.delete(key);
+            this._preparedCache.set(key, cached);
+            try {
+                return await this.executeReused(cached.name, cached.fields, paramTypes, params, options, savepoint);
+            }
+            catch (e) {
+                if (e?.code !== '0A000')
+                    throw e;
+                this._preparedCache.delete(key);
+                // ROLLBACK TO leaves the savepoint itself in place, so the retry
+                // must not open a second one under the same name - it runs bare
+                // and releases the one already held.
+                if (savepoint)
+                    await this._execute('ROLLBACK TO ' + savepoint);
+                const result = await this.queryOnce(sql, paramTypes, params, options);
+                if (savepoint)
+                    await this._execute('RELEASE ' + savepoint);
+                return result;
+            }
+        }
+        if (!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
+        // is simply never reused. It runs outside the savepoint, as the
+        // prepare() the transaction path used to do ahead of its own wrapper.
+        const { fields } = await this.prepareOnce(sql, paramTypes, name);
+        const entry = { name, fields };
+        await this._evictPreparedIfFull();
+        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;
+        while (this._preparedCache.size >= max) {
+            const oldest = this._preparedCache.keys().next();
+            if (oldest.done)
+                return;
+            const entry = this._preparedCache.get(oldest.value);
+            this._preparedCache.delete(oldest.value);
+            // A statement that cannot be closed is already gone as far as this
+            // connection is concerned; losing the cache entry is the part that
+            // matters, and failing the caller's query over it would be worse.
+            await this._closePreparedStatement(entry.name).catch(() => undefined);
+        }
+    }
+    /**
+     * Closes an evicted statement server-side. Close answers CloseComplete
+     * but no ReadyForQuery, so the Sync goes separately and both are awaited
+     * together - the same shape PreparedStatement._close() uses.
+     */
+    async _closePreparedStatement(name) {
+        const closed = this.socket.sendCloseMessage({ type: 'S', name }, (code, msg, done) => {
+            if (code === Protocol.BackendMessageCode.CloseComplete)
+                done(undefined);
+            else if (code === Protocol.BackendMessageCode.ErrorResponse)
+                done(msg);
+        });
+        const synced = this.socket.sendSyncMessage((code, msg, done) => {
+            if (code === Protocol.BackendMessageCode.ReadyForQuery) {
+                this.transactionStatus = msg.status;
+                done(undefined);
+            }
+            else if (code === Protocol.BackendMessageCode.ErrorResponse)
+                done(msg);
+        });
+        await Promise.all([closed, synced]);
+    }
+    async queryOnce(sql, paramTypes, params, options, savepoint) {
         this.assertConnected();
         this.ref();
         try {
@@ -496,6 +735,9 @@ export class IntlConnection extends SafeEventEmitter {
             let commandTag;
             let error;
             const rowDecoder = resolveRowDecoder(options);
+            // See executeReused() for what a savepoint riding along does to the
+            // CommandComplete stream.
+            let leadingCommandTags = savepoint ? 1 : 0;
             this.runningQueryCount++;
             await this.socket
                 .sendExtendedQueryMessages({
@@ -503,6 +745,8 @@ export class IntlConnection extends SafeEventEmitter {
                 bind: { typeMap, paramTypes, params, queryOptions: options },
                 describe: { type: 'P' },
                 execute: { fetchCount: options.fetchCount || 100 },
+                before: savepoint ? 'SAVEPOINT ' + savepoint : undefined,
+                after: savepoint ? 'RELEASE ' + savepoint : undefined,
             }, (code, msg, done) => {
                 switch (code) {
                     case Protocol.BackendMessageCode.ParseComplete:
@@ -521,7 +765,10 @@ export class IntlConnection extends SafeEventEmitter {
                         rows.push(msg);
                         break;
                     case Protocol.BackendMessageCode.CommandComplete:
-                        commandTag = msg;
+                        if (leadingCommandTags)
+                            leadingCommandTags--;
+                        else if (!commandTag)
+                            commandTag = msg;
                         break;
                     case Protocol.BackendMessageCode.ErrorResponse:
                         error = msg;
@@ -620,7 +867,352 @@ export class IntlConnection extends SafeEventEmitter {
      * the RowDescription fields prepareOnce() already fetched instead of
      * re-Describing a fresh portal on every call.
      */
-    async executeReused(statementName, cachedFields, paramTypes, params, options) {
+    /**
+     * Parsers and wrapped field descriptions for a statement whose
+     * RowDescription prepare() already fetched, memoised per RowDescription
+     * 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;
+        const cached = this._executeReusedParserCache.get(cachedFields);
+        if (cached &&
+            cached.typeMap === typeMap &&
+            columnFormatsEqual(cached.columnFormat, columnFormat)) {
+            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);
+        this._executeReusedParserCache.set(cachedFields, {
+            typeMap,
+            columnFormat,
+            parsers,
+            resultFields,
+        });
+        return { parsers, resultFields };
+    }
+    /**
+     * Executes one prepared statement once per parameter set, as a single
+     * Bind/Execute stream closed by one Sync (see
+     * PgSocket.sendBatchBindExecuteMessages() for the wire shape and what
+     * the single Sync implies).
+     *
+     * Sets map to results positionally: the server answers each Execute with
+     * its own CommandComplete, and rows that arrive before one belong to the
+     * set it closes. When the server rejects a set, everything behind it is
+     * discarded unexecuted - the completed prefix is attached to the thrown
+     * error as `batchResults`, and the rejected set's index as `failedIndex`,
+     * so a caller can tell how far the batch actually got.
+     */
+    /**
+     * Runs several different statements as one Parse/Bind/Describe/Execute
+     * stream closed by a single Sync (see PgSocket.sendPipelineMessages() for
+     * the wire shape and what that framing implies).
+     *
+     * The counterpart to executeBatchReused(): that one runs a single
+     * prepared statement over many parameter sets, this one runs many
+     * statements once each. Results map to statements positionally - the
+     * server answers each Execute with its own CommandComplete, and any rows
+     * that arrive before one belong to the statement it closes.
+     */
+    async executePipeline(requests, options) {
+        this.assertConnected();
+        this.ref();
+        try {
+            const typeMap = options.typeMap || GlobalTypeMap;
+            const timingEnabled = options.timing ?? this.config.timing ?? false;
+            const startTime = timingEnabled ? performance.now() : 0;
+            const rowDecoder = resolveRowDecoder(options);
+            const results = [];
+            let pendingFields;
+            let pendingRows;
+            let error;
+            // 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);
+                }
+                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,
+                    },
+                    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++;
+            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);
+                                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;
+                            }
+                            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)})`));
+                    }
+                })
+                    .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;
+                let i;
+                for (i = 0; i < l; i++)
+                    results[i].executeTime = elapsed;
+            }
+            return results;
+        }
+        finally {
+            this.unref();
+        }
+    }
+    async executeBatchReused(statementName, cachedFields, paramTypes, paramSets, options) {
+        this.assertConnected();
+        this.ref();
+        try {
+            const typeMap = options.typeMap || GlobalTypeMap;
+            const timingEnabled = options.timing ?? this.config.timing ?? false;
+            const startTime = timingEnabled ? performance.now() : 0;
+            const rowDecoder = resolveRowDecoder(options);
+            let parsers;
+            let resultFields;
+            if (cachedFields) {
+                const resolved = this._resolveReusedParsers(cachedFields, typeMap, options);
+                parsers = resolved.parsers;
+                resultFields = resolved.resultFields;
+            }
+            const results = [];
+            let pendingRows;
+            let error;
+            const binds = paramSets.map(params => ({
+                typeMap,
+                statement: statementName,
+                paramTypes,
+                params,
+                queryOptions: options,
+            }));
+            this.runningQueryCount++;
+            await this.socket
+                .sendBatchBindExecuteMessages({
+                binds,
+                // Unlimited, never options.fetchCount: a suspended portal would
+                // break the positional set-to-result mapping above.
+                execute: { fetchCount: 0 },
+            }, (code, msg, done) => {
+                switch (code) {
+                    case Protocol.BackendMessageCode.BindComplete:
+                    case Protocol.BackendMessageCode.NoticeResponse:
+                        break;
+                    case Protocol.BackendMessageCode.DataRow:
+                        (pendingRows || (pendingRows = [])).push(msg);
+                        break;
+                    case Protocol.BackendMessageCode.EmptyQueryResponse:
+                    case Protocol.BackendMessageCode.CommandComplete: {
+                        const item = {};
+                        if (msg?.command)
+                            item.command = msg.command;
+                        if (item.command === 'DELETE' ||
+                            item.command === 'INSERT' ||
+                            item.command === 'UPDATE')
+                            item.rowsAffected = msg.rowCount;
+                        if (pendingRows && parsers && resultFields) {
+                            const l = pendingRows.length;
+                            let i;
+                            for (i = 0; i < l; i++) {
+                                pendingRows[i] = rowDecoder.decode(parsers, pendingRows[i].data, pendingRows[i].columnCount, options, resultFields);
+                            }
+                            item.rows = pendingRows;
+                            if (!item.command)
+                                item.command = 'SELECT';
+                        }
+                        pendingRows = undefined;
+                        results.push(item);
+                        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)})`));
+                }
+            })
+                .catch((e) => {
+                // The rejected set is the one right after everything that
+                // completed, since results only grow on CommandComplete.
+                if (e instanceof DatabaseError && error === e) {
+                    e.failedIndex = results.length;
+                    e.batchResults = results;
+                }
+                throw e;
+            })
+                .finally(() => {
+                this.runningQueryCount--;
+            });
+            let totalRowsAffected = 0;
+            const l = results.length;
+            let i;
+            for (i = 0; i < l; i++)
+                totalRowsAffected += results[i].rowsAffected || 0;
+            const out = { results, totalRowsAffected };
+            if (resultFields)
+                out.fields = resultFields;
+            if (timingEnabled)
+                out.executeTime = performance.now() - startTime;
+            return out;
+        }
+        finally {
+            this.unref();
+        }
+    }
+    async executeReused(statementName, cachedFields, paramTypes, params, options, savepoint) {
         this.assertConnected();
         this.ref();
         try {
@@ -635,35 +1227,17 @@ export class IntlConnection extends SafeEventEmitter {
             let error;
             const rowDecoder = resolveRowDecoder(options);
             if (cachedFields) {
-                const columnFormat = options.columnFormat != null
-                    ? options.columnFormat
-                    : DEFAULT_COLUMN_FORMAT;
-                const cached = this._executeReusedParserCache.get(cachedFields);
-                if (cached &&
-                    cached.typeMap === typeMap &&
-                    columnFormatsEqual(cached.columnFormat, columnFormat)) {
-                    parsers = cached.parsers;
-                    resultFields = cached.resultFields;
-                }
-                else {
-                    const fields = cachedFields.map((f, i) => ({
-                        ...f,
-                        format: Array.isArray(columnFormat)
-                            ? columnFormat[i]
-                            : columnFormat,
-                    }));
-                    parsers = getParsers(typeMap, fields);
-                    resultFields = wrapRowDescription(typeMap, fields, columnFormat);
-                    this._executeReusedParserCache.set(cachedFields, {
-                        typeMap,
-                        columnFormat,
-                        parsers,
-                        resultFields,
-                    });
-                }
+                const resolved = this._resolveReusedParsers(cachedFields, typeMap, options);
+                parsers = resolved.parsers;
+                resultFields = resolved.resultFields;
                 result.fields = resultFields;
                 result.rowType = resolveRowType(options);
             }
+            // The SAVEPOINT/RELEASE pair rollbackOnError needs travels with the
+            // statement instead of costing a round trip each - see
+            // PreparedStatement._withTransaction(), which hands the name down
+            // rather than sending them itself.
+            let leadingCommandTags = savepoint ? 1 : 0;
             this.runningQueryCount++;
             await this.socket
                 .sendBindExecuteMessages({
@@ -675,8 +1249,11 @@ export class IntlConnection extends SafeEventEmitter {
                     queryOptions: options,
                 },
                 execute: { fetchCount: options.fetchCount || 100 },
+                before: savepoint ? 'SAVEPOINT ' + savepoint : undefined,
+                after: savepoint ? 'RELEASE ' + savepoint : undefined,
             }, (code, msg, done) => {
                 switch (code) {
+                    case Protocol.BackendMessageCode.ParseComplete:
                     case Protocol.BackendMessageCode.BindComplete:
                     case Protocol.BackendMessageCode.NoticeResponse:
                     case Protocol.BackendMessageCode.PortalSuspended:
@@ -685,7 +1262,14 @@ export class IntlConnection extends SafeEventEmitter {
                         rows.push(msg);
                         break;
                     case Protocol.BackendMessageCode.CommandComplete:
-                        commandTag = msg;
+                        // Three statements can answer here when a savepoint rides
+                        // along: SAVEPOINT's tag, then the caller's own, then
+                        // RELEASE's. Only the middle one describes what the caller
+                        // asked for.
+                        if (leadingCommandTags)
+                            leadingCommandTags--;
+                        else if (!commandTag)
+                            commandTag = msg;
                         break;
                     case Protocol.BackendMessageCode.ErrorResponse:
                         error = msg;